test(acp): snapshot system prompts as Markdown

2026-07-11 22:24:20 +08:00
parent ee3e4ea8f9
commit 9339622d3b
20 changed files with 543 additions and 135 deletions
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -5,8 +5,8 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie
 Three layers, importable separately:

 - **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the golden + purity check, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo).
- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), and the composable `scrubRequestHeaders` (header bulk → `{{system}}`/`{{tools}}`, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, the per-header-class pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must be called at vitest collection time.
+- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), `scrubSystemPrompts` (prompt text → `{{system}}` in every JSONL), and `scrubRequestHeaders` (the remaining header bulk → `{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header RFC](../../../docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario golden + re-persisted-log compares, record/refresh fixture write-back, the per-header-class pin (`system-prompt.golden.md` plus the JSONL's full tool schemas) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt-scrubbed, non-pinning fixtures fully header-scrubbed). Must be called at vitest collection time.

 A consuming `*.snapshot.ts` is the scenario table plus one factory call:

@@ -35,8 +35,8 @@ 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.
+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 plus comparable session-log goldens 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).
+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).

 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).
--- a/packages/support/acp-snapshot/src/index.ts
+++ b/packages/support/acp-snapshot/src/index.ts
@@ -3,7 +3,7 @@
 * 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}), and the suite factory
+ * {@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
@@ -29,6 +29,7 @@ export {
  normalizeSessionLog,
  normalizeStdout,
  scrubRequestHeaders,
+  scrubSystemPrompts,
  type NormalizeContext,
 } from './normalize.ts'
 export {
--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -12,14 +12,14 @@
 * `durationMs` (wall-clock hook runtime) → 0. NOT scrubbed: the log's `seq`
 * (deterministic — `seq = log.length`, part of the event-log contract).
 *
- * A separate, composable normalizer — {@link scrubRequestHeaders} — replaces
- * the bulky request-header CONTENT (the composed system prompt, the tool
- * schema list, and the session prefix) with
- * `{{system}}`/`{{tools}}`/`{{messagePrefix}}` tokens. It is deliberately NOT
- * folded into {@link normalizeSessionLog}: each suite's one header-pinning
- * scenario compares that content verbatim, every other scenario composes the
- * scrub in (the `pinsHeader` flag on the scenario table, consumed by the suite
- * factory in ./suite.ts; see the pinned-header RFC,
+ * 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.
@@ -135,37 +135,37 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
 }

 /**
- * Replace request-header CONTENT in a session JSONL with stable tokens,
- * keeping its structure: a `request/header` event's `data.header.system` →
- * `{{system}}`, `data.header.tools` → `{{tools}}`, and
- * `data.header.messagePrefix` → one `{{messagePrefix}}` token per message
- * (the session prefix is model-visible bulk — an AGENTS digest, a skills
- * catalog — so its COUNT stays a structural fact while its text never lands
- * in a fixture); a
- * `request/header-delta` event keeps every structural fact — the system
- * delta's `keepStart`/`keepEnd` line positions and inserted-line COUNT (one
- * `{{system}}` token per inserted line), the tools delta's
- * added/removed/changed tool NAMES, the prefix replacement's message COUNT —
- * and tokenizes only the bulk (prompt
- * text; each added/changed schema's fields other than `name` → `{{tools}}`;
- * each replacement prefix message → `{{messagePrefix}}`),
- * so two different deltas still compare different.
- * Absent fields stay absent — WHETHER a header carried a system prompt,
- * tools, or a prefix is behavior and stays visible; `config` and `reason`
- * are small and
- * stable, so they stay verbatim (a model swap churns every fixture by design
- * — it invalidates the recorded responses; a prompt/schema edit churns none —
- * replay never reads this content, see dsh-llm-replay).
- *
- * Only lines with something to scrub are re-serialized; every other line
- * passes through byte-for-byte, so the transform is idempotent and applying
- * it to an already-scrubbed fixture is a no-op — the on-disk-fixtures guard
- * in ./suite.ts relies on exactly that.
+ * Replace system-prompt content in request headers and header deltas with
+ * `{{system}}` tokens while retaining field presence and delta structure.
+ * Other header content stays verbatim, so a header-pinning fixture can keep
+ * its complete tool schemas while every JSONL fixture omits the prompt text.
+ * Lines without a system payload pass through byte-for-byte; the transform is
+ * idempotent.
 *
 * @param rawLog The raw session `.jsonl` content.
- * @returns The JSONL with header content tokenized, other lines byte-identical.
+ * @returns The JSONL with system-prompt content tokenized.
+ */
+export function scrubSystemPrompts(rawLog: string): string {
+  return scrubHeaderContent(rawLog, false)
+}
+
+/**
+ * Replace all bulky request-header content in a session JSONL with stable
+ * tokens. This includes the system-prompt fields handled by
+ * {@link scrubSystemPrompts}, tool schemas, and session-prefix messages. It
+ * keeps system-delta line positions and arity, tool-delta names, prefix
+ * message counts, field presence, config, and reason. Lines without content
+ * to scrub pass through byte-for-byte, and the transform is idempotent.
+ *
+ * @param rawLog The raw session `.jsonl` content.
+ * @returns The JSONL with all header bulk tokenized, other lines byte-identical.
 */
 export function scrubRequestHeaders(rawLog: string): string {
+  return scrubHeaderContent(rawLog, true)
+}
+
+/** Transform header content, optionally including tool schemas and the session prefix. */
+function scrubHeaderContent(rawLog: string, scrubToolsAndPrefix: boolean): string {
  const lines = rawLog.split('\n')
  const out = lines.map((line) => {
    if (line.trim().length === 0) return line
@@ -175,11 +175,14 @@ export function scrubRequestHeaders(rawLog: string): string {
    if (record.type === 'request/header') {
      const header = data.header as Record<string, unknown> | null | undefined
      if (header === null || typeof header !== 'object') return line
-      if (!('system' in header) && !('tools' in header) && !('messagePrefix' in header)) return line
-      if ('system' in header) header.system = SYSTEM
-      if ('tools' in header) header.tools = TOOLS
-      if (Array.isArray(header.messagePrefix)) header.messagePrefix = header.messagePrefix.map(() => MESSAGE_PREFIX)
-      return JSON.stringify(record)
+      let touched = false
+      if ('system' in header) { header.system = SYSTEM; touched = true }
+      if (scrubToolsAndPrefix && 'tools' in header) { header.tools = TOOLS; touched = true }
+      if (scrubToolsAndPrefix && Array.isArray(header.messagePrefix)) {
+        header.messagePrefix = header.messagePrefix.map(() => MESSAGE_PREFIX)
+        touched = true
+      }
+      return touched ? JSON.stringify(record) : line
    }
    if (record.type === 'request/header-delta') {
      let touched = false
@@ -189,11 +192,11 @@ export function scrubRequestHeaders(rawLog: string): string {
        touched = true
      }
      const tools = data.tools as Record<string, unknown> | null | undefined
-      if (tools !== null && typeof tools === 'object') {
+      if (scrubToolsAndPrefix && tools !== null && typeof tools === 'object') {
        if (Array.isArray(tools.added)) { tools.added = tools.added.map(scrubToolSchema); touched = true }
        if (Array.isArray(tools.changed)) { tools.changed = tools.changed.map(scrubToolSchema); touched = true }
      }
-      if (Array.isArray(data.messagePrefix)) {
+      if (scrubToolsAndPrefix && Array.isArray(data.messagePrefix)) {
        data.messagePrefix = data.messagePrefix.map(() => MESSAGE_PREFIX)
        touched = true
      }
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -10,15 +10,14 @@
 * (recorded scenarios) and the expected produced log (both sides normalized
 * before comparing).
 *
- * Request-header content (the composed system prompt + tool schemas riding on
- * `request/header` events) is pinned by exactly ONE scenario per HEADER CLASS
- * — scenarios that boot the same config compose the same header; each class's
- * `pinsHeader` scenario commits it verbatim — and scrubbed to
- * `{{system}}`/`{{tools}}` tokens in every other fixture and compare, so a
- * prompt or tool-schema edit churns one committed line per class instead of
- * every fixture. A per-run uniformity guard keeps each pin sound: every live
- * header must equal its class's pinned one, and no header-delta may appear
- * outside a pinning scenario (see the pinned-header RFC,
+ * 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
@@ -37,7 +36,16 @@ import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from './normalize.ts'
+import {
+  type NormalizeContext,
+  normalizeSessionLog,
+  normalizeStdout,
+  scrubRequestHeaders,
+  scrubSystemPrompts,
+} from './normalize.ts'
+
+/** The readable system-prompt snapshot beside each header-pinning fixture. */
+const SYSTEM_PROMPT_SNAPSHOT = 'system-prompt.golden.md'

 /** A snapshot scenario and how its fixtures are produced. */
 export interface Scenario {
@@ -81,14 +89,13 @@ export interface Scenario {
   */
  childSessions?: number
  /**
-   * Whether THIS scenario's fixtures keep the full request-header content (the
-   * composed system prompt and tool schema list on `request/header` /
-   * `request/header-delta` events) and compare it verbatim. Exactly one
-   * scenario per HEADER CLASS ({@link headerClass}) pins it; every other
-   * scenario of that class stores and compares that content as
-   * `{{system}}`/`{{tools}}` tokens ({@link scrubRequestHeaders}),
-   * so a system prompt or tool-schema change shows up as ONE committed-fixture
-   * diff per class, not one per scenario. One pin per class suffices because
+   * 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
@@ -124,7 +131,7 @@ export interface SnapshotSuiteOptions {
  agent: AgentUnderTest
  /** Absolute path of the suite's `snapshots/` directory (one subdir per scenario). */
  snapshotsDir: string
-  /** The scenario table; exactly one entry must set `pinsHeader`. */
+  /** The scenario table; exactly one entry per header class must set `pinsHeader`. */
  scenarios: Scenario[]
  /**
   * `replay` (keyless, the default tier), `record` (live API; re-records the
@@ -192,6 +199,35 @@ export function normalizedHeaders(rawLog: string, ctx: NormalizeContext): unknow
    .map(record => record.data?.header)
 }

+/**
+ * The normalized string-valued system prompts carried by request headers in a
+ * session JSONL, in log order. Headers without a string prompt are omitted so
+ * callers can assert one prompt per header explicitly.
+ *
+ * @param rawLog The session `.jsonl` content to inspect.
+ * @param ctx The volatile values of the run that produced it.
+ * @returns The normalized system prompts, in header order.
+ */
+export function normalizedSystemPrompts(rawLog: string, ctx: NormalizeContext): string[] {
+  return normalizedHeaders(rawLog, ctx).flatMap((header) => {
+    if (header === null || typeof header !== 'object') return []
+    const system = (header as { system?: unknown }).system
+    return typeof system === 'string' ? [system] : []
+  })
+}
+
+/**
+ * Render a normalized prompt as a repository-friendly Markdown snapshot.
+ * Prompt text is unchanged except that a missing terminal newline is added so
+ * the committed file follows the repository newline contract.
+ *
+ * @param prompt The normalized system prompt.
+ * @returns Markdown snapshot text ending in a newline.
+ */
+export function formatSystemPromptSnapshot(prompt: string): string {
+  return prompt.endsWith('\n') ? prompt : `${prompt}\n`
+}
+
 /**
 * Count the `request/header-delta` events in a session JSONL.
 *
@@ -289,7 +325,8 @@ export function stabilizeRefreshLog(fresh: string, existing: string, replacement
 * Register the suite: one `describe` per scenario (the golden/log compares and
 * the header-uniformity guard) plus the fixture guard block (no orphan
 * scenario dirs, required files present, exactly one pin per header class,
- * pinning fixtures well-formed, non-pinning fixtures header-scrubbed). Must
+ * pinning fixtures well-formed, every JSONL prompt-scrubbed, non-pinning
+ * fixtures fully header-scrubbed). Must
 * run at vitest collection time — it calls `describe`/`it`. Throws
 * immediately if any header class lacks a pinning scenario or carries two
 * (the uniformity guard needs exactly one comparison anchor per class).
@@ -364,11 +401,12 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
        // 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
-        // non-pinning scenario's fixtures are written header-scrubbed, so a
-        // re-record/refresh can never smuggle the full prompt/schema content
-        // back into every fixture.
+        // 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.
        const scrub = scenario.pinsHeader === true
-          ? (log: string): string => log
+          ? scrubSystemPrompts
          : scrubRequestHeaders
        const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)]
        const existingFixtures = REFRESHING
@@ -391,6 +429,16 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
              REFRESHING ? stabilizeRefreshLog(child, existingFixtures[i] as string, replacements) : child,
            ))
          }
+          if (scenario.pinsHeader === true) {
+            const prompts = result.sessionLogs.flatMap(log => normalizedSystemPrompts(log.content, ctx))
+            expect(prompts.length, `${mode} produced no system prompt to snapshot`).toBeGreaterThan(0)
+            const snapshot = formatSystemPromptSnapshot(prompts[0] as string)
+            for (const prompt of prompts) {
+              expect(formatSystemPromptSnapshot(prompt), 'the pinning run produced divergent system prompts')
+                .toEqual(snapshot)
+            }
+            await writeFile(join(dir, SYSTEM_PROMPT_SNAPSHOT), snapshot)
+          }
        }

        const stdout = normalizeStdout(result.rawStdout, ctx)
@@ -406,12 +454,10 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          // 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).
-          // Unless this scenario pins the header, both sides ALSO pass through
-          // scrubRequestHeaders: the live log carries the real prompt/schemas, the
-          // fixture carries the `{{system}}`/`{{tools}}` tokens, and the scrub is
-          // idempotent — so the compare checks the header's presence, position,
-          // reason, and config, but not its bulk content (pinned once, in the
-          // `pinsHeader` scenario).
+          // 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.
          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)
@@ -421,34 +467,30 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          }
        }

-        // Header-uniformity guard: a class's single pin is sound only while
-        // every session in that class composes the SAME header and keeps it
-        // for the whole run. Assert both halves live. (1) Every
-        // request/header the run produced (parent, spawn child, fork child,
-        // initial or resume) must equal the CLASS's pinned fixture's header
-        // after each side is normalized against its own volatile values.
-        // (2) No request/header-delta may appear at all — a mid-run header
-        // change diverges from the pin by construction, and its content
-        // would be invisible under the scrub. If either fails, either the
-        // header changed (update the pin: re-record or hand-edit the pinning
-        // scenario's fixture) or composition became session-dependent by
-        // design (give the divergent shape its own pinning scenario and
-        // class).
-        if (scenario.pinsHeader !== true) {
-          /* 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 pinnedFixture = await readFile(join(snapshotsDir, pinningScenario.name, 'session.jsonl'), 'utf8')
-          const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
-          expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
-            .toBe(1)
-          for (const log of result.sessionLogs) {
-            expect(headerDeltaCount(log.content), `session ${log.id}: a request/header-delta in a non-pinning scenario`)
-              .toBe(0)
-            const headers = normalizedHeaders(log.content, ctx)
-            for (const [k, header] of headers.entries()) {
-              expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`)
-                .toEqual(pinned[0])
-            }
+        // 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. No header delta is representable by
+        // those two static artifacts, so any delta fails loud.
+        /* 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)
+        const pinnedFixture = await readFile(join(pinningDir, 'session.jsonl'), 'utf8')
+        const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
+        const promptSnapshot = await readFile(join(pinningDir, SYSTEM_PROMPT_SNAPSHOT), 'utf8')
+        expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
+          .toBe(1)
+        for (const log of result.sessionLogs) {
+          expect(headerDeltaCount(log.content), `session ${log.id}: a request/header-delta is not represented by the class pin`)
+            .toBe(0)
+          const headers = normalizedHeaders(scrubSystemPrompts(log.content), ctx)
+          const prompts = normalizedSystemPrompts(log.content, ctx)
+          expect(prompts.length, `session ${log.id}: every request/header must carry a string system prompt`)
+            .toBe(headers.length)
+          for (const [k, header] of headers.entries()) {
+            expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`)
+              .toEqual(pinned[0])
+            expect(formatSystemPromptSnapshot(prompts[k] as string), `session ${log.id}: system prompt #${k + 1} diverged from ${pinningScenario.name}/${SYSTEM_PROMPT_SNAPSHOT}`)
+              .toEqual(promptSnapshot)
          }
        }
      })
@@ -479,13 +521,15 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
      // `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.
-      for (const { name, overridden, childSessions } of scenarios) {
+      for (const { name, overridden, childSessions, pinsHeader } of scenarios) {
        const dir = join(snapshotsDir, name)
        expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
        expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true)
        expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
        expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``)
          .toBe(overridden === true)
+        expect(existsSync(join(dir, SYSTEM_PROMPT_SNAPSHOT)), `${name}/${SYSTEM_PROMPT_SNAPSHOT} presence must match \`pinsHeader\``)
+          .toBe(pinsHeader === true)
        // A nested-agent scenario ships one child fixture per recorded subagent
        // session (`session.1.jsonl` …), the replay source for that child session.
        for (const childFixture of childFixturePaths(dir, childSessions ?? 0)) {
@@ -511,7 +555,7 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
      }
    })

-    it('every pinning fixture carries exactly one request/header and no deltas', async () => {
+    it('every pinning fixture carries exactly one request/header, one readable prompt, and no 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 a mid-run header-delta —
@@ -520,19 +564,18 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
      for (const scenario of pinningByClass.values()) {
        const fixture = await readFile(join(snapshotsDir, scenario.name, 'session.jsonl'), 'utf8')
        const headers = normalizedHeaders(fixture, fixtureContext(fixture))
+        const promptSnapshot = await readFile(join(snapshotsDir, scenario.name, SYSTEM_PROMPT_SNAPSHOT), 'utf8')
        expect(headers.length, `${scenario.name}: a pinning fixture must carry exactly one request/header`).toBe(1)
+        expect(promptSnapshot.length, `${scenario.name}/${SYSTEM_PROMPT_SNAPSHOT} must not be empty`).toBeGreaterThan(0)
+        expect(promptSnapshot.endsWith('\n'), `${scenario.name}/${SYSTEM_PROMPT_SNAPSHOT} must end in a newline`).toBe(true)
        expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry no request/header-delta`).toBe(0)
      }
    })

-    it('committed fixtures carry request-header content ONLY in the pinning scenario', async () => {
-      // The whole point of the pin: a system-prompt or tool-schema change must
-      // churn exactly one committed line. A non-pinning fixture that carries the
-      // full header (a hand-recorded file, or a header line hand-edited out of
-      // its canonical JSON form) silently reopens the suite-wide churn, so fail
-      // loud here: every non-pinning session*.jsonl must be a fixed point of
-      // scrubRequestHeaders (apply the scrub to fix a violation), and the
-      // pinning scenario's fixtures must NOT be (their content IS the pin).
+    it('every committed JSONL omits system prompts and only pinning fixtures keep other header bulk', async () => {
+      // System prompts always live in the readable Markdown artifact. Header
+      // pins keep tool schemas/prefixes in JSONL; every other fixture tokenizes
+      // all header bulk. Fixed-point checks make both storage rules fail loud.
      for (const scenario of scenarios) {
        const dir = join(snapshotsDir, scenario.name)
        const files = [
@@ -541,8 +584,10 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
        ]
        for (const file of files) {
          const fixture = await readFile(join(dir, file), 'utf8')
+          expect(scrubSystemPrompts(fixture), `${scenario.name}/${file} carries an unscrubbed system prompt`)
+            .toEqual(fixture)
          if (scenario.pinsHeader === true) {
-            expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} must PIN the full header content`)
+            expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} must pin the non-system header content`)
              .not.toEqual(fixture)
          } else {
            expect(scrubRequestHeaders(fixture), `${scenario.name}/${file} carries unscrubbed header content`)
--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/session.jsonl
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/session.jsonl
@@ -1,2 +1,2 @@
 {"type":"session","id":"ccdc749f-56f3-4267-9750-598b5c60b7b2","createdAt":600,"cwd":"/var/folders/2g/b32ct0qn1d728l_v6tdkjytr0000gn/T/acp-snap-cwd-nOQ4Gy"}
-{"type":"request/header","seq":0,"time":4,"data":{"header":{"config":{"model":"fake"},"system":"SYS PROMPT","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
+{"type":"request/header","seq":0,"time":4,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/system-prompt.golden.md
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/system-prompt.golden.md
@@ -0,0 +1 @@
+SYS PROMPT
--- a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/session.jsonl
+++ b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/session.jsonl
@@ -1,3 +1,3 @@
 {"type":"session","id":"12121212-3434-4545-8686-787878787878","createdAt":7,"cwd":"/rec/pin-cwd"}
-{"type":"request/header","seq":0,"time":7,"data":{"header":{"config":{"model":"fake"},"system":"SYS PROMPT","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
+{"type":"request/header","seq":0,"time":7,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":[{"name":"t1","description":"D1","parameters":{"type":"object"}}]},"reason":"initial"}}
 {"type":"turn/start","seq":1,"time":7,"data":{"turn":1}}
--- a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/system-prompt.golden.md
+++ b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/system-prompt.golden.md
@@ -0,0 +1 @@
+SYS PROMPT
--- a/packages/support/acp-snapshot/tests/normalize.spec.ts
+++ b/packages/support/acp-snapshot/tests/normalize.spec.ts
@@ -1,5 +1,11 @@
 import { describe, expect, it } from 'vitest'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout, scrubRequestHeaders } from '../src/normalize.ts'
+import {
+  type NormalizeContext,
+  normalizeSessionLog,
+  normalizeStdout,
+  scrubRequestHeaders,
+  scrubSystemPrompts,
+} from '../src/normalize.ts'

 /**
 * Unit tests for the pure snapshot normalizers. Live as a *.spec.ts (runs in
@@ -260,3 +266,43 @@ describe('scrubRequestHeaders', () => {
    expect(scrubRequestHeaders(once)).toBe(once)
  })
 })
+
+describe('scrubSystemPrompts', () => {
+  it('scrubs only system prompt payloads while keeping tools and prefixes verbatim', () => {
+    const header = JSON.stringify({
+      type: 'request/header', seq: 1, time: 2,
+      data: {
+        header: {
+          system: 'full prompt',
+          tools: [{ name: 'read', description: 'full schema' }],
+          messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'full prefix' }] }],
+        },
+        reason: 'initial',
+      },
+    })
+    const delta = JSON.stringify({
+      type: 'request/header-delta', seq: 2, time: 3,
+      data: {
+        system: { keepStart: 1, keepEnd: 2, insert: ['new prompt line'] },
+        tools: { changed: [{ name: 'read', description: 'changed schema' }] },
+        messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }],
+      },
+    })
+    const toolsOnly = JSON.stringify({
+      type: 'request/header', seq: 3, time: 4,
+      data: { header: { tools: [{ name: 'read', description: 'schema only' }] }, reason: 'resume' },
+    })
+
+    const out = scrubSystemPrompts(`${header}\n${delta}\n${toolsOnly}\n`)
+    expect(out).toContain('"system":"{{system}}"')
+    expect(out).toContain('"insert":["{{system}}"]')
+    expect(out).not.toContain('full prompt')
+    expect(out).not.toContain('new prompt line')
+    expect(out).toContain('full schema')
+    expect(out).toContain('full prefix')
+    expect(out).toContain('changed schema')
+    expect(out).toContain('changed prefix')
+    expect(out.split('\n')[2]).toBe(toolsOnly)
+    expect(scrubSystemPrompts(out)).toBe(out)
+  })
+})
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -8,8 +8,10 @@ import { defineAcpSnapshotSuite, type HarvestedLog, type Scenario } from '../src
 import {
  childFixturePaths,
  fixtureContext,
+  formatSystemPromptSnapshot,
  headerDeltaCount,
  normalizedHeaders,
+  normalizedSystemPrompts,
  refreshFixtureReplacements,
  stabilizeRefreshLog,
 } from '../src/suite.ts'
@@ -78,6 +80,7 @@ afterAll(async () => {

 function staleRefreshFixtures(dir: string): void {
  writeFileSync(join(dir, 'plain-turn', 'stdout.golden.jsonl'), 'stale stdout\n')
+  writeFileSync(join(dir, 'pin-turn', 'system-prompt.golden.md'), 'STALE PROMPT\n')

  const plainBehaviorFile = join(dir, 'plain-turn', 'behavior.json')
  const plainBehavior = JSON.parse(readFileSync(plainBehaviorFile, 'utf8')) as Record<string, unknown>
@@ -124,6 +127,8 @@ describe('defineAcpSnapshotSuite: refresh write-back', () => {
    const authored = readFileSync(join(refreshDir, 'authored-error', 'session.jsonl'), 'utf8')
    expect(authored).toContain('"error":"model exploded"')
    expect(authored).not.toContain('"error":"stale"')
+
+    expect(readFileSync(join(refreshDir, 'pin-turn', 'system-prompt.golden.md'), 'utf8')).toBe('SYS PROMPT\n')
  })
 })

@@ -219,6 +224,28 @@ describe('normalizedHeaders', () => {
  })
 })

+describe('normalizedSystemPrompts', () => {
+  it('extracts normalized string prompts and omits absent or non-string fields', () => {
+    const log = [
+      '{"type":"session","id":"a","createdAt":5,"cwd":"/w"}',
+      '{"type":"request/header","seq":0,"time":9,"data":{"header":{"system":"work in /w"}}}',
+      '{"type":"request/header","seq":1,"time":9,"data":{"header":{}}}',
+      '{"type":"request/header","seq":2,"time":9,"data":{"header":{"system":null}}}',
+      '{"type":"request/header","seq":3,"time":9,"data":{"header":null}}',
+      '{"type":"request/header","seq":4,"time":9,"data":{"header":"invalid"}}',
+      '',
+    ].join('\n')
+    expect(normalizedSystemPrompts(log, { sessionIds: [], cwd: '/w' })).toEqual(['work in {{cwd}}'])
+  })
+})
+
+describe('formatSystemPromptSnapshot', () => {
+  it('adds a missing terminal newline without changing an existing one', () => {
+    expect(formatSystemPromptSnapshot('prompt')).toBe('prompt\n')
+    expect(formatSystemPromptSnapshot('prompt\n')).toBe('prompt\n')
+  })
+})
+
 describe('headerDeltaCount', () => {
  it('counts request/header-delta events, ignoring blanks and other lines', () => {
    const delta = JSON.stringify({ type: 'request/header-delta', seq: 2, time: 9, data: {} })