Skip to content

Commit d40280d

Browse files
committed
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 acd8b26 commit d40280d

6 files changed

Lines changed: 177 additions & 23 deletions

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

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -480,10 +480,13 @@ Every divergence includes `resume: { allowed, from, reason?, planDigest, alterna
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.
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.
487490

488491
`alternateFrom` is an **additive optional** ordinal (#1262) that makes the `caution`/`manual` dual-path
489492
structured-caller-legible, not text-only. Those two hints have TWO legitimate repairs the daemon cannot
@@ -501,19 +504,24 @@ contradicts the primary. Absent for `record-and-heal` (its `from` already IS the
501504
structured wire advertise the identical next command — closing both the text-vs-structured disagreement a
502505
client-side re-derivation would reintroduce and the parity gap where a structured caller saw only `from`.
503506

504-
If the shifted `from` equals `actions.length + 1` (the diverged step was the plan's LAST step), that is a
507+
If the resume ordinal equals `actions.length + 1` (the diverged step was the plan's LAST step), that is a
505508
legal EMPTY-TAIL resume, not an error: there is nothing left to replay, so the resumed run executes zero
506509
device actions and falls straight through to the normal end-of-plan completion path, correctly flipping an
507510
armed repair transaction COMPLETE (decision 6, R7's `close` commit gate). Rejecting this ordinal outright
508511
would force the agent to `close` an INCOMPLETE transaction instead, which aborts and discards the corrective
509512
action it just recorded. This one-past-the-end ordinal is authorized ONLY for the EXACT session and target
510513
that produced it — the daemon stamps a per-session watermark (`expectedFrom`, the recorded action count at
511-
divergence time) whenever a `record-and-heal` divergence reports `allowed: true`, and a later `--from`
512-
request is accepted at `actions.length + 1` only when it matches that watermark AND the session's action
513-
count has grown since (proof the corrective press was actually recorded) — never a blanket "one past the
514-
end is fine" for any session or repair kind, which would let an unrelated or blind resume silently skip the
515-
plan's unresolved final step and commit an incomplete repair. The same watermark match, independent of
516-
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`
517525
continuation: resuming at the reported `from` with the action count unchanged is rejected as proof the
518526
corrective press never happened, rather than silently resuming past the unrepaired step.
519527
`planDigest` is SHA-256 over

‎src/daemon/handlers/__tests__/session-replay-resume.test.ts‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ test('buildReplayDivergenceResume reports allowed:true with from/planDigest for
146146
actions,
147147
planDigest: 'abc123',
148148
repairHint: 'state-repair',
149+
sessionExists: true,
149150
});
150151
assert.deepEqual(resume, { allowed: true, from: 2, planDigest: 'abc123' });
151152
});
@@ -164,6 +165,7 @@ test('buildReplayDivergenceResume reports allowed:false with from/planDigest/rea
164165
actions,
165166
planDigest: 'abc123',
166167
repairHint: 'manual',
168+
sessionExists: true,
167169
});
168170
assert.equal(resume.allowed, false);
169171
assert.equal(resume.from, 2);
@@ -187,6 +189,7 @@ test('buildReplayDivergenceResume with repairHint record-and-heal resumes AFTER
187189
actions,
188190
planDigest: 'abc123',
189191
repairHint: 'record-and-heal',
192+
sessionExists: true,
190193
});
191194
assert.deepEqual(resume, { allowed: true, from: 3, planDigest: 'abc123' });
192195
});
@@ -204,6 +207,7 @@ test('buildReplayDivergenceResume with repairHint record-and-heal on the LAST pl
204207
actions,
205208
planDigest: 'abc123',
206209
repairHint: 'record-and-heal',
210+
sessionExists: true,
207211
});
208212
assert.deepEqual(resume, { allowed: true, from: 3, planDigest: 'abc123' });
209213
});
@@ -225,6 +229,7 @@ test('buildReplayDivergenceResume with repairHint record-and-heal still rejects
225229
actions,
226230
planDigest: 'abc123',
227231
repairHint: 'record-and-heal',
232+
sessionExists: true,
228233
});
229234
assert.equal(resume.allowed, false);
230235
assert.equal(resume.from, 3);
@@ -251,6 +256,7 @@ test('buildReplayDivergenceResume: caution mid-plan (skip-safe diverged step) ca
251256
actions,
252257
planDigest: 'abc123',
253258
repairHint: 'caution',
259+
sessionExists: true,
254260
});
255261
assert.equal(resume.allowed, true);
256262
assert.equal(resume.from, 2); // unshifted
@@ -265,6 +271,7 @@ test('buildReplayDivergenceResume: manual last-step (skip-safe diverged step) ca
265271
actions,
266272
planDigest: 'abc123',
267273
repairHint: 'manual',
274+
sessionExists: true,
268275
});
269276
assert.equal(resume.allowed, true);
270277
assert.equal(resume.from, 2);
@@ -286,6 +293,7 @@ test('buildReplayDivergenceResume: caution whose diverged step is a runScript ca
286293
actions: midPlan,
287294
planDigest: 'abc123',
288295
repairHint: 'caution',
296+
sessionExists: true,
289297
});
290298
assert.equal(midPlanResume.allowed, true); // resuming AT 2 is fine
291299
assert.equal(midPlanResume.from, 2);
@@ -301,6 +309,7 @@ test('buildReplayDivergenceResume: caution whose diverged step is a runScript ca
301309
actions: lastStep,
302310
planDigest: 'abc123',
303311
repairHint: 'caution',
312+
sessionExists: true,
304313
});
305314
assert.equal(lastStepResume.allowed, true);
306315
assert.equal(lastStepResume.from, 2);
@@ -329,6 +338,7 @@ test('buildReplayDivergenceResume: manual whose diverged step is inside runtime
329338
actions: midPlan,
330339
planDigest: 'abc123',
331340
repairHint: 'manual',
341+
sessionExists: true,
332342
});
333343
assert.equal('alternateFrom' in midPlanResume, false);
334344

@@ -338,6 +348,7 @@ test('buildReplayDivergenceResume: manual whose diverged step is inside runtime
338348
actions: lastStep,
339349
planDigest: 'abc123',
340350
repairHint: 'manual',
351+
sessionExists: true,
341352
});
342353
assert.equal('alternateFrom' in lastStepResume, false);
343354
});
@@ -354,13 +365,64 @@ test('buildReplayDivergenceResume: record-and-heal and state-repair never carry
354365
actions,
355366
planDigest: 'abc123',
356367
repairHint,
368+
sessionExists: true,
357369
});
358370
assert.equal(resume.allowed, true);
359371
if (!resume.allowed) return;
360372
assert.equal(resume.alternateFrom, undefined, `expected no alternateFrom for ${repairHint}`);
361373
}
362374
});
363375

376+
// --- #1262 (re-review): the EMPTY-TAIL alternate (`failedIndex + 1 >
377+
// actions.length`) is authorizable only via the `pendingRecordAndHeal`
378+
// watermark, which can only be stamped on a LIVE session. With NO session — a
379+
// one-step `open` failure, or a session closed mid-replay — advertising
380+
// `--from actions.length + 1` would be rejected as out of range, so it must
381+
// not be emitted. A MID-PLAN alternate (in range) needs no watermark and stays
382+
// session-independent. ---
383+
384+
test('buildReplayDivergenceResume: LAST-step caution/manual with NO session carries NO alternateFrom (empty-tail needs a watermark, which needs a session)', () => {
385+
const actions: SessionAction[] = [action({ command: 'open' }), action({ command: 'click' })];
386+
for (const repairHint of ['caution', 'manual'] as const) {
387+
const resume = buildReplayDivergenceResume({
388+
failedIndex: 2, // last step → alternate would be the one-past-end ordinal 3
389+
actions,
390+
planDigest: 'abc123',
391+
repairHint,
392+
sessionExists: false,
393+
});
394+
assert.equal(resume.allowed, true); // resuming AT the failed step (2) is still fine
395+
if (!resume.allowed) return;
396+
assert.equal(
397+
resume.alternateFrom,
398+
undefined,
399+
`expected no empty-tail alternateFrom without a session for ${repairHint}`,
400+
);
401+
}
402+
});
403+
404+
test('buildReplayDivergenceResume: MID-PLAN caution/manual with NO session STILL carries alternateFrom (in-range, no watermark needed)', () => {
405+
// 3-step plan; failedIndex 2 → alternate 3 is IN RANGE (<= actions.length),
406+
// so it needs no watermark and is emitted regardless of session existence.
407+
const actions: SessionAction[] = [
408+
action({ command: 'open' }),
409+
action({ command: 'click' }),
410+
action({ command: 'click' }),
411+
];
412+
for (const repairHint of ['caution', 'manual'] as const) {
413+
const resume = buildReplayDivergenceResume({
414+
failedIndex: 2,
415+
actions,
416+
planDigest: 'abc123',
417+
repairHint,
418+
sessionExists: false,
419+
});
420+
assert.equal(resume.allowed, true);
421+
if (!resume.allowed) return;
422+
assert.equal(resume.alternateFrom, 3, `expected mid-plan alternateFrom for ${repairHint}`);
423+
}
424+
});
425+
364426
// --- stampPendingRecordAndHealWatermark (#1262): the watermark is now ALSO
365427
// stamped for `caution`/`manual`, but ONLY for the LAST-step empty-tail
366428
// alternate (`failedIndex === actions.length`, targeting `failedIndex + 1`).
@@ -388,6 +450,7 @@ test('stampPendingRecordAndHealWatermark stamps record-and-heal at its own (alre
388450
actions: midPlanActions,
389451
planDigest: 'abc123',
390452
repairHint: 'record-and-heal',
453+
sessionExists: true,
391454
});
392455
const midPlanSession = sessionWithActions(1);
393456
stampPendingRecordAndHealWatermark({
@@ -412,6 +475,7 @@ test('stampPendingRecordAndHealWatermark stamps record-and-heal at its own (alre
412475
actions: lastStepActions,
413476
planDigest: 'abc123',
414477
repairHint: 'record-and-heal',
478+
sessionExists: true,
415479
});
416480
const lastStepSession = sessionWithActions(1);
417481
stampPendingRecordAndHealWatermark({
@@ -434,6 +498,7 @@ test('stampPendingRecordAndHealWatermark stamps caution at the LAST-step empty-t
434498
actions,
435499
planDigest: 'abc123',
436500
repairHint: 'caution',
501+
sessionExists: true,
437502
});
438503
assert.equal(resume.from, 2); // unshifted — item 1 of #1262's resolution
439504
const session = sessionWithActions(1);
@@ -459,6 +524,7 @@ test('stampPendingRecordAndHealWatermark stamps manual the same way as caution a
459524
actions,
460525
planDigest: 'abc123',
461526
repairHint: 'manual',
527+
sessionExists: true,
462528
});
463529
const session = sessionWithActions(1);
464530
stampPendingRecordAndHealWatermark({
@@ -487,6 +553,7 @@ test('stampPendingRecordAndHealWatermark does NOT stamp for a MID-PLAN caution/m
487553
actions,
488554
planDigest: 'abc123',
489555
repairHint,
556+
sessionExists: true,
490557
});
491558
const session = sessionWithActions(1);
492559
stampPendingRecordAndHealWatermark({ session, resume, repairHint, failedIndex: 2, actions });
@@ -513,6 +580,7 @@ test('stampPendingRecordAndHealWatermark does not stamp for a LAST-step caution/
513580
actions,
514581
planDigest: 'abc123',
515582
repairHint: 'caution',
583+
sessionExists: true,
516584
});
517585
const session = sessionWithActions(2);
518586
stampPendingRecordAndHealWatermark({
@@ -532,6 +600,7 @@ test('stampPendingRecordAndHealWatermark never stamps for state-repair (not in t
532600
actions,
533601
planDigest: 'abc123',
534602
repairHint: 'state-repair',
603+
sessionExists: true,
535604
});
536605
const session = sessionWithActions(1);
537606
stampPendingRecordAndHealWatermark({
@@ -553,6 +622,7 @@ test('stampPendingRecordAndHealWatermark clears a stale watermark from an earlie
553622
actions,
554623
planDigest: 'abc123',
555624
repairHint: 'state-repair',
625+
sessionExists: true,
556626
});
557627
stampPendingRecordAndHealWatermark({
558628
session,

‎src/daemon/handlers/__tests__/session-replay-runtime-failure.test.ts‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { SessionStore } from '../../session-store.ts';
1212
import type { DaemonResponse } from '../../types.ts';
1313
import { dispatchCommand } from '../../../core/dispatch.ts';
1414
import { makeIosSession } from '../../../__tests__/test-utils/session-factories.ts';
15+
import { formatReplayDivergenceReport } from '../../../replay/divergence.ts';
1516
import {
1617
baseReplayRequest as baseReq,
1718
writeReplayFile,
@@ -102,6 +103,52 @@ test('a failing replay step returns REPLAY_DIVERGENCE with cause preserved and c
102103
expect(resume.planDigest).toMatch(/^[0-9a-f]{64}$/);
103104
});
104105

106+
test('#1262: a LAST-step failure with NO active session carries NO empty-tail alternateFrom and never advertises --from length+1 in text', async () => {
107+
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-no-session-tail-'));
108+
const sessionStore = new SessionStore(path.join(root, 'sessions'));
109+
const sessionName = 'default';
110+
// NO session is pre-seeded — a single-step plan whose only (LAST) step fails
111+
// before any session exists (mirrors a one-step `open` failure, or a session
112+
// closed mid-replay). The empty-tail alternate `--from 2` would need a
113+
// `pendingRecordAndHeal` watermark, which can only be stamped on a live
114+
// session — with none, the daemon would reject `--from 2` as out of range,
115+
// so it must not be advertised.
116+
const filePath = writeReplayFile(root, ['click "Save"']);
117+
mockDispatchCommand.mockRejectedValue(new Error('no device runner available'));
118+
119+
const response = await runReplayScriptFile({
120+
req: baseReq({ positionals: [filePath] }),
121+
sessionName,
122+
logPath: path.join(root, 'daemon.log'),
123+
sessionStore,
124+
invoke: async () => ({
125+
ok: false,
126+
error: { code: 'COMMAND_FAILED', message: 'not hittable' },
127+
}),
128+
});
129+
130+
expect(response.ok).toBe(false);
131+
if (response.ok) return;
132+
expect(response.error.code).toBe('REPLAY_DIVERGENCE');
133+
const divergence = response.error.details?.divergence as {
134+
repairHint: string;
135+
resume: { allowed: boolean; from: number; alternateFrom?: number };
136+
};
137+
// No session → capture unavailable → `manual`; resuming AT the failed step
138+
// (1) is still fine, but the one-past-end alternate is withheld.
139+
expect(divergence.repairHint).toBe('manual');
140+
expect(divergence.resume.allowed).toBe(true);
141+
expect(divergence.resume.from).toBe(1);
142+
expect(divergence.resume.alternateFrom).toBeUndefined();
143+
144+
// Text side: the state-fix `--from 1` may appear, but the empty-tail
145+
// `--from 2` (which the daemon would reject) must NOT.
146+
const report = formatReplayDivergenceReport(response.error.details);
147+
expect(report).not.toBeNull();
148+
expect(report!).toMatch(/Repair hint: manual/);
149+
expect(report!).not.toMatch(/--from 2\b/);
150+
});
151+
105152
test('a normalized nested failure preserves typed recovery signals on REPLAY_DIVERGENCE', async () => {
106153
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-recovery-signals-'));
107154
const sessionStore = new SessionStore(path.join(root, 'sessions'));

‎src/daemon/handlers/session-replay-divergence.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,9 @@ export async function buildReplayFailureDivergence(params: {
124124
actions: planActions,
125125
planDigest,
126126
repairHint,
127+
// A live session is required to stamp the empty-tail watermark below, so it
128+
// gates whether the one-past-the-end `alternateFrom` may be advertised.
129+
sessionExists: session !== undefined,
127130
});
128131
if (session) {
129132
stampPendingRecordAndHealWatermark({

0 commit comments

Comments
 (0)