Merge remote-tracking branch 'origin/master' into codex/simp-prune-tools-prompt-surface

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/services.md # packages/core/agent-loop/src/loop.ts # packages/core/session/README.md # packages/core/session/tests/derived-cache.spec.ts
2026-07-14 17:30:34 +08:00
parent 6682149348 fb126e164a
commit 32ed403500
562 changed files with 4438 additions and 12565 deletions
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -37,9 +37,9 @@ defineAcpSnapshotSuite({

 A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode scenarios are the template. Each pinning directory's generated `system-prompt.golden.md` is the reviewable snapshot of the normalized composed prompt; `session.jsonl` stores `"system":"{{system}}"` while retaining the complete tool list.

-The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config RFC](../../../docs/rfc/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log goldens, and each pin's Markdown prompt snapshot from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).
+Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, and prompt snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).

-Constraints: `suite.ts` imports vitest, so the package is importable only inside a vitest run (the harness and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the harness speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug). Session config options are scriptable too: the `setConfigOption` step switches a knob over `session/set_config_option`, and `setConfigOptionExpectError` asserts the bridge rejects an unknown id or out-of-vocabulary value (the error frame stays in the transcript).
+`suite.ts` imports Vitest, so use this package only inside a Vitest run. The ACP-specific script queues permission answers by stable option kind and maps them to current option ids; a missing answer cancels, while an unavailable kind fails the scenario after cancelling the agent request. It can also set session config options or assert that unknown ids and values are rejected in the transcript.

 ## Model Experience

--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -1,18 +1,8 @@
 /**
- * Shared subprocess harness for ACP snapshot suites. A library module driven by
- * the suite factory in ./suite.ts (and directly by harness-level specs); each
- * example's `*.snapshot.ts` names its own agent-under-test paths.
- *
- * It boots the REAL agent bin subprocess via the cordis Loader (so the
- * export-shape bug class stays guarded — see docs/postmortem/0001), drives it
- * over real ACP JSON-RPC stdio with a deterministic input script, tees raw
- * stdout (for the golden + a purity check) into an SDK `ClientSideConnection`,
- * and — in record mode — harvests the persisted session JSONL after a graceful
- * shutdown flush. The pure normalizers in ./normalize.ts turn the captured
- * stdout frames and the session-log events into stable, snapshot-able text.
- *
- * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
- *
+ * Shared ACP snapshot subprocess harness. It boots the real agent bin through the Cordis
+ * loader, drives deterministic ACP JSON-RPC over stdio, captures protocol-pure stdout, and
+ * harvests persisted session logs after graceful shutdown. Normalization stays in
+ * `normalize.ts`; suite registration stays in `suite.ts`.
 * @module @deepseek-ai/dsh-acp-snapshot/harness
 */

@@ -66,16 +56,10 @@ export interface AgentUnderTest {
 }

 /**
- * One step of a scenario's deterministic input script (`input.json`). The
- * harness interprets these in order. `newSession` captures the server-issued
- * (random) session id into a `{{sessionId}}` variable that later steps
- * reference, since a committed file cannot know the id in advance.
- *
- * `promptAndCancel` sends a prompt WITHOUT awaiting its response, waits until
- * the client observes the first streamed `agent_message_chunk` (so the emitted
- * frames deterministically precede the cancellation), then cancels the turn —
- * the only way to exercise a cancel deterministically (a plain `prompt` step
- * awaits the response, which a cancel/hang scenario would block on forever).
+ * One step of a scenario's deterministic input script (`input.json`). The harness interprets
+ * these in order. `newSession` captures the server-issued (random) session id into a
+ * `{{sessionId}}` variable that later steps reference. `promptAndCancel` sends without awaiting,
+ * waits for the first streamed message, then cancels, making transcript order deterministic.
 */
 export type InputStep =
  | { op: 'initialize'; terminalOutput?: boolean }
@@ -92,16 +76,9 @@ export type InputStep =
 export interface InputScript {
  steps: InputStep[]
  /**
-   * Ordered answers for the agent's `session/request_permission` round-trips,
-   * consumed FIFO — the Nth request gets the Nth answer. Each answer selects
-   * by option KIND: option ids are agent-issued randoms a committed script
-   * cannot know, while kinds are the ACP-stable vocabulary, so the client maps
-   * kind → the offered `optionId` at answer time. A request beyond the queue
-   * (or with no queue at all) is answered `cancelled` — the stub behavior a
-   * scenario without approvals relies on. A scripted kind the request does
-   * not offer REJECTS the run: the scenario scripted an impossible click,
-   * and {@link runScenario} throws once the in-flight step settles (the
-   * agent itself just sees `cancelled`, so it cannot absorb the bug).
+   * FIFO permission answers selected by stable option kind; the harness maps each kind to the
+   * agent-issued option id. Exhaustion cancels, while a kind the agent did not offer fails the
+   * scenario.
   */
  permissionAnswers?: PermissionAnswer[]
 }
@@ -201,8 +178,6 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
  const stderrChunks: string[] = []
  try {
    // Seed the workspace if the scenario ships one (a file the agent reads/edits).
-    // Copied into the temp cwd so the agent's bash tools see it; the goldens
-    // normalize the cwd, so the seeded paths stay stable across runs.
    if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) {
      await cp(opts.workspaceDir, cwd, { recursive: true })
    }
@@ -229,10 +204,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
    child.stderr.setEncoding('utf8')
    child.stderr.on('data', (c: string) => stderrChunks.push(c))

-    // Tee raw stdout: accumulate the bytes for the golden + purity check, and ALSO
-    // feed the same bytes to the SDK client through a passthrough. Buffer the raw
-    // bytes (not per-chunk utf8 strings) and decode once at the end, so a
-    // multibyte sequence split across two 'data' events can't corrupt the golden.
+    // Tee the same raw bytes to the golden and SDK client. Decode once at the end so a UTF-8
+    // sequence split across stream chunks cannot corrupt the transcript.
    const passthrough = new Readable({ read() {} })
    child.stdout.on('data', (buf: Buffer) => {
      rawBuffers.push(buf)
@@ -255,13 +228,8 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
    // Permission answers are consumed FIFO across the whole run; exhaustion
    // falls back to `cancelled` so approval-free scenarios keep the plain stub.
    const permissionQueue = [...input.permissionAnswers ?? []]
-    // A scenario bug detected inside a client callback (a scripted permission
-    // kind the agent never offered). It cannot fail the run from in there: a
-    // callback throw only becomes a JSON-RPC error RESPONSE to the agent, and
-    // a tolerant agent treats that as a denial and carries on — the run (or
-    // worse, a record) would absorb the impossible click silently. So the
-    // callback answers `cancelled` (a well-defined path for the agent),
-    // captures the error here, and the step loop fails the run on it.
+    // A callback throw would become only an RPC error the agent could absorb. Record an
+    // impossible permission choice here, answer cancelled, and fail the outer scenario.
    let scriptError: Error | undefined
    const makeClient = (_agent: AcpAgent): Client => ({
      sessionUpdate(params: SessionNotification): Promise<void> {
@@ -356,10 +324,8 @@ async function runStep(
      return
    }
    case 'newSessionExpectError': {
-      // The bridge rejects a session/new that widens the workspace scope
-      // (non-empty additionalDirectories / mcpServers — unimplemented). The SDK
-      // surfaces that as a rejected RPC; swallow it so the run completes and the
-      // error frame is captured in the transcript.
+      // The bridge rejects a session/new that widens the workspace scope (non-empty
+      // additionalDirectories / mcpServers — unimplemented).
      await client.newSession({
        cwd,
        mcpServers: [],
@@ -379,10 +345,8 @@ async function runStep(
    case 'promptExpectError': {
      const sessionId = getSessionId()
      if (sessionId === undefined) throw new Error('snapshot-harness: promptExpectError before newSession')
-      // The model fails this turn (a recorded provider error), so the bridge
-      // answers the prompt with a JSON-RPC error and the SDK rejects. That
-      // rejection IS the expected editor experience — swallow it so the run
-      // completes and the stdout transcript (the error frame) is captured.
+      // The model fails this turn (a recorded provider error), so the bridge answers the prompt
+      // with a JSON-RPC error and the SDK rejects.
      await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
        .then(() => { throw new Error('snapshot-harness: expected the prompt to fail but it succeeded') },
          () => { /* expected: the turn failed and the bridge returned an error */ })
@@ -391,13 +355,8 @@ async function runStep(
    case 'promptAndCancel': {
      const sessionId = getSessionId()
      if (sessionId === undefined) throw new Error('snapshot-harness: promptAndCancel before newSession')
-      // Dispatch the prompt WITHOUT awaiting (a hang fixture never resolves on
-      // its own). To pin frame order deterministically, wait until the client
-      // has OBSERVED the hang's streamed agent_message_chunk before cancelling —
-      // so those update frames always precede the cancelled prompt response in
-      // the transcript (without this, the late chunk and the response race).
-      // Then cancel and await the prompt, which the bridge settles as
-      // `cancelled` once the abort propagates.
+      // A hang fixture never resolves alone. Wait for its streamed chunk before cancellation
+      // so updates deterministically precede the cancelled prompt response.
      const promptDone = client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
      await waitForUpdate(u => u.sessionUpdate === 'agent_message_chunk')
      await client.cancel({ sessionId })
@@ -483,14 +442,8 @@ async function harvestSessionLogs(root: string): Promise<HarvestedLog[]> {
      })
    }
  }
-  // Primary (no parentSession) first, then children by ascending createdAt. A
-  // 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.<n>.jsonl maps to the same child on record and replay — replay
-  // re-sorts childFiles by the same key, so the two stay consistent.
+  // Match replay fixture assignment: primary first, then children by creation time, with id as
+  // a deterministic collision tiebreaker.
  logs.sort((a, b) => {
    const ap = a.parentSession === undefined ? 0 : 1
    const bp = b.parentSession === undefined ? 0 : 1
--- a/packages/support/acp-snapshot/src/index.ts
+++ b/packages/support/acp-snapshot/src/index.ts
@@ -1,17 +1,7 @@
 /**
- * ACP snapshot suite kit — the shared machinery behind the keyless snapshot
- * tier (`pnpm run test:snapshot`). Three layers, composable per example:
- * the subprocess scenario harness ({@link runScenario}), the pure golden
- * normalizers ({@link normalizeStdout} / {@link normalizeSessionLog} /
- * {@link scrubRequestHeaders} / {@link scrubSystemPrompts}), and the suite factory
- * ({@link defineAcpSnapshotSuite}) that registers a scenario table as a full
- * describe/it tree. An example's `*.snapshot.ts` supplies only its
- * {@link AgentUnderTest} paths, its snapshots directory, and its
- * {@link Scenario} table.
- *
- * NOTE: ./suite.ts imports vitest, so this package is importable only inside a
- * vitest run — a support-tier constraint stated in the README.
- *
+ * ACP snapshot suite kit: subprocess scenario harness, pure golden normalizers, and the Vitest
+ * suite factory behind `pnpm run test:snapshot`. Because this entry exports `suite.ts`, importing
+ * it requires a Vitest run.
 * @module @deepseek-ai/dsh-acp-snapshot
 */

--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -1,29 +1,8 @@
 /**
- * Pure normalizers for the ACP snapshot goldens. They replace the
- * non-deterministic values in the two captured surfaces — the stdout JSON-RPC
- * transcript and the persisted session JSONL — with stable tokens, so a golden
- * compare reflects behavior, not run-to-run noise. Kept dependency-free and
- * side-effect-free so they unit-test trivially.
- *
- * Scrubbed: `randomUUID()` session ids → `{{sessionId}}`; the temp `mkdtemp`
- * cwd → `{{cwd}}` (it appears in terminal-card `_meta` and the log header);
- * JSON-RPC request `id` → a stable per-transcript sequence; the log's per-event
- * `time` (epoch ms) and header `createdAt` → 0; a `hook/result` event's
- * `durationMs` (wall-clock hook runtime) → 0. NOT scrubbed: the log's `seq`
- * (deterministic — `seq = log.length`, part of the event-log contract).
- *
- * Separate, composable normalizers keep bulky request-header content out of
- * session fixtures. {@link scrubSystemPrompts} replaces the composed system
- * prompt in EVERY fixture; {@link scrubRequestHeaders} additionally replaces
- * tool schemas and the session prefix outside each suite's header-pinning
- * scenario. They are deliberately NOT folded into
- * {@link normalizeSessionLog}: the suite factory composes the right scrub for
- * each scenario and snapshots the pin's actual prompt as Markdown (see the
- * pinned-header RFC,
- * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
- *
- * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
- *
+ * Pure ACP transcript and session-log normalizers. They scrub session ids, temp cwd, RPC ids,
+ * timestamps, and hook duration while preserving deterministic event sequence numbers.
+ * Request-header scrubbers stay separate so one scenario per header class can pin tools and a
+ * readable prompt while other fixtures omit duplicated header bulk.
 * @module @deepseek-ai/dsh-acp-snapshot/normalize
 */

@@ -68,12 +47,10 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
 }

 /**
- * Normalize a raw stdout transcript (newline-delimited JSON-RPC frames) into a
- * stable golden in the SAME shape as the wire: one compact JSON frame per line
- * (NDJSON), with the JSON-RPC `id` rewritten to a per-transcript sequence
- * (1, 2, 3, …) and all volatile strings scrubbed. Throws if any non-empty line
- * is not valid JSON — that doubles as the stdout-purity check (no logger leaked
- * onto the protocol).
+ * Normalize a raw stdout transcript (newline-delimited JSON-RPC frames) into a stable golden
+ * in the same shape as the wire: one compact JSON frame per line (NDJSON), with the JSON-RPC
+ * `id` rewritten to a per-transcript sequence (1, 2, 3, …) and all volatile strings scrubbed.
+ * Invalid JSON throws, doubling as a protocol-stdout purity check.
 *
 * @param rawStdout The captured stdout bytes, decoded utf8.
 * @param ctx The run's volatile values to scrub.
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -1,33 +1,12 @@
 /**
- * The ACP snapshot suite factory (REPLAY by default, keyless). A suite is a
- * scenario table plus a snapshots directory: each scenario under
- * `<snapshotsDir>/<name>/` ships an `input.json` (the client stdin script) and
- * a `session.jsonl` fixture; replay boots the real agent subprocess
- * (./harness.ts), drives it, and diffs the normalized stdout transcript
- * against the committed `stdout.golden.jsonl`. For model scenarios it ALSO
- * checks the re-persisted session log — against the `session.jsonl` fixture
- * itself, not a separate golden: the fixture doubles as the replay source
- * (recorded scenarios) and the expected produced log (both sides normalized
- * before comparing).
- *
- * Request-header content is pinned by exactly ONE scenario per HEADER CLASS —
- * scenarios that boot the same config compose the same header. Every JSONL
- * fixture scrubs the system prompt to `{{system}}`; each class's pinning
- * scenario stores the readable prompt in `system-prompt.golden.md` and keeps its full
- * tool schemas in `session.jsonl`, while every other fixture also scrubs tools
- * to `{{tools}}`. A per-run uniformity guard compares both artifacts against
- * every live header and forbids unrepresented header deltas (see the
- * pinned-header RFC,
- * docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md).
- *
- * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the
- * `session.jsonl` fixtures against the real API and refreshes the stdout golden
- * in one pass. `pnpm run test:snapshot:refresh` (DSH_SNAPSHOT=refresh) instead
- * replays the committed model scripts keylessly and writes the current stdout
- * + persisted-log goldens back without calling a live LLM. The caller resolves
- * that env into {@link SnapshotSuiteOptions} (env reading stays at the suite
- * edge, not in this library).
+ * Keyless-by-default ACP snapshot suite factory. Each scenario drives the real subprocess and
+ * compares normalized stdout; comparable session fixtures are both replay input and expected
+ * output. Record mode refreshes reproducible model scenarios from the live API, while refresh
+ * mode replays committed scripts and rewrites derived artifacts without a key.
 *
+ * Exactly one scenario per header-composition class pins tool schemas in JSONL and the system
+ * prompt in Markdown. Every live header is checked against that pin, so session-dependent
+ * composition must declare a separate class instead of escaping coverage.
 * @module @deepseek-ai/dsh-acp-snapshot/suite
 */

@@ -89,20 +68,8 @@ export interface Scenario {
   */
  childSessions?: number
  /**
-   * Whether THIS scenario pins its header class's model-facing request-header
-   * content. Its actual composed prompt is maintained as a readable
-   * `system-prompt.golden.md`; its JSONL keeps full tool schemas but stores the prompt
-   * as `{{system}}`. Every other scenario of the class stores tools as
-   * `{{tools}}` too ({@link scrubRequestHeaders}). A prompt or tool-schema
-   * change therefore shows up in one focused artifact per class, not every
-   * session fixture. One pin per class suffices because
-   * header composition is class-uniform (parent, spawn child, and fork child
-   * all compose the same prompt-modulo-cwd and the same tools) — and that
-   * premise is ASSERTED, not assumed: every non-pinning run's live headers
-   * must equal its class's pinned fixture's (normalized), so a
-   * session-dependent header (say, a restricted subagent toolset) fails loud
-   * until it gets its own pinning scenario.
-   * Defaults to false.
+   * Whether this scenario is its header class's sole request-header pin. Its Markdown file owns
+   * the prompt, its JSONL keeps tool schemas, and every classmate is checked for equality.
   */
  pinsHeader?: boolean
  /**
@@ -164,17 +131,9 @@ export function childFixturePaths(dir: string, childSessions: number): string[]
 }

 /**
- * Derive the {@link NormalizeContext} for a `session.jsonl` fixture from its own
- * header line (`{ type: 'session', id, cwd }`). A committed fixture carries the
- * session id and cwd of the run that harvested it — different from the live
- * replay run — so normalizing it against the live run's ctx would leave those
- * recorded values unscrubbed. Reading them from the header scrubs the fixture's
- * own id/cwd to the same `{{sessionId}}`/`{{cwd}}` tokens the replay output gets.
- * An authored fixture whose header is already normalized (`id:'{{sessionId}}'`,
- * `cwd:'{{cwd}}'`) yields those tokens as the volatile values, so scrubbing them
- * is an idempotent no-op. A header with no `cwd` falls back to a sentinel that
- * cannot occur in a log (NOT `''`, which `String.split` would match on every
- * character boundary and corrupt the output).
+ * Derive normalization values from a fixture's own session header. Recorded ids and cwd differ
+ * from the live replay run; the non-empty sentinel for missing cwd avoids accidental empty-
+ * string replacement.
 *
 * @param fixture The committed `session.jsonl` content.
 * @returns The fixture's own volatile values, ready for {@link normalizeSessionLog}.
@@ -419,10 +378,8 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {

  for (const scenario of scenarios) {
    describe(`snapshot: ${scenario.name}`, () => {
-      // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the
-      // `authored` ones (sidecar-driven errors/cancel) are never re-recorded.
-      // REFRESH mode is replay-backed and deterministic, so it runs every
-      // scenario and rewrites the comparable fixtures from that replay run.
+      // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the `authored` ones
+      // (sidecar-driven errors/cancel) are never re-recorded.
      it.skipIf(RECORDING && !scenario.recorded)('matches the goldens', async () => {
        const dir = join(snapshotsDir, scenario.name)
        const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
@@ -444,10 +401,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          ...scenario.configPath !== undefined ? { configPath: scenario.configPath } : {},
        })

-        // Scrub every volatile id the run produced: the ACP server-issued session
-        // id plus every harvested log's recorded id (a subagent child id never
-        // surfaces over ACP, but it appears in the child's own log header). The
-        // normalizer's UUID catch-all covers any we don't enumerate.
+        // Scrub every volatile id the run produced: the ACP server-issued session id plus every
+        // harvested log's recorded id (a subagent child id never surfaces over ACP, but it
+        // appears in the child's own log header).
        const ctx: NormalizeContext = {
          sessionIds: [
            ...result.sessionId !== undefined ? [result.sessionId] : [],
@@ -456,15 +412,8 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          cwd: result.cwd,
        }

-        // RECORD mode (recorded model scenarios only): persist the freshly-harvested
-        // live logs back to their fixtures. REFRESH mode does the same from a
-        // keyless replay run for every comparable log, including authored
-        // scenarios that live record deliberately skips. The primary goes to
-        // session.jsonl, each child to session.<n>.jsonl in harvest order. A
-        // Every fixture is written with its system prompt scrubbed. A pinning
-        // scenario keeps the remaining header content (notably tool schemas);
-        // every other scenario scrubs that bulk too. Record/refresh therefore
-        // cannot smuggle prompt text back into JSONL or duplicate schemas.
+        // Record writes live model fixtures; keyless refresh writes every comparable replayed
+        // fixture. Pins keep tools but all JSONL files scrub prompt text.
        const scrub = scenario.pinsHeader === true
          ? scrubSystemPrompts
          : scrubRequestHeaders
@@ -515,14 +464,7 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
        // A model turn always produces a log worth comparing; a hook scenario can
        // produce one without a model turn (a `rejected` turn carrying `hook/*`).
        if (comparesLog) {
-          // The harvested logs (primary-first) must match their committed fixtures
-          // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS
-          // OWN volatile values — the live run's via `ctx`, the committed fixture's
-          // via its own header (a committed file cannot share the live run's ids).
-          // Both sides pass through the scenario's idempotent scrub: every live
-          // prompt becomes the fixture's `{{system}}`; non-pinning scenarios
-          // additionally tokenize tools/prefix. The dedicated header guard below
-          // compares those omitted values against their class's pin artifacts.
+          // The harvested logs (primary-first) must match their committed fixtures 1:1.
          expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1)
          for (let i = 0; i < fixtureFiles.length; i++) {
            const harvested = scrub((result.sessionLogs[i] as HarvestedLog).content)
@@ -532,11 +474,8 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          }
        }

-        // Header-uniformity guard: every live header in a class must equal the
-        // class pin split across its JSONL header (system token + real tools)
-        // and readable Markdown prompt. A pinning scenario may carry its
-        // declared header deltas; their prompt edits live in the Markdown
-        // golden while JSONL retains the tokenized edit structure.
+        // Header-uniformity guard: every live header in a class must equal the class pin split
+        // across its JSONL header (system token + real tools) and readable Markdown prompt.
        /* v8 ignore next -- construction guarantees the pin exists; a miss would fail the one-header assertion loudly. */
        const pinningScenario = pinningByClass.get(classOf(scenario)) ?? scenario
        const pinningDir = join(snapshotsDir, pinningScenario.name)
@@ -586,18 +525,7 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
    })

    it('every registered scenario has its required fixture files', () => {
-      // Every scenario has an input script and an stdout golden. EVERY scenario
-      // also needs `session.jsonl`: the suite boots `llm-replay` with that path
-      // as the replay source for ALL scenarios (the factory passes
-      // `fixtureFile: <dir>/session.jsonl` unconditionally), and `loadReplayScript`
-      // throws "fixture not found" when it is absent and no override replaces it.
-      // A no-model scenario ships a header-only `session.jsonl` (it derives to an
-      // empty script — no model call is made); a model scenario's fixture also
-      // doubles as the expected-log artifact the run is diffed against. The
-      // `replay.override.json` sidecar is matched BOTH ways against the table's
-      // `overridden` flag: required when set, forbidden when not — the harness
-      // forwards the file purely on existence, so an unregistered stray sidecar
-      // would silently replace the derived script.
+      // Every scenario has an input script and an stdout golden.
      for (const { name, overridden, childSessions, pinsHeader } of scenarios) {
        const dir = join(snapshotsDir, name)
        expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
@@ -616,10 +544,8 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
    })

    it('exactly one scenario pins the request-header content of each header class', () => {
-      // Zero pins would drop a class's prompt/schema surface from the suite
-      // entirely; two would split it. One pin per class is the design
-      // (pinned-header RFC); WHICH scenario pins is the scenario table's
-      // reviewable choice.
+      // Zero pins would drop a class's prompt/schema surface from the suite entirely; two would
+      // split it.
      const pins = new Map<string, string[]>()
      for (const scenario of scenarios.filter(s => s.pinsHeader === true)) {
        const cls = classOf(scenario)
@@ -633,12 +559,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
    })

    it('every pinning fixture carries one request/header, one readable prompt, and its declared deltas', async () => {
-      // The live uniformity guard runs only in NON-pinning scenarios, so a
-      // class made of just its pinning scenario would otherwise accept a
-      // re-recorded pin with several headers or an undeclared mid-run
-      // header-delta — shapes the pin design cannot represent. Assert the
-      // committed pins directly; a scenario whose arc legitimately rewrites
-      // a prompt section declares the exact count via expectedHeaderDeltas.
+      // The live uniformity guard runs only in NON-pinning scenarios, so a class made of just
+      // its pinning scenario would otherwise accept a re-recorded pin with several headers or
+      // an undeclared mid-run header-delta — shapes the pin design cannot represent.
      for (const scenario of pinningByClass.values()) {
        const fixture = await readFile(join(snapshotsDir, scenario.name, 'session.jsonl'), 'utf8')
        const headers = normalizedHeaders(fixture, fixtureContext(fixture))
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -1,19 +1,7 @@
 /**
- * Scripted fake ACP agent bin for `dsh-acp-snapshot`'s unit specs. Speaks
- * newline-delimited JSON-RPC on stdio like the real `dsh-acp-agent` bin, but
- * every behavior — how prompts settle, whether session/new rejects, which
- * session logs get persisted, what filesystem noise to leave — comes from a
- * `behavior.json` sitting NEXT to the `$DSH_SNAPSHOT_FILE` fixture, so a spec
- * scripts a whole subprocess run from data. The specs launch it through the
- * REAL `runScenario` spawn path (tsx loader, temp cwd, env plumbing), so the
- * harness plumbing is exercised for real; only the agent behind the protocol
- * is scripted.
- *
- * The specs (not the golden tier) own this bin: it asserts nothing, echoes
- * observable facts into `session/update` text chunks (env probe, permission
- * outcome, seeded-workspace listing) for the spec to read off `rawStdout`, and
- * exits 0 on stdin EOF after writing the scripted logs — mirroring the real
- * bin's dispose-flush-exit shape.
+ * Scripted ACP agent for snapshot-kit tests. A fixture-adjacent `behavior.json` controls the
+ * subprocess reached through the real harness path; the bin reports observations over ACP and
+ * writes scripted logs before exiting on stdin EOF.
 */

 import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -308,11 +308,8 @@ describe('runScenario', () => {

  it('rejects the run on a scripted permission kind the agent never offered', { timeout: 20_000 }, async () => {
    const { fixtureFile } = await scenario({ permissionProbe: true })
-    // The fake bin offers allow_once/reject_once; scripting allow_always is a
-    // scenario bug. The agent is answered `cancelled` (it must not be able to
-    // absorb the bug as an error-means-denial), and the RUN fails: a callback
-    // throw would only reach the agent as a JSON-RPC error response, letting
-    // a tolerant agent carry on and the scenario pass — or record.
+    // The fake offers only allow_once/reject_once. The harness must reject an impossible click,
+    // not merely send an RPC error that a tolerant agent could absorb.
    await expect(runScenario(
      { steps: [...boot, { op: 'prompt', text: 'impossible click' }], permissionAnswers: [{ kind: 'allow_always' }] },
      { agent: AGENT, mode: 'replay', fixtureFile },
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -18,21 +18,14 @@ import {
 } from '../src/suite.ts'

 /**
- * Unit tests for the suite factory, by running it: two synthetic suites over
- * the scripted fake ACP bin (./fixtures/fake-acp-agent.ts) register REAL
- * describe/it trees at collection time, so every factory path — golden and log
- * compares, the per-suite header pin and its uniformity guard, record-mode
- * fixture write-back, skip semantics, and the fixture guard block — executes
- * as an ordinary green test. The pure helpers get direct cases below.
+ * Unit tests for the suite factory, by running it: two synthetic suites over the scripted fake
+ * ACP bin (./fixtures/fake-acp-agent.ts) register real describe/it trees at collection time,
+ * so every factory path — golden and log compares, the per-suite header pin and its uniformity
+ * guard, record-mode fixture write-back, skip semantics, and the fixture guard block —
+ * executes as an ordinary green test.
 *
- * The replay suite runs against the committed fixtures in ./fixtures/suite.
- * The record suite runs against a TEMP COPY of ./fixtures/record-suite
- * (record mode writes session fixtures back into its snapshots dir; a run must
- * never touch the committed tree). To re-bootstrap the record tree's goldens
- * after changing the fake bin's output, run this spec once with
- * `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1` (points the record suite at the committed
- * tree so vitest creates/updates the goldens and the write-back lands there),
- * then commit the result.
+ * Record tests use a temp copy. To intentionally rebuild their committed fixtures, run this
+ * spec once with `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1`, then review and commit the resulting tree.
 */

 const AGENT = {
@@ -44,12 +37,7 @@ const AGENT = {
 const REPLAY_DIR = fileURLToPath(new URL('./fixtures/suite', import.meta.url))
 const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta.url))

-// The replay suite doubles as the header-CLASS coverage: every scenario names
-// the same explicit class (the record suite exercises the 'default' fallback),
-// and plain-turn boots through a per-scenario configPath override (the same
-// dummy path the agent default carries — the plumbing, not the composition,
-// is what this suite can exercise; the real overlay boot is the acp-agent
-// example's code-mode scenarios).
+// Replay pins explicit header classes; recording covers the default fallback.
 const REPLAY_SCENARIOS: Scenario[] = [
  { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderDeltas: 1, headerClass: 'main' },
  { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1, headerClass: 'main', configPath: AGENT.configPath },
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -39,7 +39,7 @@ Agent status (per agent):

 Model requests (on `llm/stream`):

- **a loop-built request is exactly what the log reconstructs** — a frozen request with a live `sessionId` (the loop-built marker; hand-built one-shots like compaction's summarize are unfrozen and skipped) must carry frozen `messages` deep-equal to the derivation over the log prefix strictly before the in-flight step's `step/start` (rebuilt through a FRESH `Session`, so the live cache cannot vouch for itself — and boundary-correct: content logged after `step/start` legitimately belongs to the next request), and every non-content field must equal the fold of the log's `request/header*` events (see [the reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). Registered with `prepend: true` so a short-circuiting `llm/stream` listener (the replay adapter) cannot silence it; prepend orders it against append-registered listeners only — correctness rests on the seq-bounded rebuild, never listener timing.
+- **a loop-built request is exactly what the log reconstructs** — a frozen request with a live `sessionId` is rebuilt through a fresh `Session` from the prefix before its in-flight `step/start`; later content belongs to the next request, and hand-built unfrozen one-shots are excluded. Frozen messages must match that derivation, while every other field matches folded `request/header*` events. The prepended check runs before ordinary short-circuiting stream listeners, but correctness comes from the sequence boundary rather than listener timing. See the [reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).

 On any violation it throws `InvariantError` (`code: 'INVARIANT'`).

--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -1,21 +1,9 @@
 /**
- * Runtime invariants: a pure-listener plugin that asserts relationships in
- * the harness event contract. It is intended for development diagnostics but
- * has no environment guard, so it is active in every composition that mounts
- * it (including the default `dsh-agent-core` bundle).
- *
- * Everything is a plugin — this is just listeners on `session/created`,
- * `session/event`, `agent/status`, and the scoped dispatch and request seams.
- * Custom compositions can omit it when the runtime assertion cost is
- * undesirable. When mounted, a contract violation is a loud failure rather
- * than a subtle one. It doubles as executable documentation of the event
- * taxonomy: the assertions below are the contract.
- *
- * Session owns immutable log storage: it snapshots and deep-freezes every
- * accepted event at the source. This plugin checks relationships that one
- * event's types and immutability cannot express, including turn/step nesting,
- * scoped dispatch, status transitions, and request reconstructability.
- *
+ * Runtime listeners that fail loudly when cross-event contracts are broken:
+ * turn and step nesting, scoped dispatch, status transitions, and request
+ * reconstruction. The plugin has no environment guard and is active wherever
+ * mounted, including the default `dsh-agent-core` bundle; custom compositions
+ * may omit it. Sessions still own event snapshots and freezing.
 * @module @deepseek-ai/dsh-invariants
 */

@@ -330,19 +318,15 @@ function replayEvent(trace: SessionTrace, event: SessionEvent): void {
  applyTransition(trace, validateEvent(trace, event))
 }

-/** Legal agent status transitions (the only state machine the loop guarantees). */
+/** Allow an initial observation, idle/running transitions, and terminal disposal; reject repeats and leaving disposed. */
 function checkTransition(from: AgentStatus | undefined, to: AgentStatus): void {
-  // First observation: any status is a valid starting point.
  if (from === undefined) return
-  // A no-op transition is illegal — setStatus dedups, so we never see it.
  if (from === to) {
    throw new InvariantError(`agent/status repeated ${to} (no-op transition)`)
  }
-  // Leaving `disposed` is illegal — disposal is terminal.
  if (from === 'disposed') {
    throw new InvariantError(`agent/status left terminal state disposed → ${to}`)
  }
-  // idle↔running and (idle|running)→disposed are all legal; nothing else exists.
 }

 /**
--- a/packages/support/invariants/tests/invariants.spec.ts
+++ b/packages/support/invariants/tests/invariants.spec.ts
@@ -325,19 +325,17 @@ describe('HMR state rebuild', () => {
  it('rebuilds trace state for a session that exists at (re-)apply time', async () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)
-    // First registration, mid-turn: a turn is open when the plugin reloads.
    const first = await ctx.plugin(Invariants)
    const session = ctx.sessions.create()
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('step/start', { turn: 1, step: 1 })
    await first.dispose()

-    // Re-apply (HMR): the fresh fiber must replay the existing log so the open
-    // step is known — the next chunk must NOT be a false positive.
+    // Re-apply mid-step: the new fiber must reconstruct the open boundaries from the log.
    await ctx.plugin(Invariants)
    expect(() => session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } }))
      .not.toThrow()
-    // And a genuine violation is still caught after the rebuild.
+    // Rebuild must not disable later violations.
    expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
      .toThrow(/turn 1 is still open/)
  })
@@ -541,25 +539,17 @@ describe('surface invariants', () => {
  })

  it('rejects sourceEventSeqs referencing unknown seq (gap in event log)', async () => {
-    // The unknown-seq check fires when a ref passes the "earlier" test but is
-    // not in knownSeqs — only possible with a gap in seqs. We create a gap by
-    // directly manipulating the private log array to skip a seq.
+    // Create an impossible-through-public-API gap so seq 2 is earlier but unknown.
    const { ctx } = await setup()
    const session = ctx.sessions.create()
    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
    session.append('step/start', { turn: 1, step: 1 })
-    // Push a fake event at seq 3 into the internal log, creating a gap at seq 2.
-    // The invariants plugin replays session.events on every append, so it sees
-    // this gap during trace reconstruction.
    ;(session as unknown as { log: unknown[] }).log.push({
      type: 'assistant/chunk',
      seq: 3,
      time: Date.now(),
      data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'x' } },
    })
-    // Now the log has seqs 0, 1, 3 (gap at 2). Append at what session believes
-    // is seq 3 (log.length). Reference seq 2: passes earlier (2 < 3) but not
-    // in knownSeqs ({0, 1, 3} — gap at 2).
    expect(() => {
      session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [2] })
    }).toThrow(/unknown seq 2/)
@@ -803,12 +793,8 @@ describe('request-reconstruction cross-check (llm/stream)', () => {

 describe('request cross-check ordering (prepend)', () => {
  it('runs ahead of a short-circuiting llm/stream listener registered before it', async () => {
-    // The replay adapter returns its chunks WITHOUT calling next(), which
-    // would silence a later-registered check — snapshot compositions load
-    // replay before the app bundle that loads invariants. The check prepends,
-    // so it fires ahead of append-registered listeners regardless of load
-    // order. (Prepend orders it against APPENDED listeners only; correctness
-    // rests on the seq-bounded rebuild, not on listener timing.)
+    // Replay short-circuits without next(), so the check prepends ahead of ordinary listeners;
+    // correctness still comes from its sequence-bounded rebuild, not listener timing.
    const ctx = new Context()
    await ctx.plugin(SessionStore)
    ctx.on('llm/stream', () => (async function* () {})() as never) // short-circuits, no next()
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -1,50 +1,8 @@
 /**
- * Replay LLM plugin for snapshot tests.
- *
- * Installs a single `llm/stream` waterfall listener that short-circuits the
- * waterfall (never calls `next()`) and yields model streams reconstructed from
- * a recorded **session JSONL** fixture — so a snapshot test can boot the real
- * agent against a fixed model transcript with no API key. See
- * docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
- *
- * The fixture IS the persisted session log (`<scenario>/session.jsonl`): its
- * `assistant/chunk` events carry every {@link StreamChunk}, so grouping them by
- * `(turn, step)` reconstructs each `stream()` call's chunk sequence (one model
- * call per loop step — see packages/core/agent-loop/src/loop.ts). Recording is
- * therefore "run the real agent once and harvest the `.jsonl`", done by the
- * snapshot harness — this plugin does not record. A fixture may carry its
- * `request/header` content tokenized to `{{system}}`/`{{tools}}` (the harness
- * pins that content in one scenario and scrubs the rest); replay is
- * indifferent — derivation reads ONLY `assistant/chunk` events and the line-0
- * session header.
- *
- * A NESTED-agent scenario records more than one log: the parent plus one per
- * in-process subagent (each subagent runs as its own {@link Session} on the same
- * context). Replay loads them all ({@link loadSessionScripts}), derives a script
- * per recorded session, and keys each live call by its calling session id
- * (`GenerateOptions.sessionId`, stamped by the loop). Live session ids are fresh
- * random values, so a live session binds to a recorded script by FIRST-CALL
- * order (parent first — it streams before it delegates); see
- * {@link installLlmReplay}.
- *
- * Two failure modes are NOT reconstructable from `assistant/chunk` alone — a
- * pure throw before any chunk (e.g. an HTTP 401: the log holds only a
- * `turn/end {error}`, no chunks) and a cancel/hang (timing, not chunk content).
- * A scenario that needs those supplies an optional sidecar
- * (`<scenario>/replay.override.json`: a `ReplayEntry[]`) that REPLACES the
- * derived script.
- *
- * It lives in its own package (not under `examples/`) so its derive/parse/
- * replay logic falls under the per-file 100% coverage gate on package `src`
- * trees — its tests previously lived under `examples/`, which the gate does
- * not measure, leaving these branches (clean chunks / mid-stream throw / hang)
- * unguarded. Its consumer is the ACP snapshot harness in `examples/acp-agent`,
- * which loads it (via `cordis.snapshot.yml`) in place of a real LLM adapter.
- *
- * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default
- * export (the cordis Loader's `unwrapExports` does `exports.default ?? exports`,
- * so a stray default would drop the namespace — see docs/postmortem/0001).
- *
+ * Keyless snapshot-test LLM replay. It derives one model-call script per
+ * recorded session from `assistant/chunk` events and binds fresh live sessions
+ * to parent/child scripts by first-call order. Throw and hang cases require an
+ * explicit override because a session log cannot reconstruct them alone.
 * @module @deepseek-ai/dsh-llm-replay
 */

@@ -56,21 +14,9 @@ import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmError, assertNever } from '@deepseek-ai/dsh-llm'

 /**
- * One recorded model call. A discriminated union (not a bare `StreamChunk[]`)
- * so it can faithfully replay BOTH branches of the documented LLM failure
- * contract — an adapter may THROW from `stream()` or end with a `finish` error
- * chunk — plus a `hang` marker for cancellation scenarios (mirrors the
- * `MockAdapter` `hang` support in packages/core/agent-loop/tests).
- *
- * A `throw` entry carries any `chunks` the adapter emitted BEFORE it threw, so
- * a mid-stream transport failure (partial output then `STREAM_CLOSED`) replays
- * the partial chunks first and only then throws — exactly what the agent loop
- * saw live (it may already have emitted partial assistant chunks).
- *
- * The normal/finish-terminated cases are DERIVED from the session JSONL
- * ({@link deriveReplayScript}); only the throw and hang cases need a
- * hand-authored sidecar entry (a thrown stream leaves no terminal `finish` in
- * the log, so it cannot be derived as `chunks`).
+ * One recorded model call. `throw` may replay prefix chunks before failing;
+ * `hang` models cancellation. Only ordinary chunk entries derive from JSONL;
+ * the other variants come from an override sidecar.
 */
 export type ReplayEntry =
  | { kind: 'chunks'; chunks: StreamChunk[] }
@@ -102,13 +48,8 @@ export interface ReplayConfig {
 }

 /**
- * One recorded session's replay script: the per-call entries plus the header
- * facts needed to ORDER and key it. Live session ids are freshly random at
- * replay time and never equal the recorded `id`, so the recorded id is only a
- * diagnostic; `createdAt` is the load-bearing field — scripts are ordered by it
- * (a parent is created before its children) and each newly-seen live session is
- * bound to the next script in that order (= first-call order in the synchronous
- * nested cut, where the parent streams before it delegates).
+ * Recorded calls plus header facts used to order parent and child scripts.
+ * Recorded ids are diagnostic; fresh live ids bind by ordered first use.
 */
 export interface SessionScript {
  /** The recorded session id (diagnostics only — the live id differs). */
@@ -134,9 +75,7 @@ export interface SessionScript {
 export function parseSessionLog(text: string): SessionEvent[] {
  const lines = text.split('\n').filter(line => line.trim().length > 0)
  const events: SessionEvent[] = []
-  // Skip line 0 (the header). A reader distinguishes it by its `type:'session'`
-  // tag; we simply drop the first line, which the JSONL backend guarantees is
-  // the header.
+  // The JSONL backend guarantees line 0 is the session header.
  for (let i = 1; i < lines.length; i++) {
    const parsed: unknown = JSON.parse(lines[i] as string)
    events.push(parsed as SessionEvent)
@@ -145,14 +84,8 @@ export function parseSessionLog(text: string): SessionEvent[] {
 }

 /**
- * Read the identifying facts off a session log's header line (line 0): the
- * recorded session `id` (diagnostics), `createdAt` (the deterministic ordering
- * key that binds a recorded script to a live session — see
- * {@link SessionScript}), and `seedLength` (the seed boundary — how many leading
- * events were INHERITED via a fork seed rather than produced by this session's
- * own model calls; absent ⇒ 0). A header missing a field falls back to a stable
- * default (`''` / `0` / `0`) rather than throwing: a no-model fixture is
- * header-only and still orders fine as the single (primary) script.
+ * Read replay identity, ordering, and fork-seed facts from the JSONL header.
+ *
 * @param text - the raw `.jsonl` file contents (only the header line is read).
 * @returns the header's `id`, `createdAt`, and `seedLength`, defaulted when absent.
 */
@@ -169,21 +102,9 @@ export function parseSessionHeader(text: string): { id: string; createdAt: numbe
 /**
 * Reconstruct the per-`stream()` replay script from a recorded session log.
 *
- * The agent loop makes exactly one `ctx.llm.stream()` call per step and appends
- * every chunk as an `assistant/chunk` event tagged with the current
- * `(turn, step)`. Grouping those events by `(turn, step)` in log order
- * therefore yields one `{kind:'chunks'}` entry per model call, in call order.
- *
- * A group is only valid if it ends in a `finish` chunk — the adapter contract
- * guarantees a successful (or finish-error) stream terminates with `finish`,
- * and the loop relies on it. A group WITHOUT a terminal `finish` is the
- * fingerprint of a *thrown* `stream()` (the loop recorded the prefix chunks,
- * then an `error`/`turn/end`, but no `finish`): such a stream cannot be
- * faithfully replayed as `{kind:'chunks'}` (that would look like a clean stop),
- * so deriving it is an error — the scenario must supply a `replay.override.json`
- * sidecar with an explicit `throw` (or `hang`) entry instead. {@link
- * deriveReplayScript} throws, naming the offending `(turn, step)`, so a missing
- * override fails loud rather than silently replaying a thrown call as success.
+ * Groups `assistant/chunk` events by turn and step. Every group must end in a
+ * `finish`; a missing terminator means the live stream threw, so derivation
+ * rejects and the scenario must provide an explicit override.
 * @param events - the recorded session's events; only `assistant/chunk` is consulted.
 * @returns one `chunks` entry per recorded model call, in call order.
 */
@@ -242,17 +163,9 @@ export function loadReplayScript(config: ReplayConfig): ReplayEntry[] {
 }

 /**
- * Load every recorded session's script for a scenario, ordered by `createdAt`
- * (earliest first), ready to bind to live sessions in first-call order.
+ * Load the primary and child scripts in bind order. Child derivation begins at
+ * `seedLength` so inherited parent chunks are never replayed as child calls.
 *
- * The PRIMARY session (`config.file`, with its optional `overrideFile`) is the
- * parent; each `config.childFiles` entry is a recorded subagent session. A
- * single-session scenario has no `childFiles`, so this returns one script and
- * behaves exactly like the old single-cursor replay. The primary always sorts
- * first when ties occur (a sub-millisecond parent/child `createdAt` collision):
- * the parent issues the FIRST model call (it must stream before it can delegate
- * in the synchronous nested cut), so binding it to the first live session is
- * correct regardless of a timestamp tie.
 * @param config - the fixture paths: the primary log plus any recorded child logs.
 * @returns the primary script first, then the child scripts in bind order.
 */
@@ -274,12 +187,8 @@ export function loadSessionScripts(config: ReplayConfig): SessionScript[] {
    }
    const text = readFileSync(childFile, 'utf8')
    const header = parseSessionHeader(text)
-    // Derive the child's script from its OWN events only — events AT OR AFTER
-    // the seed boundary. A FORK child's log begins with the seeded parent prefix
-    // (the parent's events, including its `assistant/chunk`s); replaying those as
-    // the child's model calls would feed the child the PARENT's recorded
-    // responses. `seedLength` is 0 for a fresh (spawn) child, so this is a no-op
-    // there.
+    // Derive the child's script from its own events only — events AT OR after the seed
+    // boundary.
    const ownEvents = parseSessionLog(text).slice(header.seedLength)
    children.push({
      recordedId: header.id,
@@ -288,20 +197,8 @@ export function loadSessionScripts(config: ReplayConfig): SessionScript[] {
      primary: false,
    })
  }
-  // 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. 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.
+  // Synchronous children start in creation order; the id only stabilizes timestamp ties.
+  // XXX(concurrent-subagents): concurrent children need an explicit first-call ordinal.
  children.sort((a, b) => a.createdAt - b.createdAt || a.recordedId.localeCompare(b.recordedId))
  return [primary, ...children]
 }
@@ -344,31 +241,11 @@ async function* replayEntry(entry: ReplayEntry, signal: AbortSignal | undefined)
 }

 /**
- * Install the replay `llm/stream` listener on `ctx`. Returns the listener
- * disposer (so a fiber dispose removes it — HMR safety). Exported separately
- * from {@link apply} so unit tests can drive it without the Loader or env vars.
+ * Install per-session positional replay. A newly seen live session takes the
+ * next ordered recorded script, then advances its own cursor synchronously at
+ * invocation time; calls without `sessionId` share one anonymous session.
+ * Returns the effect disposer for HMR-safe removal.
 *
- * Replay is PER-SESSION POSITIONAL: each recorded session has its own script
- * (parent + any subagent children, loaded by {@link loadSessionScripts} ordered
- * by `createdAt`), and the Nth `stream()` call FROM A GIVEN SESSION serves that
- * session's Nth entry. The calling session is read off `options.sessionId` (the
- * agent loop stamps it from `agent.session.id`).
- *
- * Live session ids are freshly random and never equal the recorded ones, so a
- * live session binds to a recorded script by FIRST-CALL ORDER: the first live
- * session to make any call takes the first ordered script (the parent — earliest
- * `createdAt`, and the first to stream because it must run before it delegates),
- * the next new live session takes the next script, and so on. This keys by WHO
- * calls rather than global call order, so it stays correct even if subagents
- * ever run concurrently/backgrounded (a global cursor would interleave them).
- *
- * A call with no `sessionId` (a direct unit-test `ctx.llm.stream` that omits it)
- * is treated as one anonymous session — it binds to the first script, so the
- * single-session path behaves exactly as the old global cursor did.
- *
- * Each per-session cursor advances synchronously at listener-invocation time
- * (not lazily inside the generator) so call ORDER within a session, not
- * iteration order, fixes the mapping.
 * @param ctx - the context whose `llm/stream` waterfall the listener short-circuits.
 * @param config - the resolved fixture paths (env-var defaulting is `apply`'s job).
 * @returns the `ctx.on` disposer that removes the listener.
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -427,11 +427,8 @@ describe('loadSessionScripts', () => {
  })

  it('derives a FORK child script from its OWN events only (skips the seeded parent prefix)', () => {
-    // A fork child's log begins with the seeded parent prefix — the parent's
-    // events, INCLUDING its assistant/chunk events. Deriving the child script
-    // from the whole log would replay the PARENT's recorded responses as the
-    // child's model calls. With seedLength recorded, the child script must
-    // contain only the child's OWN chunks (those after the boundary).
+    // A fork log includes the parent's assistant chunks before `seedLength`. Deriving from the
+    // whole log would replay parent responses as child calls, so only child-owned chunks qualify.
    const parentChunk: StreamChunk = { type: 'text-delta', index: 0, text: 'PARENT-RESPONSE' }
    const childChunks: StreamChunk[] = [{ type: 'text-delta', index: 0, text: 'CHILD-RESPONSE' }, { type: 'finish', reason: { kind: 'stop' } }]
    const f = writeSession('session.jsonl', { id: 'parent', createdAt: 100 }, [TEXT_CHUNKS])
@@ -488,11 +485,8 @@ describe('loadSessionScripts', () => {
  })

  it('keeps the primary first even when a child sorts BEFORE it in input order', () => {
-    // The primary is appended first internally but the child has an EARLIER
-    // createdAt — the primary must still win on the tie-break against a
-    // later-but-equal child, and lose only to a genuinely earlier child via
-    // createdAt (here the child is earlier, so order is child-then-primary only
-    // if createdAt strictly less; equal createdAt keeps primary first).
+    // The primary is appended first internally. A strictly earlier child sorts before it, while
+    // equal creation times preserve primary-first order regardless of input order.
    const f = writeSession('session.jsonl', { id: 'parent', createdAt: 100 }, [TEXT_CHUNKS])
    const earlier = writeSession('session.1.jsonl', { id: 'early', createdAt: 100 }, [TEXT_CHUNKS])
    const scripts = loadSessionScripts({ file: f, childFiles: [earlier] })
--- a/packages/support/subagent-mock/src/index.ts
+++ b/packages/support/subagent-mock/src/index.ts
@@ -1,13 +1,7 @@
 /**
- * A scripted {@link SubagentProvider} for testing the subagent seam WITHOUT a
- * model or a real child agent. Mirrors `@deepseek-ai/dsh-llm-replay`: it lets a
- * test drive the service and the model-facing tool through the REAL cordis
- * Loader / export path, exercising registration, capability validation, the
- * run lifecycle, and the structured-output branch deterministically.
- *
- * Plugin export shape: named `name`/`inject`/`Config`/`apply`, NO default —
- * a functional plugin (it only registers a provider; it is never injected).
- *
+ * Scripted, model-free subagent provider for deterministic coverage of registration,
+ * capability checks, lifecycle, the model-facing tool, and structured results through the real
+ * loader path. It is a named-export functional plugin; no default export.
 * @module @deepseek-ai/dsh-subagent-mock
 */

@@ -28,12 +22,7 @@ const STOP_REASONS = ['completed', 'aborted', 'error', 'max-tokens', 'refusal']

 const DEFAULT_CAPS: SubagentCapabilities = { outputSchema: true, depthLimit: true, toolFilter: true, persona: true }

-/**
- * A scripted provider: every {@link start} returns a ready run whose `result`
- * resolves on the next task with the configured reply (and a structured value
- * when the request asked for one and the capability is on). The required
- * signal and `dispose()` both flip an unsettled result to `aborted`.
- */
+/** Scripted provider whose configured result aborts if disposed or signalled first. */
 class MockSubagentProvider implements SubagentProvider {
  readonly capabilities: SubagentCapabilities
  readonly inheritsParentContext: boolean
--- a/packages/support/subagent-mock/tests/subagent-mock.spec.ts
+++ b/packages/support/subagent-mock/tests/subagent-mock.spec.ts
@@ -105,10 +105,7 @@ describe('dsh-subagent-mock', () => {
  })

  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/inject/Config/apply', () => {
-    // Postmortem 0001 guard: this plugin HAS `inject = ['subagents']`, so a stray
-    // `export default apply` would collapse the module via `unwrapExports`
-    // (`exports.default ?? exports`), DROP `inject`, and crash at load with
-    // "cannot get property … without inject". Guard the shape directly.
+    // A default export would make Loader unwrap only that value and drop `inject`.
    expect('default' in mock).toBe(false)
    expect(mock.name).toBe('subagent-mock')
    expect(mock.inject).toEqual(['subagents'])