fix: improve ref-based interaction recovery

[thymikee]

Summary

• Treat every positional after fill @ref as replacement text, so fill @e57 good morning enters good morning instead of interpreting good as a fallback label.
• When a model drops a generation suffix from an emitted scoped ref, return the exact safe ref to retry when the current frame proves it exists. This remains fail-closed and never rewrites refs silently.
• Make iOS TEXT_INPUT_COMMIT_NOT_OBSERVED recovery inspect the field first, then retry a quoted paced fill only when the value is actually missing.
• Update generated help and command documentation for the corrected fill grammar.

Validation

• pnpm check:affected --base origin/main --head HEAD --run: all runnable checks passed, including 311 related test files / 2,344 tests and provider integration.
• iOS XCTest runner build passed locally.
• Android Element 08 live benchmark: a dropped @e24 suffix returned @e24~s467960; the model retried it directly, fill reported 12 characters, and the settled snapshot showed good morning before send.
• iOS Element 08 independently exercised the exact-ref recovery (@e40 suggested @e40~s362848). That scenario was ultimately blocked by an unrelated Element “Threads no longer experimental” modal, so it is not claimed as iOS fill success evidence.
• The quoted iOS fill investigation showed TEXT_INPUT_COMMIT_NOT_OBSERVED followed immediately by a snapshot containing the complete expected value, motivating inspect-before-retry guidance without weakening verification.

The PR touches 10 files in the interaction command family (source, tests, Apple recovery text, help, and docs). Scope did not grow beyond ref-based interaction and text-entry recovery. Benchmark harness cleanup and benchmark artifacts are intentionally excluded.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-31 11:37 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.53 MB	2.48 MB	-45.2 kB
JS gzip	847.2 kB	834.7 kB	-12.6 kB
npm tarball	973.7 kB	957.9 kB	-15.7 kB
npm unpacked	3.36 MB	3.32 MB	-47.2 kB

npm unpacked components

Component	Base	Current	Diff
JS / dist source	2.68 MB	2.64 MB	-46.9 kB
Apple runner source/project	581.1 kB	581.2 kB	+59 B
macOS helper source	54.8 kB	54.8 kB	0 B
Android helper artifacts	0 B	0 B	0 B
Other package files	45.6 kB	45.3 kB	-301 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	24.6 ms	24.2 ms	-0.3 ms
CLI --help	65.8 ms	63.2 ms	-2.6 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/src2.js	+47.3 kB	+14.1 kB
dist/src/runner-client.js	+44.1 kB	+12.8 kB
dist/src/snapshot.js	+33.1 kB	+10.6 kB
dist/src/android.js	+26.0 kB	+9.1 kB
dist/src/cli.js	+26.4 kB	+8.8 kB

Top changed packed files

Packed file	Base	Current	Diff
dist/src/mechanics.js	154.2 kB	0 B	-154.2 kB
dist/src/src7.js	47.5 kB	0 B	-47.5 kB
dist/src/src2.js	661 B	47.3 kB	+46.6 kB
dist/src/runner-disposal.js	45.7 kB	0 B	-45.7 kB
dist/src/runner-client.js	41.7 kB	85.8 kB	+44.1 kB
dist/src/snapshot.js	2.6 kB	33.1 kB	+30.5 kB
dist/src/perf-facade.js	27.3 kB	0 B	-27.3 kB
dist/src/snapshot-helper.js	0 B	25.9 kB	+25.9 kB
dist/src/sdk-android-adb.js	0 B	25.6 kB	+25.6 kB
dist/src/src8.js	25.4 kB	0 B	-25.4 kB

[thymikee]

Reviewed exact head 0a77faff103f089c7a7e4bb23c04fcc2c2923fe3 against the shipped interaction route and ref-frame policy. No actionable code findings.

• fill @ref now treats every remaining positional as replacement text across CLI decoding and daemon parsing; the regressions cover the prior first-word/fallback-label split.
• Partial-frame recovery remains fail-closed: it suggests an exact pinned ref only when that ref was emitted in the current scope, and requires an explicit retry rather than silently rewriting.
• Exact-head checks are green, including Android/iOS/macOS/Linux smoke, Coverage, Integration Tests, Repo Guards, Size, and command-docs.

The Android live run exercises suffix-drop → exact-ref suggestion → successful fill. The iOS evidence covers exact-ref recovery; its separate fill attempt was blocked by an unrelated modal and is not overstated.

Clean for human review; merge remains a maintainer decision.