Merge newest origin/master into token-meter-service

2026-07-17 22:49:54 +08:00
parent 35ff333e51 350a636ece
commit 06ea8643ff
106 changed files with 1488 additions and 1353 deletions
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -35,7 +35,7 @@ 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 and filesystem scenarios are templates. Each pinning directory stores the normalized composed prompt in generated `system-prompt.golden.md` and the initial schemas plus schema deltas in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix.
+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 and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences.

 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, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md).

--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -125,8 +125,8 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
 }

 /**
- * Replace system-prompt content in request headers and header deltas with
- * `{{system}}` tokens while retaining field presence and delta structure.
+ * Replace system-prompt content in request headers with `{{system}}` tokens
+ * while retaining field presence.
 * 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
@@ -140,11 +140,11 @@ export function scrubSystemPrompts(rawLog: string): string {
 }

 /**
- * Replace tool schemas in request headers and header deltas with `{{tools}}`
- * tokens while retaining field presence, tool names, and delta structure.
- * System prompts and session-prefix messages stay verbatim so pinning fixtures
- * can move only schema bulk into their dedicated JSON sidecar. Lines without a
- * tool payload pass through byte-for-byte; the transform is idempotent.
+ * Replace tool schemas in full request-header snapshots with `{{tools}}`
+ * tokens while retaining field presence. System prompts and session-prefix
+ * messages stay verbatim so pinning fixtures can move only schema bulk into
+ * their dedicated JSON sidecar. Lines without a tool payload pass through
+ * byte-for-byte; the transform is idempotent.
 *
 * @param rawLog The raw session `.jsonl` content.
 * @returns The JSONL with tool-schema content tokenized.
@@ -157,9 +157,9 @@ export function scrubToolSchemas(rawLog: string): string {
 * 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.
+ * keeps 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.
@@ -195,33 +195,7 @@ function scrubHeaderContent(rawLog: string, options: HeaderScrubOptions): string
      }
      return touched ? JSON.stringify(record) : line
    }
-    if (record.type === 'request/header-delta') {
-      let touched = false
-      const system = data.system as Record<string, unknown> | null | undefined
-      if (options.system === true && system !== null && typeof system === 'object' && Array.isArray(system.insert)) {
-        system.insert = system.insert.map(() => SYSTEM)
-        touched = true
-      }
-      const tools = data.tools as Record<string, unknown> | null | undefined
-      if (options.tools === true && 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 (options.prefix === true && Array.isArray(data.messagePrefix)) {
-        data.messagePrefix = data.messagePrefix.map(() => MESSAGE_PREFIX)
-        touched = true
-      }
-      return touched ? JSON.stringify(record) : line
-    }
    return line
  })
  return out.join('\n')
 }
-
-/** Tokenize one tool schema's bulk (description, parameters, anything else), keeping its identifying `name`. */
-function scrubToolSchema(tool: unknown): unknown {
-  if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) return tool
-  const out: Record<string, unknown> = {}
-  for (const [k, v] of Object.entries(tool)) out[k] = k === 'name' ? v : TOOLS
-  return out
-}
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -1,14 +1,17 @@
 /**
- * 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.
- * Replay scenarios run concurrently because each subprocess owns unique temp cwd and persistence
- * roots and only reads committed fixtures. Record and refresh scenarios stay serial while writing.
+ * 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.
+ * Replay scenarios run concurrently because each subprocess owns unique temp
+ * cwd and persistence roots and reads only committed fixtures. Record and
+ * refresh stay serial while writing.
 *
- * Exactly one scenario per header-composition class pins the system prompt and tool schemas in
- * dedicated sidecars. Every live header is checked against that pin, so session-dependent
- * composition must declare a separate class instead of escaping coverage.
+ * Exactly one scenario per header-composition class pins the full prompt and
+ * tool-schema sequences in dedicated sidecars. 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
 */

@@ -82,14 +85,11 @@ export interface Scenario {
   */
  pinsHeader?: boolean
  /**
-   * How many `request/header-delta` events this PINNING scenario's fixture
-   * legitimately carries (default 0). A recorded mid-run header change — a
-   * config-option switch rewriting a prompt section — is part of the pinned
-   * surface, with readable prompt text in Markdown; any OTHER count
-   * still fails, so fixture rot stays caught. Meaningless off the pin (the
-   * live uniformity guard keeps non-pinning scenarios delta-free).
+   * How many changed `request/header` snapshots this PINNING scenario's primary
+   * fixture legitimately carries (default 0). Their full prompt text is kept in
+   * the readable Markdown pin; any other count fails. Meaningless off the pin.
   */
-  expectedHeaderDeltas?: number
+  expectedHeaderChanges?: number
  /**
   * Which header-composition class this scenario belongs to. Scenarios that
   * boot the same config compose the same header; each class has exactly one
@@ -210,114 +210,58 @@ export function normalizedToolSchemas(rawLog: string, ctx: NormalizeContext): un
  })
 }

-/**
- * Extract normalized tool-schema edits from request-header deltas in log order.
- * Deltas without an object-valued tools edit are omitted; their remaining
- * structure stays pinned in the session JSONL.
- *
- * @param rawLog The session `.jsonl` content to inspect.
- * @param ctx The volatile values of the run that produced it.
- * @returns The normalized tool-schema edits, in event order.
- */
-export function normalizedToolSchemaDeltas(rawLog: string, ctx: NormalizeContext): unknown[] {
-  return normalizeSessionLog(rawLog, ctx)
-    .split('\n')
-    .filter(line => line.trim().length > 0)
-    .map(line => JSON.parse(line) as { type?: unknown; data?: { tools?: unknown } })
-    .filter(record => record.type === 'request/header-delta')
-    .flatMap((record) => {
-      const tools = record.data?.tools
-      return tools !== null && typeof tools === 'object' && !Array.isArray(tools) ? [tools] : []
-    })
-}
-
 /** The structured contents of a tool-schema sidecar. */
 export interface ToolSchemasSnapshot {
  /** The complete tool schemas from the pinned request header. */
  initial: unknown[]
-  /** Complete tool-schema edits from subsequent request-header deltas. */
-  deltas: unknown[]
+  /** Complete tool schemas from subsequent changed-header snapshots. */
+  changes: unknown[][]
 }

 /**
- * Render tool schemas and later schema edits as canonical, readable JSON.
+ * Render the full tool-schema sequence as canonical, readable JSON.
 *
 * @param initial The pinned request header's complete tool schemas.
- * @param deltas Complete tool-schema edits from request-header deltas.
+ * @param changes Complete tool schemas from later changed headers.
 * @returns A pretty-printed JSON snapshot ending in one newline.
 */
-export function formatToolSchemasSnapshot(initial: readonly unknown[], deltas: readonly unknown[] = []): string {
-  return `${JSON.stringify({ initial, deltas }, null, 2)}\n`
+export function formatToolSchemasSnapshot(initial: readonly unknown[], changes: readonly unknown[][] = []): string {
+  return `${JSON.stringify({ initial, changes }, null, 2)}\n`
 }

 /**
 * Parse and validate the stable top-level shape of a tool-schema sidecar.
 *
 * @param snapshot The JSON sidecar text.
- * @returns Its initial schemas and schema deltas.
+ * @returns Its initial and changed-header schema sets.
 */
 export function parseToolSchemasSnapshot(snapshot: string): ToolSchemasSnapshot {
  const parsed = JSON.parse(snapshot) as unknown
  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
    throw new Error('acp-snapshot: tool-schema snapshot must be an object')
  }
-  const { initial, deltas } = parsed as { initial?: unknown; deltas?: unknown }
-  if (!Array.isArray(initial) || !Array.isArray(deltas)) {
-    throw new Error('acp-snapshot: tool-schema snapshot must carry array-valued initial and deltas fields')
+  const { initial, changes } = parsed as { initial?: unknown; changes?: unknown }
+  if (!Array.isArray(initial) || !Array.isArray(changes) || !changes.every(Array.isArray)) {
+    throw new Error('acp-snapshot: tool-schema snapshot must carry array-valued initial and changes fields')
  }
-  return { initial, deltas }
+  return { initial, changes }
 }

 /**
- * Restore a sidecar's initial schemas into a tokenized pinned header.
+ * Restore one sidecar schema set into a tokenized pinned header.
 *
 * @param header The parsed request header carrying `tools: "{{tools}}"`.
- * @param snapshot The parsed tool-schema sidecar.
- * @returns A copy of the header with its complete initial schemas restored.
+ * @param schemas The complete schemas for this full header snapshot.
+ * @returns A copy of the header with its complete schemas restored.
 */
-export function restorePinnedToolSchemas(header: unknown, snapshot: ToolSchemasSnapshot): unknown {
+export function restorePinnedToolSchemas(header: unknown, schemas: readonly unknown[]): unknown {
  if (header === null || typeof header !== 'object' || Array.isArray(header)) {
    throw new Error('acp-snapshot: pinned request header must be an object')
  }
  if ((header as { tools?: unknown }).tools !== TOOLS_TOKEN) {
    throw new Error(`acp-snapshot: pinned request header tools must equal ${TOOLS_TOKEN}`)
  }
-  return { ...header, tools: snapshot.initial }
-}
-
-/** One normalized system-prompt edit carried by a `request/header-delta`. */
-export interface SystemPromptDeltaSnapshot {
-  /** How many leading lines remain from the prior prompt. */
-  keepStart: number
-  /** How many trailing lines remain from the prior prompt. */
-  keepEnd: number
-  /** The normalized replacement lines inserted between the retained ranges. */
-  insert: string[]
-}
-
-/**
- * Extract normalized system-prompt edits from request-header deltas in log
- * order. Deltas without a well-formed system edit are omitted; their non-prompt
- * structure remains pinned in JSONL.
- *
- * @param rawLog The session `.jsonl` content to inspect.
- * @param ctx The volatile values of the run that produced it.
- * @returns The normalized system-prompt edits, in event order.
- */
-export function normalizedSystemPromptDeltas(rawLog: string, ctx: NormalizeContext): SystemPromptDeltaSnapshot[] {
-  return normalizeSessionLog(rawLog, ctx)
-    .split('\n')
-    .filter(line => line.trim().length > 0)
-    .map(line => JSON.parse(line) as { type?: unknown; data?: { system?: unknown } })
-    .filter(record => record.type === 'request/header-delta')
-    .flatMap((record) => {
-      const system = record.data?.system
-      if (system === null || typeof system !== 'object') return []
-      const { keepStart, keepEnd, insert } = system as { keepStart?: unknown; keepEnd?: unknown; insert?: unknown }
-      if (typeof keepStart !== 'number' || typeof keepEnd !== 'number' || !Array.isArray(insert)) return []
-      if (!insert.every(line => typeof line === 'string')) return []
-      return [{ keepStart, keepEnd, insert: insert }]
-    })
+  return { ...header, tools: schemas }
 }

 /**
@@ -326,38 +270,40 @@ export function normalizedSystemPromptDeltas(rawLog: string, ctx: NormalizeConte
 * the committed file follows the repository newline contract.
 *
 * @param prompt The normalized system prompt.
- * @param deltas Normalized prompt edits to append as readable sections.
+ * @param changes Full normalized prompts from later changed-header snapshots.
 * @returns Markdown snapshot text ending in a newline.
 */
 export function formatSystemPromptSnapshot(
  prompt: string,
-  deltas: readonly SystemPromptDeltaSnapshot[] = [],
+  changes: readonly string[] = [],
 ): string {
  let snapshot = prompt.endsWith('\n') ? prompt : `${prompt}\n`
-  for (const [index, delta] of deltas.entries()) {
-    snapshot += `\n<!-- request/header-delta ${index + 1}: keepStart=${delta.keepStart}, keepEnd=${delta.keepEnd} -->\n\n`
-    const insert = delta.insert.join('\n')
-    snapshot += insert.endsWith('\n') ? insert : `${insert}\n`
+  for (const [index, change] of changes.entries()) {
+    snapshot += `\n<!-- request/header change ${index + 1} -->\n\n`
+    snapshot += change.endsWith('\n') ? change : `${change}\n`
  }
  return snapshot
 }

-/** Return the initial-prompt portion of a possibly delta-bearing snapshot. */
+/** Return the initial-prompt portion of a possibly multi-header snapshot. */
 function initialSystemPromptSnapshot(snapshot: string): string {
-  const marker = snapshot.indexOf('\n<!-- request/header-delta ')
+  const marker = snapshot.indexOf('\n<!-- request/header change ')
  return marker < 0 ? snapshot : snapshot.slice(0, marker)
 }

 /**
- * Count the `request/header-delta` events in a session JSONL.
+ * Count changed `request/header` snapshots in a session JSONL.
 *
 * @param rawLog The session `.jsonl` content.
- * @returns How many `request/header-delta` events the log carries.
+ * @returns How many headers carry reason `change`.
 */
-export function headerDeltaCount(rawLog: string): number {
+export function headerChangeCount(rawLog: string): number {
  return rawLog.split('\n')
    .filter(line => line.trim().length > 0)
-    .filter(line => (JSON.parse(line) as { type?: unknown }).type === 'request/header-delta')
+    .filter((line) => {
+      const record = JSON.parse(line) as { type?: unknown; data?: { reason?: unknown } }
+      return record.type === 'request/header' && record.data?.reason === 'change'
+    })
    .length
 }

@@ -567,30 +513,19 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
            ))
          }
          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 initialSnapshot = formatSystemPromptSnapshot(prompts[0] as string)
-            for (const prompt of prompts) {
-              expect(formatSystemPromptSnapshot(prompt), 'the pinning run produced divergent system prompts')
-                .toEqual(initialSnapshot)
-            }
            const primary = result.sessionLogs[0] as HarvestedLog
-            const snapshot = formatSystemPromptSnapshot(
-              prompts[0] as string,
-              normalizedSystemPromptDeltas(primary.content, ctx),
-            )
+            const prompts = normalizedSystemPrompts(primary.content, ctx)
+            expect(prompts.length, `${mode} produced no system prompt to snapshot`).toBeGreaterThan(0)
+            const snapshot = formatSystemPromptSnapshot(prompts[0] as string, prompts.slice(1))
            await writeFile(join(dir, SYSTEM_PROMPT_SNAPSHOT), snapshot)

-            const schemaSets = result.sessionLogs.flatMap(log => normalizedToolSchemas(log.content, ctx))
+            const schemaSets = normalizedToolSchemas(primary.content, ctx)
            expect(schemaSets.length, `${mode} produced no tool schemas to snapshot`).toBeGreaterThan(0)
-            const initialSchemaSnapshot = formatToolSchemasSnapshot(schemaSets[0] as unknown[])
-            for (const schemas of schemaSets) {
-              expect(formatToolSchemasSnapshot(schemas), 'the pinning run produced divergent tool schemas')
-                .toEqual(initialSchemaSnapshot)
-            }
+            expect(schemaSets.length, `${mode} produced a tool-schema sequence that differs from its prompt sequence`)
+              .toBe(prompts.length)
            await writeFile(join(dir, TOOL_SCHEMAS_SNAPSHOT), formatToolSchemasSnapshot(
              schemaSets[0] as unknown[],
-              normalizedToolSchemaDeltas(primary.content, ctx),
+              schemaSets.slice(1),
            ))
          }
        }
@@ -614,8 +549,8 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          }
        }

-        // Header-uniformity guard: every live header in a class must equal the class pin split
-        // across tokenized JSONL plus readable prompt and structured schema sidecars.
+        // Every live full header must equal its class pin reconstructed from
+        // tokenized JSONL plus readable prompt and structured schema sidecars.
        /* 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)
@@ -623,17 +558,23 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
        const pinned = normalizedHeaders(pinnedFixture, fixtureContext(pinnedFixture))
        const promptSnapshot = await readFile(join(pinningDir, SYSTEM_PROMPT_SNAPSHOT), 'utf8')
        const initialPromptSnapshot = initialSystemPromptSnapshot(promptSnapshot)
+        expect(pinned.length, `the pinning fixture (${pinningScenario.name}) has an unexpected request/header count`)
+          .toBe(1 + (pinningScenario.expectedHeaderChanges ?? 0))
        const toolSchemasSnapshot = await readFile(join(pinningDir, TOOL_SCHEMAS_SNAPSHOT), 'utf8')
        const toolSchemas = parseToolSchemasSnapshot(toolSchemasSnapshot)
-        expect(pinned.length, `the pinning fixture (${pinningScenario.name}) must carry exactly one request/header`)
-          .toBe(1)
-        const pinnedHeader = restorePinnedToolSchemas(pinned[0], toolSchemas)
+        const pinnedSchemaSets = [toolSchemas.initial, ...toolSchemas.changes]
+        expect(pinnedSchemaSets.length, `the pinning fixture (${pinningScenario.name}) has an unexpected tool-schema count`)
+          .toBe(pinned.length)
+        const pinnedHeaders = pinned.map((header, index) => restorePinnedToolSchemas(
+          header,
+          pinnedSchemaSets[index] as unknown[],
+        ))
        for (const [logIndex, log] of result.sessionLogs.entries()) {
-          const expectedDeltas = scenario.pinsHeader === true && logIndex === 0
-            ? scenario.expectedHeaderDeltas ?? 0
+          const expectedChanges = scenario.pinsHeader === true && logIndex === 0
+            ? scenario.expectedHeaderChanges ?? 0
            : 0
-          expect(headerDeltaCount(log.content), `session ${log.id}: request/header-delta count`)
-            .toBe(expectedDeltas)
+          expect(headerChangeCount(log.content), `session ${log.id}: changed request/header count`)
+            .toBe(expectedChanges)
          const headers = normalizedHeaders(scrubSystemPrompts(log.content), ctx)
          const prompts = normalizedSystemPrompts(log.content, ctx)
          const schemaSets = normalizedToolSchemas(log.content, ctx)
@@ -642,21 +583,24 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          expect(schemaSets.length, `session ${log.id}: every request/header must carry an array-valued tools field`)
            .toBe(headers.length)
          for (const [k, header] of headers.entries()) {
+            const expected = expectedChanges > 0 ? pinnedHeaders[k] : pinnedHeaders[0]
            expect(header, `session ${log.id}: request/header #${k + 1} diverged from the pinned (${pinningScenario.name}) header`)
-              .toEqual(pinnedHeader)
-            expect(formatSystemPromptSnapshot(prompts[k] as string), `session ${log.id}: initial system prompt #${k + 1} diverged from ${pinningScenario.name}/${SYSTEM_PROMPT_SNAPSHOT}`)
-              .toEqual(initialPromptSnapshot)
+              .toEqual(expected)
+            if (expectedChanges === 0) {
+              expect(formatSystemPromptSnapshot(prompts[k] as string), `session ${log.id}: initial system prompt #${k + 1} diverged from ${pinningScenario.name}/${SYSTEM_PROMPT_SNAPSHOT}`)
+                .toEqual(initialPromptSnapshot)
+            }
          }
          if (scenario.pinsHeader === true && logIndex === 0) {
            expect(formatSystemPromptSnapshot(
              prompts[0] as string,
-              normalizedSystemPromptDeltas(log.content, ctx),
-            ), `session ${log.id}: system-prompt deltas diverged from ${pinningScenario.name}/${SYSTEM_PROMPT_SNAPSHOT}`)
+              prompts.slice(1),
+            ), `session ${log.id}: changed system prompts diverged from ${pinningScenario.name}/${SYSTEM_PROMPT_SNAPSHOT}`)
              .toEqual(promptSnapshot)
            expect(formatToolSchemasSnapshot(
              schemaSets[0] as unknown[],
-              normalizedToolSchemaDeltas(log.content, ctx),
-            ), `session ${log.id}: tool-schema deltas diverged from ${pinningScenario.name}/${TOOL_SCHEMAS_SNAPSHOT}`)
+              schemaSets.slice(1),
+            ), `session ${log.id}: changed tool schemas diverged from ${pinningScenario.name}/${TOOL_SCHEMAS_SNAPSHOT}`)
              .toEqual(toolSchemasSnapshot)
          }
        }
@@ -711,25 +655,30 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
      }
    })

-    it('every pinning fixture carries one tokenized request/header, two sidecars, 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.
+    it('every pinning fixture carries one tokenized header sequence and two sidecars', async () => {
+      // Assert the committed pin directly because a class containing only its
+      // pinning scenario has no non-pinning live run to catch undeclared changes.
      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}: unexpected request/header count`)
+          .toBe(1 + (scenario.expectedHeaderChanges ?? 0))
        const toolSchemasSnapshot = await readFile(join(snapshotsDir, scenario.name, TOOL_SCHEMAS_SNAPSHOT), 'utf8')
        const toolSchemas = parseToolSchemasSnapshot(toolSchemasSnapshot)
-        expect(headers.length, `${scenario.name}: a pinning fixture must carry exactly one request/header`).toBe(1)
-        expect(() => restorePinnedToolSchemas(headers[0], toolSchemas), `${scenario.name}: tools must use the sidecar token`)
-          .not.toThrow()
+        const schemaSets = [toolSchemas.initial, ...toolSchemas.changes]
+        expect(schemaSets.length, `${scenario.name}: tool-schema sequence must match the header sequence`)
+          .toBe(headers.length)
+        for (const [index, header] of headers.entries()) {
+          expect(() => restorePinnedToolSchemas(header, schemaSets[index] as unknown[]), `${scenario.name}: tools must use the sidecar token`)
+            .not.toThrow()
+        }
        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(toolSchemasSnapshot, `${scenario.name}/${TOOL_SCHEMAS_SNAPSHOT} must use canonical JSON formatting`)
-          .toBe(formatToolSchemasSnapshot(toolSchemas.initial, toolSchemas.deltas))
-        expect(headerDeltaCount(fixture), `${scenario.name}: a pinning fixture must carry exactly its declared request/header-deltas`)
-          .toBe(scenario.expectedHeaderDeltas ?? 0)
+          .toBe(formatToolSchemasSnapshot(toolSchemas.initial, toolSchemas.changes))
+        expect(headerChangeCount(fixture), `${scenario.name}: a pinning fixture must carry exactly its declared changed headers`)
+          .toBe(scenario.expectedHeaderChanges ?? 0)
      }
    })

--- a/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/tool-schemas.golden.json
+++ b/packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/tool-schemas.golden.json
@@ -8,5 +8,5 @@
      }
    }
  ],
-  "deltas": []
+  "changes": []
 }
--- a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/behavior.json
+++ b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/behavior.json
@@ -5,7 +5,7 @@
    "lines": [
      { "type": "session", "id": "{{SID}}", "createdAt": 100, "cwd": "{{CWD}}" },
      { "type": "request/header", "seq": 0, "time": 100, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "initial" } },
-      { "type": "request/header-delta", "seq": 1, "time": 100, "data": { "system": { "keepStart": 1, "keepEnd": 0, "insert": ["NEW PROMPT LINE"] } } },
+      { "type": "request/header", "seq": 1, "time": 100, "data": { "header": { "config": { "model": "fake" }, "system": "SYS PROMPT\n\nNEW PROMPT LINE", "tools": [{ "name": "t1", "description": "D1", "parameters": { "type": "object" } }] }, "reason": "change" } },
      { "type": "turn/start", "seq": 2, "time": 100, "data": { "turn": 1 } }
    ]
  }]
--- 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,4 +1,4 @@
 {"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":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
-{"type":"request/header-delta","seq":1,"time":7,"data":{"system":{"keepStart":1,"keepEnd":0,"insert":["{{system}}"]}}}
+{"type":"request/header","seq":1,"time":7,"data":{"header":{"config":{"model":"fake"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}}
 {"type":"turn/start","seq":2,"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
@@ -1,5 +1,7 @@
 SYS PROMPT

-<!-- request/header-delta 1: keepStart=1, keepEnd=0 -->
+<!-- request/header change 1 -->
+
+SYS PROMPT

 NEW PROMPT LINE
--- a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json
+++ b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json
@@ -8,5 +8,15 @@
      }
    }
  ],
-  "deltas": []
+  "changes": [
+    [
+      {
+        "name": "t1",
+        "description": "D1",
+        "parameters": {
+          "type": "object"
+        }
+      }
+    ]
+  ]
 }
--- a/packages/support/acp-snapshot/tests/normalize.spec.ts
+++ b/packages/support/acp-snapshot/tests/normalize.spec.ts
@@ -227,89 +227,19 @@ describe('scrubRequestHeaders', () => {
    expect(scrubRequestHeaders(`${headerLine}\n${odd}\n`)).toContain('"messagePrefix":"weird"')
  })

-  it('scrubs a header-delta prefix replacement to one token per message', () => {
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: { messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'leaked opener' }] }] },
-    })
-    const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`)
-    expect(out).toContain('"messagePrefix":["{{messagePrefix}}"]')
-    expect(out).not.toContain('leaked opener')
-    // The empty-array transition-to-absence stays a structural fact.
-    const toNone = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { messagePrefix: [] } })
-    expect(scrubRequestHeaders(`${headerLine}\n${toNone}\n`)).toContain('"messagePrefix":[]')
-  })
-
-  it('leaves a delta with no scrubbable payload byte-identical (config-only, or non-array shapes)', () => {
-    const configOnly = JSON.stringify({ type: 'request/header-delta', seq: 8, time: 9, data: { config: { model: 'm2' } } })
-    const oddShapes = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { system: { insert: 'not-an-array' }, tools: null } })
+  it('leaves malformed headers with no scrubbable payload byte-identical', () => {
    const headerless = JSON.stringify({ type: 'request/header', seq: 10, time: 9, data: { reason: 'initial' } })
    const nullData = JSON.stringify({ type: 'request/header', seq: 11, time: 9, data: null })
-    const raw = `${headerLine}\n${configOnly}\n${oddShapes}\n${headerless}\n${nullData}\n`
+    const raw = `${headerLine}\n${headerless}\n${nullData}\n`
    expect(scrubRequestHeaders(raw)).toBe(raw)
  })

-  it('scrubs a one-sided tools delta and passes non-object schema entries through', () => {
-    const addedOnly = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: { tools: { added: [null, 'weird', { name: 'x', description: 'D' }] } },
-    })
-    const out = scrubRequestHeaders(`${headerLine}\n${addedOnly}\n`)
-    // Non-object entries survive untouched; the object entry keeps only name.
-    expect(out).toContain('"added":[null,"weird",{"name":"x","description":"{{tools}}"}]')
-    const changedOnly = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: { tools: { changed: [{ name: 'y', parameters: {} }] } },
-    })
-    expect(scrubRequestHeaders(`${headerLine}\n${changedOnly}\n`))
-      .toContain('"changed":[{"name":"y","parameters":"{{tools}}"}]')
-  })
-
-  it('scrubs a header-delta system payload but keeps its line positions and arity', () => {
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: { system: { keepStart: 1, keepEnd: 4, insert: ['leaked prompt line', 'second line'] }, config: { model: 'm2' } },
-    })
-    const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`)
-    // One token PER inserted line: the edit's position AND extent survive.
-    expect(out).toContain('"insert":["{{system}}","{{system}}"]')
-    expect(out).toContain('"keepStart":1')
-    expect(out).toContain('"keepEnd":4')
-    expect(out).toContain('"config":{"model":"m2"}')
-    expect(out).not.toContain('leaked prompt line')
-    expect(out).not.toContain('{{tools}}') // no tools delta → none invented
-  })
-
-  it('scrubs a header-delta tools payload but keeps the added/removed/changed names', () => {
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: {
-        tools: {
-          added: [{ name: 'grep', description: 'Search files.', parameters: { type: 'object' } }],
-          removed: ['bash_kill'],
-          changed: [{ name: 'read', description: 'Read v2.', parameters: { type: 'object' } }],
-        },
-      },
-    })
-    const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`)
-    // WHICH tools changed is behavior and survives; their bulk does not.
-    expect(out).toContain('"added":[{"name":"grep","description":"{{tools}}","parameters":"{{tools}}"}]')
-    expect(out).toContain('"removed":["bash_kill"]')
-    expect(out).toContain('"changed":[{"name":"read","description":"{{tools}}","parameters":"{{tools}}"}]')
-    expect(out).not.toContain('Search files')
-    expect(out).not.toContain('Read v2')
-  })
-
  it('passes every other line through byte-for-byte and is idempotent', () => {
    const other = JSON.stringify({ type: 'assistant/chunk', seq: 4, time: 9, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } } })
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 8, time: 9,
-      data: { system: { keepStart: 0, keepEnd: 0, insert: ['x'] }, tools: { added: [{ name: 't', description: 'd', parameters: {} }], removed: [], changed: [] } },
-    })
-    const raw = `${headerLine}\n${headerEvent({ config: { model: 'm' }, system: 's', tools: [] })}\n${delta}\n${other}\n`
+    const raw = `${headerLine}\n${headerEvent({ config: { model: 'm' }, system: 's', tools: [] })}\n${other}\n`
    const once = scrubRequestHeaders(raw)
    expect(once.split('\n')[0]).toBe(headerLine)
-    expect(once.split('\n')[3]).toBe(other)
+    expect(once.split('\n')[2]).toBe(other)
    expect(scrubRequestHeaders(once)).toBe(once)
  })
 })
@@ -327,12 +257,15 @@ describe('scrubSystemPrompts', () => {
        reason: 'initial',
      },
    })
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 2, time: 3,
+    const changed = JSON.stringify({
+      type: 'request/header', 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' }] }],
+        header: {
+          system: 'new prompt',
+          tools: [{ name: 'read', description: 'changed schema' }],
+          messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }],
+        },
+        reason: 'change',
      },
    })
    const toolsOnly = JSON.stringify({
@@ -340,11 +273,10 @@ describe('scrubSystemPrompts', () => {
      data: { header: { tools: [{ name: 'read', description: 'schema only' }] }, reason: 'resume' },
    })

-    const out = scrubSystemPrompts(`${header}\n${delta}\n${toolsOnly}\n`)
+    const out = scrubSystemPrompts(`${header}\n${changed}\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).not.toContain('new prompt')
    expect(out).toContain('full schema')
    expect(out).toContain('full prefix')
    expect(out).toContain('changed schema')
@@ -367,12 +299,15 @@ describe('scrubToolSchemas', () => {
        reason: 'initial',
      },
    })
-    const delta = JSON.stringify({
-      type: 'request/header-delta', seq: 2, time: 3,
+    const changed = JSON.stringify({
+      type: 'request/header', seq: 2, time: 3,
      data: {
-        system: { keepStart: 1, keepEnd: 2, insert: ['new prompt line'] },
-        tools: { added: [{ name: 'grep', description: 'new schema' }], changed: [{ name: 'read', description: 'changed schema' }] },
-        messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }],
+        header: {
+          system: 'new prompt',
+          tools: [{ name: 'grep', description: 'new schema' }],
+          messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }],
+        },
+        reason: 'change',
      },
    })
    const systemOnly = JSON.stringify({
@@ -380,15 +315,12 @@ describe('scrubToolSchemas', () => {
      data: { header: { system: 'prompt only' }, reason: 'resume' },
    })

-    const out = scrubToolSchemas(`${header}\n${delta}\n${systemOnly}\n`)
-    expect(out).toContain('"tools":"{{tools}}"')
-    expect(out).toContain('"added":[{"name":"grep","description":"{{tools}}"}]')
-    expect(out).toContain('"changed":[{"name":"read","description":"{{tools}}"}]')
+    const out = scrubToolSchemas(`${header}\n${changed}\n${systemOnly}\n`)
+    expect(out.match(/"tools":"{{tools}}"/g)).toHaveLength(2)
    expect(out).not.toContain('full schema')
    expect(out).not.toContain('new schema')
-    expect(out).not.toContain('changed schema')
    expect(out).toContain('full prompt')
-    expect(out).toContain('new prompt line')
+    expect(out).toContain('new prompt')
    expect(out).toContain('full prefix')
    expect(out).toContain('changed prefix')
    expect(out.split('\n')[2]).toBe(systemOnly)
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -9,12 +9,10 @@ import {
  childFixturePaths,
  fixtureContext,
  formatSystemPromptSnapshot,
+  headerChangeCount,
  formatToolSchemasSnapshot,
-  headerDeltaCount,
  normalizedHeaders,
-  normalizedSystemPromptDeltas,
  normalizedSystemPrompts,
-  normalizedToolSchemaDeltas,
  normalizedToolSchemas,
  parseToolSchemasSnapshot,
  refreshFixtureReplacements,
@@ -45,7 +43,7 @@ const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta.

 // 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: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderChanges: 1, headerClass: 'main' },
  { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1, headerClass: 'main', configPath: AGENT.configPath },
  { name: 'no-model', hasModelTurn: false, recorded: false, headerClass: 'main' },
  { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false, headerClass: 'main' },
@@ -76,7 +74,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')
-  writeFileSync(join(dir, 'pin-turn', 'tool-schemas.golden.json'), '{"initial":[{"name":"stale"}],"deltas":[]}\n')
+  writeFileSync(join(dir, 'pin-turn', 'tool-schemas.golden.json'), '{"initial":[{"name":"stale"}],"changes":[]}\n')

  const plainBehaviorFile = join(dir, 'plain-turn', 'behavior.json')
  const plainBehavior = JSON.parse(readFileSync(plainBehaviorFile, 'utf8')) as Record<string, unknown>
@@ -127,7 +125,9 @@ describe('defineAcpSnapshotSuite: refresh write-back', () => {
    expect(readFileSync(join(refreshDir, 'pin-turn', 'system-prompt.golden.md'), 'utf8')).toBe([
      'SYS PROMPT',
      '',
-      '<!-- request/header-delta 1: keepStart=1, keepEnd=0 -->',
+      '<!-- request/header change 1 -->',
+      '',
+      'SYS PROMPT',
      '',
      'NEW PROMPT LINE',
      '',
@@ -262,65 +262,41 @@ describe('normalizedToolSchemas', () => {
  })
 })

-describe('normalizedToolSchemaDeltas', () => {
-  it('extracts and normalizes object-valued schema edits', () => {
-    const log = [
-      '{"type":"request/header-delta","data":{"tools":{"added":[{"name":"read","description":"work in /w"}]}}}',
-      '{"type":"request/header-delta","data":{"tools":null}}',
-      '{"type":"request/header-delta","data":{"tools":"invalid"}}',
-      '{"type":"request/header-delta","data":{"tools":[]}}',
-      '{"type":"request/header-delta","data":{"system":{"insert":[]}}}',
-      '{"type":"request/header","data":{"tools":{"added":[]}}}',
-      '',
-    ].join('\n')
-    expect(normalizedToolSchemaDeltas(log, { sessionIds: [], cwd: '/w' })).toEqual([
-      { added: [{ name: 'read', description: 'work in {{cwd}}' }] },
-    ])
-  })
-})
-
-describe('normalizedSystemPromptDeltas', () => {
-  it('extracts and normalizes well-formed system edits', () => {
-    const log = [
-      '{"type":"request/header-delta","data":{"system":{"keepStart":1,"keepEnd":0,"insert":["work in /w"]}}}',
-      '{"type":"request/header-delta","data":{"tools":{"replace":[]}}}',
-      '{"type":"request/header-delta","data":{"system":{"keepStart":"1","keepEnd":0,"insert":[]}}}',
-      '{"type":"request/header-delta","data":{"system":{"keepStart":1,"keepEnd":0,"insert":[null]}}}',
-      '',
-    ].join('\n')
-    expect(normalizedSystemPromptDeltas(log, { sessionIds: [], cwd: '/w' })).toEqual([
-      { keepStart: 1, keepEnd: 0, insert: ['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')
  })

-  it('renders readable system-prompt delta sections', () => {
-    expect(formatSystemPromptSnapshot('prompt', [
-      { keepStart: 1, keepEnd: 0, insert: ['new', 'lines'] },
-    ])).toBe('prompt\n\n<!-- request/header-delta 1: keepStart=1, keepEnd=0 -->\n\nnew\nlines\n')
+  it('renders readable changed-prompt sections', () => {
+    expect(formatSystemPromptSnapshot('prompt', ['new\nlines']))
+      .toBe('prompt\n\n<!-- request/header change 1 -->\n\nnew\nlines\n')
  })

-  it('does not double the newline of a delta insert with a trailing blank line', () => {
-    expect(formatSystemPromptSnapshot('prompt\n', [
-      { keepStart: 2, keepEnd: 1, insert: ['tail', ''] },
-    ])).toBe('prompt\n\n<!-- request/header-delta 1: keepStart=2, keepEnd=1 -->\n\ntail\n')
+  it('does not double the newline of a changed prompt', () => {
+    expect(formatSystemPromptSnapshot('prompt\n', ['changed\n']))
+      .toBe('prompt\n\n<!-- request/header change 1 -->\n\nchanged\n')
+  })
+})
+
+describe('headerChangeCount', () => {
+  it('counts changed request headers, ignoring anchors, blanks, and other lines', () => {
+    const change = JSON.stringify({ type: 'request/header', seq: 2, time: 9, data: { reason: 'change' } })
+    const anchor = JSON.stringify({ type: 'request/header', seq: 0, time: 9, data: { reason: 'initial' } })
+    const other = JSON.stringify({ type: 'turn/start', seq: 1, time: 9, data: {} })
+    expect(headerChangeCount(`${anchor}\n${other}\n\n${change}\n${change}\n`)).toBe(2)
+    expect(headerChangeCount(`${anchor}\n`)).toBe(0)
  })
 })

 describe('tool-schema snapshots', () => {
  const snapshot = {
    initial: [{ name: 'read', description: 'Read a file.' }],
-    deltas: [{ added: [{ name: 'grep', description: 'Search files.' }] }],
+    changes: [[{ name: 'grep', description: 'Search files.' }]],
  }

  it('formats and parses canonical structured JSON', () => {
-    const formatted = formatToolSchemasSnapshot(snapshot.initial, snapshot.deltas)
+    const formatted = formatToolSchemasSnapshot(snapshot.initial, snapshot.changes)
    expect(formatted).toBe(`${JSON.stringify(snapshot, null, 2)}\n`)
    expect(parseToolSchemasSnapshot(formatted)).toEqual(snapshot)
  })
@@ -329,29 +305,21 @@ describe('tool-schema snapshots', () => {
    expect(() => parseToolSchemasSnapshot('null')).toThrow(/must be an object/)
    expect(() => parseToolSchemasSnapshot('"invalid"')).toThrow(/must be an object/)
    expect(() => parseToolSchemasSnapshot('[]')).toThrow(/must be an object/)
-    expect(() => parseToolSchemasSnapshot('{"initial":{},"deltas":[]}')).toThrow(/array-valued/)
-    expect(() => parseToolSchemasSnapshot('{"initial":[],"deltas":{}}')).toThrow(/array-valued/)
+    expect(() => parseToolSchemasSnapshot('{"initial":{},"changes":[]}')).toThrow(/array-valued/)
+    expect(() => parseToolSchemasSnapshot('{"initial":[],"changes":{}}')).toThrow(/array-valued/)
+    expect(() => parseToolSchemasSnapshot('{"initial":[],"changes":[{}]}')).toThrow(/array-valued/)
  })

  it('restores initial schemas into the pinned header token', () => {
-    expect(restorePinnedToolSchemas({ system: '{{system}}', tools: '{{tools}}' }, snapshot))
+    expect(restorePinnedToolSchemas({ system: '{{system}}', tools: '{{tools}}' }, snapshot.initial))
      .toEqual({ system: '{{system}}', tools: snapshot.initial })
  })

  it('rejects invalid headers and a missing tool token', () => {
-    expect(() => restorePinnedToolSchemas(null, snapshot)).toThrow(/must be an object/)
-    expect(() => restorePinnedToolSchemas('invalid', snapshot)).toThrow(/must be an object/)
-    expect(() => restorePinnedToolSchemas([], snapshot)).toThrow(/must be an object/)
-    expect(() => restorePinnedToolSchemas({ tools: [] }, snapshot)).toThrow(/must equal/)
-  })
-})
-
-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: {} })
-    const other = JSON.stringify({ type: 'request/header', seq: 0, time: 9, data: {} })
-    expect(headerDeltaCount(`${other}\n\n${delta}\n${delta}\n`)).toBe(2)
-    expect(headerDeltaCount(`${other}\n`)).toBe(0)
+    expect(() => restorePinnedToolSchemas(null, snapshot.initial)).toThrow(/must be an object/)
+    expect(() => restorePinnedToolSchemas('invalid', snapshot.initial)).toThrow(/must be an object/)
+    expect(() => restorePinnedToolSchemas([], snapshot.initial)).toThrow(/must be an object/)
+    expect(() => restorePinnedToolSchemas({ tools: [] }, snapshot.initial)).toThrow(/must equal/)
  })
 })

--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -40,7 +40,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` 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).
+- **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 latest logged `request/header` (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.

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

--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -346,7 +346,7 @@ export function apply(ctx: Context): void {
  //   the boundary (an `agent/request`-window inject) is legitimately absent
  //   from this request, and a current-surface comparison would false-fire.
  // - header: every non-content field must equal the fold of the log's
-  //   `request/header*` events — the loop logs the header event BEFORE
+  //   `request/header` events — the loop logs the header event BEFORE
  //   dispatch, so the fold already covers this request.
  //
  // Registered with `prepend: true` so a short-circuiting llm/stream listener
--- a/packages/support/invariants/tests/invariants.spec.ts
+++ b/packages/support/invariants/tests/invariants.spec.ts
@@ -613,7 +613,7 @@ describe('surface contract under the invariants composition', () => {
    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
    session.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 3
    // Replace node 2 (position 0) with seq 4 — surface is now [4, 3], so seq 4
-    // precedes seq 3 in linked-list order even though 4 > 3 numerically.
+    // precedes seq 3 in surface order even though 4 > 3 numerically.
    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [2] }) // seq 4
    // A replace with start=3, end=4 passes the seq check (3 <= 4) but is
    // reversed positionally (3 is at pos 1, 4 is at pos 0).
@@ -704,7 +704,7 @@ describe('request-reconstruction cross-check (llm/stream)', () => {
  it('expects the folded header\'s session prefix ahead of the derivation (prefix + derived)', async () => {
    const { ctx, session, boundary } = await requestSetup()
    const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: '<system-reminder>catalog</system-reminder>' }] }
-    session.append('request/header-delta', { messagePrefix: [prefix] })
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' })
    // The prefixed request matches the fold…
    const prefixed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })
    expect(() => { dispatch(ctx, prefixed) }).not.toThrow()