Skip to content

Commit 5936ce9

Browse files
committed
fix(replay): default-exclude observation-only reads from repair heals, add --record opt-in (#1271 stage 2)
Amends ADR 0012 decision 6: snapshot/get/is/a read-only find are excluded from a repair-armed heal by default (session.saveScriptBoundary set), never from ordinary open --save-script authoring recording. wait keeps recording (flow timing, not observation). The corrective-read trap (wave-3 E3: the diverged step was itself a get) means blanket read-exclusion is unsafe, so a new --record flag forces one action through when the correction is itself a read. --record/--no-record are mutually exclusive (INVALID_ARGS if both are set) and are plumbed identically across CLI, the Node client, and MCP. The exclusion lives at the single daemon-side choke point (recordActionEntry/isExcludedRepairSegmentObservation), so an excluded read never grows session.actions.length -- the same counter the existing record-and-heal resume watermark (describeUnperformedRecordAndHeal) already checks, so the empty-segment fail-loud guard falls out for free (message updated to mention --record). Also fixes a latent bug found along the way: the get/is/find/snapshot CLI readers never forwarded --no-record/--record into the built request (only `open` did), so stage 1's "use --no-record" guidance was silently inert via the CLI.
1 parent 733f81d commit 5936ce9

32 files changed

Lines changed: 1148 additions & 87 deletions

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 109 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Status
44

5-
Accepted (2026-07-10); partially implemented (last updated 2026-07-13). See [Migration progress](#migration-progress) for the per-step landing record.
5+
Accepted (2026-07-10); partially implemented (last updated 2026-07-16). See [Migration progress](#migration-progress) for the per-step landing record.
66

77
**Implemented and merged to `main`:**
88

@@ -12,6 +12,10 @@ Accepted (2026-07-10); partially implemented (last updated 2026-07-13). See [Mig
1212
`REPLAY_DIVERGENCE` repair-loop fix (#1223).
1313
- Decision 6, the base agent-supervised re-record repair — `replay --save-script` arming, the
1414
post-watermark healed slice, `repairHint`, and the writer's bare-`@ref` fail-loud guard (#1228).
15+
- Decision 6, R7 + commit state machine (repair-transaction lifecycle) — the ARMED → COMPLETE → COMMITTED
16+
commit state machine, keep-alive keyed off the persisted transaction (`resume.repairSessionHeld`, never
17+
the per-request `--save-script` flag), terminal-source-`close` skipping, the `REPAIR_SESSION_EXPIRED`
18+
tombstone, and race-safe atomic publication via exclusive `linkSync` (#1235).
1519
- Decision 4 amendment, `screen`'s capture scope and ref selection — the divergence `screen` capture runs
1620
through the same `captureSnapshot` wrapper as plain `snapshot` (full-window scope + Android freshness /
1721
post-action retry parity) under a clean, fixed capture-flags policy (a failed raw/scoped/`-d` action can
@@ -24,12 +28,9 @@ Accepted (2026-07-10); partially implemented (last updated 2026-07-13). See [Mig
2428
(a shared Android framework resource id such as `android:id/title`, or a reused RN `FlatList` `testID`)
2529
falls back to role+label in both `computeTargetEvidence`'s `target-v1` tuple and
2630
`buildSelectorChainForNode`'s chain (#1269).
27-
28-
**Accepted but NOT yet implemented** (this amendment; tracked by #1235 — repair-transaction lifecycle):
29-
the R7 repair-transaction keep-alive and its distinct `resume.repairSessionHeld` signal, the ARMED →
30-
COMPLETE → COMMITTED commit state machine, terminal-source-`close` skipping, the `REPAIR_SESSION_EXPIRED`
31-
tombstone, and race-safe atomic publication. Until #1235 lands, `--save-script` on a diverging replay
32-
does not carry the lifetime, abort-on-incomplete, or atomic-commit guarantees R7 specifies.
31+
- Decision 6 amendment, repair-segment default exclusion of observation-only commands and the `--record`
32+
opt-in — stage 1 (interim guidance only, #1287) and stage 2 (the semantic default-exclusion fix,
33+
this amendment) of #1271. See the amendment under decision 6 below.
3334

3435
## Context (historical baseline)
3536

@@ -942,6 +943,90 @@ re-run guidance to restart the repair from the original script), never a bare `S
942943
`replay --save-script` on the same key **clears the tombstone and starts a fresh transaction** (`ARMED`).
943944
The tombstone itself expires after its bounded window, after which the key is fully free.
944945

946+
> **Amendment (#1271 stage 2): repair-segment default exclusion of observation-only commands, and the
947+
> `--record` opt-in.** #1271 reported that read-only diagnostics an agent runs mid-repair to LOCATE the
948+
> repair target — `snapshot -i`, `get attrs`, `find`, `is` — recorded into the healed script exactly like
949+
> the corrective action itself. The wave-3 E3 experiment measured 0/4 trials producing a clean healed
950+
> script hands-off; one recorded `get attrs` caused a second, self-inflicted `identity-mismatch` divergence
951+
> on fresh replay. Stage 1 (#1287) shipped interim guidance only — the divergence `repairHint` and `help
952+
> workflow` told the agent to pass `--no-record` on those commands by hand. This amendment makes the safer
953+
> behavior the default, superseding stage 1's "opt out by hand" guidance with "opt in by hand" for the one
954+
> case that needs it.
955+
>
956+
> **1. Which read-only commands are excluded.** Exactly the enumerated set stage 1 already named:
957+
> `snapshot`, `get`, `is`, and a **read-only** `find` sub-action (`exists`, `wait`, `get_text`, `get_attrs`).
958+
> A **mutating** `find … click|fill|focus|type` is not in this set — it is a corrective action like `press`/
959+
> `fill` and always records. The top-level `wait` command is deliberately **not** in this set either: it is
960+
> flow timing/synchronisation (pacing the script), not observation, so it must keep recording unconditionally
961+
> even inside a repair segment — a healed script that silently dropped its own timing steps would replay
962+
> differently from what actually happened.
963+
>
964+
> **2. The corrective-read trap, and why blanket exclusion by command class is unsafe.** "Exclude every
965+
> read from a repair segment" is not a safe rule on its own: a divergence's **correction** can itself be a
966+
> read. In the wave-3 E3 drift, the diverged step **was** a `get`, so its corrective replacement is a
967+
> recorded `get` that **must** land in the heal — a blanket read-exclusion would silently drop the very
968+
> step being repaired, producing an incomplete heal with no signal anything was missing (the same class of
969+
> silent-failure mode decision 3 exists to close for target-binding, and decision 6 R4 exists to close for
970+
> bare `@ref` exports). Distinguishing "the read that replaces the diverged step" from "reads used to locate
971+
> the target" by POSITION (e.g., relative to the eventual `--from` resume) was considered and rejected: the
972+
> daemon records each action as it happens and has no reliable way to know, at record time, which one the
973+
> agent will later treat as the resume boundary — and a position-based rule would silently reinterpret
974+
> intent after the fact rather than let the agent state it. The adopted rule instead makes this an **explicit
975+
> opt-in per action**: `--record` (below) marks the ONE read that must count, independent of its position in
976+
> the repair segment.
977+
>
978+
> **3. Explicit recording remains possible.** `--record` is a new, standalone flag — distinct from
979+
> `saveScript`, and the mirror image of `--no-record` — that forces the action it is passed on into the heal
980+
> even though its command is observation-only. It is a no-op outside a repair-armed session (there is no
981+
> default exclusion to override) and a no-op on any non-observation-only command (those already always
982+
> record). `--record` and `--no-record` express opposite intents for the same action and are **mutually
983+
> exclusive**: passing both is rejected as `INVALID_ARGS` before the command runs, uniformly for every
984+
> surface, rather than letting one silently win.
985+
>
986+
> **4. How the rule projects across CLI/Node/MCP surfaces.** The exclusion is enforced at a single
987+
> daemon-side choke point — `isExcludedRepairSegmentObservation` in `recordActionEntry`
988+
> (`src/daemon/session-action-recorder.ts`), gated on `session.saveScriptBoundary !== undefined` (set ONLY
989+
> by a repair-armed `replay --save-script`; an ordinary, non-repair `open --save-script`/`close --save-script`
990+
> authoring recording never sets it — see decision 6's "Scope" note above) and on the entry's
991+
> `observationOnly` marker (set by the caller — `get`/`is`/a read-only `find` in
992+
> `src/daemon/selector-recording.ts`, `snapshot` in `src/daemon/snapshot-runtime.ts` — never inferred from
993+
> `command`/`positionals`, since a mutating `find … click` shares the literal string `command: 'find'` with
994+
> its read-only sibling). Every surface reaches this same function because every surface's request reaches
995+
> the same daemon: the CLI parses `--record`/`--no-record` into `CommandFlags` (`src/contracts/cli-flags.ts`,
996+
> `src/commands/cli-grammar/flag-definitions-action.ts`, `src/commands/cli-grammar/flag-groups.ts`'s
997+
> `COMMON_COMMAND_SUPPORTED_FLAG_KEYS` — so both flags are syntactically valid on every command, exactly like
998+
> `--no-record` already was); the Node client threads the same-named option through
999+
> `buildRequestFlags`/`buildFlags` (`src/commands/command-flags.ts`) from `InternalRequestOptions` and
1000+
> `AppOpenOptions` (`src/client/client-types.ts`) and from each typed per-command Options type
1001+
> (`GetOptions`/`IsOptions`/`FindOptions`/`CaptureSnapshotOptions`); and the MCP tool schema exposes `record`/
1002+
> `noRecord` fields on the `get`/`is`/`find`/`snapshot` tools (`src/commands/interaction/metadata.ts`,
1003+
> `src/commands/capture/snapshot.ts`) that flow through the same `CommandMetadata.inputSchema` +
1004+
> `readMetadataCommandFlags` path every other typed field already uses. `management/app.ts` mirrors both
1005+
> flags onto `open` for symmetry with `--no-record`'s existing presence there, though neither has an effect
1006+
> on a command that is never observation-only. No surface has a separate recording contract; all of them
1007+
> hit the identical daemon-side default.
1008+
>
1009+
> **5. The fail-loud guard is the EXISTING resume watermark, not new state.** Because the exclusion happens
1010+
> at the same point `--no-record` is enforced — before an action ever reaches `session.actions` — an excluded
1011+
> diagnostic read never grows `session.actions.length`. That counter is exactly what
1012+
> `describeUnperformedRecordAndHeal` (`src/daemon/handlers/session-replay-runtime-plan.ts`, R2/#1262's
1013+
> `pendingRecordAndHeal` watermark) already compares against `actionsCountAtDivergence` to prove a corrective
1014+
> action happened before authorizing a `record-and-heal`-shaped `--from` resume. No additional bookkeeping is
1015+
> needed: a repair segment containing only excluded diagnostic reads is indistinguishable, at that check,
1016+
> from a repair segment containing no activity at all, so the existing guard already refuses it. This
1017+
> amendment only updates the guard's message to name `--record` alongside the existing `--no-record`
1018+
> mention, since the missing corrective action may have been a read rather than a press: "no corrective
1019+
> action was recorded in this repair segment; press the correct control via a blessed `@ref` … — or, if your
1020+
> corrective action was a read, re-run it with `--record` … — before resuming."
1021+
>
1022+
> **Regression coverage** proves: a diagnostic read inside an armed repair segment is omitted from the
1023+
> healed script by default; a corrective action remains for both a mutating press/fill (unaffected — never
1024+
> observation-only) and a `--record`ed read (the diverged-step-was-a-`get` case); the resulting healed script
1025+
> replays cleanly in a fresh session; the empty-segment guard refuses a blind resume with the actionable
1026+
> `--record` hint; and ordinary, non-repair `open --save-script` authoring recording is completely unchanged
1027+
> — a read in a fresh authoring session still records with no flag needed, because `session.saveScriptBoundary`
1028+
> is never set there.
1029+
9451030
## Consequences
9461031

9471032
- `--from` makes app state the caller's responsibility, and only accepts a resume when the planner can
@@ -1039,8 +1124,8 @@ each states its dependencies explicitly.
10391124
daemon-side `repairHint` computation over all four `kind`s (R3), `--save-script` arming plus the
10401125
repair-run boundary watermark on `replay` (R1/R6), the writer's post-watermark slice and bare-`@ref`
10411126
fail-loud guard (R4/R6) — reusing `close --save-script`'s existing `session.actions` serializer.
1042-
9. **Repair-transaction lifecycle** (decision 6, R7 + commit state machine) — **NOT YET IMPLEMENTED,
1043-
tracked by #1235**; depends on 8. Adds: the distinct `resume.repairSessionHeld` divergence signal and
1127+
9. **Repair-transaction lifecycle** (decision 6, R7 + commit state machine) — **SHIPPED (#1235)**;
1128+
depends on 8. Adds: the distinct `resume.repairSessionHeld` divergence signal and
10441129
R7 keep-alive keyed off the session's **persisted** repair-transaction state (so `--from` continuations
10451130
need no repeat of `--save-script`), with `fail-fast-before-step-1` when keep-alive is impossible; the
10461131
`ARMED → COMPLETE → COMMITTED` commit state machine where **any teardown** (explicit `close`,
@@ -1053,10 +1138,19 @@ each states its dependencies explicitly.
10531138
pre-existing target — complete or partial, default or explicit path alike, and uniformly for an
10541139
ordinary non-repair recording's target too, since the publish primitive is shared — never overwriting
10551140
one; see "Scope" under Decision 6 above).
1141+
10. **Repair-segment default exclusion of observation-only commands, and the `--record` opt-in**
1142+
(decision 6 amendment) — **SHIPPED (#1271 stage 2)**; depends on 9 (`session.saveScriptBoundary`/
1143+
`repairSessionHeld` are the signals the exclusion and its guidance key off). Adds: default exclusion of
1144+
`snapshot`/`get`/`is`/a read-only `find` from `session.actions` while repair-armed
1145+
(`isExcludedRepairSegmentObservation`, `session-action-recorder.ts`); the `--record` opt-in, plumbed
1146+
across CLI/Node client/MCP identically to `--no-record`, and rejected together with it as
1147+
`INVALID_ARGS`; and an updated `describeUnperformedRecordAndHeal` message naming `--record` for the
1148+
corrective-read case. Stage 1 (#1287) shipped interim `--no-record` guidance only, gated on this same
1149+
`repairSessionHeld` signal.
10561150

10571151
## Migration progress
10581152

1059-
Landing record for the plan above (main as of 2026-07-13). This section tracks progress only; it does
1153+
Landing record for the plan above (main as of 2026-07-16). This section tracks progress only; it does
10601154
not restate or amend the decisions.
10611155

10621156
| Step | Decision | Status | Landed in |
@@ -1069,11 +1163,13 @@ not restate or amend the decisions.
10691163
| 6. `--update` retirement | 1 | Shipped | #1211 |
10701164
| 7. Benchmark extension | 5 | Deferred | — |
10711165
| 8. Agent-supervised re-record repair, base | 6 (R1-R6) | Shipped | #1228 |
1072-
| 9. Repair-transaction lifecycle | 6 (R7) | Not yet | #1235 |
1166+
| 9. Repair-transaction lifecycle | 6 (R7) | Shipped | #1235 |
1167+
| 10. Repair-segment default exclusion + `--record` | 6 amendment | Shipped | #1271 stage 2 |
10731168

10741169
Step 4 (#1209) added the `selector-miss`/`identity-mismatch`/`identity-unverifiable` divergence kinds
10751170
and a post-resolution target guard that cross-checks the dispatched winner against the verified member.
10761171
Issue #1221 ("Complete ADR 0012 replay target-binding verification") was closed as already implemented:
10771172
its verification scope is covered by step 4. Step 7 remains deferred. Step 8 implements the repair
1078-
design accepted in #1226 and shipped in #1228; step 9 (R7 + commit machine) remains unimplemented,
1079-
tracked by #1235.
1173+
design accepted in #1226 and shipped in #1228; step 9 (R7 + commit machine) shipped in #1235. Step 10
1174+
is #1271's two-stage arc: stage 1 (#1287) shipped interim `--no-record` guidance only; stage 2 (this
1175+
amendment) makes exclusion the default and adds the `--record` opt-in.

0 commit comments

Comments
 (0)