press/click/fill --settle: settled observation in the interaction response

[thymikee]

Collapse the dominant agent-loop pair (interact → observe) into one round trip: press @e2 --settle executes the press, waits for the UI to go quiet, and returns the settled observation in the same response — saving one full model inference per step, which dwarfs every daemon-side optimization available.

Design (agreed)

• Opt-in flag on press/click/fill/longpress (scroll --settle deferred: infinite feeds settle-then-load, a semantic trap needing its own design).
• Payload = settled diff vs the pre-action tree by default (the baseline already exists — --verify captures it). Composes with response levels: digest = changed-count summary, full = whole interactive tree. A full tree per interaction would invert the snapshot token-budget principle; the diff is what agents actually reason about.
• Best-effort settle, never an action failure: quiet-window semantics from wait stable absorb finite animations; never-settling content (carousels, tickers) returns the latest capture with settled: false + a hint (generalize the tiny-tree hint machinery). The press succeeded; observation quality is advisory — same principle as --verify evidence.
• --verify composition: settle's final capture doubles as the verify evidence source — --settle --verify costs no extra captures.
• Fresh refs ride along (refsGeneration included; MCP re-pins): settle flows structurally dissolve the stale-ref hazard — the feat: warn when @refs outlive the session snapshot they came from #1093/feat: versioned snapshot refs with MCP auto-pinning #1096 warnings become the fallback for non-settle paths, not the main defense.
• Rails from this week slot in directly: response through the refactor: single construction site for interaction responses (ADR 0011 Layer 2) #1083 builder (construction guard enforces), flag classified in the progress model, appliesTo scoping on the guarantee matrix, settle budget via refactor: declare command timeout policy on descriptors (ADR 0011) #1084's flag-sourced timeoutPolicy, one contract scenario per dispatch path.

Costs & platform notes

• Per-call latency: quiet window (default ~500ms) + captures (~300ms each on iOS; Android comparable with the snapshot helper, which is the only supported production configuration — helper-less Android is an internal-testing artifact, typically agents forgetting build:all).
• Side fix bundled here or separately: when the Android helper is missing on a source checkout, the degradation hint should say run pnpm build:all explicitly.

Acceptance evidence

Bluesky dogfood: a fixed multi-step flow measured as tokens + wall-clock per step, --settle vs the two-call baseline. The claim is one fewer inference per step; the measurement should show it.

[thymikee]

End-to-end benchmark protocol (the acceptance evidence, per maintainer: same agent, same task, wall-clock + total tokens + success):

Harness (built, parked in the bench scratchpad; arm A exercised today): headless claude -p --output-format json --allowedTools Bash --max-turns 40 driving the CLI, per-run app reset (relaunch → wait → seed refs), reporting wall_ms / num_turns / cost / input+cache-read+output tokens / DONE-line success. Task: Bluesky — search "alpenglow", open first account, report handle; then first notification label. Arms: (A) current tooling, (B) identical prompt with --settle taught in one line. Models: haiku AND sonnet, N≥3 per cell, medians + success rate.

Arm-A early data (1 Haiku run, machine under load): FAILED after 404s, 38 turns, ~1.48M cache-read tokens, $0.31 — the small model flailed in act→observe loops and ended by breaking the session's accessibility state. This is precisely the "before" behavior the settle hypothesis targets: fewer turns = fewer chances to mis-observe.

Environment finding from the same run (separate issue-worthy): the Haiku agent's rapid-fire command pattern wedged the iOS runner hard enough that snapshot requests kept timing out across a subsequent open --relaunch (daemon correctly survived per the preserve-on-snapshot-timeout policy; the runner did not self-recover without a kill). Agent-abuse resilience is its own workstream.

Full A/B runs when the prototype lands, on a quiet machine — today's host was saturated by parallel work, which contaminates wall-clock.