diff --git a/docs/rfc/implemented/testing/2026-06-22-subagent-snapshot-replay.md b/docs/rfc/implemented/testing/2026-06-22-subagent-snapshot-replay.md index 92a324104e..422c8d0301 100644 --- a/docs/rfc/implemented/testing/2026-06-22-subagent-snapshot-replay.md +++ b/docs/rfc/implemented/testing/2026-06-22-subagent-snapshot-replay.md @@ -29,6 +29,8 @@ Live session ids are freshly random every run and never equal the recorded ones, This keys by WHO calls, not by global call order — so it stays correct even if subagents ever run concurrently or in the background (a global cursor would interleave them). A call carrying no `sessionId` (a direct unit-test `stream()`) is treated as one anonymous session bound to the primary script, so the single-session path is byte-for-byte the old behavior. More distinct live sessions than recorded scripts is a fail-loud error (an unrecorded subagent appeared), never a silent mis-route. +The ordering key is the session header `createdAt`. In the current synchronous cut this is sound because sibling children are created **strictly sequentially** — the subagent tool awaits one child's result and disposes it before the parent's next tool call starts the next child — so their `createdAt` values are strictly ordered and match first-call order exactly. A same-millisecond sibling tie is therefore unreachable; the `recordedId` tiebreak only keeps such a degenerate collision deterministic, it does not recover first-call order. A future cut that runs siblings concurrently/backgrounded WOULD be able to create two children in the same millisecond, and must then thread a real first-call ordinal (the order live sessions first stream) rather than leaning on `createdAt` — flagged with `XXX(concurrent-subagents)` at the sort site. + The alternative considered and rejected was a **call-ordered merge of the parent and child logs** into one global script (sound only because in-process subagent execution is strictly nested — the parent blocks on the child). It is simpler for today's synchronous cut but bakes in the parent-blocks-on-child invariant that a future backgrounded/concurrent subagent would break; per-session keying does not. ### 3. The harness harvests every log, primary-first diff --git a/examples/acp-agent/tests/snapshot-harness.ts b/examples/acp-agent/tests/snapshot-harness.ts index 80847f08dd..8285b870bf 100644 --- a/examples/acp-agent/tests/snapshot-harness.ts +++ b/examples/acp-agent/tests/snapshot-harness.ts @@ -369,8 +369,13 @@ async function harvestSessionLogs(root: string): Promise { } } // Primary (no parentSession) first, then children by ascending createdAt. A - // scenario has exactly one top-level session; ties among children fall back to - // recorded id for a stable order. + // scenario has exactly one top-level session. In the synchronous cut sibling + // children are created strictly sequentially, so their createdAt values are + // strictly ordered; the recordedId tiebreak only keeps a degenerate + // same-millisecond collision (unreachable here) deterministic. This harvest + // order must match the replay load order in dsh-llm-replay's loadSessionScripts + // so session..jsonl maps to the same child on record and replay — replay + // re-sorts childFiles by the same key, so the two stay consistent. logs.sort((a, b) => { const ap = a.parentSession === undefined ? 0 : 1 const bp = b.parentSession === undefined ? 0 : 1 diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts index ce761e6f13..b804c8ebd9 100644 --- a/packages/support/llm-replay/src/index.ts +++ b/packages/support/llm-replay/src/index.ts @@ -266,10 +266,18 @@ export function loadSessionScripts(config: ReplayConfig): SessionScript[] { } // The primary (parent) always binds first — it issues the first model call, // because it must run a turn before it can delegate. Children follow in - // createdAt order (the order they were spawned in the synchronous nested cut), - // ties broken by recorded id for determinism. Keeping the primary at the head - // rather than sorting it among the children means a sub-millisecond - // parent/child createdAt collision can never reorder it behind a child. + // createdAt order. In the current synchronous cut sibling children are created + // STRICTLY SEQUENTIALLY — the subagent tool awaits one child's result and + // disposes it before the parent's next tool call can start the next — so their + // createdAt values are strictly ordered and match first-call order exactly. + // The recordedId tiebreak only makes a degenerate same-millisecond collision + // (unreachable in this cut) deterministic; it does NOT recover first-call + // order, so it is arbitrary if such a tie ever occurs. + // XXX(concurrent-subagents): a future cut that runs siblings concurrently or + // backgrounded could create two children in the same millisecond, where this + // createdAt+id order may diverge from first-call order. That cut must thread a + // real first-call ordinal (the order live sessions first stream) instead of + // leaning on createdAt — see the per-session-replay RFC. children.sort((a, b) => a.createdAt - b.createdAt || a.recordedId.localeCompare(b.recordedId)) return [primary, ...children] }