Skip to content

Commit 0436793

Browse files
authored
fix(replay): extend resume.from record-and-heal shape to caution/manual (#1267)
* fix(replay): extend resume.from record-and-heal shape to caution/manual (#1262) caution/manual divergences kept resume.from unshifted (correct — per resolution item 1, N stays unconditionally legal) but never offered a concrete N+1 continuation for their record-and-heal-shaped alternate repair, and a last-step caution/manual divergence repaired by a recorded action was a dead end: pendingRecordAndHeal was only ever stamped for record-and-heal, so the N+1 empty-tail resume was unauthorized (out of range) and close on the not-yet-COMPLETE transaction discarded the just-recorded corrective action — the same trap #1260 closed only for record-and-heal. - buildRepairHintGuidance (src/replay/divergence.ts) now renders BOTH concrete commands for caution/manual when resume.allowed: --from N for a --no-record state fix, --from N+1 for a recorded corrective action. - stampPendingRecordAndHealWatermark (session-replay-resume.ts) now also stamps for caution/manual, but only when the diverged step is the plan's LAST one and N+1 is independently preflight-safe — a mid-plan --from N+1 was already unconditionally legal and un-gated for these hints (unlike record-and-heal, they never mandate a corrective action), so that pre-existing pattern stays un-gated. * fix(replay): add resume.alternateFrom so caution/manual dual-path never advertises a --from the daemon refuses (#1262) The dual-path text guidance offered `--from N + 1` whenever resuming AT `N` was allowed, but `--from N + 1` needs its OWN preflight — which additionally requires the diverged step `N` to be skip-safe. When `N` is a runScript (outputEnv producer) or inside runtime control flow, preflight(N) passes while preflight(N+1) fails, so the text advertised a command the daemon then refused (the text-vs-structured disagreement #1260 blocker 2 banned). - Add optional `resume.alternateFrom` to the decision-4 wire shape (`ReplayDivergenceResume`). The daemon populates it (`N + 1`) for caution/manual ONLY when `evaluateReplayResumePreflight({ from: N + 1 })` passes — the same acceptance condition on both the mid-plan (un-gated, in range) and last-step (watermark-stamp) paths. Its checked range is a strict superset of `from`'s, so alternateFrom present implies allowed. - The text renderer gates the `N + 1` command on `alternateFrom`'s PRESENCE and renders its value verbatim, never re-deriving resumability — so text and the structured wire can never disagree on the advertised next command. - This also closes a parity gap: a JSON/MCP caller now gets both ordinals (previously the dual-path was text-only, structured callers saw only `from`). - ADR-0012 decision-4 documents alternateFrom as additive/optional; projection and trigger tests cover both positions (runScript/control-flow → no alternateFrom, no `--from N + 1`; skip-safe → alternateFrom present). * fix(replay): withhold empty-tail alternateFrom when no session can stamp the watermark (#1262) The empty-tail alternate (`alternateFrom > actions.length`) is accepted by the range check ONLY when it matches a stamped `pendingRecordAndHeal` watermark, and that watermark can only be stamped on a live session. For a last-step caution/manual failure with no active session — a one-step `open` failure, or a session closed mid-replay — the watermark can never be stamped, so the advertised `--from length+1` is then rejected as out of range, re-introducing the text/structured mismatch this arc fixed. - Thread `sessionExists` into `buildReplayDivergenceResume`; gate the one-past-the-end `alternateFrom` on it (mid-plan alternate stays in-range and session-independent). Both divergence sites pass `session !== undefined`. - At the last step this makes `computeReplayResumeAlternateFrom`'s emit condition exactly `computeRecordAndHealWatermark`'s stamp condition, so alternateFrom present ⟺ the watermark gets stamped in the same request. - ADR-0012 decision 4: reword the mechanical resume.from parity statement for the dual-path hints (from=N + optional alternateFrom=N+1); update the empty-tail paragraph to cover caution/manual last-step stamping and the no-session withholding. - Tests: unit (last-step no-session → no alternateFrom; mid-plan no-session → still present) + integration (single-step failure, no session → no alternateFrom on the wire, no --from length+1 in text).
1 parent 236016e commit 0436793

12 files changed

Lines changed: 1340 additions & 130 deletions

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

Lines changed: 37 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -475,29 +475,53 @@ executable plan and must be in range. It is never a YAML line number, fractional
475475
repeat iteration label. Static includes, platform conditions, and fixed-count repeats expand before
476476
indexing, so repeated source lines are distinguished by their plan index.
477477

478-
Every divergence includes `resume: { allowed, from, reason?, planDigest, repairSessionHeld? }`.
478+
Every divergence includes `resume: { allowed, from, reason?, planDigest, alternateFrom?, repairSessionHeld? }`.
479479
`from` is not merely the failed step's ordinal — it is the ordinal the caller should actually pass to
480480
`--from`, computed from the same `repairHint` carried alongside it (decision 6, R2/R3): for `record-and-heal`,
481481
`from` is the failed step's index **+ 1** (the agent performs that step manually before resuming, so
482482
resuming AT it would re-diverge on the exact step just completed); for every other hint (`state-repair`,
483-
`caution`, `manual`), `from` equals the failed step's index unchanged. This keeps the structured `resume`
484-
block and the `repairHint` text guidance below in agreement — a JSON/MCP-first caller that blindly resumes
485-
at `resume.from` gets the same continuation a text caller reads out of the rendered guidance, never a stale
486-
`from` that loops the caller back onto the step it just repaired.
487-
488-
If the shifted `from` equals `actions.length + 1` (the diverged step was the plan's LAST step), that is a
483+
`caution`, `manual`), `from` equals the failed step's index unchanged. For the SINGLE-path hints
484+
(`record-and-heal`, `state-repair`) `from` is the whole continuation, and a JSON/MCP-first caller that
485+
blindly resumes at `resume.from` reads the identical command the text guidance renders — never a stale `from`
486+
that loops the caller back onto the step it just repaired. The DUAL-path hints (`caution`, `manual`) are the
487+
exception: `from` (`N`) carries only their app-state-fix continuation, and a second ordinal — the optional
488+
`alternateFrom` (`N + 1`, below) — carries the record-and-heal-shaped alternate, so the structured caller
489+
reads BOTH fields to match the text guidance rather than `resume.from` alone.
490+
491+
`alternateFrom` is an **additive optional** ordinal (#1262) that makes the `caution`/`manual` dual-path
492+
structured-caller-legible, not text-only. Those two hints have TWO legitimate repairs the daemon cannot
493+
disambiguate at divergence time: an app-state fix (`--no-record`, then re-run the unchanged step at `from` =
494+
`N`), and a record-and-heal-shaped correction (perform the diverged step's intent as a recorded action, then
495+
resume PAST it at `N + 1`). `from` carries the first; `alternateFrom` carries the second (`N + 1`), present
496+
**only when a `--from N + 1` request for this divergence would actually be accepted** — the daemon computes
497+
it as `evaluateReplayResumePreflight({ from: N + 1, actions }).allowed`, which additionally requires the
498+
diverged step `N` itself to be skip-safe (so it is absent when `N` is a `runScript` outputEnv producer or
499+
sits inside runtime control flow, where `--from N + 1` would be refused). Because that preflight's checked
500+
range is a strict superset of `from`'s, `alternateFrom` present implies `allowed: true` — it never
501+
contradicts the primary. Absent for `record-and-heal` (its `from` already IS the `N + 1` continuation) and
502+
`state-repair` (no recorded-action alternate). The `repairHint` text guidance renders the `N + 1` command
503+
**iff `alternateFrom` is present**, never re-deriving resumability client-side, so the text surface and the
504+
structured wire advertise the identical next command — closing both the text-vs-structured disagreement a
505+
client-side re-derivation would reintroduce and the parity gap where a structured caller saw only `from`.
506+
507+
If the resume ordinal equals `actions.length + 1` (the diverged step was the plan's LAST step), that is a
489508
legal EMPTY-TAIL resume, not an error: there is nothing left to replay, so the resumed run executes zero
490509
device actions and falls straight through to the normal end-of-plan completion path, correctly flipping an
491510
armed repair transaction COMPLETE (decision 6, R7's `close` commit gate). Rejecting this ordinal outright
492511
would force the agent to `close` an INCOMPLETE transaction instead, which aborts and discards the corrective
493512
action it just recorded. This one-past-the-end ordinal is authorized ONLY for the EXACT session and target
494513
that produced it — the daemon stamps a per-session watermark (`expectedFrom`, the recorded action count at
495-
divergence time) whenever a `record-and-heal` divergence reports `allowed: true`, and a later `--from`
496-
request is accepted at `actions.length + 1` only when it matches that watermark AND the session's action
497-
count has grown since (proof the corrective press was actually recorded) — never a blanket "one past the
498-
end is fine" for any session or repair kind, which would let an unrelated or blind resume silently skip the
499-
plan's unresolved final step and commit an incomplete repair. The same watermark match, independent of
500-
whether `from` lands one past the end or still inside the plan, also gates every OTHER `record-and-heal`
514+
divergence time) when a `record-and-heal` divergence reports `allowed: true` (its own `from` is already
515+
`N + 1`), and — per #1262 — also for a `caution`/`manual` LAST-step divergence whose `alternateFrom` (`N + 1`)
516+
is preflight-safe (their `from` stays `N`, so the watermark tracks the alternate's `N + 1` empty-tail
517+
ordinal). Because the watermark can only be stamped on a live session, an empty-tail `alternateFrom` is
518+
withheld entirely when no session exists (a one-step `open` failure, or a session closed mid-replay) —
519+
otherwise the daemon would advertise a `--from N + 1` it must then reject. A later `--from` request is
520+
accepted at `actions.length + 1` only when it matches that watermark AND the session's action count has
521+
grown since (proof the corrective press was actually recorded) — never a blanket "one past the end is fine"
522+
for any session or repair kind, which would let an unrelated or blind resume silently skip the plan's
523+
unresolved final step and commit an incomplete repair. The same watermark match, independent of whether the
524+
resume ordinal lands one past the end or still inside the plan, also gates every OTHER `record-and-heal`
501525
continuation: resuming at the reported `from` with the action count unchanged is rejected as proof the
502526
corrective press never happened, rather than silently resuming past the unrepaired step.
503527
`planDigest` is SHA-256 over

0 commit comments

Comments
 (0)