refactor: derive every --settle surface from the descriptor trait (#1652) (#1945)

Author: thymikee

packages/contracts/src/facades/interaction.ts

@@ -152,6 +152,7 @@ export {
 } from '../scroll-command.ts';
 export type {
   ScrollCommandOptions,
+  ScrollCommandResult,
   ScrollDistanceOptions,
   ScrollExecutionOptions,
   ResolvedScrollExecutionOptions,

packages/contracts/src/scroll-command.ts

@@ -1,4 +1,6 @@
 import { AppError } from '@agent-device/kernel/errors';
+import type { SettleObservation } from './interaction.ts';
+import type { ScrollDirection } from './scroll-gesture.ts';
 
 export const SCROLL_DURATION_MAX_MS = 10_000;
 export const DEFAULT_MOBILE_SCROLL_DURATION_MS = 300;
@@ -67,3 +69,26 @@ export function honoredScrollDurationMs(
 ): number | undefined {
   return typeof result?.durationMs === 'number' ? result.durationMs : undefined;
 }
+
+/**
+ * `scroll` — the generic-route result built by `buildDispatchedScrollResult`
+ * (src/core/dispatch-interactions.ts): the resolved direction, the edge-pass
+ * bookkeeping for `top`/`bottom` scrolls, the honored distance/timing echo,
+ * and the success message. Platform leaves add gesture-plan coordinates
+ * (`x1`/`y1`/`x2`/`y2`, reference frame) on top; the output schema stays
+ * non-strict so those additive fields validate. The one field the dispatcher
+ * itself may add: `settle`, the opt-in `--settle` observation (#1638),
+ * attached after the command — same shape as `BackCommandResult`.
+ */
+export type ScrollCommandResult = {
+  direction: ScrollDirection;
+  /** Set for `top`/`bottom` requests: the extreme being scrolled to. */
+  edge?: 'top' | 'bottom';
+  /** Edge scrolls only: how many scroll-and-check passes ran. */
+  passes?: number;
+  amount?: number;
+  pixels?: number;
+  durationMs?: number;
+  message?: string;
+  settle?: SettleObservation;
+};

src/cli-schema/cli-help-topics.test.ts

@@ -521,10 +521,8 @@ test('usageForCommand resolves dogfood help topic', async () => {
   assert.match(help, /direct Android localhost URL opens with a port auto-configure/);
   assert.match(help, /Keep stateful commands serial within the same session/);
   assert.match(help, /agent-device wait 'role=tab' 10000/);
-  assert.match(
-    help,
-    /scroll takes direction then amount and does not support a selector or --settle/,
-  );
+  assert.match(help, /scroll takes a selector-less direction\+amount form/);
+  assert.match(help, /Use --settle to wait for the UI to go quiet/);
   assert.match(help, /prefer agent-device open "Expo Go" <url>/);
   assert.match(help, /dogfood-output\/report\.md/);
   assert.match(help, /ID, severity, category, title, affected flow\/screen/);

src/cli-schema/cli-help.ts

@@ -970,7 +970,7 @@ Rules:
   Findings must come from observed runtime behavior, not source reads.
   After each mutation, use the --settle diff as evidence when available; otherwise re-snapshot.
   Wait timeouts are integer milliseconds in the trailing positional: agent-device wait 'role=tab' 10000. Do not write duration suffixes such as 10s.
-  scroll takes direction then amount and does not support a selector or --settle: agent-device scroll down 3.
+  scroll takes a selector-less direction+amount form: agent-device scroll down 3. Use --settle to wait for the UI to go quiet and get the settled diff.
   Keep commands in the report reproducible; use selectors or refs from fresh snapshots, not guessed coordinates.
   Prefer refs for exploration and selectors for deterministic replay.
   Use logs, network, screenshot --overlay-refs, trace, perf frames, perf memory, native profiles, or react-devtools only when they add evidence to a specific issue.

src/commands/cli-grammar/common.ts

@@ -140,6 +140,8 @@ export function selectorSnapshotOptionsFromFlags(flags: CliFlags): SelectorSnaps
 // Descriptor post-action observation commands use --settle (#1101).
 // --timeout doubles as the settle deadline only when --settle is present; a
 // bare --timeout stays compatible and is ignored by touch commands.
+// #1652: readers do NOT spread this themselves — `readInputFromCli` merges
+// `settleInputForCommand` at the one seam every reader passes through.
 export function settleInputFromFlags(flags: CliFlags): Record<string, unknown> {
   return compactRecord({
     settle: flags.settle,

src/commands/cli-grammar/registry.ts

@@ -1,6 +1,7 @@
 import type { CliFlags } from '@agent-device/contracts/command';
 import type { CommandName } from '../command-metadata.ts';
 import { listCommandFamilyCliReaders } from '../family/registry.ts';
+import { settleInputForCommand } from '../post-action-observation-grammar.ts';
 
 const cliReaders = listCommandFamilyCliReaders();
 
@@ -13,5 +14,8 @@ export function readInputFromCli(
   if (!reader) {
     throw new Error(`Missing CLI reader for command: ${command}`);
   }
-  return reader(positionals, flags);
+  // #1652: the `--settle` triple merges here, at the one seam every reader
+  // passes through, instead of being hand-spread per settle-capable reader —
+  // a drop at any one of those silently disabled the flag.
+  return { ...reader(positionals, flags), ...settleInputForCommand(command, flags) };
 }

src/commands/interaction/interactions.ts

@@ -30,7 +30,6 @@ import {
   request,
   requiredDaemonString,
   selectorSnapshotInputFromFlags,
-  settleInputFromFlags,
   targetInputFromClientTarget,
 } from '../cli-grammar/common.ts';
 import type { CliReader, DaemonWriter } from '../cli-grammar/types.ts';
@@ -41,7 +40,6 @@ export const interactionCliReaders = {
     ...commonInputFromFlags(flags),
     ...selectorSnapshotInputFromFlags(flags),
     ...repeatedInputFromFlags(flags),
-    ...settleInputFromFlags(flags),
     target: targetInputFromClientTarget(readInteractionTargetFromPositionals(positionals)),
     button: flags.clickButton,
     verify: flags.verify,
@@ -50,7 +48,6 @@ export const interactionCliReaders = {
     ...commonInputFromFlags(flags),
     ...selectorSnapshotInputFromFlags(flags),
     ...repeatedInputFromFlags(flags),
-    ...settleInputFromFlags(flags),
     target: targetInputFromClientTarget(readInteractionTargetFromPositionals(positionals)),
     verify: flags.verify,
   }),
@@ -59,15 +56,13 @@ export const interactionCliReaders = {
     return {
       ...commonInputFromFlags(flags),
       ...selectorSnapshotInputFromFlags(flags),
-      ...settleInputFromFlags(flags),
       target: targetInputFromClientTarget(decoded),
       durationMs: decoded.durationMs,
     };
   },
   hover: (positionals, flags) => ({
     ...commonInputFromFlags(flags),
     ...selectorSnapshotInputFromFlags(flags),
-    ...settleInputFromFlags(flags),
     target: targetInputFromClientTarget(readInteractionTargetFromPositionals(positionals)),
   }),
   swipe: (positionals, flags) => ({
@@ -93,7 +88,6 @@ export const interactionCliReaders = {
     return {
       ...commonInputFromFlags(flags),
       ...selectorSnapshotInputFromFlags(flags),
-      ...settleInputFromFlags(flags),
       target: targetInputFromClientTarget(decoded.target),
       text: decoded.text,
       delayMs: flags.delayMs,
@@ -103,7 +97,6 @@ export const interactionCliReaders = {
   },
   scroll: (positionals, flags) => ({
     ...commonInputFromFlags(flags),
-    ...settleInputFromFlags(flags),
     direction: readScrollDirection(positionals[0]),
     amount: optionalCliNumber(positionals[1]),
     pixels: flags.pixels,

src/commands/interaction/output.ts

@@ -5,11 +5,12 @@ import { displayLabel, formatRole } from '../../snapshot/snapshot-lines.ts';
 import { readCommandMessage } from '../../utils/success-text.ts';
 import {
   messageCliOutput,
+  messageOutput,
   pinnedRefText,
   resultOutput,
   type CliOutputFormatter,
 } from '../output-common.ts';
-import { appendResponseNotes, messageWithSettleOutput } from '../settle-output.ts';
+import { withSettleCapableNotes } from '../settle-output.ts';
 
 function getCliOutput(params: { result: CommandRequestResult; format?: string }): CliOutput {
   const data = params.result as Record<string, unknown>;
@@ -73,27 +74,29 @@ function tapCliOutput(result: CommandRequestResult): CliOutput {
   const x = data.x;
   const y = data.y;
   if (!ref || typeof x !== 'number' || typeof y !== 'number') {
-    const output = defaultCommandCliOutput(data);
-    return { data: output.data, text: appendResponseNotes(output.text, data) };
+    return defaultCommandCliOutput(data);
   }
-  return { data, text: appendResponseNotes(`Tapped @${ref} (${x}, ${y})`, data) };
+  return { data, text: `Tapped @${ref} (${x}, ${y})` };
 }
 
-export const interactionCliOutputFormatters = {
+// #1652: settle-capable entries (click, press, fill, longpress, hover, scroll)
+// get the warning/settle notes appended by the trait-derived wrapper; the rest
+// of the map is returned untouched.
+export const interactionCliOutputFormatters = withSettleCapableNotes({
   click: resultOutput(tapCliOutput),
   press: resultOutput(tapCliOutput),
-  fill: messageWithSettleOutput,
-  longpress: messageWithSettleOutput,
-  hover: messageWithSettleOutput,
-  scroll: messageWithSettleOutput,
+  fill: messageOutput,
+  longpress: messageOutput,
+  hover: messageOutput,
+  scroll: messageOutput,
   get: ({ input, result }) =>
     getCliOutput({
       result: result as CommandRequestResult,
       format: input.format as Parameters<typeof getCliOutput>[0]['format'],
     }),
   is: resultOutput(isCliOutput),
   find: resultOutput(findCliOutput),
-} as const satisfies Record<string, CliOutputFormatter>;
+} satisfies Record<string, CliOutputFormatter>);
 
 function defaultCommandCliOutput(result: CommandRequestResult): CliOutput {
   return messageCliOutput(result as Record<string, unknown>);

src/commands/post-action-observation-client-options.ts

@@ -0,0 +1,35 @@
+import type {
+  ClickOptions,
+  FillOptions,
+  HoverOptions,
+  LongPressOptions,
+  PressOptions,
+  ScrollOptions,
+  SettleCommandOptions,
+} from '@agent-device/contracts/client';
+import type { PostActionObservationCommandName } from '../core/command-descriptor/post-action-observation.ts';
+import type { NavigationCommandOptions } from './system/navigation-projection.ts';
+
+/**
+ * Compile-time completeness for the contracts half of the `--settle` surface
+ * (#1652): every client options type whose command carries the descriptor
+ * post-action observation trait must intersect `SettleCommandOptions`.
+ *
+ * The `Record` over the trait command union makes a missing or extra cell a
+ * compile error, and the `satisfies` assignability check fails when any listed
+ * option type drops its `& SettleCommandOptions` intersection — the same
+ * strategy `packages/contracts/src/interaction-guarantees.ts` uses to make
+ * guarantee completeness a compile error instead of a runtime assertion.
+ */
+const SETTLE_CAPABLE_CLIENT_OPTION_TYPES = {
+  click: {} as ClickOptions,
+  press: {} as PressOptions,
+  longpress: {} as LongPressOptions,
+  hover: {} as HoverOptions,
+  fill: {} as FillOptions,
+  scroll: {} as ScrollOptions,
+  back: {} as NavigationCommandOptions<'back'>,
+} as const satisfies Record<PostActionObservationCommandName, SettleCommandOptions>;
+
+export type SettleCapableClientOptionCommands =
+  readonly (keyof typeof SETTLE_CAPABLE_CLIENT_OPTION_TYPES)[];

src/commands/post-action-observation-grammar.ts

@@ -1,20 +1,22 @@
+import type { CliFlags } from '@agent-device/contracts/command';
 import type { PostActionObservationSupportFor } from '../core/command-descriptor/post-action-observation.ts';
 import {
   commandSupportsSettleObservation,
   commandSupportsVerifyEvidence,
 } from '../core/command-descriptor/registry.ts';
+import { settleInputFromFlags } from './cli-grammar/common.ts';
 import { SETTLE_FLAGS } from './cli-grammar/flag-groups.ts';
 import type { FlagKey } from './cli-grammar/flag-types.ts';
 import { booleanField, integerField } from './command-input.ts';
 
 /**
- * The two caller-facing surfaces a command's post-action observation trait
+ * The caller-facing surfaces a command's post-action observation trait
  * entitles it to (`--verify` / `--settle`, #1047/#1101): the metadata input
- * fields (Node SDK options + MCP tool schema) and the CLI allowed flags. Both
- * are materialized from the descriptor registry rather than hand-listed per
- * command. This lives outside the interaction family because the trait does
- * too: `scroll` and `back` carry it on the generic daemon route (#1638), and
- * `back` is a system command.
+ * fields (Node SDK options + MCP tool schema), the CLI allowed flags, and the
+ * CLI reader input (#1652). All are materialized from the descriptor registry
+ * rather than hand-listed per command. This lives outside the interaction
+ * family because the trait does too: `scroll` and `back` carry it on the
+ * generic daemon route (#1638), and `back` is a system command.
  *
  * A descriptor gate (`post-action-observation.test.ts`) asserts, over every
  * descriptor, that both surfaces are present exactly when the trait is — so a
@@ -60,3 +62,14 @@ export function postActionObservationCliFlags(command: string): readonly FlagKey
   if (commandSupportsSettleObservation(command)) flags.push(...SETTLE_FLAGS);
   return flags;
 }
+
+/**
+ * #1652: the settle triple a command's reader owes the daemon, merged at the
+ * `readInputFromCli` seam so no reader can forget it (the pre-seam per-reader
+ * spreads silently no-op'd when dropped). Non-settle commands get `{}` — and
+ * their parsers refuse `--settle` anyway via `postActionObservationCliFlags`.
+ */
+export function settleInputForCommand(command: string, flags: CliFlags): Record<string, unknown> {
+  if (!commandSupportsSettleObservation(command)) return {};
+  return settleInputFromFlags(flags);
+}