Merge latest origin/master into parallel-tool-call

# Conflicts:
#	docs/architecture.md
#	examples/acp-agent/tests/snapshots/bash-spill/session.jsonl
#	examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl
#	examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl
#	examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl
#	packages/core/agent-loop/src/loop.ts

packages/compact/README.md

@@ -5,7 +5,7 @@ A three-package capability seam (see [capability seams](../../docs/rfc/implement
 | Package | Role | ctx key |
 |---|---|---|
 | `compact/` | Abstract compaction seam (interface + `compact/*` events + `CompactionResult`) | `ctx.compact` |
-| `compact-basic/` | A backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization | (registers `ctx.compact`) |
+| `compact-basic/` | A backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization | (registers `ctx.compact`) |
 | `tool-compact/` (deferred) | Model-facing `/compact` tool over `ctx.compact` | (registers on `ctx.tools`) |
 
-The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`. Unlike the bash seam, it depends on `dsh-session` and `dsh-llm` — its verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so the contract cannot be expressed without naming them. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam RFC](../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md). A tokenizer- or template-based backend would replace `compact-basic` without touching the interface or the tool.
+The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`. Unlike the bash seam, it depends on `dsh-session` and `dsh-llm` — its verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so the contract cannot be expressed without naming them. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam RFC](../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md). Token measurement is a reusable LLM-family service rather than a `CompactService` method; a template- or model-backed compactor can replace `compact-basic` without changing the meter or callers.

packages/compact/compact-basic/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-compact-basic
 
-The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with a chars-per-token heuristic (the `charsPerToken` config, default 4), token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call (interceptable at `llm/stream`).
+The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call (interceptable at `llm/stream`).
 
 This is the implementation tier of the compaction capability — see the [interface package](../compact/README.md) for the seam and the [capability-seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
 
@@ -8,51 +8,43 @@ This is the implementation tier of the compaction capability — see the [interf
 
 This backend owns the compaction policy:
 
-- **Estimation** — a configurable characters-per-token heuristic counts the current session prefix supplied to pre-step, derived history, and system prompt, matching the next request rather than stale logged prefix state.
+- **Measurement** — the singleton `ctx.tokenMeter` prices the provisional request envelope and current surface at one consumed-log revision. The current prompt and prefix override their logged values; the pre-step boundary reuses logged tools and call config.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes; a single unit larger than the budget remains out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
 - **Summarization** — a direct `llm/stream` call uses the configured provider/model pair and cap, falling back to the latest logged request target and then the agent target, without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
 - **Framing** — the replacement user message marks established checkpoint context with `<compacted-summary>` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint.
-- **Lifecycle** — `compactRegion()` records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
+- **Lifecycle** — `compactRegion()` requires its agent to own the exact target session and rejects mismatch before resolution or mutation; a valid call records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
 - **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. Recoverable failure records an error end and leaves the surface unchanged.
 
-`estimateContentTokens()` and `summarize()` are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the retention walk and surface plumbing. `summarize()` returns the summary blocks together with the call envelope it actually used (`{ summary, provider, model, maxTokens? }`) — the caller logs that envelope on the `compact/summary` provenance event, so an overriding backend reports its own envelope honestly.
+`summarize()` is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on `ctx.tokenMeter`. The hook returns the summary blocks together with the call envelope it used (`{ summary, provider, model, maxTokens? }`), which is logged on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
-Every knob is **required** except `auto` — there is no concrete data yet to justify default thresholds/budgets, so a consumer states each value explicitly rather than inherit a guessed default. `auto` alone defaults to `true`.
+Every setting is optional. The pressure and retention policy applies to the token meter's single context window. Unrecognized top-level keys are rejected.
 
 | Key | Required | Meaning |
 |---|---|---|
-| `contextWindow` | yes | Context window size in tokens. |
-| `thresholdRatio` | yes | Compact when estimated usage exceeds this fraction of the window. |
-| `retainTokens` | yes | Tokens of recent context to keep intact. |
-| `summarizationProvider` | yes | Provider for summarization (`''` together with an empty model → use the latest logged request pair, then the agent pair). |
-| `summarizationModel` | yes | Model for summarization (`''` together with an empty provider → use the latest logged request pair, then the agent pair). |
-| `maxTokens` | yes | Provider generation cap for the summarization call; may include reasoning tokens. |
-| `compactionRetries` | yes | Extra compaction attempts after the first if the compacted surface remains over threshold. |
-| `auto` | no (default `true`) | Register the `agent/pre-step` auto-compaction listener. Set `false` for manual-only. |
-| `charsPerToken` | no (default `4`) | Token-estimator text density (estimated tokens = chars / `charsPerToken`; may be fractional). The default suits English text; CJK-heavy deployments should set ~1-2 or the estimate undershoots several-fold and compaction fires too late. |
+| `thresholdRatio` | no (default `0.8`) | Compact at `floor(contextWindow × ratio)`. |
+| `retainTokens` | no (default `floor(contextWindow × 0.16)`) | Recent surface budget kept verbatim; must be below the threshold. |
+| `summarizationProvider` | no (default `''`) | Set together with `summarizationModel`; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. |
+| `summarizationModel` | no (default `''`) | Set together with `summarizationProvider`; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. |
+| `maxTokens` | no (default `8192`) | Provider generation cap for the summarization call; may include reasoning tokens. |
+| `compactionRetries` | no (default `1`) | Extra attempts after the first when pressure remains above threshold. |
+| `auto` | no (default `true`) | Register the `agent/pre-step` automatic listener. Set `false` for manual-only. |
 
 ## Usage
 
 ```ts
 import type { Context } from 'cordis'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 
 export const name = 'compact-basic'
 export const inject = ['llm']
 
 export function apply(ctx: Context): void {
-  ctx.plugin(BasicCompactService, {
-    contextWindow: 128000,
-    thresholdRatio: 0.8,
-    retainTokens: 20480,
-    summarizationProvider: '',
-    summarizationModel: '',
-    maxTokens: 8192,
-    compactionRetries: 1,
-  })
+  ctx.plugin(TokenMeterService)
+  ctx.plugin(BasicCompactService)
 }
 ```
 
@@ -124,8 +116,8 @@ Rules:
 
 ## Known Limitations and Deferred Work
 
-- **Token estimation is the chars/`charsPerToken` heuristic** — a marked TODO schedules replacing it with an exact count (a real tokenizer, or provider `usage` fed back) so thresholds track the model's actual budget.
-- **`estimatePressure()` does not count the request's `tools` field** — pressure is underestimated by the size of the serialized tool schemas the request also carries.
+- **Pre-step sees a provisional request envelope** — the current prompt and prefix are exact, but routing and tool changes made later in `agent/request` are not logged yet. A router-only agent with no provisional provider/model pair skips that check.
+- **Meter accuracy follows the fixed heuristic** — missing reusable provider usage falls back to character count plus structural overhead rather than exact tokenization.
 - **`compactRegion` requires an open turn** — a manual call on a fully-closed session throws ("no open turn") rather than compacting.
 - **Summarization failure fails closed with full, over-budget history** — including truncation at the summarization `maxTokens`, which hidden reasoning tokens can consume; the auto path logs a warning and proceeds.
 - **The summarization call has no transcript-snapshot coverage** — `dsh-llm-replay` derives calls from `assistant/chunk` events, so this chunk-less direct `ctx.llm.stream()` call cannot replay (named deferred replay infrastructure in [the seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)).

packages/compact/compact-basic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-compact-basic",
-  "description": "Basic compaction backend (chars-per-token estimation + token-budget retention + llm.generate() summarization) for the DeepSeek Harness",
+  "description": "Token-meter-driven compaction policy and LLM summarization backend for the DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -26,9 +26,15 @@
     "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
@@ -36,6 +42,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/compact/compact-basic/src/automatic.ts

@@ -0,0 +1,52 @@
+/**
+ * Automatic pre-step pressure listener for compact-basic.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/automatic
+ */
+
+import type { Context } from 'cordis'
+import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+
+interface AutomaticCompactor {
+  compactIfNeeded(
+    agent: Agent,
+    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
+    signal: AbortSignal,
+  ): Promise<CompactionResult | null>
+}
+
+/**
+ * Register the implementation-owned automatic compaction listener.
+ * @param ctx - context owning the listener effect and logger.
+ * @param service - compactor whose public methods remain dynamically dispatched.
+ */
+export function registerAutomaticCompaction(
+  ctx: Context,
+  service: AutomaticCompactor,
+): void {
+  ctx.on('agent/pre-step', async (
+    agent: Agent,
+    _turn: number,
+    _step: number,
+    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
+    signal: AbortSignal,
+  ) => {
+    try {
+      const result = await service.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
+      if (result !== null) {
+        ctx.logger.info(
+          `compaction: shadowed ${result.shadowedSeqs.length} surface nodes `
+          + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, `
+          + `~${result.shadowedTokenCount} tokens)`,
+        )
+      }
+    } catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      ctx.logger.warn(`compaction failed: ${message}; proceeding with full history`)
+    }
+  })
+}

packages/compact/compact-basic/src/config.ts

@@ -0,0 +1,107 @@
+/**
+ * Runtime defaulting and policy validation for compact-basic.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/config
+ */
+
+import { deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { TokenMeterService } from '@deepseek-ai/dsh-token-meter'
+import type { BasicCompactConfig, ResolvedConfig } from './types.ts'
+
+/** Default request-pressure fraction of the token meter's context window. */
+const DEFAULT_THRESHOLD_RATIO = 0.8
+
+/** Default verbatim-tail fraction of the token meter's context window. */
+const DEFAULT_RETAIN_RATIO = 0.16
+
+/** Complete public configuration key set. */
+const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  'thresholdRatio',
+  'retainTokens',
+  'summarizationProvider',
+  'summarizationModel',
+  'maxTokens',
+  'compactionRetries',
+  'auto',
+])
+
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateConfigKeys(config: BasicCompactConfig): void {
+  for (const key of Object.keys(config)) {
+    if (!BASIC_COMPACT_CONFIG_KEYS.has(key)) {
+      throw new Error(
+        `BasicCompactConfig: unknown key "${key}" `
+        + '(allowed: thresholdRatio, retainTokens, summarizationProvider, summarizationModel, maxTokens, compactionRetries, auto)',
+      )
+    }
+  }
+}
+
+/**
+ * Resolve defaults and validate the service-wide compaction policy.
+ * @param config - raw compact-basic configuration.
+ * @param tokenMeter - token meter supplying the context capacity.
+ * @returns a detached deeply immutable configuration.
+ */
+export function resolveConfig(
+  config: BasicCompactConfig = {},
+  tokenMeter: TokenMeterService,
+): ResolvedConfig {
+  validateConfigKeys(config)
+  const thresholdRatio = config.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO
+  const retainTokens = config.retainTokens
+    ?? Math.floor(tokenMeter.contextWindow * DEFAULT_RETAIN_RATIO)
+  const resolved: ResolvedConfig = {
+    thresholdRatio,
+    retainTokens,
+    summarizationProvider: config.summarizationProvider ?? '',
+    summarizationModel: config.summarizationModel ?? '',
+    maxTokens: config.maxTokens ?? 8192,
+    compactionRetries: config.compactionRetries ?? 1,
+    auto: config.auto ?? true,
+  }
+
+  assertRatio('thresholdRatio', resolved.thresholdRatio)
+  assertNonNegativeInteger('retainTokens', resolved.retainTokens)
+  const thresholdTokens = Math.floor(tokenMeter.contextWindow * resolved.thresholdRatio)
+  if (resolved.retainTokens >= thresholdTokens) {
+    throw new Error(
+      `BasicCompactConfig: retainTokens (${resolved.retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
+    )
+  }
+  assertPositiveInteger('maxTokens', resolved.maxTokens)
+  assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
+  if (typeof resolved.summarizationProvider !== 'string') {
+    throw new Error('BasicCompactConfig: summarizationProvider must be a string')
+  }
+  if (typeof resolved.summarizationModel !== 'string') {
+    throw new Error('BasicCompactConfig: summarizationModel must be a string')
+  }
+  if ((resolved.summarizationProvider.length === 0) !== (resolved.summarizationModel.length === 0)) {
+    throw new Error(
+      'BasicCompactConfig: summarizationProvider and summarizationModel must both be set or both be empty',
+    )
+  }
+  if (typeof resolved.auto !== 'boolean') {
+    throw new Error('BasicCompactConfig: auto must be a boolean')
+  }
+  return deepFreeze(resolved)
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive integer`)
+  }
+}
+
+function assertNonNegativeInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a non-negative integer`)
+  }
+}
+
+function assertRatio(name: string, value: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a number in (0, 1]`)
+  }
+}

packages/compact/compact-basic/src/index.ts

@@ -1,291 +1,118 @@
 /**
- * Basic compaction backend. It estimates request pressure, retains a recent
- * tool-balanced surface tail, summarizes the older head through a one-shot model
- * call, and replaces that head with one checkpoint. Auto-compaction runs before
- * every step so a growing turn can compact its earlier closed steps.
+ * Basic replay-aware compaction backend.
+ *
  * @module @deepseek-ai/dsh-compact-basic
  */
 
 import { Context } from 'cordis'
-import { CompactService, renderTranscript, toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import z from 'schemastery'
+import { CompactService } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import { BlockAssembler } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { BasicCompactConfig, ResolvedConfig } from './types.ts'
-import { resolveConfig } from './types.ts'
+import { registerAutomaticCompaction } from './automatic.ts'
+import { resolveConfig } from './config.ts'
+import { compactSurfaceRegion, selectCompactableRange } from './region.ts'
+import { summarizeWithLlm } from './summarizer.ts'
+import type {
+  BasicCompactConfig,
+  ResolvedConfig,
+} from './types.ts'
 
-export type { BasicCompactConfig, ResolvedConfig } from './types.ts'
-export { resolveConfig } from './types.ts'
+export { resolveConfig } from './config.ts'
+export type {
+  BasicCompactConfig,
+  ResolvedConfig,
+} from './types.ts'
 
-/** Per-block structural overhead for JSON framing / type tag. */
-const BLOCK_OVERHEAD = 4
-
-/** Role-field framing overhead added per message in {@link BasicCompactService.estimateTokens}. */
-const ROLE_OVERHEAD = 4
-
-/** Tags wrapping the structured summary inside the landed checkpoint node. */
-const SUMMARY_OPEN_TAG = '<compacted-summary>'
-const SUMMARY_CLOSE_TAG = '</compacted-summary>'
-
-/**
- * Fixed summary structure for resumable checkpoints. A tagged prior checkpoint
- * is merged with newer history instead of copied forward verbatim.
- */
-const SUMMARIZE_SYSTEM_PROMPT = [
-  'You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.',
-  '',
-  'Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section.',
-  '',
-  '## Primary Request and Intent',
-  "- [the user's original and evolving goals; quote verbatim where the exact wording matters]",
-  '',
-  '## Key Technical Concepts',
-  '- [technologies, frameworks, patterns, and conventions in play]',
-  '',
-  '## Files and Code',
-  '- [exact path: why it matters, key changes or snippets]',
-  '',
-  '## Errors and Fixes',
-  '- [error: how it was resolved, plus any related user feedback]',
-  '',
-  '## Pending Tasks',
-  '- [explicitly requested work not yet completed]',
-  '',
-  '## Current Work',
-  '- [precisely what was in progress at this checkpoint]',
-  '',
-  '## Next Step',
-  '- [the single next action, directly in line with the most recent request, or "(none)"]',
-  '',
-  '## Critical Context',
-  '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
-  '',
-  'Rules:',
-  '- Preserve exact file paths, commands, error strings, identifiers, and function signatures.',
-  '- Capture user feedback and explicit instructions faithfully, especially corrections.',
-  '- Do NOT mention this summarization process or that the context was compacted.',
-  `- If the transcript already contains a ${SUMMARY_OPEN_TAG} block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.`,
-].join('\n')
-
-/** Framing that makes a landed summary established context rather than a new request. */
-const CHECKPOINT_PREAMBLE =
-  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.'
-
-/**
- * Map a terminal summary failure to an error. A max-token finish is rejected
- * because committing an incomplete checkpoint would shadow the full history.
- */
-function finishError(finish: FinishReason): Error | undefined {
-  switch (finish.kind) {
-    case 'error': {
-      const error = new Error(finish.message) as Error & { code?: string }
-      if (finish.code !== undefined) error.code = finish.code
-      return error
-    }
-    case 'aborted': {
-      const error = new Error('summarization stream aborted') as Error & { code?: string }
-      error.code = 'ABORTED'
-      return error
-    }
-    case 'max-tokens': {
-      const error = new Error('summarization truncated at the token cap (incomplete checkpoint)') as Error & { code?: string }
-      error.code = 'MAX_TOKENS'
-      return error
-    }
-    default:
-      return undefined
+/** Resolve the latest actual routed provider/model, then the complete agent fallback pair. */
+function effectiveTarget(agent: Agent): { provider: string; model: string } | undefined {
+  const latest = agent.session.requestHeader()?.config
+  if (latest !== undefined) return { provider: latest.provider, model: latest.model }
+  const { provider, model } = agent.options
+  if (provider === undefined || provider.length === 0 || model === undefined || model.length === 0) {
+    return undefined
   }
+  return { provider, model }
 }
 
 /**
- * Basic, dependency-light compaction backend: estimates the surface's token
- * footprint, summarizes the stale prefix through the model, and shadows it
- * behind a durable checkpoint. Every threshold/budget knob is required config
- * ({@link BasicCompactConfig}); the estimator's text density is the
- * `charsPerToken` knob.
+ * Build the provisional pre-step request envelope. Prompt and prefix are exact;
+ * tools and non-model call config come from the latest logged request because
+ * later request middleware has not run yet.
+ */
+function provisionalHeader(
+  target: { provider: string; model: string },
+  session: Session,
+  fullSystemPrompt: string,
+  sessionPrefix: readonly Message[],
+): EpochHeader {
+  const latest = session.requestHeader()
+  return canonicalHeader({
+    config: latest === undefined ? target : { ...latest.config, ...target },
+    ...fullSystemPrompt.length === 0 ? {} : { system: fullSystemPrompt },
+    ...latest?.tools === undefined ? {} : { tools: latest.tools },
+    ...sessionPrefix.length === 0 ? {} : { messagePrefix: [...sessionPrefix] },
+  })
+}
+
+/**
+ * Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
+ * retention, provenance, and summary-convergence pricing.
+ *
+ * `summarize()` is the sole subclass customization hook; the replay and durable
+ * mutation strategy stays fixed so every pricing decision uses the singleton
+ * token meter.
  */
 export class BasicCompactService extends CompactService {
-  static inject = ['llm']
+  static inject = ['llm', 'tokenMeter']
 
-  /** Resolved configuration (`auto` defaulted). */
+  static Config: z<BasicCompactConfig> = z.object({
+    thresholdRatio: z.number().default(0.8),
+    retainTokens: z.number().step(1),
+    summarizationProvider: z.string().default(''),
+    summarizationModel: z.string().default(''),
+    maxTokens: z.number().step(1).min(1).default(8192),
+    compactionRetries: z.number().step(1).min(0).default(1),
+    auto: z.boolean().default(true),
+  })
+
+  /** Resolved and validated compaction configuration. */
   readonly config: ResolvedConfig
 
-  constructor(ctx: Context, config: BasicCompactConfig) {
+  constructor(ctx: Context, config: BasicCompactConfig = {}) {
     super(ctx)
-    this.config = resolveConfig(config)
-
-    if (this.config.auto) {
-      // Check before every step so a single growing turn can compact earlier closed steps.
-      // This serial pre-step seam mutates the surface outside the pending step.
-      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => {
-        try {
-          const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
-          if (result) {
-            const after = this.estimatePressure(agent.session, fullSystemPrompt, sessionPrefix)
-            ctx.logger.info(
-              `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` +
-              `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` +
-              `~${result.shadowedTokenCount} tokens) ` +
-              `→ ${after} estimated tokens after compaction`,
-            )
-          }
-        } catch (error: unknown) {
-          // A failed compaction must not prevent the model call — the surface is
-          // untouched on failure, so the loop derives the full history and the
-          // call proceeds.
-          const msg = error instanceof Error ? error.message : String(error)
-          ctx.logger.warn(`compaction failed: ${msg}; proceeding with full history`)
-        }
-      })
-    }
-  }
-
-  // ---- Token estimation (overridable hooks) ----
-
-  // TODO: chars/charsPerToken is a coarse heuristic. Replace with an exact
-  // count — a real tokenizer, or the provider's post-response `usage` (input
-  // tokens) fed back as a correction — so threshold decisions match the
-  // model's actual budget.
-  /**
-   * Estimate the token count of content blocks — chars divided by the
-   * `charsPerToken` config, with per-block overhead. Override in a subclass to
-   * plug in a real tokenizer.
-   *
-   * @param blocks - the blocks to estimate; `tool-result` blocks recurse into
-   *   their nested content, and unknown (merge-extended) types fall back to
-   *   their JSON-stringified length.
-   * @returns the estimated token count.
-   */
-  estimateContentTokens(blocks: readonly ContentBlock[]): number {
-    const { charsPerToken } = this.config
-    let tokens = 0
-    for (const block of blocks) {
-      switch (block.type) {
-        case 'text':
-        case 'reasoning':
-          tokens += Math.ceil(block.text.length / charsPerToken) + BLOCK_OVERHEAD
-          break
-        case 'tool-call':
-          tokens += Math.ceil(block.name.length / charsPerToken)
-            + Math.ceil(block.arguments.length / charsPerToken)
-            + BLOCK_OVERHEAD
-          break
-        case 'tool-result':
-          tokens += this.estimateContentTokens(block.content) + BLOCK_OVERHEAD
-          break
-        default:
-          // Unknown block types (merge-extensible ContentBlockMap):
-          // estimate conservatively via JSON stringify.
-          tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / charsPerToken)
-      }
-    }
-    return tokens
+    this.config = resolveConfig(config, ctx.tokenMeter)
+    if (this.config.auto) registerAutomaticCompaction(ctx, this)
   }
 
   /**
-   * Estimate token count for a single session event. Returns 0 for non-message
-   * event types (boundaries, chunks, usage, errors, compact markers).
-   *
-   * @param event - any session event; only the message-bearing types carry
-   *   content to count.
-   * @returns the estimated token count of the event's content, or 0 for a
-   *   non-message event.
-   */
-  estimateEventTokens(event: SessionEvent): number {
-    switch (event.type) {
-      case 'user/message':
-      case 'assistant/message':
-      case 'context/message':
-      case 'steering/message':
-      case 'tool/result':
-        return this.estimateContentTokens(event.data.content)
-      default:
-        return 0
-    }
-  }
-
-  /**
-   * Estimate total tokens across a list of messages plus optional system prompt.
-   *
-   * @param messages - the derived conversation messages; each adds a fixed
-   *   role-framing overhead on top of its content estimate.
-   * @param systemPrompt - counted at chars / `charsPerToken` when provided.
-   * @returns the estimated token footprint of the whole request.
-   */
-  estimateTokens(messages: readonly Message[], systemPrompt?: string): number {
-    let total = 0
-    for (const msg of messages) {
-      total += this.estimateContentTokens(msg.content)
-      total += ROLE_OVERHEAD
-    }
-    if (systemPrompt) total += Math.ceil(systemPrompt.length / this.config.charsPerToken)
-    return total
-  }
-
-  /**
-   * Summarize through a direct one-shot `ctx.llm.stream()` call, not an agent
-   * step or `agent/request` dispatch. Failure finishes and truncated summaries
-   * reject; the signal is forwarded, only text reaches the checkpoint, and the
-   * returned envelope identifies the provider/model actually used.
-   *
-   * @param text - plain-text rendering of the conversation region to condense.
-   * @param agent - supplies the request-header/creation fallback target and the
-   *   session id stamped on the call; throws when no complete target exists.
-   * @param signal - optional abort signal, forwarded into the model call.
-   * @returns the text-only summary blocks plus the call envelope used
-   *   (`provider`, `model`, and `maxTokens` when the summarizer has a cap).
+   * Summarize a rendered region through a direct one-shot `ctx.llm.stream()`
+   * call. Override this sole hook for a template or remote summarizer.
+   * @param text - plain-text conversation region to condense.
+   * @param agent - supplies routed-model history, fallback model, and session id.
+   * @param signal - optional cancellation forwarded to the adapter.
+   * @returns safe text summary blocks and exact auxiliary-call provenance.
    */
   async summarize(
-    text: string, agent: Agent, signal?: AbortSignal,
+    text: string,
+    agent: Agent,
+    signal?: AbortSignal,
   ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> {
-    const assembler = new BlockAssembler()
-    const logged = agent.session.requestHeader()?.config
-    const provider = this.config.summarizationProvider || logged?.provider || agent.options.provider || ''
-    const model = this.config.summarizationModel || logged?.model || agent.options.model || ''
-    const options: GenerateOptions = {
-      provider,
-      model,
-      messages: [{
-        role: 'user',
-        content: [{ type: 'text', text: `Summarize this conversation history:\n\n${text}\n\nSummary:` }],
-      }],
-      system: SUMMARIZE_SYSTEM_PROMPT,
-      maxTokens: this.config.maxTokens,
-      sessionId: agent.session.id,
-    }
-    // exactOptionalPropertyTypes: only set `signal` when present — assigning
-    // `undefined` to an optional `signal?: AbortSignal` is a type error.
-    if (signal) options.signal = signal
-    if (!options.provider || !options.model) {
-      throw new Error('no provider/model available for summarization: set both summarization fields or provide a logged/agent target')
-    }
-    for await (const chunk of this.ctx.llm.stream(options)) {
-      assembler.push(chunk)
-    }
-
-    const error = finishError(assembler.finish)
-    if (error) throw error
-
-    const summary = this._textOnly(assembler.message().content)
-    if (!summary.some(block => block.type === 'text' && block.text.trim().length > 0)) {
-      throw new Error('summarization produced no text summary content')
-    }
-
-    // config.maxTokens is required and validated positive, so this backend's
-    // envelope always carries the cap; the return type's optionality exists
-    // for overriding subclasses whose summarizer has none.
-    return { summary, provider: options.provider, model: options.model, maxTokens: this.config.maxTokens }
+    return summarizeWithLlm(this.ctx, this.config, text, agent, signal)
   }
 
-  // ---- Core API (implements the abstract contract) ----
-
   /**
-   * The sole pressure gate: count the next request's prefix, derived history,
-   * and system prompt. Above threshold, retain a recent tool-balanced tail and
-   * compact the head, reconsolidating any prior automatic checkpoint. Returns
-   * `null` when no safe or necessary range exists.
+   * Check replayed pressure for the provisional pre-step envelope and compact
+   * a tool-balanced head until it falls below the service-wide threshold.
+   * A genuinely model-less router-first step skips this provisional check.
+   * @param agent - agent whose session and provisional provider/model are measured.
+   * @param fullSystemPrompt - current assembled system prompt override.
+   * @param sessionPrefix - current request-only prefix override.
+   * @param signal - live step cancellation signal forwarded to summarization.
+   * @returns the latest compaction result, or `null` when no check/work applies.
    */
   override async compactIfNeeded(
     agent: Agent,
@@ -293,47 +120,45 @@ export class BasicCompactService extends CompactService {
     sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
-    const session = agent.session
-    const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio)
-    let result: CompactionResult | null = null
-    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) {
-      const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
-      if (totalTokens < threshold) return result
+    const target = effectiveTarget(agent)
+    if (target === undefined) return null
+    const meter = this.ctx.tokenMeter
+    const requestHeader = provisionalHeader(target, agent.session, fullSystemPrompt, sessionPrefix)
+    const threshold = Math.floor(meter.contextWindow * this.config.thresholdRatio)
+    let measurement = meter.measure(agent.session, requestHeader)
+    if (measurement.totalTokens < threshold) return null
 
-      const range = this._compactableRange(session)
+    let result: CompactionResult | null = null
+    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt += 1) {
+      const range = selectCompactableRange(agent.session, measurement, this.config.retainTokens)
       if (range === null) {
-        /* v8 ignore else -- defensive for non-standard subclass mutations; the concrete replace keeps a compactable head checkpoint. */
+        /* v8 ignore else -- concrete replacement preserves a compactable checkpoint; subclass hooks cannot mutate it. */
         if (result === null) return null
-        /* v8 ignore next -- paired with the ignored defensive branch above. */
+        /* v8 ignore next -- paired with the defensive post-success branch above. */
         break
       }
-
-      result = await this.compactRegion(session, range.start, range.end, agent, signal)
+      result = await this.compactRegion(agent.session, range.start, range.end, agent, signal)
+      measurement = meter.measure(agent.session, requestHeader)
+      if (measurement.totalTokens < threshold) return result
     }
 
-    const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
-    if (totalTokens < threshold) return result
-
     throw new Error(
       `compaction still above threshold after ${this.config.compactionRetries + 1} compaction attempts `
-      + `(${totalTokens} estimated tokens >= threshold ${threshold})`,
+      + `(${measurement.totalTokens} estimated tokens >= threshold ${threshold})`,
     )
   }
 
   /**
-   * Estimated token pressure of the NEXT request: the session prefix
-   * (`EpochHeader.messagePrefix` — request-only messages the loop sends in
-   * front of the derived history, composed before the pre-step seam and
-   * handed to the gate), the derived history, and the system prompt.
-   * @param session - the session whose next request is being estimated.
-   * @param fullSystemPrompt - the assembled system prompt (counts toward pressure).
-   * @param sessionPrefix - the instance's composed session prefix (counts toward pressure).
-   * @returns the estimated token total the next request will carry.
+   * Compact one inclusive positional surface range using the effective
+   * token meter for all retention and shrink pricing. Reject an agent that does
+   * not own the exact target before any mutation.
+   * @param session - session whose surface is mutated; must equal `agent.session`.
+   * @param start - inclusive first surface-node seq.
+   * @param end - inclusive last surface-node seq.
+   * @param agent - owner of the target session, used by the summarizer.
+   * @param signal - optional summarization cancellation signal.
+   * @returns the successful durable compaction result.
    */
-  estimatePressure(session: Session, fullSystemPrompt: string, sessionPrefix: readonly Message[]): number {
-    return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt)
-  }
-
   override async compactRegion(
     session: Session,
     start: number,
@@ -341,215 +166,13 @@ export class BasicCompactService extends CompactService {
     agent: Agent,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
-    // Resolve by surface position: a newer replacement seq may occupy an older slot.
-    const nodes = session.surface.nodes
-    const startIdx = nodes.findIndex(n => n.seq === start)
-    const endIdx = nodes.findIndex(n => n.seq === end)
-    if (startIdx === -1) throw new Error(`compactRegion: start seq ${start} not found in surface`)
-    if (endIdx === -1) throw new Error(`compactRegion: end seq ${end} not found in surface`)
-    if (startIdx > endIdx) {
-      throw new Error(`compactRegion: start seq ${start} (position ${startIdx}) is after end seq ${end} (position ${endIdx}) on the surface`)
+    if (session !== agent.session) {
+      throw new Error('compactRegion: agent.session must be the exact target session')
     }
-
-    // Both range edges must preserve assistant tool-call/result pairing.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const startNode = nodes[startIdx]!
-    if (!toolPairingBalancedBefore(session, startNode)) {
-      throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`)
-    }
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const endNode = nodes[endIdx]!
-    if (!toolPairingBalancedAfter(session, endNode)) {
-      throw new Error(`compactRegion: end seq ${end} is not a balanced boundary (would split a step, or the step is still open)`)
-    }
-
-    if (this._isCompactionInProgress(session)) {
-      throw new Error('compaction already in progress')
-    }
-
-    // Compaction's events (compact/* and the replacement user/message) must be turn-enclosed:
-    // the session-log contract rejects any plugin event appended outside an open turn.
-    const openTurn = this._openTurn(session)
-    if (openTurn === null) {
-      throw new Error('compactRegion: no open turn — compaction events must be enclosed in a turn')
-    }
-    // Slice the ordered surface nodes [startIdx, endIdx] inclusive — the
-    // shadowed range is positional, so this is the set the replace op covers.
-    const shadowedSeqs = nodes.slice(startIdx, endIdx + 1).map(n => n.seq)
-
-    // --- Acquire lock ---
-    const startEvent = session.append('compact/start', { turn: openTurn })
-
-    try {
-      // --- Extract text and summarize ---
-      const text = renderTranscript(session.events, shadowedSeqs)
-      const { summary, provider, model, maxTokens } = await this.summarize(text, agent, signal)
-
-      // Estimate token count of the shadowed content for provenance.
-      let shadowedTokenCount = 0
-      for (const seq of shadowedSeqs) {
-        // seq comes from a surface node — always a valid log index by construction.
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        shadowedTokenCount += this.estimateEventTokens(session.events[seq]!)
-      }
-      const framedSummary = this._frameSummary(summary)
-      const framedSummaryTokenCount = this.estimateContentTokens(framedSummary)
-      if (framedSummaryTokenCount >= shadowedTokenCount) {
-        throw new Error(
-          `summary is not smaller than the shadowed content (${framedSummaryTokenCount} estimated framed tokens >= ${shadowedTokenCount})`,
-        )
-      }
-      // --- Provenance record (log-only) ---
-      const summaryEvent = session.append('compact/summary', {
-        summary,
-        shadowedRange: { start, end },
-        shadowedSeqs,
-        shadowedTokenCount,
-        provider,
-        model,
-        ...maxTokens !== undefined ? { maxTokens } : {},
-      })
-
-      // --- Surface replacement --- The user/message directly shadows all compacted surface
-      // nodes with a single replace op.
-      session.append('user/message', {
-        content: framedSummary,
-        source: { kind: 'plugin', plugin: 'compact' },
-      }, {
-        surfaceOp: { op: 'replace', start, end },
-        sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
-      })
-
-      // --- Release lock (log-only) ---
-      // Appended LAST so the lock brackets the WHOLE operation: a crash between
-      // compact/start and here leaves a detectable orphaned lock (a compact/start
-      // with no matching compact/end) rather than a compact/end that falsely
-      // claims compaction finished before the surface replacement landed.
-      const endEvent = session.append('compact/end', { turn: openTurn })
-
-      return {
-        startSeq: startEvent.seq,
-        summarySeq: summaryEvent.seq,
-        endSeq: endEvent.seq,
-        summary,
-        shadowedRange: { start, end },
-        shadowedSeqs,
-        shadowedTokenCount,
-      }
-    } catch (error: unknown) {
-      // Always release the lock — append compact/end with the error so a
-      // wedged lock is impossible.
-      const msg = error instanceof Error ? error.message : String(error)
-      session.append('compact/end', { turn: openTurn, error: msg })
-      throw error
-    }
-  }
-
-  // ---- Internal helpers ----
-
-  /**
-   * Frame the raw summary blocks into the content that lands on the surface:
-   * a checkpoint preamble (so a resuming model reads it as a checkpoint, not a
-   * fresh user request) followed by the summary wrapped in
-   * {@link SUMMARY_OPEN_TAG}/{@link SUMMARY_CLOSE_TAG}. The tags make a prior
-   * checkpoint detectable in the transcript on the next compaction cycle, which
-   * triggers the merge rule in the summarization prompt. The raw, unframed
-   * `summary` is preserved separately on the `compact/summary` provenance event.
-   */
-  private _frameSummary(summary: readonly ContentBlock[]): ContentBlock[] {
-    return [
-      { type: 'text', text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
-      ...summary,
-      { type: 'text', text: SUMMARY_CLOSE_TAG },
-    ]
-  }
-
-  /**
-   * Whether a compaction is currently in progress for `session` — an unmatched `compact/start`
-   * (no later `compact/end`) WITHIN the current turn.
-   */
-  private _isCompactionInProgress(session: Session): boolean {
-    const events = session.events
-    for (let i = events.length - 1; i >= 0; i--) {
-      // Index bounded by i >= 0 and i < events.length — never undefined.
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const e = events[i]!
-      if (e.type === 'compact/start') return true
-      if (e.type === 'compact/end') break
-      // A turn/end bounds the scan: anything before it belongs to a prior
-      // (closed) turn and cannot be an in-progress compaction of THIS turn.
-      if (e.type === 'turn/end') break
-    }
-    return false
-  }
-
-  /** Resolve the next head-anchored compactable surface range, or `null`. */
-  private _compactableRange(session: Session): { start: number; end: number } | null {
-    const nodes = session.surface.nodes
-    if (nodes.length === 0) return null
-
-    const events = session.events
-    const retainBudget = this.config.retainTokens
-
-    // Walk tail→head summing per-node token estimates. `keepFromIdx` is the
-    // index of the OLDEST node we retain verbatim; everything strictly older
-    // (`[0, keepFromIdx - 1]`) is the compactable range.
-    let accumulated = 0
-    let keepFromIdx = nodes.length // nothing retained yet
-    for (let i = nodes.length - 1; i >= 0; i--) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const node = nodes[i]!
-      const event = events[node.seq]
-      /* v8 ignore next -- node.seq is a surface-node seq, always a valid log index by construction */
-      if (event) accumulated += this.estimateEventTokens(event)
-      keepFromIdx = i
-      if (accumulated >= retainBudget) break
-    }
-
-    // The whole surface fits the retain budget — nothing to compact.
-    if (keepFromIdx === 0) return null
-
-    // Round the cutoff to a tool-pairing boundary: if the cut before `nodes[keepFromIdx]` is
-    // unbalanced (an unanswered tool-call sits before it — i.e. it is mid-step), extend the
-    // retained side head-ward until the cut is balanced, so the compacted range ends without
-    // splitting an assistant↔result pair.
-    while (keepFromIdx > 0) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      if (toolPairingBalancedBefore(session, nodes[keepFromIdx]!)) break
-      keepFromIdx -= 1
-    }
-    if (keepFromIdx === 0) return null
-
-    // The compacted range is [head … keepFromIdx - 1], anchored at the head.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const firstSeq = nodes[0]!.seq
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const cutoffSeq = nodes[keepFromIdx - 1]!.seq
-    return { start: firstSeq, end: cutoffSeq }
-  }
-
-  /** Keep only text; checkpoints cannot contain reasoning or orphan tool calls. */
-  private _textOnly(blocks: readonly ContentBlock[]): ContentBlock[] {
-    return blocks.filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
-  }
-
-  /**
-   * The turn number of the currently OPEN turn — a `turn/start` not yet
-   * followed by its `turn/end` — or `null` if the session has no open turn.
-   *
-   * Compaction's events must be enclosed in a turn, so scanning back from the
-   * tail: a `turn/start` means that turn is open (return it); a `turn/end` means
-   * the most recent turn already closed (return null). The whole compaction
-   * sequence (compact/start … compact/end) is stamped with this turn.
-   */
-  private _openTurn(session: Session): number | null {
-    for (let i = session.events.length - 1; i >= 0; i--) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const e = session.events[i]!
-      if (e.type === 'turn/start') return e.data.turn
-      if (e.type === 'turn/end') return null
-    }
-    return null
+    return compactSurfaceRegion({
+      meter: this.ctx.tokenMeter,
+      summarize: (text, owner, abort) => this.summarize(text, owner, abort),
+    }, session, start, end, agent, signal)
   }
 }
 

packages/compact/compact-basic/src/region.ts

@@ -0,0 +1,197 @@
+/**
+ * Surface retention selection and the log-recorded compaction transaction.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/region
+ */
+
+import {
+  renderTranscript,
+  toolPairingBalancedAfter,
+  toolPairingBalancedBefore,
+} from '@deepseek-ai/dsh-compact'
+import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { TokenMeasurement, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { frameSummary } from './summarizer.ts'
+import type { SummaryResult } from './summarizer.ts'
+
+interface RegionDependencies {
+  readonly meter: TokenMeterService
+  summarize(text: string, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>
+}
+
+/**
+ * Resolve the next head-anchored range while retaining a priced recent tail
+ * and never splitting an assistant tool-call/result pair.
+ * @param session - session supplying authoritative current surface positions.
+ * @param measurement - unified pressure and surface measurement from the conversation meter.
+ * @param retainTokens - minimum recent tail budget retained verbatim.
+ * @returns the inclusive positional seq range to compact, or `null`.
+ */
+export function selectCompactableRange(
+  session: Session,
+  measurement: TokenMeasurement,
+  retainTokens: number,
+): { start: number; end: number } | null {
+  const pricedNodes = measurement.nodes
+  if (pricedNodes.length === 0) return null
+
+  const surfaceNodes = session.surface.nodes
+  if (surfaceNodes.length !== pricedNodes.length
+    || surfaceNodes.some((seq, index) => seq !== pricedNodes[index]?.seq)) {
+    throw new Error('compaction: token-meter surface does not match the current session surface')
+  }
+
+  let accumulated = 0
+  let keepFromIdx = pricedNodes.length
+  for (let index = pricedNodes.length - 1; index >= 0; index -= 1) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    accumulated += pricedNodes[index]!.tokens
+    keepFromIdx = index
+    if (accumulated >= retainTokens) break
+  }
+  if (keepFromIdx === 0) return null
+
+  while (keepFromIdx > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    if (toolPairingBalancedBefore(session, surfaceNodes[keepFromIdx]!)) break
+    keepFromIdx -= 1
+  }
+  if (keepFromIdx === 0) return null
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const first = surfaceNodes[0]!
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const cutoff = surfaceNodes[keepFromIdx - 1]!
+  return { start: first, end: cutoff }
+}
+
+/**
+ * Validate and compact one positional surface span.
+ * @param dependencies - conversation meter and dynamically dispatched summarizer hook.
+ * @param session - session whose surface is mutated.
+ * @param start - inclusive first surface-node seq.
+ * @param end - inclusive last surface-node seq.
+ * @param agent - agent used by the summarizer.
+ * @param signal - optional summarization cancellation signal.
+ * @returns the successful durable compaction result.
+ */
+export async function compactSurfaceRegion(
+  dependencies: RegionDependencies,
+  session: Session,
+  start: number,
+  end: number,
+  agent: Agent,
+  signal?: AbortSignal,
+): Promise<CompactionResult> {
+  const nodes = session.surface.nodes
+  const startIdx = nodes.indexOf(start)
+  const endIdx = nodes.indexOf(end)
+  if (startIdx === -1) throw new Error(`compactRegion: start seq ${start} not found in surface`)
+  if (endIdx === -1) throw new Error(`compactRegion: end seq ${end} not found in surface`)
+  if (startIdx > endIdx) {
+    throw new Error(
+      `compactRegion: start seq ${start} (position ${startIdx}) is after end seq ${end} (position ${endIdx}) on the surface`,
+    )
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  if (!toolPairingBalancedBefore(session, nodes[startIdx]!)) {
+    throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`)
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  if (!toolPairingBalancedAfter(session, nodes[endIdx]!)) {
+    throw new Error(`compactRegion: end seq ${end} is not a balanced boundary (would split a step, or the step is still open)`)
+  }
+
+  const tail = inspectTurnTail(session.events)
+  if (tail.compactionInProgress) throw new Error('compaction already in progress')
+  if (tail.turn === null) {
+    throw new Error('compactRegion: no open turn — compaction events must be enclosed in a turn')
+  }
+
+  const shadowedSeqs = nodes.slice(startIdx, endIdx + 1)
+  const startEvent = session.append('compact/start', { turn: tail.turn })
+  try {
+    // Capture after the lock event so any later durable append, including a
+    // log-only one, invalidates the async selection before replacement.
+    const lockedMeasurement = dependencies.meter.measure(session)
+    const selected = lockedMeasurement.nodes.slice(startIdx, endIdx + 1)
+    if (selected.length !== shadowedSeqs.length
+      || selected.some((node, index) => node.seq !== shadowedSeqs[index])) {
+      throw new Error('compaction: selected surface changed before summarization began')
+    }
+    const shadowedTokenCount = selected.reduce((total, node) => total + node.tokens, 0)
+    const text = renderTranscript(session.events, shadowedSeqs)
+    const { summary, provider, model, maxTokens } = await dependencies.summarize(text, agent, signal)
+
+    const currentMeasurement = dependencies.meter.measure(session)
+    if (currentMeasurement.logRevision !== lockedMeasurement.logRevision) {
+      throw new Error('compaction: session log changed during summarization')
+    }
+    const framedSummary = frameSummary(summary)
+    const framedSummaryTokenCount = dependencies.meter.estimateMessage({
+      role: 'user',
+      content: framedSummary,
+    })
+    if (framedSummaryTokenCount >= shadowedTokenCount) {
+      throw new Error(
+        `summary is not smaller than the shadowed content (${framedSummaryTokenCount} estimated framed tokens >= ${shadowedTokenCount})`,
+      )
+    }
+
+    const summaryEvent = session.append('compact/summary', {
+      summary,
+      shadowedRange: { start, end },
+      shadowedSeqs,
+      shadowedTokenCount,
+      provider,
+      model,
+      ...maxTokens === undefined ? {} : { maxTokens },
+    })
+    session.append('user/message', {
+      content: framedSummary,
+      source: { kind: 'plugin', plugin: 'compact' },
+    }, {
+      surfaceOp: { op: 'replace', start, end },
+      sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
+    })
+    const endEvent = session.append('compact/end', { turn: tail.turn })
+    return {
+      startSeq: startEvent.seq,
+      summarySeq: summaryEvent.seq,
+      endSeq: endEvent.seq,
+      summary,
+      shadowedRange: { start, end },
+      shadowedSeqs,
+      shadowedTokenCount,
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    session.append('compact/end', { turn: tail.turn, error: message })
+    throw error
+  }
+}
+
+/** Inspect the current turn boundary and latest compaction bracket once. */
+function inspectTurnTail(
+  events: readonly SessionEvent[],
+): { turn: number | null; compactionInProgress: boolean } {
+  let compactionInProgress = false
+  let compactionStateKnown = false
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const event = events[index]!
+    if (!compactionStateKnown) {
+      if (event.type === 'compact/start') {
+        compactionInProgress = true
+        compactionStateKnown = true
+      } else if (event.type === 'compact/end') {
+        compactionStateKnown = true
+      }
+    }
+    if (event.type === 'turn/start') return { turn: event.data.turn, compactionInProgress }
+    if (event.type === 'turn/end') return { turn: null, compactionInProgress }
+  }
+  return { turn: null, compactionInProgress }
+}

packages/compact/compact-basic/src/summarizer.ts

@@ -0,0 +1,169 @@
+/**
+ * Default one-shot summarization and durable checkpoint framing.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/summarizer
+ */
+
+import type { Context } from 'cordis'
+import { BlockAssembler } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ResolvedConfig } from './types.ts'
+
+/** Tags wrapping the structured summary inside the landed checkpoint node. */
+const SUMMARY_OPEN_TAG = '<compacted-summary>'
+const SUMMARY_CLOSE_TAG = '</compacted-summary>'
+
+/** Fixed structure required from the auxiliary summarization call. */
+const SUMMARIZE_SYSTEM_PROMPT = [
+  'You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.',
+  '',
+  'Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section.',
+  '',
+  '## Primary Request and Intent',
+  "- [the user's original and evolving goals; quote verbatim where the exact wording matters]",
+  '',
+  '## Key Technical Concepts',
+  '- [technologies, frameworks, patterns, and conventions in play]',
+  '',
+  '## Files and Code',
+  '- [exact path: why it matters, key changes or snippets]',
+  '',
+  '## Errors and Fixes',
+  '- [error: how it was resolved, plus any related user feedback]',
+  '',
+  '## Pending Tasks',
+  '- [explicitly requested work not yet completed]',
+  '',
+  '## Current Work',
+  '- [precisely what was in progress at this checkpoint]',
+  '',
+  '## Next Step',
+  '- [the single next action, directly in line with the most recent request, or "(none)"]',
+  '',
+  '## Critical Context',
+  '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
+  '',
+  'Rules:',
+  '- Preserve exact file paths, commands, error strings, identifiers, and function signatures.',
+  '- Capture user feedback and explicit instructions faithfully, especially corrections.',
+  '- Do NOT mention this summarization process or that the context was compacted.',
+  `- If the transcript already contains a ${SUMMARY_OPEN_TAG} block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.`,
+].join('\n')
+
+/** Framing that makes the replacement user message established context. */
+const CHECKPOINT_PREAMBLE =
+  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.'
+
+/** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
+export interface SummaryResult {
+  summary: ContentBlock[]
+  provider: string
+  model: string
+  maxTokens?: number
+}
+
+/**
+ * Run the default direct `ctx.llm.stream()` summarization call.
+ * @param ctx - context providing the LLM service.
+ * @param config - resolved backend configuration.
+ * @param text - rendered transcript region to summarize.
+ * @param agent - supplies routed-model history, fallback model, and session id.
+ * @param signal - optional cancellation forwarded to the adapter.
+ * @returns safe text-only summary blocks and exact call provenance.
+ */
+export async function summarizeWithLlm(
+  ctx: Context,
+  config: ResolvedConfig,
+  text: string,
+  agent: Agent,
+  signal?: AbortSignal,
+): Promise<SummaryResult> {
+  const latest = agent.session.requestHeader()?.config
+  const configured = config.summarizationProvider.length === 0
+    ? undefined
+    : { provider: config.summarizationProvider, model: config.summarizationModel }
+  const agentTarget = agent.options.provider !== undefined
+    && agent.options.provider.length > 0
+    && agent.options.model !== undefined
+    && agent.options.model.length > 0
+    ? { provider: agent.options.provider, model: agent.options.model }
+    : undefined
+  const target = configured ?? latest ?? agentTarget
+  if (target === undefined) {
+    throw new Error(
+      'no provider/model available for summarization: set both BasicCompactConfig summarization fields, route one request, or set both AgentOptions fields',
+    )
+  }
+
+  const assembler = new BlockAssembler()
+  const options: GenerateOptions = {
+    provider: target.provider,
+    model: target.model,
+    messages: [{
+      role: 'user',
+      content: [{ type: 'text', text: `Summarize this conversation history:\n\n${text}\n\nSummary:` }],
+    }],
+    system: SUMMARIZE_SYSTEM_PROMPT,
+    maxTokens: config.maxTokens,
+    sessionId: agent.session.id,
+    ...signal === undefined ? {} : { signal },
+  }
+  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  const error = finishError(assembler.finish)
+  if (error !== undefined) throw error
+
+  const summary = textOnly(assembler.message().content)
+  if (!summary.some(block => block.text.trim().length > 0)) {
+    throw new Error('summarization produced no text summary content')
+  }
+  return {
+    summary,
+    provider: target.provider,
+    model: target.model,
+    maxTokens: config.maxTokens,
+  }
+}
+
+/**
+ * Wrap raw summary blocks in the durable checkpoint framing.
+ * @param summary - safe text-only model output.
+ * @returns content for the synthesized replacement user message.
+ */
+export function frameSummary(summary: readonly ContentBlock[]): ContentBlock[] {
+  return [
+    { type: 'text', text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
+    ...summary,
+    { type: 'text', text: SUMMARY_CLOSE_TAG },
+  ]
+}
+
+/** Map a terminal summarization finish to its fail-closed error. */
+function finishError(finish: FinishReason): Error | undefined {
+  switch (finish.kind) {
+    case 'error': {
+      const error = new Error(finish.message) as Error & { code?: string }
+      if (finish.code !== undefined) error.code = finish.code
+      return error
+    }
+    case 'aborted': {
+      const error = new Error('summarization stream aborted') as Error & { code?: string }
+      error.code = 'ABORTED'
+      return error
+    }
+    case 'max-tokens': {
+      const error = new Error('summarization truncated at the token cap (incomplete checkpoint)') as Error & { code?: string }
+      error.code = 'MAX_TOKENS'
+      return error
+    }
+    default:
+      return undefined
+  }
+}
+
+/** Keep only text blocks before synthesizing a user message. */
+function textOnly(
+  blocks: readonly ContentBlock[],
+): Array<Extract<ContentBlock, { type: 'text' }>> {
+  return blocks.filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
+}

packages/compact/compact-basic/src/types.ts

@@ -1,102 +1,34 @@
 /**
- * Configuration vocabulary for the basic compaction backend.
- *
- * Every tunable lives here, in the implementation — the abstract contract
- * (`@deepseek-ai/dsh-compact`) carries no config, because thresholds and
- * retention policy are HOW decisions a different backend would make
- * differently.
+ * Configuration vocabulary for the replay-aware basic compaction backend.
  *
  * @module @deepseek-ai/dsh-compact-basic/types
  */
 
-/**
- * Backend configuration. Every knob is REQUIRED except `auto` and
- * `charsPerToken`: there is no concrete data yet to justify default
- * thresholds/budgets, so a consumer must state each value explicitly rather
- * than inherit a guessed default. `auto` alone defaults to `true`
- * (auto-compaction is the intended posture), and `charsPerToken` defaults to
- * the English-text heuristic its estimator was calibrated on.
- */
+/** Basic compaction configuration; every common field has a deployment default. */
 export interface BasicCompactConfig {
-  /** Context window size in tokens. */
-  contextWindow: number
-  /** Compact when estimated token usage exceeds this fraction of context window. */
-  thresholdRatio: number
-  /** Number of tokens of recent context to retain during compaction. */
-  retainTokens: number
-  /** Provider to use for summarization (`''` with an empty model inherits the conversation target). */
-  summarizationProvider: string
-  /** Model to use for summarization (`''` with an empty provider inherits the conversation target). */
-  summarizationModel: string
-  /** Provider generation cap for the summarization call. */
-  maxTokens: number
-  /** Extra compaction attempts when the first compacted surface is still over threshold. */
-  compactionRetries: number
-  /** Enable automatic compaction on the `agent/pre-step` seam (default true). */
+  /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */
+  thresholdRatio?: number
+  /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
+  retainTokens?: number
+  /** Summary provider; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+  summarizationProvider?: string
+  /** Summary model; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+  summarizationModel?: string
+  /** Provider generation cap for summarization. Defaults to `8192`. */
+  maxTokens?: number
+  /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+  compactionRetries?: number
+  /** Enable the automatic `agent/pre-step` pressure listener. Defaults to `true`. */
   auto?: boolean
-  /**
-   * Text density for the token estimator: estimated tokens = chars /
-   * `charsPerToken`. Defaults to 4 (typical English text). A CJK-heavy
-   * deployment should set ~1-2 — CJK runs at roughly 1-2 chars per token, so
-   * the default UNDERestimates several-fold and compaction fires far too late.
-   * May be fractional.
-   */
-  charsPerToken?: number
 }
 
-/** Resolved config with `auto` and `charsPerToken` defaulted. */
-export type ResolvedConfig = Required<BasicCompactConfig>
-
-/**
- * Default `auto`/`charsPerToken` when unset and reject nonsensical numeric knobs.
- *
- * @param config - the raw, unresolved backend config.
- * @returns the validated config with `auto` and `charsPerToken` defaulted.
- */
-export function resolveConfig(config: BasicCompactConfig): ResolvedConfig {
-  const resolved: ResolvedConfig = { auto: true, charsPerToken: 4, ...config }
-
-  assertPositiveInteger('contextWindow', resolved.contextWindow)
-  assertRatio('thresholdRatio', resolved.thresholdRatio)
-  assertNonNegativeInteger('retainTokens', resolved.retainTokens)
-  assertPositiveInteger('maxTokens', resolved.maxTokens)
-  assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
-  assertPositiveFinite('charsPerToken', resolved.charsPerToken)
-  if (typeof resolved.summarizationModel !== 'string') {
-    throw new Error('BasicCompactConfig: summarizationModel must be a string.')
-  }
-  if (typeof resolved.summarizationProvider !== 'string') {
-    throw new Error('BasicCompactConfig: summarizationProvider must be a string.')
-  }
-  if ((resolved.summarizationProvider.length === 0) !== (resolved.summarizationModel.length === 0)) {
-    throw new Error('BasicCompactConfig: summarizationProvider and summarizationModel must both be empty or both be set.')
-  }
-  if (typeof resolved.auto !== 'boolean') {
-    throw new Error('BasicCompactConfig: auto must be a boolean.')
-  }
-  return resolved
-}
-
-function assertPositiveInteger(name: string, value: number): void {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive integer.`)
-  }
-}
-
-function assertNonNegativeInteger(name: string, value: number): void {
-  if (!Number.isInteger(value) || value < 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a non-negative integer.`)
-  }
-}
-
-function assertPositiveFinite(name: string, value: number): void {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive finite number.`)
-  }
-}
-
-function assertRatio(name: string, value: number): void {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a number in (0, 1].`)
-  }
+/** Validated and detached compaction configuration. */
+export interface ResolvedConfig {
+  readonly thresholdRatio: number
+  readonly retainTokens: number
+  readonly summarizationProvider: string
+  readonly summarizationModel: string
+  readonly maxTokens: number
+  readonly compactionRetries: number
+  readonly auto: boolean
 }

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -9,6 +9,7 @@ import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
 
 /**
@@ -18,15 +19,13 @@ import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
  * surface-position semantics rather than raw-log scanning.
  */
 
-const TOKENS_PER_BLOCK = 10
-
 class ReproCompactService extends BasicCompactService {
-  override estimateContentTokens(blocks: readonly ContentBlock[]): number {
-    return blocks.length * TOKENS_PER_BLOCK
-  }
-
   override async summarize(): Promise<{ summary: ContentBlock[]; provider: string; model: string }> {
-    return { summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], provider: 'mock', model: 'stub' }
+    return {
+      summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }],
+      provider: 'mock',
+      model: 'stub',
+    }
   }
 }
 
@@ -61,6 +60,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
   await mountAgentLoopTestDependencies(ctx)
   await ctx.plugin(Invariants)
   await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(TokenMeterService, { contextWindow: 400 })
   ctx.llm.registerAdapter(['mock'], new StepwiseToolAdapter(toolSteps))
   ctx.tools.register(defineTool({
     name: 'work',
@@ -70,14 +70,12 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
       return [{ type: 'text', text: 'work result' }]
     },
   }))
-  // Tiny window so a couple of tool steps cross the threshold and compaction
-  // fires within the runaway turn.
+  // Small window so several tool steps cross the threshold and compaction
+  // fires within the runaway turn after enough history can shrink.
   const compact = new ReproCompactService(ctx, {
     auto: true,
-    contextWindow: 64,
     thresholdRatio: 0.5,
-    retainTokens: 20,
-    summarizationProvider: '',
+    retainTokens: 50,
     summarizationModel: '',
     maxTokens: 8192,
     compactionRetries: 1,
@@ -117,12 +115,12 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', ()
       // its start and end cuts are balanced in surface order.
       const nodes = agent.session.surface.nodes
       for (const cp of checkpoints) {
-        const node = nodes.find(n => n.seq === cp.seq)
-        if (!node) continue // shadowed by a later checkpoint — no longer an edge.
-        expect(toolPairingBalancedBefore(agent.session, node),
-          `checkpoint seq ${node.seq} must be a balanced region START`).toBe(true)
-        expect(toolPairingBalancedAfter(agent.session, node),
-          `checkpoint seq ${node.seq} must be a balanced region END`).toBe(true)
+        const index = nodes.indexOf(cp.seq)
+        if (index === -1) continue // shadowed by a later checkpoint — no longer an edge.
+        expect(toolPairingBalancedBefore(agent.session, cp.seq),
+          `checkpoint seq ${cp.seq} must be a balanced region START`).toBe(true)
+        expect(toolPairingBalancedAfter(agent.session, cp.seq),
+          `checkpoint seq ${cp.seq} must be a balanced region END`).toBe(true)
       }
     } finally {
       await ctx.fiber.dispose()

packages/compact/compact-basic/tests/loader-composition.spec.ts

@@ -0,0 +1,94 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import LlmService from '@deepseek-ai/dsh-llm'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+async function loadYaml(lines: readonly string[]): Promise<Context> {
+  root = await mkdtemp(join(tmpdir(), 'dsh-token-meter-loader-'))
+  const configPath = join(root, 'cordis.yml')
+  await writeFile(configPath, [...lines, ''].join('\n'))
+
+  context = new Context()
+  context.baseUrl = pathToFileURL(root).href + '/'
+  await context.plugin(Loader)
+  context.loader.builtins.include = Include
+  const modules = new Map<string, unknown>([
+    ['@deepseek-ai/dsh-llm', LlmService],
+    ['@deepseek-ai/dsh-token-meter', TokenMeterService],
+    ['@deepseek-ai/dsh-compact-basic', BasicCompactService],
+  ])
+  context.loader.internal = {
+    version: 'v2',
+    async import(specifier: string) {
+      if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+      return modules.get(specifier)
+    },
+  } as unknown as NonNullable<typeof context.loader.internal>
+  await context.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(configPath).href },
+  })
+  await context.loader.await()
+  return context
+}
+
+describe('real Loader composition', () => {
+  it('loads the flat token-meter and compact-basic YAML shape', async () => {
+    const loaded = await loadYaml([
+      "- name: '@deepseek-ai/dsh-llm'",
+      "- name: '@deepseek-ai/dsh-token-meter'",
+      '  config:',
+      '    contextWindow: 4096',
+      "- name: '@deepseek-ai/dsh-compact-basic'",
+      '  config:',
+      '    thresholdRatio: 0.5',
+      '    retainTokens: 512',
+      '    auto: false',
+    ])
+
+    const unloaded = [...loaded.loader.entries()]
+      .filter(entry => entry.fiber === undefined && !entry.disabled)
+      .map(entry => entry.options.name)
+    expect(unloaded).toEqual([])
+    expect(loaded.tokenMeter.contextWindow).toBe(4096)
+    expect(loaded.get('compact')).toBeInstanceOf(BasicCompactService)
+    expect((loaded.compact as BasicCompactService).config).toMatchObject({
+      thresholdRatio: 0.5,
+      retainTokens: 512,
+      auto: false,
+    })
+  })
+
+  it('rejects stale token-meter config after Schemastery normalization', async () => {
+    context = new Context()
+    await expect(context.plugin(TokenMeterService, {
+      models: { legacy: { contextWindow: 4096 } },
+    } as never)).rejects.toThrow(/TokenMeterConfig: unknown key "models"/)
+  })
+
+  it('rejects stale compact-basic config after Schemastery normalization', async () => {
+    context = new Context()
+    await context.plugin(LlmService)
+    await context.plugin(TokenMeterService)
+    await expect(context.plugin(BasicCompactService, {
+      models: { legacy: { thresholdRatio: 0.5 } },
+    } as never)).rejects.toThrow(/BasicCompactConfig: unknown key "models"/)
+  })
+})

packages/compact/compact-basic/tsconfig.json

@@ -8,7 +8,9 @@
   "references": [
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
     { "path": "../../llm/llm" },
+    { "path": "../../llm/token-meter" },
     { "path": "../../core/session" },
     { "path": "../../core/agent" },
     { "path": "../compact" }

packages/compact/compact/README.md

@@ -7,27 +7,27 @@ This package is the interface tier of the compaction capability, split so each c
 | Package | Role |
 |---|---|
 | `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + tool-pairing boundary helpers + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) |
-| `@deepseek-ai/dsh-compact-basic` | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-compact-basic` | a backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` |
 
 Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. That deviation from the "interface depends only on cordis" guidance is intentional and recorded in the [compaction capability-seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md).
 
 ## Service API (`ctx.compact`)
 
-Both methods are **abstract** — the backend owns the entire strategy (token estimation, retention policy, event sequencing, summarization).
+Both methods are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this interface.
 
 | Member | Semantics |
 |---|---|
 | `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
-| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. The agent must own the exact target (`session === agent.session`); a backend rejects mismatch before model resolution, lock acquisition, summarization, or log mutation. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
-`compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The session being compacted comes from the agent context; the turn that the `compact/*` events belong to is recoverable from the log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value.
+`compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The turn that the `compact/*` events belong to is recoverable from the owned session's log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value.
 
 ## Tool-pairing boundaries
 
-The interface exports `toolPairingBalancedBefore(session, node)` and `toolPairingBalancedAfter(session, node)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper identifies the node by seq alone and answers from balances cached per cut in current surface order, so a stale caller-held `node.next` cannot choose the cut.
+The interface exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order.
 
-The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-node count. An unchanged generation extends the fold with unseen tail nodes only; a log-only append with no new surface node does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state.
+The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-entry count. An unchanged generation extends the fold with unseen tail entries only; a log-only append with no new surface entry does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state.
 
 ## Surface contract
 
@@ -53,7 +53,7 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati
 
 ## Implementing a backend
 
-Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. A tokenizer-, template-, or model-backed implementation can live as a sibling package without changing callers.
+Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
 
 ## Model Experience
 

packages/compact/compact/src/index.ts

@@ -29,10 +29,11 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract compaction service. Implementations own token estimation, retention,
- * and summarization, but a successful run must replace the selected surface span
- * with one summary node and prevent concurrent compaction of the same session.
- * Load one implementation per context as `ctx.compact`.
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. Load one implementation
+ * per context as `ctx.compact`.
  */
 export abstract class CompactService extends Service {
   constructor(ctx: Context) {
@@ -66,17 +67,19 @@ export abstract class CompactService extends Service {
    * `start` and `end` name an inclusive span by surface position, not numeric seq
    * order; replacements can make visible seqs non-monotonic. Both edges must be
    * balanced so assistant tool calls remain paired with their results. A model-
-   * backed implementation forwards cancellation and rejects active, missing,
-   * reversed, or unbalanced ranges.
+   * backed implementation forwards cancellation. The agent must own the exact
+   * target session object; implementations reject an ownership mismatch before
+   * model resolution, lock acquisition, summarization, or log mutation, and
+   * reject active, missing, reversed, or unbalanced ranges.
    * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
    * for the edge checks.
    *
-   * @param session - session to mutate.
+   * @param session - session to mutate; must be identical to `agent.session`.
    * @param start - first surface seq, inclusive.
    * @param end - last surface seq, inclusive.
-   * @param agent - summarizer context.
+   * @param agent - owner of the target session and summarizer context.
    * @param signal - optional cancellation; model-backed implementations must forward it.
-   * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+   * @throws when the agent does not own `session`, compaction is active, or the range is missing, reversed, or unbalanced.
    * @returns the replaced range and summary.
    */
   abstract compactRegion(

packages/compact/compact/src/tool-pairing.ts

@@ -1,24 +1,23 @@
 /**
  * Tool-pairing balance over a session surface. Compaction changes surface
  * positions, so safe cuts are derived from tool-call/result content in current
- * surface order rather than step markers or linked-list fields supplied by a
- * caller.
+ * surface order rather than step markers.
  * @module @deepseek-ai/dsh-compact/tool-pairing
  */
 
-import type { Session, SessionEvent, SurfaceNode } from '@deepseek-ai/dsh-session'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 
 /** Incremental balance state for one session surface generation. */
 interface BalanceCache {
   /** Surface rewrite generation this state describes. */
   generation: number
   /**
-   * Balance of every surface cut in current order: a surface of N nodes has
-   * N + 1 cuts, entry `i` being the cut before node `i` and the final entry
+   * Balance of every surface cut in current order: a surface of N sequences has
+   * N + 1 cuts, entry `i` being the cut before sequence `i` and the final entry
    * the cut after the surface tail.
    */
   cutBalanced: readonly boolean[]
-  /** Current surface position of each node seq, indexing {@link cutBalanced}. */
+  /** Current surface position of each event seq, indexing {@link cutBalanced}. */
   indexBySeq: Map<number, number>
   /** In-progress tool-call count after the processed surface tail. */
   inProgressToolCalls: number
@@ -27,7 +26,7 @@ interface BalanceCache {
 const balanceCacheBySession = new WeakMap<Session, BalanceCache>()
 
 /** Return how one surface event changes the in-progress tool-call count. */
-function nodeDelta(event: SessionEvent): number {
+function eventDelta(event: SessionEvent): number {
   switch (event.type) {
     case 'assistant/message':
       return event.data.content.filter(block => block.type === 'tool-call').length
@@ -38,37 +37,37 @@ function nodeDelta(event: SessionEvent): number {
   }
 }
 
-/** Read and validate the event named by a surface node. */
-function eventForNode(events: readonly SessionEvent[], node: SurfaceNode): SessionEvent {
-  const event = events[node.seq]
-  if (event === undefined || event.seq !== node.seq) {
-    throw new Error(`tool-pairing balance: surface seq ${node.seq} has no matching session event (corrupt surface)`)
+/** Read and validate the event named by a surface sequence. */
+function eventForSeq(events: readonly SessionEvent[], seq: number): SessionEvent {
+  const event = events[seq]
+  if (event === undefined || event.seq !== seq) {
+    throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`)
   }
   return event
 }
 
-/** Fold surface nodes not yet in the cache into its balance state. */
+/** Fold surface sequences not yet in the cache into its balance state. */
 function extendCache(
   session: Session,
   cache: BalanceCache,
-  nodes: readonly SurfaceNode[],
+  seqs: readonly number[],
 ): BalanceCache {
   const processed = cache.cutBalanced.length - 1
-  const tail = nodes.slice(processed)
+  const tail = seqs.slice(processed)
   // Validate the unseen tail before mutating the live cache, so a corrupt
   // append cannot leave a partially advanced state behind.
   const events = session.events
   const pendingCuts: boolean[] = []
   let inProgressToolCalls = cache.inProgressToolCalls
-  for (const node of tail) {
-    inProgressToolCalls += nodeDelta(eventForNode(events, node))
+  for (const seq of tail) {
+    inProgressToolCalls += eventDelta(eventForSeq(events, seq))
     if (inProgressToolCalls < 0) {
-      throw new Error(`tool-pairing balance: tool/result at surface seq ${node.seq} has no matching tool-call (corrupt surface)`)
+      throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`)
     }
     pendingCuts.push(inProgressToolCalls === 0)
   }
 
-  tail.forEach((node, offset) => cache.indexBySeq.set(node.seq, processed + offset))
+  tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset))
   cache.cutBalanced = cache.cutBalanced.concat(pendingCuts)
   cache.inProgressToolCalls = inProgressToolCalls
   return cache
@@ -77,11 +76,11 @@ function extendCache(
 /** Return balance state synchronized with the current session surface. */
 function balanceCache(session: Session): BalanceCache {
   const surface = session.surface
-  const nodes = surface.nodes
+  const seqs = surface.nodes
   const generation = surface.replaceGeneration
   const cached = balanceCacheBySession.get(session)
 
-  if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > nodes.length) {
+  if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) {
     // A rebuild is the same fold started from the empty-surface state, whose
     // single leading cut is trivially balanced.
     const rebuilt = extendCache(session, {
@@ -89,15 +88,15 @@ function balanceCache(session: Session): BalanceCache {
       cutBalanced: [true],
       indexBySeq: new Map(),
       inProgressToolCalls: 0,
-    }, nodes)
+    }, seqs)
     balanceCacheBySession.set(session, rebuilt)
     return rebuilt
   }
-  if (cached.cutBalanced.length - 1 < nodes.length) return extendCache(session, cached, nodes)
+  if (cached.cutBalanced.length - 1 < seqs.length) return extendCache(session, cached, seqs)
   return cached
 }
 
-/** Balance of the cut at a node's position plus offset, rejecting seqs outside current membership. */
+/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */
 function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean {
   const index = cache.indexBySeq.get(seq)
   const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset]
@@ -108,25 +107,25 @@ function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean {
 }
 
 /**
- * Whether the cut immediately before a current surface node is tool-pairing balanced.
+ * Whether the cut immediately before a current surface sequence is tool-pairing balanced.
  * @param session - session whose surface is checked.
- * @param node - surface node whose leading cut is checked; only its seq identifies it.
+ * @param seq - event sequence whose leading cut is checked.
  * @returns true when no unanswered tool call crosses the cut.
- * @throws when the seq is absent from the current surface, a surface node has no
+ * @throws when the seq is absent from the current surface, a surface sequence has no
  * matching log event, or a tool result has no preceding open call.
  */
-export function toolPairingBalancedBefore(session: Session, node: SurfaceNode): boolean {
-  return cutBalance(balanceCache(session), node.seq, 0)
+export function toolPairingBalancedBefore(session: Session, seq: number): boolean {
+  return cutBalance(balanceCache(session), seq, 0)
 }
 
 /**
- * Whether the cut immediately after a current surface node is tool-pairing balanced.
+ * Whether the cut immediately after a current surface sequence is tool-pairing balanced.
  * @param session - session whose surface is checked.
- * @param node - surface node whose trailing cut is checked; only its seq identifies it.
+ * @param seq - event sequence whose trailing cut is checked.
  * @returns true when no unanswered tool call crosses the cut.
- * @throws when the seq is absent from the current surface, a surface node has no
+ * @throws when the seq is absent from the current surface, a surface sequence has no
  * matching log event, or a tool result has no preceding open call.
  */
-export function toolPairingBalancedAfter(session: Session, node: SurfaceNode): boolean {
-  return cutBalance(balanceCache(session), node.seq, 1)
+export function toolPairingBalancedAfter(session: Session, seq: number): boolean {
+  return cutBalance(balanceCache(session), seq, 1)
 }

packages/compact/compact/tests/tool-pairing.spec.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEvent, SurfaceNode } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 const SURFACE = { surfaceOp: 'append' as const }
 
@@ -10,18 +10,18 @@ function seqOf(session: Session, type: SessionEvent['type'], nth = 0): number {
   return session.events.filter(event => event.type === type)[nth]!.seq
 }
 
-function nodeAt(session: Session, seq: number): SurfaceNode {
-  const node = session.surface.nodes.find(candidate => candidate.seq === seq)
-  if (node === undefined) throw new Error(`seq ${seq} is not a surface node`)
-  return node
+function surfaceSeq(session: Session, seq: number): number {
+  const current = session.surface.nodes.find(candidate => candidate === seq)
+  if (current === undefined) throw new Error(`seq ${seq} is not on the surface`)
+  return current
 }
 
 function before(session: Session, type: SessionEvent['type'], nth = 0): boolean {
-  return toolPairingBalancedBefore(session, nodeAt(session, seqOf(session, type, nth)))
+  return toolPairingBalancedBefore(session, surfaceSeq(session, seqOf(session, type, nth)))
 }
 
 function after(session: Session, type: SessionEvent['type'], nth = 0): boolean {
-  return toolPairingBalancedAfter(session, nodeAt(session, seqOf(session, type, nth)))
+  return toolPairingBalancedAfter(session, surfaceSeq(session, seqOf(session, type, nth)))
 }
 
 function closedToolStep(): Session {
@@ -117,9 +117,9 @@ describe('tool-pairing boundaries', () => {
 })
 
 describe('tool-pairing surface identity', () => {
-  it('rebuilds after replace and rejects nodes removed from current membership', () => {
+  it('rebuilds after replace and rejects sequences removed from current membership', () => {
     const session = closedToolStep()
-    const staleTail = nodeAt(session, seqOf(session, 'tool/result'))
+    const staleTail = surfaceSeq(session, seqOf(session, 'tool/result'))
     expect(toolPairingBalancedAfter(session, staleTail)).toBe(true)
 
     const nodes = session.surface.nodes
@@ -127,8 +127,8 @@ describe('tool-pairing surface identity', () => {
       content: [{ type: 'text', text: 'checkpoint' }],
       source: { kind: 'plugin', plugin: 'compact' },
     }, {
-      surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes.at(-1)!.seq },
-      sourceEventSeqs: nodes.map(node => node.seq),
+      surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes.at(-1)! },
+      sourceEventSeqs: [...nodes],
     })
 
     const checkpoint = session.surface.nodes[0]!
@@ -138,16 +138,16 @@ describe('tool-pairing surface identity', () => {
     expect(() => toolPairingBalancedAfter(session, staleTail)).toThrow(/surface seq .* not found/)
   })
 
-  it('ignores a caller-held node next field and answers from cached balances', () => {
+  it('answers repeated queries from cached balances', () => {
     const session = closedToolStep()
-    const assistant = nodeAt(session, seqOf(session, 'assistant/message'))
-    expect(toolPairingBalancedAfter(session, { ...assistant, next: null })).toBe(false)
-    expect(toolPairingBalancedAfter(session, { ...assistant, next: 999 })).toBe(false)
+    const assistant = surfaceSeq(session, seqOf(session, 'assistant/message'))
+    expect(toolPairingBalancedAfter(session, assistant)).toBe(false)
+    expect(toolPairingBalancedAfter(session, assistant)).toBe(false)
   })
 
   it('rejects missing seqs before and after, including an empty surface', () => {
     const session = new Session(SessionId('missing-membership'))
-    const missing: SurfaceNode = { seq: 999, prev: null, next: null }
+    const missing = 999
     expect(() => toolPairingBalancedBefore(session, missing)).toThrow(/surface seq 999 not found/)
     expect(() => toolPairingBalancedAfter(session, missing)).toThrow(/surface seq 999 not found/)
 
@@ -183,11 +183,7 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
     ]
-    const nodes: SurfaceNode[] = [
-      { seq: 0, prev: null, next: 1 },
-      { seq: 1, prev: 0, next: 2 },
-      { seq: 2, prev: 1, next: null },
-    ]
+    const nodes: number[] = [0, 1, 2]
     let generation = 0
     let eventCollectionReads = 0
     let eventIndexReads = 0
@@ -231,7 +227,7 @@ describe('tool-pairing cache refresh', () => {
       data: { content: [{ type: 'text', text: 'tail' }], source: { kind: 'user' } },
       surfaceOp: 'append',
     })
-    nodes.push({ seq: 4, prev: 2, next: null })
+    nodes.push(4)
     expect(toolPairingBalancedAfter(session, nodes[3]!)).toBe(true)
     expect(eventCollectionReads).toBe(2)
     expect(eventIndexReads).toBe(4)
@@ -253,10 +249,7 @@ describe('tool-pairing cache refresh', () => {
         surfaceOp: 'append',
       },
     )
-    nodes.push(
-      { seq: 5, prev: 4, next: 6 },
-      { seq: 6, prev: 5, next: null },
-    )
+    nodes.push(5, 6)
     expect(toolPairingBalancedAfter(session, nodes[5]!)).toBe(true)
     expect(eventCollectionReads).toBe(3)
     expect(eventIndexReads).toBe(6)
@@ -266,14 +259,14 @@ describe('tool-pairing cache refresh', () => {
       data: { content: [{ type: 'text', text: 'replacement' }], source: { kind: 'user' } },
       surfaceOp: { op: 'replace', start: 0, end: 6 },
     })
-    nodes.splice(0, nodes.length, { seq: 7, prev: null, next: null })
+    nodes.splice(0, nodes.length, 7)
     generation += 1
     expect(toolPairingBalancedAfter(session, nodes[0]!)).toBe(true)
     expect(eventCollectionReads).toBe(4)
     expect(eventIndexReads).toBe(7)
   })
 
-  it('rebuilds defensively when a same-generation surface node count regresses', () => {
+  it('rebuilds defensively when a same-generation surface entry count regresses', () => {
     const events: SessionEvent[] = [
       {
         type: 'user/message', seq: 0, time: 0,
@@ -284,10 +277,7 @@ describe('tool-pairing cache refresh', () => {
         data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append',
       },
     ]
-    const nodes: SurfaceNode[] = [
-      { seq: 0, prev: null, next: 1 },
-      { seq: 1, prev: 0, next: null },
-    ]
+    const nodes: number[] = [0, 1]
     const session = {
       events,
       surface: { nodes, replaceGeneration: 0 },
@@ -321,24 +311,24 @@ describe('tool-pairing corrupt surfaces', () => {
   })
 
   it('throws when a current surface seq has no matching event or indexes the wrong event', () => {
-    const missingNode: SurfaceNode = { seq: 1, prev: null, next: null }
+    const missingSeq = 1
     const missing = {
       events: [{
         type: 'user/message', seq: 0, time: 0,
         data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append',
       } satisfies SessionEvent],
-      surface: { nodes: [missingNode], replaceGeneration: 0 },
+      surface: { nodes: [missingSeq], replaceGeneration: 0 },
     } as unknown as Session
-    expect(() => toolPairingBalancedBefore(missing, missingNode)).toThrow(/no matching session event/)
+    expect(() => toolPairingBalancedBefore(missing, missingSeq)).toThrow(/no matching session event/)
 
-    const mismatchedNode: SurfaceNode = { seq: 0, prev: null, next: null }
+    const mismatchedSeq = 0
     const mismatched = {
       events: [{
         type: 'user/message', seq: 99, time: 0,
         data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append',
       } satisfies SessionEvent],
-      surface: { nodes: [mismatchedNode], replaceGeneration: 0 },
+      surface: { nodes: [mismatchedSeq], replaceGeneration: 0 },
     } as unknown as Session
-    expect(() => toolPairingBalancedBefore(mismatched, mismatchedNode)).toThrow(/no matching session event/)
+    expect(() => toolPairingBalancedBefore(mismatched, mismatchedSeq)).toThrow(/no matching session event/)
   })
 })

packages/context/time-context/README.md

@@ -26,7 +26,7 @@ Step 1 measures from the latest preceding model-visible message, including the p
 
 A time reading records a request-preparation attempt, not a committed step or transmitted request. Because the listener runs first, its append may remain when a later pre-step listener cancels or fails the attempt; the log is append-only and the plugin performs no rollback.
 
-The time reading stays in derived conversation history until a later compaction shadows it. Request headers and header deltas contain no time-context state. Request reconstruction uses the complete durable surface prefix at each `step/start`, so transmitted requests need not map one-to-one to readings: a failed preparation can leave an extra reading, while interval suppression can let a request reuse existing history without adding one.
+The time reading stays in derived conversation history until a later compaction shadows it. Request headers contain no time-context state. Request reconstruction uses the complete durable surface prefix at each `step/start`, so transmitted requests need not map one-to-one to readings: a failed preparation can leave an extra reading, while interval suppression can let a request reuse existing history without adding one.
 
 ## Model Experience
 

packages/context/time-context/package.json

@@ -33,6 +33,7 @@
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",

packages/context/time-context/tests/fixtures/cordis.yml

@@ -1,19 +0,0 @@
-# Test-only composition: keep time-context opt-in while exercising its real Loader/app path.
-- id: mock-llm
-  name: '../../../../../examples/echo-agent/src/mock-llm.ts'
-
-- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
-
-- id: time-context
-  name: '@deepseek-ai/dsh-time-context'
-
-- id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-demo'
-  config:
-    provider: mock
-    model: mock-echo
-    persona: 'Test the time-context plugin.'
-    welcome: 'time-context e2e ready.'
-    persistenceRoot: './.sessions'
-    workspaceContext: false

packages/context/time-context/tests/time-context.e2e.ts

@@ -4,12 +4,17 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { type SessionEvent } from '@deepseek-ai/dsh-session'
+import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 
+// Keep the Loader config under examples so both modes exercise the same deployable
+// topology: local fixture source plus bare plugins owned by the examples workspace.
 const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url))
-const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url))
+const configPath = fileURLToPath(new URL(
+  '../../../../examples/echo-agent/tests/fixtures/context/time-context/cordis.yml',
+  import.meta.url,
+))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 const PROCESS_TIMEOUT_MS = 30_000
 const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
 const FIRST_REPLY = '[main turn 1] You said: "Time sampled while preparing turn 1, step 1:'
@@ -39,21 +44,22 @@ async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> {
   workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-'))
   const cwd = workdir
   return new Promise((resolve, reject) => {
-    const proc = spawn(
-      process.execPath,
-      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
-      {
-        cwd,
-        env: {
-          ...process.env,
-          TZ: 'Asia/Shanghai',
-          TSX_TSCONFIG_PATH: repoTsconfig,
-          DSH_HOME: join(cwd, '.dsh'),
-          DSH_AGENTS_HOME: join(cwd, '.agents'),
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
+    const launch = resolveExampleLaunch({
+      srcBin: binScript,
+      configArgs: [configPath],
+      tsconfigPath: repoTsconfig,
+      exposeInternals: true,
+      env: {
+        TZ: 'Asia/Shanghai',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
       },
-    )
+    })
+    const proc = spawn(launch.command, launch.args, {
+      cwd,
+      env: { ...process.env, ...launch.env },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
     child = proc
     let stdout = ''
     let stderr = ''
@@ -119,8 +125,7 @@ describe('time-context through a real cordis.yml and stdio process', () => {
     )
     expect(contextText[1]).toMatch(/Time sampled while preparing turn 2, step 1:/)
 
-    const headers = events.filter(event => event.type === 'request/header'
-      || event.type === 'request/header-delta')
+    const headers = events.filter(event => event.type === 'request/header')
     expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing')
   }, TEST_TIMEOUT_MS)
 })

packages/context/time-context/tests/time-context.spec.ts

@@ -423,10 +423,8 @@ describe('real agent-loop request history', () => {
     expect(secondRequestText).toContain('Elapsed since the preceding step context: 1m 1s.')
 
     for (const request of adapter.requests) expect(request.system).not.toContain('Time sampled while preparing')
-    const headers = agent.session.events.filter(event => event.type === 'request/header'
-      || event.type === 'request/header-delta')
+    const headers = agent.session.events.filter(event => event.type === 'request/header')
     expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing')
-    expect(agent.session.events.filter(event => event.type === 'request/header-delta')).toHaveLength(0)
     await ctx.fiber.dispose()
   })
 })

packages/context/time-context/tsconfig.json

@@ -10,6 +10,9 @@
     { "path": "../../../vendor/cordis" },
     { "path": "../../../vendor/schemastery" },
     { "path": "../../llm/llm" },
-    { "path": "../../core/agent" }
+    { "path": "../../core/agent" },
+    { "path": "../../core/system-prompt" },
+    { "path": "../../core/agent" },
+    { "path": "../../support/loader-smoke" }
   ]
 }

packages/context/workspace-context/README.md

@@ -46,7 +46,7 @@ The core `context/message` envelope is disabled for these messages because the p
 
 ## State And Refresh
 
-Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives first because a later tool aborted the step and the loop discarded its context buffer, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
+Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy.
 
 An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only.
 

packages/context/workspace-context/src/state.ts

@@ -138,7 +138,7 @@ function visibleInstructionChanges(
   agent: Agent,
   pending: Map<string, PendingInstructionChange>,
 ): Map<string, WorkspaceInstructionChange> {
-  const visibleSeqs = new Set(agent.session.surface.nodes.map(node => node.seq))
+  const visibleSeqs = new Set(agent.session.surface.nodes)
   const visible = new Map<string, WorkspaceInstructionChange>()
   for (const [seq, event] of agent.session.events.entries()) {
     if (event.type !== 'context/message' || !isWorkspaceContextSource(event.data.source)) continue
@@ -255,8 +255,8 @@ function invalidateInstructionVersions(
 /**
  * Settle provisional tool-result state against durable session events.
  * A matching context event confirms the transition. If its owning step closes
- * first, the loop discarded its context buffer, so both duplicate suppression
- * and the metadata fast path must be re-armed for the next successful touch.
+ * first, both duplicate suppression and the metadata fast path are re-armed for
+ * the next successful touch.
  * @param session - session whose append-only log emitted `event`.
  * @param event - newly committed session event.
  * @param pendingBySession - provisional transitions awaiting log confirmation.

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -1562,7 +1562,7 @@ describe('workspace context request injection', () => {
 })
 
 describe('dynamic nested workspace context injection', () => {
-  it('re-arms a buffered instruction change when a later tool aborts the step before context append', async () => {
+  it('commits a buffered instruction change before a later tool abort closes the step', async () => {
     const root = await tempRepo()
     const home = await tempRepo()
     const ctx = new Context()
@@ -1604,12 +1604,14 @@ describe('dynamic nested workspace context injection', () => {
 
       agent.send([{ type: 'text', text: 'read and abort' }])
       await agent.whenIdle()
-      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0)
+      expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(1)
 
       agent.send([{ type: 'text', text: 'retry the read' }])
       await agent.whenIdle()
 
       const contexts = agent.session.events.filter(event => event.type === 'context/message')
+      // The aborted batch drained its accepted context before step close, so the
+      // retry sees durable history without producing a duplicate instruction.
       expect(contexts).toHaveLength(1)
       expect(adapter.requests).toHaveLength(3)
       expect(adapter.requests[2]?.messages.map(blocks => blocksText(blocks.content)).join('\n'))

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -243,6 +243,14 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'attachSurface(name: string): () => void',
     ],
   },
+  {
+    key: 'tokenMeter',
+    summary: 'Replay owner for one service-wide estimator and isolated per-session folds.',
+    methods: [
+      'measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement',
+      'estimateMessage(message: Message): number',
+    ],
+  },
   {
     key: 'tools',
     summary: 'Tool registry and execution pipeline.',
@@ -715,6 +723,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'DshEnvironmentKey',
     declaration: 'export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;',
   },
+  {
+    name: 'EpochHeader',
+    declaration: 'export interface EpochHeader {\n    config: LlmCallConfig;\n    system?: string;\n    tools?: ToolSchema[];\n    messagePrefix?: Message[];\n}',
+  },
   {
     name: 'FileDiff',
     declaration: 'export interface FileDiff {\n    path: string;\n    oldText: string | null;\n    newText: string;\n}',
@@ -795,6 +807,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'JsonValue',
     declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n    [key: string]: JsonValue;\n};',
   },
+  {
+    name: 'LlmCallConfig',
+    declaration: 'export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
+  },
   {
     name: 'LlmModelInfo',
     declaration: 'export interface LlmModelInfo {\n    provider: string;\n    id: string;\n    name: string;\n    description?: string;\n}',
@@ -1079,6 +1095,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TerminalResultView',
     declaration: 'export interface TerminalResultView {\n    card: \'terminal\';\n    title?: string;\n    output?: string;\n    exitCode?: number;\n    signal?: string;\n}',
   },
+  {
+    name: 'TokenMeasurement',
+    declaration: 'export interface TokenMeasurement {\n    readonly logRevision: number;\n    readonly baseline: TokenMeasurementBaseline;\n    readonly surfaceDeltaTokens: number;\n    readonly totalTokens: number;\n    readonly surfaceTokens: number;\n    readonly nodes: readonly TokenSurfaceNode[];\n}',
+  },
+  {
+    name: 'TokenMeasurementBaseline',
+    declaration: 'export type TokenMeasurementBaseline = {\n    readonly kind: \'none\';\n    readonly tokens: 0;\n} | {\n    readonly kind: \'estimated\';\n    readonly tokens: number;\n} | {\n    readonly kind: \'usage\';\n    readonly tokens: number;\n    readonly usage: Readonly<TokenUsage>;\n};',
+  },
+  {
+    name: 'TokenSurfaceNode',
+    declaration: 'export interface TokenSurfaceNode {\n    readonly seq: number;\n    readonly tokens: number;\n}',
+  },
   {
     name: 'TokenUsage',
     declaration: 'export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}',

packages/core/agent-loop/README.md

@@ -46,15 +46,17 @@ Configured agents start automatically. A model call requires both `provider` and
 
 - `ReactLoopAgent` — the concrete `Agent` implementation. Its inbox is a JavaScript native-private field, and one prepared session can be claimed by only one concrete driver. Everything observable happens through session events and the `agent/*` event taxonomy.
 
-`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()` and running `steer()` materialize content plus resolved source once as detached, deeply frozen lossless JSON, then share that accepted record between `agent/queued` and the inbox; malformed data throws before either boundary.
+`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()`, running `steer()`, and open-turn `inject()` materialize content plus resolved source once as detached, deeply frozen lossless JSON; malformed data throws before enqueue or append. An injection that arrives while the current step executes assistant tool calls stays in a FIFO until the batch settles; successful batches place it after the complete result batch, and interrupted batches drain it before the turn closes.
 
 ### Loop lifecycle (`loop.ts`)
 
 The driver owns one agent for its lifetime. It records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures.
 
+Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history.
+
 Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush.
 
-Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and context remain model-ordered. Abort stops new calls, drains started results, discards their context, and follows the normal abort path.
+Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, then drains accepted batch context before the turn closes through the normal abort path.
 
 ### What belongs to plugins
 

packages/core/agent-loop/src/agent.ts

@@ -8,7 +8,7 @@
 
 import type { Context } from 'cordis'
 import { agentEvents } from '@deepseek-ai/dsh-agent'
-import type { AgentId, AgentOptions, AgentStatus, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
+import type { AgentId, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm'
@@ -152,6 +152,10 @@ export class ReactLoopAgent implements Agent {
    * this set before the lifecycle unregisters the agent or detaches its session.
    */
   private pendingIdleFlushes = new Set<Promise<void>>()
+  /** Whether the current step is executing an assistant tool-call batch. */
+  private toolBatchActive = false
+  /** Open-turn injections waiting for the active assistant tool-call batch to close. */
+  private deferredInjections: HookContext[] = []
 
   constructor(
     private loopCtx: Context,
@@ -194,12 +198,11 @@ export class ReactLoopAgent implements Agent {
   }
 
   /**
-   * Accept one public send/steer payload as the exact detached record shared by
-   * the live notification and inbox. Lossless-JSON materialization reads every
-   * nested field once; deep freeze prevents an observer from rewriting queued
-   * work before the loop drains it.
+   * Accept one public message payload as a detached record. Lossless-JSON
+   * materialization reads every nested field once; deep freeze prevents later
+   * caller mutation before an inbox or deferred-injection queue drains it.
    */
-  private acceptInboxMessage(content: ContentBlock[], options?: SendOptions): InboxMessage {
+  private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage {
     const source = this.resolveSource(options)
     const accepted = snapshotJsonValue({ content, source })
     if (accepted === undefined) {
@@ -208,6 +211,15 @@ export class ReactLoopAgent implements Agent {
     return deepFreeze(accepted)
   }
 
+  /** Detach one context before it can outlive its caller in the active-batch FIFO. */
+  private acceptContext(context: HookContext): HookContext {
+    const accepted = snapshotJsonValue(context)
+    if (accepted === undefined) {
+      throw new TypeError('agent context must be losslessly JSON-serializable')
+    }
+    return deepFreeze(accepted)
+  }
+
   /** Reject a driving operation once teardown has synchronously closed the agent. */
   private assertNotDisposed(): void {
     if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`)
@@ -215,7 +227,7 @@ export class ReactLoopAgent implements Agent {
 
   send(content: ContentBlock[], options?: SendOptions): void {
     this.assertNotDisposed()
-    const accepted = this.acceptInboxMessage(content, options)
+    const accepted = this.acceptMessage(content, options)
     this.#inbox.enqueue(accepted)
     const info = { source: accepted.source, steering: false } as const
     agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
@@ -224,7 +236,7 @@ export class ReactLoopAgent implements Agent {
   steer(content: ContentBlock[], options?: SendOptions): void {
     this.assertNotDisposed()
     if (this._status !== 'running') { this.send(content, options); return }
-    const accepted = this.acceptInboxMessage(content, options)
+    const accepted = this.acceptMessage(content, options)
     this.#inbox.steer(accepted)
     const info = { source: accepted.source, steering: true } as const
     agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info)
@@ -240,10 +252,15 @@ export class ReactLoopAgent implements Agent {
       ...options?.meta !== undefined ? { meta: options.meta } : {},
     }
     if (isTurnOpen(this.session)) {
-      // A turn is open in the LOG (decided from the log, not agent status —
-      // status can be `running` with no turn open): the context/message is
-      // turn-enclosed by that turn, so append it directly.
-      this.session.append('context/message', context, { surfaceOp: 'append' })
+      const accepted = this.acceptContext(context)
+      // Provider protocols require every assistant tool-call batch to be
+      // followed only by its tool results. Historical interrupted batches do
+      // not own new context; only the currently executing batch may defer it.
+      if (this.toolBatchActive) {
+        this.deferredInjections.push(accepted)
+        return
+      }
+      this.session.append('context/message', accepted, { surfaceOp: 'append' })
       return
     }
     // No turn open: wrap the injection in a one-shot turn so every event stays
@@ -283,6 +300,34 @@ export class ReactLoopAgent implements Agent {
     }
   }
 
+  /** Append deferred open-turn injections after the loop closes a tool-result batch. */
+  private drainDeferredInjections(): void {
+    const pending = this.deferredInjections.splice(0)
+    for (const accepted of pending) {
+      this.session.append('context/message', accepted, { surfaceOp: 'append' })
+    }
+  }
+
+  /**
+   * Run one tool-call batch and drain its deferred context before settlement.
+   * The loop-owned acceptor remains valid after public disposal begins because
+   * the interrupted turn stays open until this batch settles.
+   */
+  private async withToolBatch<T>(
+    run: (acceptContext: (context: HookContext) => void) => Promise<T>,
+  ): Promise<T> {
+    this.toolBatchActive = true
+    const acceptContext = (context: HookContext): void => {
+      this.deferredInjections.push(this.acceptContext(context))
+    }
+    try {
+      return await run(acceptContext)
+    } finally {
+      this.toolBatchActive = false
+      this.drainDeferredInjections()
+    }
+  }
+
   cancel(reason?: string): void {
     // Arm only for current work; an idle marker would cancel the next prompt.
     if (this._status === 'running' || this.currentAbort !== undefined || this.#inbox.hasQueued || this.#inbox.hasSteering) {
@@ -348,6 +393,7 @@ export class ReactLoopAgent implements Agent {
       isCancelled: () => this.cancelRequested,
       cancelReason: () => this.cancelReason,
       clearCancel: () => { this.cancelRequested = false },
+      withToolBatch: run => this.withToolBatch(run),
       // Pre-step cancellation re-parks without emitting a status transition.
       settleIdle: () => { this.settleIdleWaiters() },
     })

packages/core/agent-loop/src/loop.ts

@@ -10,7 +10,7 @@ import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Messag
 import { isDeepStrictEqual } from 'node:util'
 import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm'
 import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
-import type { AgentEventDispatch, ContinuationDecision, PromptDecision } from '@deepseek-ai/dsh-agent'
+import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent'
 import { canonicalHeader } from '@deepseek-ai/dsh-session'
 import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
@@ -89,6 +89,8 @@ export interface LoopHandle {
   clearCancel(): void
   /** Settle idle waiters when pre-running cancellation skips a turn, without emitting `agent/status`. */
   settleIdle(): void
+  /** Run an active tool-call batch, accepting post-tool context into the FIFO drained before settlement. */
+  readonly withToolBatch: <T>(run: (acceptContext: (context: HookContext) => void) => Promise<T>) => Promise<T>
 }
 
 /**
@@ -334,8 +336,7 @@ async function runTurn(
       let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error }
       try {
         stepOutcome = await runStep(
-          ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages,
-          transmission, abort.signal, handle.maxParallelToolCalls)
+          ctx, events, agent, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
       } catch (error: unknown) {
         stepOutcome = { error: toError(error) }
       } finally {
@@ -472,6 +473,7 @@ async function runStep(
   ctx: Context,
   events: AgentEventDispatch,
   agent: ReactLoopAgent,
+  handle: LoopHandle,
   turn: number,
   step: number,
   assembly: PromptAssembly,
@@ -479,7 +481,6 @@ async function runStep(
   boundaryMessages: Message[],
   transmission: TransmissionLog,
   signal: AbortSignal,
-  maxParallelToolCalls: number,
 ): Promise<{ hadToolCalls: boolean; finish: FinishReason }> {
   const { session, options } = agent
 
@@ -541,7 +542,9 @@ async function runStep(
     const assembled = assembler.message()
     const assembledContent = structuredClone(assembled.content)
     let message: Message = withoutToolCalls(assembled)
-    message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)))
+    message = withoutToolCalls(await processStepResult(
+      events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
+    ))
     // Preserve usage even when max-token truncation produced no content.
     recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
     return { hadToolCalls: false, finish: assembler.finish }
@@ -551,28 +554,55 @@ async function runStep(
   const assembled = assembler.message()
   const assembledContent = structuredClone(assembled.content)
   let message: Message = assembled
-  message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))
+  message = await processStepResult(
+    events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
+  )
 
-  const toolCalls = message.content.filter(block => block.type === 'tool-call')
-
-  // Empty messages exist only to carry usage; the helper also omits empty chunk provenance.
+  // Every successful call records its completion anchor, including explicit
+  // empty chunk provenance for a contentless, usage-less provider response.
   recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
 
-  // Dispatch may overlap; policy, results, and context remain model-ordered.
-  const pendingContext = toolCalls.length > 0
-    ? await executeToolCalls(ctx, agent, turn, step, toolCalls, signal, maxParallelToolCalls)
-    : []
+  // Dispatch may overlap; policy, durable results, and result context stay model-ordered.
+  const toolCalls = message.content.filter(block => block.type === 'tool-call')
+  if (toolCalls.length === 0) return { hadToolCalls: false, finish: assembler.finish }
+  return handle.withToolBatch(async (acceptContext) => {
+    await executeToolCalls(
+      ctx, agent, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext,
+    )
+    return { hadToolCalls: true, finish: assembler.finish }
+  })
+}
 
-  // Context follows the complete result batch to preserve call/result adjacency.
-  for (const context of pendingContext) {
-    agent.inject(context.content, {
-      source: context.source,
-      ...context.envelope !== undefined ? { envelope: context.envelope } : {},
-      ...context.meta !== undefined ? { meta: context.meta } : {},
-    })
+/** Preserve successful-call accounting without retaining output that result processing rejected. */
+async function processStepResult(
+  events: AgentEventDispatch,
+  session: Session,
+  turn: number,
+  step: number,
+  config: LlmCallConfig,
+  assembledContent: ContentBlock[],
+  message: Message,
+  assembler: BlockAssembler,
+  chunkSeqs: number[],
+): Promise<Message> {
+  try {
+    return await events.waterfall(
+      'agent/step-result', turn, step, message, () => Promise.resolve(message),
+    )
+  } catch (error: unknown) {
+    recordAssistantMessage(
+      session,
+      turn,
+      step,
+      config,
+      assembledContent,
+      { ...message, content: [] },
+      assembler,
+      chunkSeqs,
+      false,
+    )
+    throw error
   }
-
-  return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish }
 }
 
 /** Record one content-or-usage assistant message with replay-safe provenance. */
@@ -585,8 +615,8 @@ function recordAssistantMessage(
   message: Message,
   assembler: BlockAssembler,
   chunkSeqs: number[],
+  preserveReplayState = true,
 ): void {
-  if (message.content.length === 0 && assembler.usage === undefined) return
   session.append(
     'assistant/message',
     {
@@ -596,11 +626,11 @@ function recordAssistantMessage(
       provenance: assistantProvenance(
         config,
         assembler.replayState,
-        isDeepStrictEqual(message.content, assembledContent),
+        preserveReplayState && isDeepStrictEqual(message.content, assembledContent),
       ),
       ...assembler.usage === undefined ? {} : { usage: assembler.usage },
     },
-    { surfaceOp: 'append', ...chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {} },
+    { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
   )
 }
 

packages/core/agent-loop/src/request-log.ts

@@ -1,11 +1,12 @@
 /**
  * Per-loop-instance request-header bookkeeping for reconstructability. The
- * comparison baseline is the header folded from the session log, so a fresh
- * loop instance needs no special resume or fork state.
+ * comparison baseline is folded from the session log; a fresh instance anchors
+ * it with an initial/resume snapshot and later logs full changed snapshots.
+ *
  * @module dsh-agent-loop/request-log
  */
 
-import { diffHeader, headerEquals, applyHeaderDelta } from '@deepseek-ai/dsh-session'
+import { headerEquals } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
 import type { Message } from '@deepseek-ai/dsh-llm'
 
@@ -32,10 +33,8 @@ export function createTransmissionLog(): TransmissionLog {
 }
 
 /**
- * Append whatever header event makes the log reproduce this request's header.
- * The first request from an instance always records a full `initial` or `resume`
- * snapshot. Later requests record nothing when unchanged, a round-tripping
- * delta when expressible, or a full `fallback` snapshot otherwise.
+ * Append the full header snapshot owed by this request: initial/resume for the
+ * instance's first request, nothing when unchanged, or change otherwise.
  *
  * @param session - the session whose log explains the request.
  * @param state - this loop instance's bookkeeping (mutated on first log).
@@ -52,12 +51,5 @@ export function recordRequestHeader(session: Session, state: TransmissionLog, he
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   const baseline = session.requestHeader()!
   if (headerEquals(baseline, header)) return
-  const delta = diffHeader(baseline, header)
-  /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same four parts */
-  if (delta === undefined) return
-  if (headerEquals(applyHeaderDelta(baseline, delta), header)) {
-    session.append('request/header-delta', delta)
-  } else {
-    session.append('request/header', { header, reason: 'fallback' })
-  }
+  session.append('request/header', { header, reason: 'change' })
 }

packages/core/agent-loop/src/tool-calls.ts

@@ -1,8 +1,8 @@
 /**
  * Schedules one assistant step's tool calls. Exclusive calls form barriers;
  * parallel calls use a bounded rolling pool and are reclassified before start.
- * Dispatch may overlap, while policy, results, and context remain model-ordered.
- * Abort stops replenishment and drains started calls.
+ * Dispatch may overlap, while policy, results, and result context remain
+ * model-ordered. Abort stops replenishment and drains started calls.
  *
  * Each started call records `tool/call`; `tool/result` commits in model order,
  * preserving derived history when audit events interleave with earlier results.
@@ -31,8 +31,8 @@ interface Slot {
 
 /**
  * Schedule one assistant step's tool calls by their live concurrency mode.
- * Started calls receive ordered results; abort drains them, discards their
- * buffered context, and rethrows so the turn owns final error handling.
+ * Started calls receive ordered results. Abort drains them and rethrows after
+ * accepting their context into the batch FIFO owned by the caller.
  *
  * @param ctx - loop context that owns the tool registry.
  * @param agent - agent and session receiving the call lifecycle.
@@ -41,7 +41,7 @@ interface Slot {
  * @param toolCalls - assistant calls in model order.
  * @param signal - abort signal shared by the step.
  * @param maxParallel - validated in-flight cap.
- * @returns buffered contexts in model call order.
+ * @param acceptContext - accepts committed result context into the active batch.
  */
 export async function executeToolCalls(
   ctx: Context,
@@ -51,7 +51,8 @@ export async function executeToolCalls(
   toolCalls: ToolCallBlock[],
   signal: AbortSignal,
   maxParallel: number,
-): Promise<HookContext[]> {
+  acceptContext: (context: HookContext) => void,
+): Promise<void> {
   const { session } = agent
 
   // Inputs are distinct because tools/execute wrappers may replace `exec.signal`.
@@ -66,7 +67,6 @@ export async function executeToolCalls(
     },
   }))
 
-  const pendingContext: HookContext[] = []
   let next = 0
   while (next < planned.length) {
     // Commit before classifying again so registry changes affect unstarted calls.
@@ -74,9 +74,8 @@ export async function executeToolCalls(
     const first = planned[next]!
     const mode = ctx.tools.executionMode(first.exec).kind
     const group = mode === 'parallel' ? planned.slice(next) : [first]
-    next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, pendingContext)
+    next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, acceptContext)
   }
-  return pendingContext
 }
 
 /** Parse model arguments, preserving invalid JSON as text and mapping empty input to `{}`. */
@@ -92,8 +91,8 @@ function parseArguments(raw: string): unknown {
  * Run one exclusive barrier or parallel pool. Later calls are reclassified
  * before start; an exclusive reclassification waits for the current pool to
  * drain and remains for the caller's next barrier. Results and contexts commit
- * in model order. Abort stops starts, drains and commits started calls, discards
- * their contexts, and throws.
+ * in model order. Abort stops starts, drains and commits started calls, accepts
+ * their contexts into the owning batch, and throws.
  */
 async function runGroup(
   ctx: Context,
@@ -104,7 +103,7 @@ async function runGroup(
   mode: ToolExecutionMode['kind'],
   signal: AbortSignal,
   maxParallel: number,
-  pendingContext: HookContext[],
+  acceptContext: (context: HookContext) => void,
 ): Promise<number> {
   /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
   if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
@@ -127,7 +126,7 @@ async function runGroup(
         : ctx.tools[TOOL_REGISTRY_SCHEDULER].finish(slot.exec, slot.result)
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
       appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!)
-      pendingContext.push(...result.additionalContexts ?? [])
+      for (const context of result.additionalContexts ?? []) acceptContext(context)
       committed++
     }
   }
@@ -189,7 +188,7 @@ async function runGroup(
   }
 
   if (aborted) {
-    // Started calls are committed; their context is discarded with the aborted step.
+    // Started calls and accepted context settle before the turn records the abort.
     /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
     throw new Error(String(signal.reason ?? 'aborted'))
   }

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -3,12 +3,12 @@ import { Context } from 'cordis'
 import LlmService, { CallId, ContentBlock, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { AgentId, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS, ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
 import { prepareReactLoopAgent } from '../src/agent.ts'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
-import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
 
 /** Regression tests for agent-loop boundary, identity, and lifecycle contracts. */
 
@@ -132,6 +132,73 @@ describe('session log records what agent/step-result actually produced', () => {
   })
 })
 
+describe('successful provider completion survives agent/step-result failure', () => {
+  async function expectContentlessCompletionAnchor(
+    response: StreamChunk[],
+    id: string,
+    providerText: string,
+  ): Promise<void> {
+    const adapter = new MockAdapter([response])
+    const ctx = await harness(adapter)
+    await ctx.plugin(Invariants)
+    const agent = ctx.agentLoop.create(AgentId(id), { provider: 'mock', model: 'mock' })
+    const failure = new Error(`${id} result processing failed`)
+    const reported: Error[] = []
+
+    ctx.on('agent/step-result', async () => {
+      throw failure
+    })
+    ctx.on('agent/error', (subject, _turn, _step, error) => {
+      if (subject === agent) reported.push(error)
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const events = [...agent.session.events]
+    const chunks = events.filter(event => event.type === 'assistant/chunk')
+    const completions = events.filter(event => event.type === 'assistant/message')
+    expect(completions).toHaveLength(1)
+    expect(completions[0]?.type === 'assistant/message' && completions[0].data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+      provenance: { provider: 'mock', model: 'mock' },
+      usage: { inputTokens: 10, outputTokens: providerText.length },
+    })
+    expect(completions[0]?.sourceEventSeqs).toEqual(chunks.map(event => event.seq))
+    expect(agent.session.deriveMessages()).toEqual([
+      { role: 'user', content: [{ type: 'text', text: 'go' }] },
+    ])
+    expect(reported).toHaveLength(1)
+    expect(reported[0]).toBe(failure)
+    const turnEnd = events.findLast(event => event.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({
+      kind: 'error',
+      step: 1,
+      message: failure.message,
+    })
+  }
+
+  it('records one content-less anchor when ordinary stop result processing rejects', async () => {
+    const providerText = 'ordinary provider output'
+    await expectContentlessCompletionAnchor(
+      textResponse(providerText),
+      'a-step-result-stop-failure',
+      providerText,
+    )
+  })
+
+  it('records one content-less anchor when max-token result processing rejects', async () => {
+    const providerText = 'truncated provider output'
+    await expectContentlessCompletionAnchor(
+      maxTokensResponse(providerText),
+      'a-step-result-max-token-failure',
+      providerText,
+    )
+  })
+})
+
 describe('abort during tool execution ends the turn', () => {
   it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => {
     const adapter = new MockAdapter([
@@ -182,6 +249,190 @@ describe('abort during tool execution ends the turn', () => {
     expect(adapter.requests).toHaveLength(1)        // no follow-up model call
     expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }])
   })
+
+  it('records context accepted before a tool-step abort in the same turn', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-abort-injection'), { provider: 'mock', model: 'mock' })
+    ctx.tools.register(defineTool({
+      name: 'aborter',
+      description: '',
+      parameters: {},
+      async execute() {
+        agent.inject([{ type: 'text', text: 'accepted before abort' }], { source: { kind: 'plugin', plugin: 'test' } })
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
+        return [{ type: 'text', text: 'done' }]
+      },
+    }))
+    ctx.on('tools/post-execute', async (): Promise<PostToolDecision> => ({
+      kind: 'accept',
+      additionalContexts: [{
+        content: [{ type: 'text', text: 'accepted result context after abort' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }],
+    }))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const events = [...agent.session.events]
+    expect(events
+      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'step/end' || event.type === 'turn/end')
+      .map(event => event.type))
+      .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end'])
+    expect(events
+      .filter(event => event.type === 'context/message')
+      .map(event => event.data.content))
+      .toEqual([
+        [{ type: 'text', text: 'accepted before abort' }],
+        [{ type: 'text', text: 'accepted result context after abort' }],
+      ])
+  })
+
+  it('records post-tool context when a later call aborts the batch', async () => {
+    const adapter = new MockAdapter([[
+      { type: 'block-start', index: 0, blockType: 'tool-call' },
+      { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'first', arguments: '{}' } },
+      { type: 'block-start', index: 1, blockType: 'tool-call' },
+      { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'aborter', arguments: '{}' } },
+      { type: 'finish', reason: { kind: 'tool-calls' } },
+    ] satisfies StreamChunk[]])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-later-abort-context'), { provider: 'mock', model: 'mock' })
+    ctx.tools.register(defineTool({
+      name: 'first',
+      description: '',
+      parameters: {},
+      async execute() {
+        return [{ type: 'text', text: 'first done' }]
+      },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'aborter',
+      description: '',
+      parameters: {},
+      async execute() {
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
+        return [{ type: 'text', text: 'aborted' }]
+      },
+    }))
+    ctx.on('tools/post-execute', async (exec, _result, next): Promise<PostToolDecision> => {
+      if (exec.callId !== CallId('c1')) return next()
+      return {
+        kind: 'accept',
+        additionalContexts: [{
+          content: [{ type: 'text', text: 'accepted after first result' }],
+          source: { kind: 'plugin', plugin: 'test' },
+        }],
+      }
+    })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const events = [...agent.session.events]
+    expect(events
+      .filter(event => event.type === 'tool/result' || event.type === 'context/message'
+        || event.type === 'step/end' || event.type === 'turn/end')
+      .map(event => event.type))
+      .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end'])
+    expect(events.find(event => event.type === 'context/message')?.data.content)
+      .toEqual([{ type: 'text', text: 'accepted after first result' }])
+  })
+
+  it('drains deferred context before disposal reaches quiescence', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'waiter', {})])
+    const ctx = await harness(adapter)
+    const started = Promise.withResolvers<undefined>()
+    let agent!: ReactLoopAgent
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      agent = inner.agentLoop.create(AgentId('a-dispose-injection'), { provider: 'mock', model: 'mock' })
+    }, { inject: ['agentLoop'] }))
+    ctx.tools.register(defineTool({
+      name: 'waiter',
+      description: '',
+      parameters: {},
+      async execute(_args, exec) {
+        agent.inject([{ type: 'text', text: 'accepted before disposal' }], { source: { kind: 'plugin', plugin: 'test' } })
+        started.resolve(undefined)
+        const signal = exec.signal
+        if (!signal) throw new Error('tool execution signal is missing')
+        await new Promise<void>((resolve) => {
+          if (signal.aborted) resolve()
+          else signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+        return [{ type: 'text', text: 'done' }]
+      },
+    }))
+    ctx.on('tools/post-execute', async (): Promise<PostToolDecision> => ({
+      kind: 'accept',
+      additionalContexts: [{
+        content: [{ type: 'text', text: 'accepted result context during disposal' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }],
+    }))
+
+    send(agent, 'go')
+    await started.promise
+    await fiber.dispose()
+
+    expect(agent.session.events
+      .filter(event => event.type === 'context/message')
+      .map(event => event.data.content))
+      .toEqual([
+        [{ type: 'text', text: 'accepted before disposal' }],
+        [{ type: 'text', text: 'accepted result context during disposal' }],
+      ])
+    expect(agent.session.events.find(event => event.type === 'turn/end')?.data.reason)
+      .toEqual({ kind: 'disposed' })
+  })
+
+  it('limits injection deferral to the current tool batch', async () => {
+    const adapter = new MockAdapter([
+      [
+        { type: 'block-start', index: 0, blockType: 'tool-call' },
+        { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'aborter', arguments: '{}' } },
+        { type: 'block-start', index: 1, blockType: 'tool-call' },
+        { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'second', arguments: '{}' } },
+        { type: 'finish', reason: { kind: 'tool-calls' } },
+      ] satisfies StreamChunk[],
+      textResponse('later turn'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' })
+    ctx.tools.register(defineTool({
+      name: 'aborter',
+      description: '',
+      parameters: {},
+      async execute() {
+        ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt')
+        return [{ type: 'text', text: 'done' }]
+      },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'second',
+      description: '',
+      parameters: {},
+      async execute() {
+        return [{ type: 'text', text: 'must not run' }]
+      },
+    }))
+
+    send(agent, 'leave an unmatched historical call')
+    await waitForIdle(ctx, agent)
+    ctx.on('agent/pre-step', (subject, turn) => {
+      if (subject === agent && turn === 2) {
+        agent.inject([{ type: 'text', text: 'new turn context' }], { source: { kind: 'plugin', plugin: 'test' } })
+      }
+    })
+    send(agent, 'start a text-only turn')
+    await waitForIdle(ctx, agent)
+
+    expect(agent.session.events.find(event => event.type === 'context/message')?.data.content)
+      .toEqual([{ type: 'text', text: 'new turn context' }])
+    expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context')
+  })
 })
 
 describe('steering from late extension points is never stranded', () => {
@@ -1118,9 +1369,10 @@ describe('tool result call identity', () => {
   })
 })
 
-describe('surface: assistant/message omits sourceEventSeqs when no chunks streamed', () => {
-  it('a step-result listener injecting content over an empty stream appends with surfaceOp but no sourceEventSeqs', async () => {
-    // Injected result content with no chunks must omit empty sourceEventSeqs.
+describe('surface: assistant/message records exact empty provenance when no chunks streamed', () => {
+  it('a step-result listener injecting content over an empty stream records sourceEventSeqs []', async () => {
+    // The explicit empty source set distinguishes a known empty provider
+    // stream from legacy events whose provenance was not recorded.
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
@@ -1137,7 +1389,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream
     const recorded = agent.session.events.find(e => e.type === 'assistant/message')!
     expect(recorded.type).toBe('assistant/message')
     expect(recorded.surfaceOp).toBe('append')
-    expect(recorded.sourceEventSeqs).toBeUndefined()
+    expect(recorded.sourceEventSeqs).toEqual([])
     // The injected content reaches derived history.
     expect(JSON.stringify(agent.session.deriveMessages())).toContain('injected')
   })

packages/core/agent-loop/tests/interception.spec.ts

@@ -375,8 +375,8 @@ describe('agent/session-prefix', () => {
       expect(request.messages[0]).toEqual(reminder)
     }
     // The anchoring snapshot is the prefix's durable record — and the ONLY
-    // header event: reuse means no request/header-delta ever.
-    const headerEvents = events(agent).filter(e => e.type === 'request/header' || e.type === 'request/header-delta')
+    // header event: reuse means no changed snapshot ever.
+    const headerEvents = events(agent).filter(e => e.type === 'request/header')
     expect(headerEvents).toHaveLength(1)
     expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.header.messagePrefix).toEqual([reminder])
     // Never session history: the derivation starts at the real user prompt.
@@ -492,7 +492,7 @@ describe('agent/session-prefix', () => {
     // cached prefix is a deep-frozen clone, so step 2's request is unchanged.
     held.content = [{ type: 'text', text: 'v2' }]
     expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'v1' }] })
-    expect(events(agent).filter(e => e.type === 'request/header-delta')).toHaveLength(0)
+    expect(events(agent).filter(e => e.type === 'request/header')).toHaveLength(1)
   })
 })
 

packages/core/agent-loop/tests/loop.spec.ts

@@ -410,22 +410,30 @@ describe('agent loop', () => {
     expect(requestText).not.toContain('<context source=')
   })
 
-  it('inject() while running appends into the open turn (no extra synthetic turn)', async () => {
+  it('defers inject() during tool execution until after the tool result', async () => {
     const adapter = new MockAdapter([
       toolCallResponse('c1', 'noticer', {}, 'calling'),
       textResponse('done'),
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
-    // A tool that injects mid-execution: at this point the agent is running, so
-    // inject must append the context/message into the ALREADY-open turn rather
-    // than wrap it in its own one-shot turn.
+    let visibleDuringTool = false
+    const meta = { kind: 'deferred-test', version: 1 }
     ctx.tools.register(defineTool({
       name: 'noticer',
       description: 'injects a notice',
       parameters: {},
       async execute() {
-        agent.inject([{ type: 'text', text: 'mid-turn notice' }], { source: { kind: 'plugin', plugin: 'x' } })
+        await Promise.resolve()
+        const first = { type: 'text' as const, text: 'mid-turn notice' }
+        agent.inject([first], {
+          source: { kind: 'plugin', plugin: 'x' },
+          envelope: 'raw',
+          meta,
+        })
+        first.text = 'mutated after inject'
+        agent.inject([{ type: 'text', text: 'second notice' }], { source: { kind: 'plugin', plugin: 'x' } })
+        visibleDuringTool = agent.session.events.some(e => e.type === 'context/message')
         return [{ type: 'text', text: 'ok' }]
       },
     }))
@@ -433,13 +441,67 @@ describe('agent loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
 
-    // Exactly ONE turn ran (no synthetic injection turn), and the mid-turn
-    // context/message sits inside it.
+    expect(visibleDuringTool).toBe(false)
+
+    // The injection stays in the open turn, but its user-role context cannot
+    // split the assistant tool call from the provider's tool-result message.
     const turnStarts = agent.session.events.filter(e => e.type === 'turn/start')
     expect(turnStarts).toHaveLength(1)
     const ts0 = turnStarts[0]!
     expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message')
-    expect(agent.session.events.some(e => e.type === 'context/message')).toBe(true)
+    const result = agent.session.events.find(e => e.type === 'tool/result')!
+    const contexts = agent.session.events.filter(e => e.type === 'context/message')
+    expect(contexts).toHaveLength(2)
+    expect(result.seq).toBeLessThan(contexts[0]!.seq)
+    expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({
+      envelope: 'raw',
+      meta,
+    })
+    expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : []))
+      .toEqual([
+        { type: 'text', text: 'mid-turn notice' },
+        { type: 'text', text: 'second notice' },
+      ])
+
+    const secondRequest = adapter.requests[1]!.messages
+    const resultIndex = secondRequest.findIndex(message =>
+      message.content.some(block => block.type === 'tool-result'))
+    const contextIndexes = secondRequest.flatMap((message, index) =>
+      message.content.some(block => block.type === 'text'
+        && (block.text.includes('mid-turn notice') || block.text.includes('second notice')))
+        ? [index]
+        : [])
+    expect(resultIndex).toBeGreaterThanOrEqual(0)
+    expect(contextIndexes).toHaveLength(2)
+    expect(contextIndexes.every(index => index > resultIndex)).toBe(true)
+  })
+
+  it('rejects non-JSON context before it enters the active tool-batch FIFO', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('c1', 'invalid-injector', {}, 'calling'),
+      textResponse('done'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('invalid-context'), { provider: 'mock', model: 'mock' })
+    ctx.tools.register(defineTool({
+      name: 'invalid-injector',
+      description: 'attempts an invalid context injection',
+      parameters: {},
+      async execute() {
+        expect(() => {
+          agent.inject([{ type: 'text', text: 'invalid' }], {
+            source: { kind: 'plugin', plugin: 'test' },
+            meta: { bigint: 1n } as never,
+          })
+        }).toThrow('agent context must be losslessly JSON-serializable')
+        return [{ type: 'text', text: 'rejected invalid context' }]
+      },
+    }))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false)
   })
 
   it('agent/turn-continuation can force-continue (/loop pattern) and force-stop', async () => {
@@ -743,10 +805,9 @@ describe('agent loop', () => {
     })
   })
 
-  it('appends no assistant/message for a max-tokens step with empty content and no usage', async () => {
-    // A max-tokens step truncated to a dropped tool call AND with no usage chunk has nothing to
-    // record: empty content and no accounting → no assistant/message (the empty-content host
-    // exists only to carry usage).
+  it('appends an empty completion anchor for a max-tokens step with no usage', async () => {
+    // The truncated tool call is dropped from durable content, while the
+    // successful provider call still needs an exact replay anchor.
     const callId = CallId('c1')
     const adapter = new MockAdapter([[
       { type: 'block-start', index: 0, blockType: 'tool-call' },
@@ -770,14 +831,20 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+      provenance: { provider: 'mock', model: 'mock' },
+    })
+    expect(assistant.sourceEventSeqs?.length).toBeGreaterThan(0)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })
 
-  it('appends no assistant/message for a normal stop finish with empty content and no usage', async () => {
-    // A clean `stop` finish that streamed nothing assembled (no blocks) and
-    // carried no usage chunk has nothing to record: the content-or-usage guard
-    // on the normal step path suppresses a pure trace-only empty assistant/message.
+  it('appends an empty completion anchor for a normal stop with no usage', async () => {
+    // A clean content-less call stays absent from derived messages but remains
+    // a durable successful-call boundary for replay consumers.
     const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
@@ -789,7 +856,14 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'completed' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+      provenance: { provider: 'mock', model: 'mock' },
+    })
+    expect(assistant.sourceEventSeqs?.length).toBe(1)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })
 

packages/core/agent-loop/tests/request-log.spec.ts

@@ -1,9 +1,8 @@
 /**
- * recordRequestHeader unit tests: exactly one of four things per request —
+ * recordRequestHeader unit tests: exactly one of three things per request —
  * an 'initial' snapshot (log has no header yet), a 'resume' snapshot (fresh
- * loop instance over a log that has one), nothing (header unchanged), a
- * round-tripping delta, or a 'fallback' snapshot when the delta encoding
- * cannot express the change (pure tool reordering).
+ * loop instance over a log that has one), nothing (header unchanged), or a
+ * full 'change' snapshot.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -23,7 +22,7 @@ function openSession(id: string): Session {
 }
 
 function headerEvents(session: Session): SessionEvent[] {
-  return session.events.filter(e => e.type === 'request/header' || e.type === 'request/header-delta')
+  return session.events.filter(e => e.type === 'request/header')
 }
 
 describe('recordRequestHeader', () => {
@@ -53,8 +52,8 @@ describe('recordRequestHeader', () => {
     expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('resume')
   })
 
-  it('logs a round-tripping delta for a mid-run change, and the fold reproduces the header', () => {
-    const session = openSession('rl-delta')
+  it("logs a full 'change' snapshot for a mid-run change, and the fold reproduces the header", () => {
+    const session = openSession('rl-change')
     const state = createTransmissionLog()
     const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] })
     recordRequestHeader(session, state, first)
@@ -63,12 +62,12 @@ describe('recordRequestHeader', () => {
     recordRequestHeader(session, state, second)
     const events = headerEvents(session)
     expect(events).toHaveLength(2)
-    expect(events[1]?.type).toBe('request/header-delta')
+    expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('change')
     expect(session.requestHeader()).toEqual(second)
   })
 
-  it("records a change the delta cannot express (pure reordering) as a 'fallback' snapshot", () => {
-    const session = openSession('rl-fallback')
+  it("records a pure tool reordering as a 'change' snapshot", () => {
+    const session = openSession('rl-reorder')
     const state = createTransmissionLog()
     const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, tools: [tool('a'), tool('b')] })
     recordRequestHeader(session, state, first)
@@ -77,9 +76,7 @@ describe('recordRequestHeader', () => {
     recordRequestHeader(session, state, reordered)
     const events = headerEvents(session)
     expect(events).toHaveLength(2)
-    expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('fallback')
-    // The fold still lands on the exact header — deltas are an encoding
-    // optimization, never a correctness dependency.
+    expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('change')
     expect(session.requestHeader()).toEqual(reordered)
   })
 })

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -1,9 +1,8 @@
 /**
  * Loop-level reconstructability: every request the loop sends is a pure function of the
- * session log — messages are the derivation at the step/start boundary, the header is the fold
- * of request/header* events — and every request is an append-extension of its predecessor
- * unless a logged event (compaction replace, header change) explains the difference. Mock-adapter
- * requests are the observable, and the final offline rebuild states the full contract end to end.
+ * session log — messages derive at the step/start boundary and the header is the latest
+ * request/header snapshot. Each request extends its predecessor unless a logged compaction
+ * replacement or header change explains the difference.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -85,7 +84,7 @@ describe('request stability across the loop', () => {
       expect(Object.isFrozen(request.messages)).toBe(true)
     }
     // One anchoring header snapshot; no further header events (nothing changed).
-    const headerEvents = agent.session.events.filter(e => e.type === 'request/header' || e.type === 'request/header-delta')
+    const headerEvents = agent.session.events.filter(e => e.type === 'request/header')
     expect(headerEvents).toHaveLength(1)
     expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.reason).toBe('initial')
   })
@@ -122,8 +121,8 @@ describe('request stability across the loop', () => {
         content: [{ type: 'text', text: '[summary of turn 1]' }],
         source: { kind: 'plugin', plugin: 'test-compact' },
       }, {
-        surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq },
-        sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq],
+        surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! },
+        sourceEventSeqs: [nodes[0]!, nodes[1]!],
       })
     })
 
@@ -137,7 +136,7 @@ describe('request stability across the loop', () => {
     expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1)
   })
 
-  it('a real system-prompt change is a logged header delta; a stable prompt logs nothing', async () => {
+  it('a real system-prompt change is a full changed-header snapshot; a stable prompt logs nothing', async () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' })
@@ -147,14 +146,15 @@ describe('request stability across the loop', () => {
     send(agent, 'second')
     await waitForIdle(ctx, agent)
     // Identical assembly re-rendered per step is NOT a change.
-    expect(agent.session.events.filter(e => e.type === 'request/header-delta')).toHaveLength(0)
+    expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1)
 
     ctx.systemPrompt.section({ name: 'extra', order: 2, text: 'new guidance' })
     send(agent, 'third')
     await waitForIdle(ctx, agent)
 
-    const deltas = agent.session.events.filter(e => e.type === 'request/header-delta')
-    expect(deltas).toHaveLength(1)
+    const snapshots = agent.session.events.filter(e => e.type === 'request/header')
+    expect(snapshots).toHaveLength(2)
+    expect(snapshots[1]?.data.reason).toBe('change')
     expect(adapter.requests[2]!.system).toContain('new guidance')
     // History is preserved across the change — only the header moved.
     expect(adapter.requests[2]!.messages.length).toBeGreaterThan(adapter.requests[1]!.messages.length)
@@ -260,9 +260,9 @@ describe('request stability across the loop', () => {
     send(agent, 'second')
     await waitForIdle(ctx, agent)
 
-    // No delta was logged (nothing really changed), and the session's own
+    // No changed snapshot was logged (nothing really changed), and the session's own
     // fold is immutable state.
-    expect(agent.session.events.filter(e => e.type === 'request/header-delta')).toHaveLength(0)
+    expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1)
     expect(Object.isFrozen(agent.session.requestHeader())).toBe(true)
     expect(adapter.requests[1]!.temperature).toBeUndefined()
   })
@@ -296,7 +296,7 @@ describe('request stability across the loop', () => {
       const rebuilt = new Session(SessionId(`rebuild-${index}`), structuredClone(events.slice(0, stepStart.seq)))
       expect(structuredClone(request.messages)).toEqual(rebuilt.deriveMessages())
 
-      // Header: the fold of request/header* events up to this step's dispatch
+      // Header: the latest request/header snapshot up to this step's dispatch
       // (its header event sits between step/start and the first chunk).
       const firstChunk = events.find(e => e.type === 'assistant/chunk' && e.seq > stepStart.seq)!
       const header = foldRequestHeader(events.slice(0, firstChunk.seq))!

packages/core/agent-loop/tests/tool-calls.spec.ts

@@ -502,7 +502,7 @@ describe('tool-call scheduler: abort handling', () => {
       .toEqual([CallId('c1')])
   })
 
-  it('stops replenishing after abort, commits started results, and drops buffered additional contexts', async () => {
+  it('stops replenishing after abort, commits started results, and drains accepted additional contexts', async () => {
     const adapter = new MockAdapter([
       multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))),
       textResponse('should never be requested'),
@@ -528,7 +528,12 @@ describe('tool-call scheduler: abort handling', () => {
       .toEqual([CallId('c1'), CallId('c2')])
     expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId))
       .toEqual([CallId('c1'), CallId('c2')])
-    expect(events(agent).filter(e => e.type === 'context/message')).toEqual([])
+    const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message')
+    expect(settled.map(e => e.type))
+      .toEqual(['tool/result', 'tool/result', 'context/message', 'context/message'])
+    expect(settled.filter(e => e.type === 'context/message')
+      .map(e => (e.data.content[0] as { text: string }).text))
+      .toEqual(['ctx-c1', 'ctx-c2'])
   })
 
   it('does not run an exclusive barrier after a parallel group aborts', async () => {

packages/core/agent/README.md

@@ -43,7 +43,7 @@ The handle every plugin programs against:
 
 - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content).
 - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle
-- `agent.inject(content, options?)` — inject in-session context (`context/message` event); the next request sees it. `options.envelope` defaults to the canonical `<context>` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md))
+- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message`. `options.envelope` defaults to the canonical `<context>` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)).
 - `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op.
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`

packages/core/agent/src/types.ts

@@ -117,10 +117,11 @@ export interface Agent {
   steer(content: ContentBlock[], options?: SendOptions): void
 
   /**
-   * Append model-facing context without running the model. Idle injection uses
-   * a one-shot turn and durability checkpoint, while injection during an open
-   * turn joins it at the current log position. Disposal awaits idle checkpoints;
-   * flush failures are reported through `agent/error`, not thrown to the caller.
+   * Append detached model-facing context without running the model. An open-turn
+   * injection joins at the current log position unless the current tool batch is
+   * executing; then it waits FIFO until that batch settles and drains before turn
+   * close even when interrupted. Idle injection uses a one-shot turn and durability
+   * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`.
    */
   inject(content: ContentBlock[], options?: InjectOptions): void
 

packages/core/session/README.md

@@ -1,6 +1,6 @@
 # dsh-session
 
-Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (a linked list of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
+Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -33,7 +33,7 @@ The store pairs announced creation with disposal, publishes post-commit append n
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
 - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs.
-- `session.deriveMessages()` incrementally projects each new surface node once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
+- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback.
 - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants.
 - `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite.
 - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
@@ -46,15 +46,14 @@ Durable values need one accepted representation, not a check followed by a secon
 
 ### Surface types
 
-- `SurfaceOp` — how a surface node entered the linked list: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace nodes from `start` through `end` inclusive — both must be valid surface node seqs; `start === end` replaces a single node). Used by compaction to shadow old nodes without deleting them.
+- `SurfaceOp` — how an event entered the ordered surface: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace entries from `start` through `end` inclusive — both must be valid surface seqs; `start === end` replaces one entry). Used by compaction to shadow old events without deleting them.
 - `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types.
-- `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list.
-- `foldSurface(events)` — replay the one canonical surface contract into detached current nodes and actual replacement ranges. The same pass rejects non-contiguous event seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface node; `SurfaceManager` shares the atomic transition while retaining its incremental cache.
-- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully-formed surface node (type is surface-eligible AND `surfaceOp` present); the second is the type-only check (is this one of the five `SurfaceEventType` values?), used to detect a surface-eligible event MISSING its marker — e.g. when validating a seed/load log.
+- `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface entry; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache.
+- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log.
 
 ### Request-header reconstruction (`request-header.ts`)
 
-`request/header` and `request/header-delta` make the non-history request envelope reconstructable from the log. `foldRequestHeader()` reconstructs the active header, `diffHeader()` encodes changes, and `applyHeaderDelta()` replays them; unsupported deltas fall back to a full snapshot. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).
+`request/header` records a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, or `change`. `foldRequestHeader()` selects the latest snapshot; legacy delta events and the removed `fallback` reason are rejected. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md).
 
 `context/message` defaults to the canonical tagged context projection. A producer may set `envelope: 'raw'` when its `content` already contains the complete model-facing frame, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`.
 
@@ -68,7 +67,7 @@ Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types
 
 Every `SessionEvent` carries two optional top-level fields (structural metadata):
 
-- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction replace node).
+- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
 
 ### Metadata types (`types.ts`)
@@ -79,15 +78,15 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata)
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
 - Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model and assistant messages require provider/model provenance. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage.
-- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns surface membership, positional links, and `replaceGeneration`.
+- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface entries behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership and `replaceGeneration`.
 
 ## Model Experience
 
 ### Derived message history
 
-**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface nodes verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
+**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface entries verbatim. A `context/message` is a user-role message containing exactly `<context source="<source-kind>">`, its content blocks, and `</context>`; `steering/message` uses the identical `<steering source="<source-kind>">` / `</steering>` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message.
 
-**Token effect**: Appended surface nodes are resent on later steps. A `replace` surface operation removes the shadowed nodes from future inputs without deleting their raw log records.
+**Token effect**: Appended surface entries are resent on later steps. A `replace` surface operation removes the shadowed entries from future inputs without deleting their raw log records.
 
 ### Crash-repair result
 

packages/core/session/src/index.ts

@@ -22,9 +22,9 @@ export * from './types.ts'
 export { isJsonValue, snapshotJsonValue } from './json.ts'
 export type { JsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
-export type { SurfaceFoldReplacement, SurfaceFoldResult, SurfaceNode } from './surface.ts'
+export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
 export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
-export { applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from './request-header.ts'
+export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -133,6 +133,9 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe
 /** Validate the fixed event envelope after one-pass JSON materialization. */
 function assertSessionEventEnvelope(value: Record<string, unknown>, index: number): asserts value is SessionEvent {
   const event = value
+  if (event['type'] === 'request/header-delta') {
+    throw new Error(`seed event at index ${index} uses unsupported legacy request/header-delta format`)
+  }
   const allowed = new Set(['type', 'seq', 'time', 'data', 'surfaceOp', 'sourceEventSeqs'])
   if (Object.keys(event).some(key => !allowed.has(key))
     || !Object.hasOwn(event, 'type') || typeof event['type'] !== 'string'
@@ -156,9 +159,6 @@ function assertCurrentLlmShape(event: Record<string, unknown>, index: number): v
     const config = typeof header === 'object' && header !== null ? (header as Record<string, unknown>)['config'] : undefined
     if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`)
   }
-  if (event['type'] === 'request/header-delta' && record['config'] !== undefined && !hasProviderModel(record['config'])) {
-    throw new Error(`seed request/header-delta at index ${index} lacks provider/model`)
-  }
   if (event['type'] === 'assistant/message' && !hasProviderModel(record['provenance'])) {
     throw new Error(`seed assistant/message at index ${index} lacks provider/model provenance`)
   }
@@ -172,6 +172,18 @@ function hasProviderModel(value: unknown): boolean {
     && typeof pair['model'] === 'string' && pair['model'].length > 0
 }
 
+/** Reject request-header vocabulary removed with the legacy delta codec. */
+function assertSupportedRequestHeader(type: string, data: unknown, location: string): void {
+  if (type === 'request/header-delta') {
+    throw new Error(`${location} uses unsupported legacy request/header-delta format`)
+  }
+  if (type === 'request/header'
+    && data !== null && typeof data === 'object' && !Array.isArray(data)
+    && (data as Record<string, unknown>)['reason'] === 'fallback') {
+    throw new Error(`${location} uses unsupported legacy request/header reason "fallback"`)
+  }
+}
+
 type SessionCallback = (...args: unknown[]) => unknown
 
 /** Resolve one listener snapshot, including Cordis's internal dispatch checks. */
@@ -243,7 +255,7 @@ export class Session {
   private readonly surfaceValidator = new SurfaceManager(this.log)
 
   /**
-   * Derived surface — a cached linked list of message-producing events.
+   * Derived surface — a cached order of message-producing event sequences.
    * Lazily rebuilt from `surfaceOp` markers in the log; processes only new
    * events (delta) on each access — the log is append-only, so prior events
    * never change.
@@ -251,7 +263,7 @@ export class Session {
    */
   private _surface: SurfaceManager | undefined
 
-  /** The surface linked list over this session's event log. */
+  /** The ordered surface over this session's event log. */
   get surface(): SurfaceManager {
     if (!this._surface) this._surface = new SurfaceManager(this.log)
     return this._surface
@@ -284,6 +296,7 @@ export class Session {
           throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`)
         }
         assertSessionEventEnvelope(snapshot, index)
+        assertSupportedRequestHeader(snapshot.type, snapshot.data, `seed event at index ${index}`)
         if (snapshot.seq !== index) {
           throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`)
         }
@@ -331,7 +344,7 @@ export class Session {
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
    * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the surface linked list; `sourceEventSeqs` records provenance (the seq
+   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
    *   numbers of events this one derives from). REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived history) and
@@ -368,6 +381,7 @@ export class Session {
     if (dataSnapshot === undefined) {
       throw new Error(`session event "${type}" carries non-JSON-serializable data`)
     }
+    assertSupportedRequestHeader(type, dataSnapshot, `session event "${type}"`)
     const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata)
     if (surfaceMetadataSnapshot === undefined) {
       throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`)
@@ -439,8 +453,8 @@ export class Session {
   private derivedGeneration = 0
 
   /**
-   * Derive the LLM message history by walking the session surface — the linked
-   * list of message-producing events maintained by `surfaceOp` markers. The
+   * Derive the LLM message history by walking the ordered sequences of
+   * message-producing events maintained by `surfaceOp` markers. The
    * surface is the single source of derived history: every message-producing
    * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
    * turn boundary) is correctly absent, and a compaction `replace` deletes the
@@ -464,11 +478,11 @@ export class Session {
       this.derivedNodes = 0
       this.derivedGeneration = generation
     }
-    for (const node of nodes.slice(this.derivedNodes)) {
-      // Surface nodes are built from this.log — node.seq is always a valid
+    for (const seq of nodes.slice(this.derivedNodes)) {
+      // Surface sequences are built from this.log — seq is always a valid
       // index by construction. The non-null assertion expresses that invariant.
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const msg = this.deriveEventMessage(this.log[node.seq]!)
+      const msg = this.deriveEventMessage(this.log[seq]!)
       // A surface node is one of the five message-producing types, but an
       // empty-content assistant/message (a max-tokens step that hosts only
       // usage) derives to null and must not enter the transcript.

packages/core/session/src/request-header.ts

@@ -1,28 +1,20 @@
 /**
- * Request-header reconstruction utilities over `request/header` snapshots and
- * `request/header-delta` events. Writers round-trip each proposed delta and use
- * a full snapshot when the encoding cannot represent the change.
+ * Request-header reconstruction utilities over full `request/header` session
+ * events. Anyone holding a session log reconstructs the {@link EpochHeader}
+ * any request was built under by taking the latest canonical snapshot; the
+ * loop uses the same equality helper to avoid logging unchanged headers.
+ *
  * @module dsh-session/request-header
  */
 
 import { callConfigEquals } from '@deepseek-ai/dsh-llm'
-import type { LlmCallConfig, Message, ToolSchema } from '@deepseek-ai/dsh-llm'
-import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts'
-
-/** The `request/header-delta` payload shape: each present field amends the folded header. */
-type HeaderDelta = {
-  system?: SystemDelta
-  tools?: ToolsDelta
-  config?: LlmCallConfig
-  messagePrefix?: Message[]
-}
+import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, SessionEvent } from './types.ts'
 
 /**
- * Normalize a header to canonical form: an empty system prompt, an empty
- * tool list, and an empty session prefix become ABSENT fields, matching how
- * requests are built (the request-build spreads skip empty values). Diff,
- * fold, and comparison all operate on canonical headers, so "no system
- * prompt" (and "no session prefix") has exactly one representation.
+ * Normalize a header to canonical form: an empty system prompt, an empty tool
+ * list, and an empty session prefix become absent fields, matching how requests
+ * are built. Logging, folding, and comparison use this one representation.
  * @param header - the header to normalize (not mutated).
  * @returns the canonical header.
  */
@@ -35,85 +27,22 @@ export function canonicalHeader(header: EpochHeader): EpochHeader {
   }
 }
 
-/** Split a canonical (possibly absent) system prompt into lines; absence is zero lines. */
-function systemLines(system: string | undefined): string[] {
-  return system === undefined ? [] : system.split('\n')
-}
-
-/** Join lines back into a canonical system value; zero lines is absence. */
-function joinSystem(lines: string[]): string | undefined {
-  return lines.length === 0 ? undefined : lines.join('\n')
-}
-
-/**
- * Compute the line-level {@link SystemDelta} between two canonical system
- * prompts: trim the common prefix and (non-overlapping) common suffix, and
- * carry the replacement lines between them. Deterministic and library-free;
- * with nothing shared it degenerates to a full replacement.
- */
-function diffSystem(prev: string | undefined, next: string | undefined): SystemDelta {
-  const a = systemLines(prev)
-  const b = systemLines(next)
-  let keepStart = 0
-  while (keepStart < a.length && keepStart < b.length && a[keepStart] === b[keepStart]) keepStart += 1
-  let keepEnd = 0
-  while (
-    keepEnd < a.length - keepStart &&
-    keepEnd < b.length - keepStart &&
-    a[a.length - 1 - keepEnd] === b[b.length - 1 - keepEnd]
-  ) keepEnd += 1
-  return { keepStart, keepEnd, insert: b.slice(keepStart, b.length - keepEnd) }
-}
-
-/** Apply a {@link SystemDelta} to a canonical system prompt. */
-function applySystem(prev: string | undefined, delta: SystemDelta): string | undefined {
-  const a = systemLines(prev)
-  return joinSystem([...a.slice(0, delta.keepStart), ...delta.insert, ...a.slice(a.length - delta.keepEnd)])
-}
-
-/** Canonical JSON equality for tool schemas — sound because schemas are
- * JSON-serializable by construction and both sides come from the same
- * assembly path, so key insertion order matches when the values do. */
+/** Canonical JSON equality for tool schemas assembled through the same path. */
 function sameSchema(a: ToolSchema, b: ToolSchema): boolean {
   return JSON.stringify(a) === JSON.stringify(b)
 }
 
-/**
- * Compute the name-keyed {@link ToolsDelta} between two canonical tool lists.
- * A pure reordering produces an empty delta — the writer's round-trip guard
- * catches that case and records a snapshot instead.
- */
-function diffTools(prev: readonly ToolSchema[], next: readonly ToolSchema[]): ToolsDelta {
-  const prevByName = new Map(prev.map(tool => [tool.name, tool]))
-  const nextNames = new Set(next.map(tool => tool.name))
-  return {
-    added: next.filter(tool => !prevByName.has(tool.name)),
-    removed: prev.filter(tool => !nextNames.has(tool.name)).map(tool => tool.name),
-    changed: next.filter((tool) => {
-      const before = prevByName.get(tool.name)
-      return before !== undefined && !sameSchema(before, tool)
-    }),
-  }
-}
-
-/** Apply a {@link ToolsDelta} to a canonical tool list: drop removed, replace changed in place, append added. */
-function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[] {
-  const removed = new Set(delta.removed)
-  const changedByName = new Map(delta.changed.map(tool => [tool.name, tool]))
-  const kept = prev
-    .filter(tool => !removed.has(tool.name))
-    .map(tool => changedByName.get(tool.name) ?? tool)
-  return [...kept, ...delta.added]
+/** Canonical JSON equality over session-prefix arrays; absence equals empty. */
+function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean {
+  return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
 }
 
 /**
- * Field-wise equality over canonical headers — the cheap comparison the writer's round-trip
- * guard runs (`applyHeaderDelta(prev, delta)` must equal the intended header) and the loop
- * runs to skip logging an unchanged header.
- *
+ * Field-wise equality over canonical headers. Tool schemas compare in order;
+ * the session prefix compares as canonical JSON.
  * @param a - one canonical header.
  * @param b - the other.
- * @returns whether config, system, tools (in order), and the session prefix all match.
+ * @returns whether config, system, tools, and session prefix all match.
  */
 export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
   if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false
@@ -123,74 +52,19 @@ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean {
   return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema))
 }
 
-/** Canonical JSON equality over session-prefix arrays; absence equals the empty array. */
-function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean {
-  return JSON.stringify(a ?? []) === JSON.stringify(b ?? [])
-}
-
 /**
- * Compute the `request/header-delta` payload between two canonical headers, or
- * `undefined` when they are equal. The encoding cannot represent every change,
- * including pure tool reordering, so callers must apply and compare the result
- * before logging it and fall back to a full snapshot on mismatch. The session
- * prefix is replaced whole; an empty array removes it.
- *
- * @param prev - the folded header the log currently implies.
- * @param next - the header the next request will actually use.
- * @returns the delta payload, or undefined when nothing changed.
- */
-export function diffHeader(prev: EpochHeader, next: EpochHeader): HeaderDelta | undefined {
-  const delta: HeaderDelta = {}
-  if (prev.system !== next.system) delta.system = diffSystem(prev.system, next.system)
-  const prevTools = prev.tools ?? []
-  const nextTools = next.tools ?? []
-  if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools)
-  if (!callConfigEquals(prev.config, next.config)) delta.config = next.config
-  if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? []
-  return Object.keys(delta).length > 0 ? delta : undefined
-}
-
-/**
- * Apply a `request/header-delta` payload to a canonical header, producing the
- * canonical header it encodes. Total for well-formed logs (the writer only
- * appends round-trip-verified deltas).
- * @param prev - the folded header before the delta.
- * @param delta - the logged delta payload.
- * @returns the canonical header after the delta.
- */
-export function applyHeaderDelta(prev: EpochHeader, delta: HeaderDelta): EpochHeader {
-  const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system
-  const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools
-  const messagePrefix = delta.messagePrefix ?? prev.messagePrefix
-  return canonicalHeader({
-    config: delta.config ?? prev.config,
-    ...system !== undefined ? { system } : {},
-    ...tools !== undefined ? { tools } : {},
-    ...messagePrefix !== undefined ? { messagePrefix } : {},
-  })
-}
-
-/**
- * Fold the header events of a log (or any prefix of one) into the {@link EpochHeader} in
- * force after the last of them: each `request/header` snapshot replaces the state, each
- * `request/header-delta` amends it.
- *
- * @param events - session events in log order (non-header events are skipped).
- * @param from - a previously folded state to continue from (the live session's incremental
- *   cursor); omit to fold from nothing.
- * @returns the folded header, or undefined when no header event exists yet.
+ * Fold the header events of a log (or any prefix) into the
+ * {@link EpochHeader} in force after the last snapshot. Non-header events are
+ * skipped. This is the pure offline reconstruction path; the live session
+ * tracks the same fold incrementally.
+ * @param events - session events in log order.
+ * @param from - a previously folded state to continue from.
+ * @returns the latest canonical header, or undefined when none exists yet.
  */
 export function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined {
-  let state: EpochHeader | undefined = from
+  let state = from
   for (const event of events) {
-    if (event.type === 'request/header') {
-      state = canonicalHeader(event.data.header)
-    } else if (event.type === 'request/header-delta') {
-      if (state === undefined) {
-        throw new Error(`request/header-delta at seq ${event.seq} before any request/header snapshot: corrupt log`)
-      }
-      state = applyHeaderDelta(state, event.data)
-    }
+    if (event.type === 'request/header') state = canonicalHeader(event.data.header)
   }
   return state
 }

packages/core/session/src/surface.ts

@@ -1,19 +1,13 @@
 /**
- * Surface layer on top of the session event log: a derived, cached linked list
- * of events that produce LLM messages. Rebuilt deterministically from
- * `surfaceOp` markers in the log — the log is the source of truth; the surface
- * is a view.
+ * Surface layer on top of the session event log: an ordered view of events
+ * that produce LLM messages. The append-only log remains the source of truth.
  *
  * @module @deepseek-ai/dsh-session/surface
  */
 
 import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
 
-/**
- * The set of event type strings that are eligible for the surface linked list.
- * Mirrors the {@link SurfaceEventType} union; kept as a runtime set so the
- * type guard can check membership without a chain of string comparisons.
- */
+/** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set<string>([
   'user/message',
   'assistant/message',
@@ -23,39 +17,22 @@ const SURFACE_EVENT_TYPES = new Set<string>([
 ])
 
 /**
- * Check only whether a type may enter the message surface; it does not require `surfaceOp`. This
- * detects eligible seed/load events missing their mandatory marker. Use {@link isSurfaceEvent} to
- * narrow a fully formed event whose marker is present.
- * @param type - the event type string to test.
- * @returns true when the type is one of the five message-producing types.
+ * Whether an event type can join the model-visible surface.
+ * @param type - event type to test.
+ * @returns true for one of the five message-producing event types.
  */
 export function isSurfaceEligibleType(type: string): boolean {
   return SURFACE_EVENT_TYPES.has(type)
 }
 
 /**
- * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the
- * event's `type` is surface-eligible AND that `surfaceOp` is present.
- * The narrowed type has mandatory {@link SurfaceOp}.
- * @param event - the event to narrow.
- * @returns true when the event is surface-eligible and carries its `surfaceOp` marker.
+ * Narrow an event to a surface-eligible event carrying its required marker.
+ * @param event - event to test.
+ * @returns true when both the type and marker identify a surface event.
  */
 export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
   if (!SURFACE_EVENT_TYPES.has(event.type)) return false
-  // surfaceOp is optional on SessionEvent (even for surface-eligible types)
-  // but mandatory on SurfaceEvent — this check is the narrowing gate.
-  if ((event as SessionEvent<SurfaceEventType>).surfaceOp === undefined) return false
-  return true
-}
-
-/** One node in the surface linked list. */
-export interface SurfaceNode {
-  /** The event seq of this surface node. */
-  seq: number
-  /** The previous surface node's seq, or null if this is the head. */
-  prev: number | null
-  /** The next surface node's seq, or null if this is the tail. */
-  next: number | null
+  return (event as SessionEvent<SurfaceEventType>).surfaceOp !== undefined
 }
 
 /** One replacement operation observed while folding a session surface. */
@@ -66,22 +43,21 @@ export interface SurfaceFoldReplacement {
   start: number
   /** Declared inclusive end seq of the replaced surface range. */
   end: number
-  /** Actual surface nodes removed by the operation, in surface order. */
+  /** Actual surface entries removed by the operation, in surface order. */
   shadowedSeqs: number[]
 }
 
 /** Complete result of replaying the surface operations in a session log. */
 export interface SurfaceFoldResult {
-  /** Current surface nodes in linked-list order. */
-  nodes: SurfaceNode[]
+  /** Current surface event sequences in model-visible order. */
+  nodes: number[]
   /** Replacement operations in event order. */
   replacements: SurfaceFoldReplacement[]
 }
 
-/** Mutable state shared by the incremental manager and the full-log fold. */
+/** Mutable state shared by complete and incremental folds. */
 interface SurfaceFoldState {
-  nodes: SurfaceNode[]
-  nodeBySeq: Map<number, SurfaceNode>
+  nodes: number[]
   replaceGeneration: number
 }
 
@@ -98,12 +74,8 @@ type SurfacePlan =
   | SurfaceReplacePlan
 
 /** Create an empty surface fold state. */
-function createFoldState(replaceGeneration = 0): SurfaceFoldState {
-  return {
-    nodes: [],
-    nodeBySeq: new Map(),
-    replaceGeneration,
-  }
+function createFoldState(): SurfaceFoldState {
+  return { nodes: [], replaceGeneration: 0 }
 }
 
 /** Whether a runtime value is a non-negative safe event sequence. */
@@ -160,8 +132,8 @@ function assertProvenance(
     if (!Array.isArray(raw)) {
       throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`)
     }
-    if (raw.length === 0) {
-      throw new Error('sourceEventSeqs must not be empty when present')
+    if (raw.length === 0 && event.type !== 'assistant/message') {
+      throw new Error('sourceEventSeqs must not be empty except on assistant/message')
     }
     let nonEarlierSource: number | undefined
     for (const source of raw) {
@@ -189,23 +161,21 @@ function replacementRange(
   state: SurfaceFoldState,
   op: Extract<SurfaceOp, { op: 'replace' }>,
 ): Pick<SurfaceReplacePlan, 'startIdx' | 'endIdx' | 'shadowedSeqs'> {
-  const startNode = state.nodeBySeq.get(op.start)
-  if (!startNode) {
+  const startIdx = state.nodes.indexOf(op.start)
+  if (startIdx === -1) {
     throw new Error(`surface replace: start seq ${op.start} not found in surface`)
   }
-  const endNode = state.nodeBySeq.get(op.end)
-  if (!endNode) {
+  const endIdx = state.nodes.indexOf(op.end)
+  if (endIdx === -1) {
     throw new Error(`surface replace: end seq ${op.end} not found in surface`)
   }
-  const startIdx = state.nodes.indexOf(startNode)
-  const endIdx = state.nodes.indexOf(endNode)
   if (startIdx > endIdx) {
     throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
   }
   return {
     startIdx,
     endIdx,
-    shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1).map(node => node.seq),
+    shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1),
   }
 }
 
@@ -235,27 +205,6 @@ function planSurfaceEvent(
   }
 }
 
-/** Apply one already-validated positional replacement. */
-function replaceSurface(state: SurfaceFoldState, plan: SurfaceReplacePlan): void {
-  const { startIdx, endIdx } = plan
-
-  const removed = state.nodes.splice(startIdx, endIdx - startIdx + 1)
-  for (const node of removed) state.nodeBySeq.delete(node.seq)
-
-  const prevNode = startIdx > 0 ? state.nodes[startIdx - 1] : undefined
-  const nextNode = startIdx < state.nodes.length ? state.nodes[startIdx] : undefined
-  const newNode: SurfaceNode = {
-    seq: plan.seq,
-    prev: prevNode?.seq ?? null,
-    next: nextNode?.seq ?? null,
-  }
-  if (prevNode) prevNode.next = plan.seq
-  if (nextNode) nextNode.prev = plan.seq
-  state.nodes.splice(startIdx, 0, newNode)
-  state.nodeBySeq.set(plan.seq, newNode)
-  state.replaceGeneration += 1
-}
-
 /** Apply one event and return replacement metadata only when one occurred. */
 function applySurfaceEvent(
   state: SurfaceFoldState,
@@ -264,13 +213,10 @@ function applySurfaceEvent(
 ): SurfaceFoldReplacement | undefined {
   const plan = planSurfaceEvent(state, event, expectedSeq)
   if (plan?.kind === 'append') {
-    const tail = state.nodes.at(-1)
-    const node: SurfaceNode = { seq: plan.seq, prev: tail?.seq ?? null, next: null }
-    if (tail) tail.next = plan.seq
-    state.nodes.push(node)
-    state.nodeBySeq.set(plan.seq, node)
+    state.nodes.push(plan.seq)
   } else if (plan?.kind === 'replace') {
-    replaceSurface(state, plan)
+    state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq)
+    state.replaceGeneration += 1
   }
   if (plan?.kind !== 'replace') return
   return {
@@ -283,16 +229,9 @@ function applySurfaceEvent(
 
 /**
  * Replay a complete session log through the canonical surface fold.
- *
- * The returned arrays and nodes are detached snapshots. The incremental
- * {@link SurfaceManager} uses the same transition functions, so query read
- * models cannot disagree with `deriveMessages()` about replacement ranges.
  * @param events - session events in contiguous seq order.
- * @returns the current surface and every positional replacement.
- * @throws when any event violates the unified surface contract: metadata must
- * be well shaped and type-eligible, event seqs must be contiguous, provenance
- * must name unique earlier events, and a positional replacement must name and
- * cite its complete range.
+ * @returns detached current sequences and replacement history.
+ * @throws when an event violates surface metadata, provenance, or range rules.
  */
 export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult {
   const state = createFoldState()
@@ -301,68 +240,44 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult
     const replacement = applySurfaceEvent(state, event, index)
     if (replacement !== undefined) replacements.push(replacement)
   }
-  return {
-    nodes: state.nodes.map(node => ({ ...node })),
-    replacements,
-  }
+  return { nodes: [...state.nodes], replacements }
 }
 
-/**
- * Maintains a cached linked list of surface nodes and validates each candidate
- * before it enters the event log. Because the log is append-only, it processes
- * only committed deltas and plans the candidate without mutation rather than
- * rescanning the whole log.
- */
+/** Incremental ordered surface view and append-boundary validator. */
 export class SurfaceManager {
-  /** Incremental state shared with the complete surface fold. */
+  /** Shared transition state; replacement history is not retained. */
   private _state = createFoldState()
-  /** The last processed seq. -1 folds the seeded log on first access. */
+  /** Last processed seq; -1 folds a seeded log on first access. */
   private _lastProcessedSeq = -1
 
   constructor(private log: readonly SessionEvent[]) {}
 
   /**
-   * Validate one candidate as the next log event without applying it. The
-   * committed log is folded first, then the candidate's complete surface and
-   * provenance transition is planned atomically; a failure leaves the current
-   * surface unchanged.
-   * @param event - candidate event that has not entered `log` yet.
+   * Validate the next candidate without mutating the committed surface.
+   * @param event - candidate event that has not entered the log yet.
    */
   validateNext(event: SessionEvent): void {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     planSurfaceEvent(this._state, event, this.log.length)
   }
 
-  /**
-   * The surface's rewrite generation, bumped by every folded `replace` op.
-   * A replace is the ONE operation that rewrites the
-   * surface non-monotonically, so an incremental consumer of {@link nodes}
-   * (the session's derived-message cache) compares this between visits — an
-   * unchanged generation guarantees every node it has not seen is a pure tail
-   * append; a changed one means its view must rebuild. Monotonic: it never
-   * moves backwards, so comparisons cannot be fooled by a re-fold.
-   */
+  /** Monotonic count of folded positional replacements. */
   get replaceGeneration(): number {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     return this._state.replaceGeneration
   }
 
-  /** The surface nodes in linked-list order (head to tail). */
-  get nodes(): readonly SurfaceNode[] {
+  /** Surface event sequences in model-visible order. */
+  get nodes(): readonly number[] {
     if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
     return this._state.nodes
   }
 
-  /**
-   * Process events from `_lastProcessedSeq + 1` through the end of the log,
-   * folding new surface markers into the existing linked list.
-   */
+  /** Fold events appended since the previous access. */
   private _processDelta(): void {
     for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) {
-      // Index is bounded by i < this.log.length — never undefined.
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const event = this.log[i]!
-      applySurfaceEvent(this._state, event, i)
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition
+      applySurfaceEvent(this._state, this.log[i]!, i)
       this._lastProcessedSeq = i
     }
   }

packages/core/session/src/types.ts

@@ -143,7 +143,7 @@ export interface TodoItem {
 
 /**
  * Logged request state outside derived history: call config, system prompt,
- * tools, and session prefix. Header snapshots and deltas reconstruct it;
+ * tools, and prefix. The latest full `request/header` snapshot reconstructs it;
  * canonical empty optional fields are absent.
  */
 export interface EpochHeader {
@@ -167,43 +167,9 @@ export interface EpochHeader {
  * Why a `request/header` snapshot was appended: `'initial'` — the log's first
  * header (a new conversation); `'resume'` — a loop instance's first request
  * over a log that already has header events (process restart, fork seed);
- * `'fallback'` — a mid-run change the delta encoding could not round-trip
- * (e.g. a pure tool reordering), recorded whole instead.
+ * `'change'` — a later request used a different header.
  */
-export type RequestHeaderReason = 'initial' | 'resume' | 'fallback'
-
-/**
- * Line-level edit of the system prompt: keep the first `keepStart` and last
- * `keepEnd` lines of the previous text, with `insert` replacing everything
- * between. Computed as a common-prefix/common-suffix trim — deterministic,
- * library-free, degenerating to a full replacement when nothing is shared.
- * Absence is encoded as zero lines (the canonical form has no empty-string
- * system), so a transition to or from "no system prompt" round-trips.
- */
-export interface SystemDelta {
-  /** Lines kept from the start of the previous system prompt. */
-  keepStart: number
-  /** Lines kept from the end of the previous system prompt. */
-  keepEnd: number
-  /** Lines replacing everything between the kept edges. */
-  insert: string[]
-}
-
-/**
- * Tool-set edit keyed by tool name (names are unique — the registry rejects
- * duplicates): `removed` names drop, `changed` schemas replace their
- * predecessor in place, `added` schemas append at the end. A change this
- * encoding cannot express (a pure reordering) fails the writer's round-trip
- * guard and is recorded as a `'fallback'` snapshot instead.
- */
-export interface ToolsDelta {
-  /** Schemas appended to the end of the tool list. */
-  added: ToolSchema[]
-  /** Names of schemas dropped from the tool list. */
-  removed: string[]
-  /** Schemas replacing the same-named predecessor in place. */
-  changed: ToolSchema[]
-}
+export type RequestHeaderReason = 'initial' | 'resume' | 'change'
 
 /**
  * The merge-extensible, append-only source of truth for an agent interaction.
@@ -276,22 +242,13 @@ export interface SessionEventMap {
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
-  /**
-   * Whole-list snapshot; the latest write wins on replay. It is log-only UI
-   * state and never enters derived model history.
-   */
+  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
   'todo/write': { todos: TodoItem[] }
   /**
-   * Full {@link EpochHeader} for the next request, appended inside its step
-   * before dispatch. It is log-only and anchors subsequent deltas.
+   * Full header for the next request, appended inside its step before dispatch.
+   * It is log-only; the latest snapshot reconstructs the request header.
    */
   'request/header': { header: EpochHeader; reason: RequestHeaderReason }
-  /**
-   * Log-only amendment to the folded {@link EpochHeader}. System and tools use
-   * their delta codecs; config and prefix replace whole, with an empty prefix
-   * encoding removal. Writers verify round-trip equality or log a fallback snapshot.
-   */
-  'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] }
 }
 
 /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
@@ -299,7 +256,7 @@ export type SessionEventType = keyof SessionEventMap
 
 /**
  * The subset of {@link SessionEventType} values whose events produce LLM
- * messages and are eligible to appear on the surface linked list. Only these
+ * messages and are eligible to appear on the ordered surface. Only these
  * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
  */
 export type SurfaceEventType =
@@ -310,7 +267,7 @@ export type SurfaceEventType =
   | 'steering/message'
 
 /**
- * A {@link SessionEvent} that is **on** the surface linked list — its
+ * A {@link SessionEvent} that is **on** the ordered surface — its
  * `surfaceOp` is guaranteed present (mandatory), narrowed from a
  * surface-eligible {@link SessionEvent} by checking both `type` and
  * `surfaceOp` at runtime.
@@ -321,7 +278,7 @@ export type SurfaceEventType =
 export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: SurfaceOp }
 
 /**
- * How a session event entered the surface linked list. Only valid on
+ * How a session event entered the ordered surface. Only valid on
  * {@link SurfaceEventType} events.
  *
  * - `'append'`: added to the tail — normal path for user/assistant/tool/context
@@ -342,6 +299,12 @@ export type SurfaceOp =
  */
 export interface SurfaceIntent {
   surfaceOp: SurfaceOp
+  /**
+   * Complete known provenance source set. `assistant/message` may use a
+   * present empty array for a known empty provider stream; omission means its
+   * provenance was not recorded. Other surface events require a non-empty set
+   * when this field is present.
+   */
   sourceEventSeqs?: number[]
 }
 
@@ -370,7 +333,9 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /**
      * Seq numbers of events that are provenance sources of this event
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node).
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */

packages/core/session/tests/derived-cache.spec.ts

@@ -40,7 +40,7 @@ describe('derived-message cache', () => {
     const nodes = session.surface.nodes
     session.append('context/message', {
       content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
-    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
 
     expect(session.deriveMessages()).toHaveLength(1)
     expect(session.deriveMessages()).toEqual(scratch(session))

packages/core/session/tests/request-header.spec.ts

@@ -1,14 +1,7 @@
-/**
- * Request-header utility tests: canonical form, the system line-diff
- * (prefix/suffix trim), the name-keyed tools delta, config replacement, the
- * round-trip contract (including the reorder case the encoding cannot
- * express), and the log fold. These pin the reconstruction algebra: for every
- * logged delta, apply(prev, delta) === next, and folding a log prefix yields
- * the header its next request was built under.
- */
+/** Request-header canonicalization, equality, snapshot folding, and format rejection. */
 
 import { describe, expect, it } from 'vitest'
-import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, canonicalHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session'
 import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm'
 
@@ -22,165 +15,77 @@ function msg(text: string): Message {
   return { role: 'user', content: [{ type: 'text', text }] }
 }
 
-/** Round-trip helper: diff must reproduce `next` from `prev` exactly. */
-function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType<typeof diffHeader> {
-  const delta = diffHeader(prev, next)
-  if (delta !== undefined) {
-    expect(applyHeaderDelta(prev, delta)).toEqual(canonicalHeader(next))
-  }
-  return delta
-}
-
 describe('canonicalHeader', () => {
-  it('normalizes empty system and empty tools to absent fields', () => {
-    expect(canonicalHeader({ config: CONFIG, system: '', tools: [] })).toEqual({ config: CONFIG })
-    const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')] })
-    expect(full.system).toBe('s')
-    expect(full.tools).toHaveLength(1)
+  it('normalizes empty optional fields to absence and preserves populated fields', () => {
+    expect(canonicalHeader({ config: CONFIG, system: '', tools: [], messagePrefix: [] })).toEqual({ config: CONFIG })
+    const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
+    expect(full).toEqual({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
   })
 })
 
-describe('diffHeader / applyHeaderDelta', () => {
-  it('returns undefined for equal headers', () => {
-    const header = canonicalHeader({ config: CONFIG, system: 'a\nb', tools: [tool('t')] })
-    expect(diffHeader(header, header)).toBeUndefined()
+describe('headerEquals', () => {
+  const base = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] })
+
+  it('compares every canonical field and preserves tool order', () => {
+    expect(headerEquals(base, structuredClone(base))).toBe(true)
+    expect(headerEquals(base, { ...base, config: { provider: 'mock', model: 'other' } })).toBe(false)
+    expect(headerEquals(base, { ...base, system: 'other' })).toBe(false)
+    expect(headerEquals(base, { ...base, messagePrefix: [msg('other')] })).toBe(false)
+    expect(headerEquals(base, { ...base, tools: [] })).toBe(false)
+    expect(headerEquals(base, { ...base, tools: [tool('a', 'changed')] })).toBe(false)
+    expect(headerEquals({ config: CONFIG, tools: [tool('a'), tool('b')] }, { config: CONFIG, tools: [tool('b'), tool('a')] })).toBe(false)
   })
 
-  it('encodes a mid-prompt line change as a prefix/suffix trim', () => {
-    const prev = canonicalHeader({ config: CONFIG, system: 'keep1\nold\nkeep2\nkeep3' })
-    const next = canonicalHeader({ config: CONFIG, system: 'keep1\nnew A\nnew B\nkeep2\nkeep3' })
-    const delta = roundTrip(prev, next)
-    expect(delta?.system).toEqual({ keepStart: 1, keepEnd: 2, insert: ['new A', 'new B'] })
-    expect(delta?.tools).toBeUndefined()
-    expect(delta?.config).toBeUndefined()
-  })
-
-  it('degenerates to a full replacement when nothing is shared, and round-trips absence transitions', () => {
-    const none = canonicalHeader({ config: CONFIG })
-    const some = canonicalHeader({ config: CONFIG, system: 'x\ny' })
-    const gained = roundTrip(none, some)
-    expect(gained?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: ['x', 'y'] })
-    const lost = roundTrip(some, none)
-    expect(lost?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: [] })
-  })
-
-  it('does not double-count overlapping prefix and suffix (repeated lines)', () => {
-    const prev = canonicalHeader({ config: CONFIG, system: 'a\na' })
-    const next = canonicalHeader({ config: CONFIG, system: 'a\na\na' })
-    roundTrip(prev, next)
-  })
-
-  it('encodes tool addition, removal, and in-place schema change by name', () => {
-    const prev = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('drop'), tool('edit', 'before')] })
-    const next = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('edit', 'after'), tool('new')] })
-    const delta = roundTrip(prev, next)
-    expect(delta?.tools?.added.map(t => t.name)).toEqual(['new'])
-    expect(delta?.tools?.removed).toEqual(['drop'])
-    expect(delta?.tools?.changed.map(t => t.name)).toEqual(['edit'])
-  })
-
-  it('round-trips a tool set gained from a tool-less header and lost back to one', () => {
-    const none = canonicalHeader({ config: CONFIG })
-    const some = canonicalHeader({ config: CONFIG, tools: [tool('t')] })
-    const gained = roundTrip(none, some)
-    expect(gained?.tools?.added.map(t => t.name)).toEqual(['t'])
-    const lost = roundTrip(some, none)
-    expect(lost?.tools?.removed).toEqual(['t'])
-  })
-
-  it('cannot express a pure reordering — the writer detects it via the round-trip check', () => {
-    const prev = canonicalHeader({ config: CONFIG, tools: [tool('a'), tool('b')] })
-    const next = canonicalHeader({ config: CONFIG, tools: [tool('b'), tool('a')] })
-    const delta = diffHeader(prev, next)
-    // A delta IS produced (the lists differ)…
-    expect(delta).toBeDefined()
-    // …but applying it cannot reproduce the new order — exactly the case the
-    // writer's guard turns into a 'fallback' snapshot.
-    expect(applyHeaderDelta(prev, delta!)).not.toEqual(next)
-  })
-
-  it('replaces the config whole and leaves untouched parts alone', () => {
-    const prev = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 's', tools: [tool('t')] })
-    const next = canonicalHeader({ config: { provider: 'mock', model: 'm2', temperature: 0.1 }, system: 's', tools: [tool('t')] })
-    const delta = roundTrip(prev, next)
-    expect(delta).toEqual({ config: { provider: 'mock', model: 'm2', temperature: 0.1 } })
-  })
-})
-
-describe('the session prefix (messagePrefix)', () => {
-  it('canonicalHeader normalizes an empty prefix to an absent field', () => {
-    expect(canonicalHeader({ config: CONFIG, messagePrefix: [] })).toEqual({ config: CONFIG })
-    const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
-    expect(full.messagePrefix).toEqual([msg('p')])
-  })
-
-  it('headerEquals treats absence and empty as one representation, content differences as unequal', () => {
-    expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true)
-    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false)
-    expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG })).toBe(false)
-  })
-
-  it('replaces a changed prefix whole and leaves untouched parts alone', () => {
-    const prev = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('old')] })
-    const next = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('new'), msg('more')] })
-    const delta = roundTrip(prev, next)
-    expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] })
-  })
-
-  it('round-trips a prefix gained from a bare header and lost back to one (empty array encodes absence)', () => {
-    const none = canonicalHeader({ config: CONFIG })
-    const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] })
-    const gained = roundTrip(none, some)
-    expect(gained).toEqual({ messagePrefix: [msg('p')] })
-    const lost = roundTrip(some, none)
-    expect(lost).toEqual({ messagePrefix: [] })
-  })
-
-  it('folds prefix deltas over the log like any other header amendment', () => {
-    const session = new Session(SessionId('fold-prefix'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] })
-    session.append('request/header', { header: first, reason: 'initial' })
-    const second = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v2')] })
-    session.append('request/header-delta', diffHeader(first, second)!)
-    expect(foldRequestHeader(session.events)).toEqual(second)
-    session.append('request/header-delta', diffHeader(second, canonicalHeader({ config: CONFIG }))!)
-    expect(foldRequestHeader(session.events)).toEqual({ config: CONFIG })
+  it('treats absent and empty prefix/tool arrays as equivalent canonical absence', () => {
+    expect(headerEquals({ config: CONFIG }, { config: CONFIG, tools: [], messagePrefix: [] })).toBe(true)
   })
 })
 
 describe('foldRequestHeader', () => {
-  function headerEvents(session: Session): readonly SessionEvent[] {
-    return session.events
-  }
-
-  it('returns undefined on a log with no header events', () => {
-    const session = new Session(SessionId('fold-none'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(foldRequestHeader(headerEvents(session))).toBeUndefined()
+  it('returns the supplied baseline when no snapshot follows', () => {
+    const from: EpochHeader = { config: CONFIG, system: 'baseline' }
+    const unrelated: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    ]
+    expect(foldRequestHeader(unrelated)).toBeUndefined()
+    expect(foldRequestHeader(unrelated, from)).toBe(from)
   })
 
-  it('folds snapshot then deltas into the header in force, skipping unrelated events', () => {
+  it('takes the latest full snapshot and skips unrelated events', () => {
     const session = new Session(SessionId('fold'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] })
-    session.append('request/header', { header: first, reason: 'initial' })
+    session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' })
     session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-
-    const second = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nc', tools: [tool('t')] })
-    session.append('request/header-delta', diffHeader(first, second)!)
-    expect(foldRequestHeader(headerEvents(session))).toEqual(second)
-
-    // A later snapshot replaces the state wholesale (the 'resume'/'fallback' anchor).
-    const third = canonicalHeader({ config: { provider: 'mock', model: 'other' } })
-    session.append('request/header', { header: third, reason: 'resume' })
-    expect(foldRequestHeader(headerEvents(session))).toEqual(third)
-  })
-
-  it('throws on a delta before any snapshot (corrupt log)', () => {
-    const session = new Session(SessionId('fold-corrupt'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('request/header-delta', { config: { provider: 'mock', model: 'x' } })
-    expect(() => foldRequestHeader(headerEvents(session))).toThrow(/before any request\/header snapshot/)
+    session.append('request/header', { header: { config: { provider: 'mock', model: 'other' }, tools: [] }, reason: 'change' })
+    expect(foldRequestHeader(session.events)).toEqual({ config: { provider: 'mock', model: 'other' } })
+  })
+})
+
+describe('legacy request-header format', () => {
+  it('rejects request/header-delta in seeds and untyped appends', () => {
+    const legacy = [{
+      type: 'request/header-delta', seq: 0, time: 1, data: { config: CONFIG },
+    }] as unknown as SessionEvent[]
+    expect(() => new Session(SessionId('legacy'), legacy)).toThrow(/unsupported legacy request\/header-delta/)
+
+    const session = new Session(SessionId('legacy-append-delta'))
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+    expect(() => appendLegacy('request/header-delta', { config: CONFIG }))
+      .toThrow(/unsupported legacy request\/header-delta/)
+    expect(session.events).toHaveLength(0)
+  })
+
+  it('rejects the removed fallback reason in seeds and untyped appends', () => {
+    const legacy = [{
+      type: 'request/header', seq: 0, time: 1, data: { header: { config: CONFIG }, reason: 'fallback' },
+    }] as unknown as SessionEvent[]
+    expect(() => new Session(SessionId('legacy-seed-reason'), legacy))
+      .toThrow('unsupported legacy request/header reason "fallback"')
+
+    const session = new Session(SessionId('legacy-append-reason'))
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+    expect(() => appendLegacy('request/header', { header: { config: CONFIG }, reason: 'fallback' }))
+      .toThrow('unsupported legacy request/header reason "fallback"')
+    expect(session.events).toHaveLength(0)
   })
 })

packages/core/session/tests/session.spec.ts

@@ -101,13 +101,6 @@ describe('Session', () => {
     expect(() => new Session(SessionId('old-header'), [requestHeader]))
       .toThrow('seed request/header at index 0 lacks provider/model')
 
-    const requestDelta = {
-      type: 'request/header-delta', seq: 0, time: 1,
-      data: { config: { model: 'old-model' } },
-    } as unknown as SessionEvent
-    expect(() => new Session(SessionId('old-delta'), [requestDelta]))
-      .toThrow('seed request/header-delta at index 0 lacks provider/model')
-
     const assistantMessage = {
       type: 'assistant/message', seq: 0, time: 1,
       data: { turn: 1, step: 1, content: [{ type: 'text', text: 'old' }] },
@@ -1244,8 +1237,8 @@ describe('todo/write event', () => {
     session.append('todo/write', { todos: [{ content: 'a task', status: 'pending' }] })
     // The todo event must not add a message to the derived history…
     expect(session.deriveMessages()).toHaveLength(before)
-    // …and must not appear on the surface linked list.
-    expect(session.surface.nodes.some(node => node.seq === session.seq - 1)).toBe(false)
+    // …and must not appear on the ordered surface.
+    expect(session.surface.nodes).not.toContain(session.seq - 1)
   })
 
   it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => {

packages/core/session/tests/surface.spec.ts

@@ -54,6 +54,23 @@ describe('foldSurface provenance', () => {
     expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/)
   })
 
+  it('accepts explicit empty provenance on an assistant message', () => {
+    const event = {
+      type: 'assistant/message',
+      seq: 0,
+      time: 0,
+      data: {
+        provenance: { provider: 'mock', model: 'mock' },
+        turn: 1,
+        step: 1,
+        content: [],
+      },
+      surfaceOp: 'append',
+      sourceEventSeqs: [],
+    } as SessionEvent
+    expect(() => foldSurface([event])).not.toThrow()
+  })
+
   it.each([
     ['a non-array', [{ ...provenanceEvent(0, undefined), sourceEventSeqs: 'invalid' }], /must be an array/],
     ['an empty array', [provenanceEvent(0, [])], /must not be empty/],
@@ -78,7 +95,7 @@ describe('foldSurface provenance', () => {
 })
 
 describe('SurfaceManager', () => {
-  it('shares exact nodes and nested replacement ranges with foldSurface', () => {
+  it('shares ordered entries and nested replacement ranges with foldSurface', () => {
     const s = new Session(SessionId('shared-fold'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
@@ -91,9 +108,10 @@ describe('SurfaceManager', () => {
       { seq: 2, start: 0, end: 0, shadowedSeqs: [0] },
       { seq: 3, start: 2, end: 1, shadowedSeqs: [2, 1] },
     ])
-    folded.nodes[0]!.next = 99
+    folded.nodes[0] = 99
     folded.replacements[0]!.shadowedSeqs.push(99)
-    expect(s.surface.nodes).toEqual([{ seq: 3, prev: null, next: null }])
+    expect(s.surface.nodes).toEqual([3])
+    expect(foldSurface(s.events).nodes).toEqual([3])
     expect(foldSurface(s.events).replacements[0]!.shadowedSeqs).toEqual([0])
   })
 
@@ -102,7 +120,7 @@ describe('SurfaceManager', () => {
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'b' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
 
-    expect(s.surface.nodes).toEqual([{ seq: 1, prev: null, next: null }])
+    expect(s.surface.nodes).toEqual([1])
     const manager = s.surface as unknown as { _state: object }
     expect(Object.hasOwn(manager._state, 'replacements')).toBe(false)
     expect(foldSurface(s.events).replacements).toEqual([
@@ -133,7 +151,7 @@ describe('SurfaceManager', () => {
 
     expect(s.events).toHaveLength(1)
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(s.surface.nodes.map(node => node.seq)).toEqual([0, 1])
+    expect(s.surface.nodes).toEqual([0, 1])
   })
 
   it('foldSurface rejects a surface-eligible event without its mandatory marker', () => {
@@ -161,18 +179,12 @@ describe('SurfaceManager', () => {
       .toThrow(/not surface-eligible and cannot carry surfaceOp/)
   })
 
-  it('rebuilds a linked list from surfaceOp: append markers', () => {
+  it('folds an ordered sequence list from surfaceOp: append markers', () => {
     const s = surfaceSession()
     const nodes = s.surface.nodes
     // Only the user/message and assistant/message carry surfaceOp: 'append'.
     // The turn boundaries do not have surface markers.
-    expect(nodes.length).toBe(2)
-    expect(nodes[0]!.seq).toBe(1) // user/message (turn/start is seq 0)
-    expect(nodes[0]!.prev).toBeNull()
-    expect(nodes[0]!.next).toBe(2) // assistant/message (seq 2)
-    expect(nodes[1]!.seq).toBe(2)
-    expect(nodes[1]!.prev).toBe(1)
-    expect(nodes[1]!.next).toBeNull()
+    expect(nodes).toEqual([1, 2])
   })
 
   it('empty surface yields empty nodes', () => {
@@ -193,9 +205,7 @@ describe('SurfaceManager', () => {
     // Append another surface node
     s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
     expect(s.surface.nodes.length).toBe(3)
-    expect(s.surface.nodes[2]!.seq).toBe(4) // seq 4: after turn/end at seq 3
-    expect(s.surface.nodes[2]!.prev).toBe(2)
-    expect(s.surface.nodes[1]!.next).toBe(4)
+    expect(s.surface.nodes[2]!).toBe(4) // seq 4: after turn/end at seq 3
   })
 
   it('replays identically from a seeded log with surface markers', () => {
@@ -203,21 +213,17 @@ describe('SurfaceManager', () => {
     original.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
     const replayed = new Session(SessionId('replay'), [...original.events])
     // Surface rebuilds from the seeded log's markers.
-    expect(replayed.surface.nodes.map(n => n.seq)).toEqual([1, 2, 4])
+    expect(replayed.surface.nodes).toEqual([1, 2, 4])
     expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
   })
 
   it('rebuild with replace operation splices out shadowed nodes', () => {
     const s = surfaceSession()
-    // Replace surface seqs 1 (user) and 2 (assistant) with the summary.
     s.append('assistant/message',
       { provenance: { provider: 'mock', model: 'mock' }, turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
     )
-    expect(s.surface.nodes.length).toBe(1)
-    expect(s.surface.nodes[0]!.seq).toBe(4) // seq of the compaction marker
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([4])
   })
 
   it('replace with both ends at real nodes splices only the range', () => {
@@ -230,12 +236,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
       { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
     ) // seq 3
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([3, 2])
-    // Links: 3 ↔ 2
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBe(2)
-    expect(s.surface.nodes[1]!.prev).toBe(3)
-    expect(s.surface.nodes[1]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([3, 2])
   })
 
   it('single-node replacement (start === end)', () => {
@@ -247,9 +248,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 2
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 2])
-    expect(s.surface.nodes[0]!.next).toBe(2)
-    expect(s.surface.nodes[1]!.prev).toBe(0)
+    expect(s.surface.nodes).toEqual([0, 2])
   })
 
   it('throws when replace start is not found', () => {
@@ -293,7 +292,7 @@ describe('SurfaceManager', () => {
     expect(logged.sourceEventSeqs).toEqual([0])
   })
 
-  it('replace starting at non-head position links to previous node correctly', () => {
+  it('replace starting at non-head position preserves surrounding order', () => {
     const s = new Session(SessionId('mid-replace'))
     s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
     s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
@@ -303,14 +302,7 @@ describe('SurfaceManager', () => {
       { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
       { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
     ) // seq 3
-    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 3, 2])
-    // Links: 0 → 3 → 2
-    expect(s.surface.nodes[0]!.prev).toBeNull()
-    expect(s.surface.nodes[0]!.next).toBe(3)
-    expect(s.surface.nodes[1]!.prev).toBe(0)
-    expect(s.surface.nodes[1]!.next).toBe(2)
-    expect(s.surface.nodes[2]!.prev).toBe(3)
-    expect(s.surface.nodes[2]!.next).toBeNull()
+    expect(s.surface.nodes).toEqual([0, 3, 2])
   })
 
   it('surfaceOp replace object is snapshot so caller mutation is isolated', () => {
@@ -484,7 +476,7 @@ describe('SurfaceManager.replaceGeneration', () => {
     const nodes = s.surface.nodes
     s.append('context/message', {
       content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' },
-    }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] })
+    }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] })
     expect(s.surface.replaceGeneration).toBe(1)
   })
 })

packages/core/tools/src/index.ts

@@ -312,8 +312,8 @@ export interface ToolExecutionResult {
    */
   error?: ToolErrorInfo
   /**
-   * Model-facing context for the next request, separate from this tool result.
-   * The loop buffers it until all step results are logged, preserving pairing.
+   * Model-facing context for the next request, separate from this tool result. The loop
+   * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted.
    */
   additionalContexts?: HookContext[]
   /**
@@ -1013,7 +1013,7 @@ export class ToolRegistry extends Service {
    * its {@link PostToolDecision}: `accept` keeps the call successful (replacing
    * `content` when given), `block` turns it into an `isError` whose content is
    * the corrective `feedback`. Either decision may attach `additionalContexts`,
-   * which are ferried on the returned result for the loop's per-step buffer.
+   * which are ferried on the returned result for the loop's active-batch FIFO.
    * Context deferred by the tool body survives an accepted result but is
    * discarded when the outer call is blocked; a block exposes only context the
    * blocking decision explicitly supplied.

packages/llm/README.md

@@ -5,7 +5,8 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 | Package | Role | ctx key |
 |---|---|---|
 | `llm/` | Abstract LLM service + content-block vocabulary + chunk assembler | `ctx.llm` |
+| `token-meter/` | Replay-aware request and surface token measurement | `ctx.tokenMeter` |
 | `llm-deepseek/` | DeepSeek API adapter (hand-rolled fetch/SSE) | (registers on `ctx.llm`) |
 | `llm-pi-ai/` | Multi-provider adapter via `@earendil-works/pi-ai` | (registers on `ctx.llm`) |
 
-The interface lives at `llm/llm/`; adapters are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. A new provider adapter joins here and registers one or more provider routes on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations.
+The interface lives at `llm/llm/`; adapters and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. A new provider adapter joins here and registers one or more provider routes on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations and the [replay token meter RFC](../../docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership.

packages/llm/llm/src/call-config.ts

@@ -1,8 +1,8 @@
 /**
- * Conversation call configuration and freeze utilities. Model and sampling
- * values, including provider routing, are request-header state that can affect cache reuse; request
- * waterfalls replace them and the loop logs changes instead of allowing
- * silent per-call drift.
+ * Conversation call configuration and freeze utilities. Provider routing,
+ * model, and sampling values are request-header state that can affect cache
+ * reuse; request waterfalls replace them and the loop logs changed snapshots
+ * instead of allowing silent per-call drift.
  * @module dsh-llm/call-config
  */
 
@@ -22,7 +22,7 @@ export interface LlmCallConfig {
 /**
  * Field-wise equality over {@link LlmCallConfig} — the comparison a caller
  * runs to decide whether a proposed configuration is a real change (worth a
- * logged header delta) or the held one restated.
+ * logged header snapshot) or the held one restated.
  * @param a - one configuration.
  * @param b - the other.
  * @returns whether every field (including the `stop` list, element-wise) matches.

packages/llm/llm/tests/call-config.spec.ts

@@ -1,6 +1,6 @@
 /**
  * call-config unit tests: field-wise LlmCallConfig equality (the real-change
- * detector behind logged header deltas) and the deepFreeze ownership helper
+ * detector behind logged changed headers) and the deepFreeze ownership helper
  * the loop applies to every built request.
  */
 

packages/llm/token-meter/README.md

@@ -0,0 +1,50 @@
+# @deepseek-ai/dsh-token-meter
+
+Replay-aware token measurement through the singleton `ctx.tokenMeter` service. It advances one isolated fold per session from the durable log, so compaction and other pressure-sensitive plugins can share accounting without depending on `CompactService`.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `contextWindow` | `128000` | Positive integer service-wide context capacity. |
+
+The estimator intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. `contextWindow` is the only deployment setting. Direct construction validates it; Loader mounts first apply the package's Schemastery shape validation. Unrecognized top-level keys are rejected.
+
+## Measurement contract
+
+`ctx.tokenMeter` directly exposes two operations:
+
+- `measure(session, requestHeader?)` returns request pressure and the current priced surface at one consumed-log revision.
+- `estimateMessage(message)` prices one message with the fixed heuristic.
+
+`measure()` synchronizes once and returns one detached, deeply immutable snapshot. `totalTokens` is request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override affects pressure fields only; the surface fields still describe the current session. Every call clones the positional nodes, so measurement is O(surface).
+
+The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and assistant-chunk provenance. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
+
+Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty provenance list means a known empty provider stream, while absent legacy provenance conservatively treats the durable assistant output as provider output.
+
+## Composition
+
+```yaml
+- name: '@deepseek-ai/dsh-token-meter'
+- name: '@deepseek-ai/dsh-compact-basic'
+```
+
+Both plugins have usable defaults. A deployment with a different capacity configures the meter once:
+
+```yaml
+- name: '@deepseek-ai/dsh-token-meter'
+  config:
+    contextWindow: 32768
+```
+
+## Model Experience
+
+Indirectly, through consumers such as `dsh-compact-basic`; the service itself adds no prompt, message, schema, tool, or model call.
+
+## Known Limitations and Deferred Work
+
+- **The fixed heuristic is approximate** — content without reusable provider usage is priced by character count plus structural overhead, not an exact provider tokenizer or request serializer.
+- **Every measurement clones the current surface** — coherent immutable snapshots make reads O(surface), including below-threshold pressure checks.
+- **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, provider, model, or call-config changes deliberately fall back to full heuristic estimation.
+- **Legacy provenance is conservative** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.

packages/llm/token-meter/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-token-meter",
+  "description": "Replay-aware token measurement service (ctx.tokenMeter) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/llm/token-meter/src/index.ts

@@ -0,0 +1,419 @@
+/**
+ * Single replay-aware token-meter service for request and surface pressure.
+ *
+ * @module @deepseek-ai/dsh-token-meter
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, Session, SessionEvent, SurfaceEvent } from '@deepseek-ai/dsh-session'
+import { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import type {
+  TokenMeasurement,
+  TokenMeasurementBaseline,
+  TokenMeterConfig,
+  TokenSurfaceNode,
+} from './types.ts'
+
+export type * from './types.ts'
+
+/** Default service-wide provider context capacity. */
+const DEFAULT_CONTEXT_WINDOW = 128_000
+
+/** Complete public configuration key set. */
+const TOKEN_METER_CONFIG_KEYS: ReadonlySet<string> = new Set(['contextWindow'])
+
+/** Fixed text-density estimate used until exact tokenization is needed. */
+const CHARS_PER_TOKEN = 4
+
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4
+
+/** Role-field framing overhead added to every priced message. */
+const ROLE_OVERHEAD = 4
+
+interface MeasurementAnchor {
+  readonly header: EpochHeader | undefined
+  readonly surfaceTokens: number
+  readonly baseline: Exclude<TokenMeasurementBaseline, { kind: 'none' }>
+}
+
+interface ReplayState {
+  consumedEvents: number
+  header: EpochHeader | undefined
+  surface: TokenSurfaceNode[]
+  surfaceTokens: number
+  stepStart: { turn: number; step: number; surfaceTokens: number } | undefined
+  anchor: MeasurementAnchor | undefined
+}
+
+interface PreparedSurfaceMutation {
+  readonly tokens: number
+  commit(state: ReplayState): void
+}
+
+/** Sum disjoint provider usage buckets without double-counting reasoning output. */
+function usageTokens(usage: TokenUsage): number {
+  return usage.inputTokens
+    + (usage.cacheReadTokens ?? 0)
+    + (usage.cacheWriteTokens ?? 0)
+    + usage.outputTokens
+}
+
+/** Compare optional envelopes so a headerless estimate can track later surface deltas. */
+function optionalHeaderEquals(
+  left: EpochHeader | undefined,
+  right: EpochHeader | undefined,
+): boolean {
+  if (left === undefined || right === undefined) return left === right
+  return headerEquals(left, right)
+}
+
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateConfigKeys(config: TokenMeterConfig): void {
+  for (const key of Object.keys(config)) {
+    if (!TOKEN_METER_CONFIG_KEYS.has(key)) {
+      throw new Error(
+        `TokenMeterConfig: unknown key "${key}" (allowed: contextWindow)`,
+      )
+    }
+  }
+}
+
+/** Resolve and validate the one service-wide context capacity. */
+function resolveContextWindow(config: TokenMeterConfig): number {
+  validateConfigKeys(config)
+  const contextWindow = config.contextWindow === undefined
+    ? DEFAULT_CONTEXT_WINDOW
+    : config.contextWindow
+  if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+    throw new Error(
+      `TokenMeterConfig: contextWindow (${contextWindow}) must be a positive integer`,
+    )
+  }
+  return contextWindow
+}
+
+declare module 'cordis' {
+  interface Context {
+    tokenMeter: TokenMeterService
+  }
+}
+
+/** Replay owner for one service-wide estimator and isolated per-session folds. */
+export class TokenMeterService extends Service {
+  static Config: z<TokenMeterConfig> = z.object({
+    contextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
+  })
+
+  /** Provider context-window capacity used by pressure consumers. */
+  readonly contextWindow: number
+
+  private readonly states = new WeakMap<Session, ReplayState>()
+
+  constructor(ctx: Context, config: TokenMeterConfig = {}) {
+    super(ctx, 'tokenMeter')
+    this.contextWindow = resolveContextWindow(config)
+
+    // Readers catch up independently, while eager observation bounds ordinary
+    // read latency without creating state for sessions no consumer has read.
+    ctx.on('session/event', (session) => {
+      if (this.states.has(session)) this._sync(session)
+    })
+  }
+
+  /**
+   * Measure current request pressure and surface through the durable tail.
+   *
+   * Provider usage is reused only when the latest successful call's canonical
+   * request envelope matches `requestHeader` and its total is no lower than
+   * that call's full heuristic anchor; otherwise the complete envelope and
+   * surface are heuristically repriced.
+   *
+   * `requestHeader` affects request pressure only; surface fields always
+   * describe the current session surface. Every call clones those positional
+   * nodes, so measurement is O(surface).
+   *
+   * @param session - session to replay through its current durable tail.
+   * @param requestHeader - optional effective request envelope replacing the latest logged header.
+   * @returns a detached deeply immutable pressure and surface measurement.
+   */
+  measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement {
+    const state = this._sync(session)
+    const header = requestHeader === undefined
+      ? state.header
+      : canonicalHeader(requestHeader)
+    const anchor = state.anchor
+
+    let baseline: TokenMeasurementBaseline
+    let surfaceDeltaTokens: number
+    if (anchor !== undefined && optionalHeaderEquals(anchor.header, header)) {
+      baseline = anchor.baseline
+      surfaceDeltaTokens = state.surfaceTokens - anchor.surfaceTokens
+    } else if (header === undefined && state.surfaceTokens === 0) {
+      baseline = { kind: 'none', tokens: 0 }
+      surfaceDeltaTokens = 0
+    } else {
+      baseline = {
+        kind: 'estimated',
+        tokens: this._estimateHeader(header) + state.surfaceTokens,
+      }
+      surfaceDeltaTokens = 0
+    }
+
+    return deepFreeze(structuredClone({
+      logRevision: state.consumedEvents,
+      baseline,
+      surfaceDeltaTokens,
+      totalTokens: Math.max(0, baseline.tokens + surfaceDeltaTokens),
+      surfaceTokens: state.surfaceTokens,
+      nodes: state.surface,
+    }))
+  }
+
+  /**
+   * Heuristically price one model-visible message.
+   * @param message - message to price without mutation.
+   * @returns content and role-framing tokens under the fixed service heuristic.
+   */
+  estimateMessage(message: Message): number {
+    return this._estimateContent(message.content) + ROLE_OVERHEAD
+  }
+
+  /** Catch one session's fold up to the current durable tail. */
+  private _sync(session: Session): ReplayState {
+    let state = this.states.get(session)
+    if (state === undefined) {
+      state = {
+        consumedEvents: 0,
+        header: undefined,
+        surface: [],
+        surfaceTokens: 0,
+        stepStart: undefined,
+        anchor: undefined,
+      }
+      this.states.set(session, state)
+    }
+
+    while (state.consumedEvents < session.events.length) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- contiguous session seqs index the durable log
+      const event = session.events[state.consumedEvents]!
+      this._foldEvent(session, state, event)
+      state.consumedEvents += 1
+    }
+    return state
+  }
+
+  /**
+   * Validate and prepare every fallible part before mutating replay state.
+   * A malformed event remains unread on every retry instead of partially
+   * applying the same mutation more than once.
+   */
+  private _foldEvent(session: Session, state: ReplayState, event: SessionEvent): void {
+    let nextHeader = state.header
+    let nextStepStart = state.stepStart
+    let nextAnchor = state.anchor
+
+    switch (event.type) {
+      case 'request/header':
+        nextHeader = canonicalHeader(event.data.header)
+        break
+      case 'step/start':
+        if (state.stepStart !== undefined) {
+          throw new Error(
+            `token meter: step/start at seq ${event.seq} arrived before turn ${state.stepStart.turn}/step ${state.stepStart.step} ended`,
+          )
+        }
+        nextStepStart = { ...event.data, surfaceTokens: state.surfaceTokens }
+        break
+      case 'step/end':
+        if (state.stepStart === undefined
+          || state.stepStart.turn !== event.data.turn
+          || state.stepStart.step !== event.data.step) {
+          throw new Error(`token meter: step/end at seq ${event.seq} has no matching step/start boundary`)
+        }
+        nextStepStart = undefined
+        break
+      default:
+        break
+    }
+
+    const surface = isSurfaceEvent(event)
+      ? this._prepareSurfaceMutation(session, state, event)
+      : undefined
+
+    if (event.type === 'assistant/message') {
+      const stepStart = state.stepStart
+      if (stepStart === undefined
+        || stepStart.turn !== event.data.turn
+        || stepStart.step !== event.data.step) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} has no matching step/start boundary`)
+      }
+
+      // assistant/message is surface-mandatory at every append/seed boundary.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const eventTokens = surface!.tokens
+      if (event.data.usage !== undefined && nextHeader !== undefined) {
+        const providerAssistantTokens = this._estimateProviderAssistant(
+          session,
+          event,
+          eventTokens,
+        )
+        const anchorSurfaceTokens = stepStart.surfaceTokens + providerAssistantTokens
+        const providerTokens = usageTokens(event.data.usage)
+        const estimatedAnchorTokens = this._estimateHeader(nextHeader) + anchorSurfaceTokens
+        nextAnchor = {
+          header: nextHeader,
+          surfaceTokens: anchorSurfaceTokens,
+          // Signed heuristic deltas remain conservative only from an anchor
+          // that is at least as large as the matching full heuristic price.
+          baseline: providerTokens >= estimatedAnchorTokens
+            ? { kind: 'usage', tokens: providerTokens, usage: event.data.usage }
+            : { kind: 'estimated', tokens: estimatedAnchorTokens },
+        }
+      } else {
+        const anchorSurfaceTokens = stepStart.surfaceTokens + eventTokens
+        nextAnchor = {
+          header: nextHeader,
+          surfaceTokens: anchorSurfaceTokens,
+          baseline: {
+            kind: 'estimated',
+            tokens: this._estimateHeader(nextHeader) + anchorSurfaceTokens,
+          },
+        }
+      }
+    }
+
+    state.header = nextHeader
+    state.stepStart = nextStepStart
+    if (surface !== undefined) surface.commit(state)
+    state.anchor = nextAnchor
+  }
+
+  /** Validate one surface operation and return its allocation-light commit. */
+  private _prepareSurfaceMutation(
+    session: Session,
+    state: ReplayState,
+    event: SurfaceEvent,
+  ): PreparedSurfaceMutation {
+    const tokens = this._estimateSurfaceEvent(session, event)
+    const op = event.surfaceOp
+    if (op === 'append') {
+      return {
+        tokens,
+        commit(target) {
+          target.surface.push({ seq: event.seq, tokens })
+          target.surfaceTokens += tokens
+        },
+      }
+    }
+
+    const startIdx = state.surface.findIndex(node => node.seq === op.start)
+    const endIdx = state.surface.findIndex(node => node.seq === op.end)
+    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+      throw new Error(
+        `token meter: replace at seq ${event.seq} has invalid current range ${op.start}-${op.end}`,
+      )
+    }
+    const removedTokens = state.surface
+      .slice(startIdx, endIdx + 1)
+      .reduce((total, node) => total + node.tokens, 0)
+    return {
+      tokens,
+      commit(target) {
+        target.surface.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, tokens })
+        target.surfaceTokens += tokens - removedTokens
+      },
+    }
+  }
+
+  /** Price one current surface event exactly as it projects to a request. */
+  private _estimateSurfaceEvent(session: Session, event: SurfaceEvent): number {
+    const message = session.deriveEventMessage(event)
+    return message === null ? 0 : this.estimateMessage(message)
+  }
+
+  /**
+   * Reassemble provider output from exact chunk provenance for a usage anchor.
+   * Missing legacy provenance conservatively treats the durable output as the
+   * provider output; explicit empty provenance prices a known empty stream.
+   */
+  private _estimateProviderAssistant(
+    session: Session,
+    event: SessionEvent<'assistant/message'>,
+    durableEventTokens: number,
+  ): number {
+    const sourceSeqs = event.sourceEventSeqs
+    if (sourceSeqs === undefined) return durableEventTokens
+
+    const assembler = new BlockAssembler()
+    const seen = new Set<number>()
+    for (const seq of sourceSeqs) {
+      if (seq >= event.seq) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not earlier`)
+      }
+      if (seen.has(seq)) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} repeats source seq ${seq}`)
+      }
+      seen.add(seq)
+      // Session construction validates contiguous seqs, and the explicit
+      // earlier-than-assistant check above therefore guarantees existence.
+      const source = session.events[seq]
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const sourceEvent = source!
+      if (sourceEvent.type !== 'assistant/chunk') {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not assistant/chunk`)
+      }
+      if (sourceEvent.data.turn !== event.data.turn || sourceEvent.data.step !== event.data.step) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} belongs to another step`)
+      }
+      assembler.push(sourceEvent.data.chunk)
+    }
+    const providerMessage = assembler.message()
+    return providerMessage.content.length === 0 ? 0 : this.estimateMessage(providerMessage)
+  }
+
+  /** Price content blocks recursively under the fixed density heuristic. */
+  private _estimateContent(blocks: readonly ContentBlock[]): number {
+    let tokens = 0
+    for (const block of blocks) {
+      switch (block.type) {
+        case 'text':
+        case 'reasoning':
+          tokens += Math.ceil(block.text.length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+          break
+        case 'tool-call':
+          tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN)
+            + Math.ceil(block.arguments.length / CHARS_PER_TOKEN)
+            + BLOCK_OVERHEAD
+          break
+        case 'tool-result':
+          tokens += this._estimateContent(block.content) + BLOCK_OVERHEAD
+          break
+        default:
+          // ContentBlockMap is merge-extensible; unknown blocks retain a
+          // conservative structural JSON price under the fixed heuristic.
+          tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN)
+      }
+    }
+    return tokens
+  }
+
+  /** Price the canonical non-surface request envelope. */
+  private _estimateHeader(header: EpochHeader | undefined): number {
+    if (header === undefined) return 0
+    let tokens = 0
+    for (const message of header.messagePrefix ?? []) tokens += this.estimateMessage(message)
+    if (header.system !== undefined) {
+      tokens += Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD
+    }
+    if (header.tools !== undefined && header.tools.length > 0) {
+      tokens += Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD
+    }
+    return tokens
+  }
+}
+
+export default TokenMeterService

packages/llm/token-meter/src/types.ts

@@ -0,0 +1,43 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @deepseek-ai/dsh-token-meter/types
+ */
+
+import type { TokenUsage } from '@deepseek-ai/dsh-llm'
+
+/** Token-meter plugin configuration. */
+export interface TokenMeterConfig {
+  /** Service-wide context-window capacity in tokens. Defaults to `128000`. */
+  contextWindow?: number
+}
+
+/** The baseline from which a signed surface delta produces current pressure. */
+export type TokenMeasurementBaseline =
+  | { readonly kind: 'none'; readonly tokens: 0 }
+  | { readonly kind: 'estimated'; readonly tokens: number }
+  | { readonly kind: 'usage'; readonly tokens: number; readonly usage: Readonly<TokenUsage> }
+
+/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
+export interface TokenMeasurement {
+  /** Number of durable events consumed; equal to the next unread event seq. */
+  readonly logRevision: number
+  /** Provider or heuristic anchor used for this measurement. */
+  readonly baseline: TokenMeasurementBaseline
+  /** Signed repricing of current surface content relative to the baseline anchor. */
+  readonly surfaceDeltaTokens: number
+  /** Non-negative current request-and-response pressure. */
+  readonly totalTokens: number
+  /** Total heuristic tokens across the current surface. */
+  readonly surfaceTokens: number
+  /** Current surface nodes in positional head-to-tail order. */
+  readonly nodes: readonly TokenSurfaceNode[]
+}
+
+/** One token-priced node in the current ordered session surface. */
+export interface TokenSurfaceNode {
+  /** Durable sequence number of the surface event. */
+  readonly seq: number
+  /** Heuristic tokens for the exact message projected by this node. */
+  readonly tokens: number
+}

packages/llm/token-meter/tests/token-meter.spec.ts

@@ -0,0 +1,649 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { Session, SessionId, canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import type { TokenMeasurement, TokenMeterConfig } from '@deepseek-ai/dsh-token-meter'
+
+function header(model: string, extras: Omit<EpochHeader, 'config'> = {}): EpochHeader {
+  return canonicalHeader({ config: { provider: 'mock', model }, ...extras })
+}
+
+function textMessage(text: string, role: Message['role'] = 'user'): Message {
+  return { role, content: [{ type: 'text', text }] }
+}
+
+function appendHeader(session: Session, value: EpochHeader): void {
+  session.append('request/header', { header: value, reason: 'initial' })
+}
+
+/** Inject malformed persisted history after the live append boundary for defensive replay tests. */
+function appendUnchecked(session: Session, event: SessionEvent): void {
+  const log = (session as unknown as { log: SessionEvent[] }).log
+  log.push(event)
+}
+
+interface SuccessfulCallOptions {
+  turn?: number
+  step?: number
+  providerText?: string
+  durableText?: string
+  usage?: TokenUsage
+  provenance?: 'exact' | 'empty' | 'absent'
+}
+
+function appendSuccessfulCall(
+  session: Session,
+  value: EpochHeader,
+  options: SuccessfulCallOptions = {},
+): void {
+  const turn = options.turn ?? 1
+  const step = options.step ?? 1
+  const providerText = options.providerText ?? 'provider answer'
+  const durableText = options.durableText ?? providerText
+  const provenance = options.provenance ?? 'exact'
+  session.append('step/start', { turn, step })
+  appendHeader(session, value)
+
+  const sources: number[] = []
+  if (provenance === 'exact') {
+    const chunks = [
+      { type: 'block-start' as const, index: 0, blockType: 'text' as const },
+      { type: 'text-delta' as const, index: 0, text: providerText },
+      { type: 'block-end' as const, index: 0, block: { type: 'text' as const, text: providerText } },
+      ...options.usage === undefined ? [] : [{ type: 'usage' as const, usage: options.usage }],
+      { type: 'finish' as const, reason: { kind: 'stop' as const } },
+    ]
+    for (const chunk of chunks) {
+      sources.push(session.append('assistant/chunk', { turn, step, chunk }).seq)
+    }
+  }
+
+  const intent = provenance === 'absent'
+    ? { surfaceOp: 'append' as const }
+    : { surfaceOp: 'append' as const, sourceEventSeqs: provenance === 'empty' ? [] : sources }
+  session.append('assistant/message', {
+    provenance: {
+      provider: value.config.provider,
+      model: value.config.model,
+    },
+    turn,
+    step,
+    content: durableText.length === 0 ? [] : [{ type: 'text', text: durableText }],
+    ...options.usage === undefined ? {} : { usage: options.usage },
+  }, intent)
+  session.append('step/end', { turn, step })
+}
+
+function meter(config: TokenMeterConfig = {}): TokenMeterService {
+  return new TokenMeterService(new Context(), config)
+}
+
+function expectSurfaceTotal(measurement: TokenMeasurement): void {
+  expect(measurement.nodes.reduce((total, node) => total + node.tokens, 0))
+    .toBe(measurement.surfaceTokens)
+}
+
+describe('TokenMeterService configuration and registration', () => {
+  it('provides one zero-config context window', () => {
+    const service = meter()
+    expect(service.contextWindow).toBe(128_000)
+  })
+
+  it('accepts one service-wide context-window override', () => {
+    expect(meter({ contextWindow: 32_000 }).contextWindow).toBe(32_000)
+  })
+
+  it.each(['models', 'contextWidow'])('rejects unknown top-level config key %s', (key) => {
+    expect(() => meter({ [key]: {} }))
+      .toThrow(`TokenMeterConfig: unknown key "${key}"`)
+  })
+
+  it.each([
+    { contextWindow: 0 },
+    { contextWindow: -1 },
+    { contextWindow: 1.5 },
+    { contextWindow: Number.NaN },
+    { contextWindow: null },
+  ] as unknown as TokenMeterConfig[])('rejects invalid context capacity %#', (config) => {
+    expect(() => meter(config)).toThrow(/contextWindow .* positive integer/)
+  })
+
+  it('registers and unregisters ctx.tokenMeter with its plugin fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(TokenMeterService)
+    expect(ctx.get('tokenMeter')).toBeInstanceOf(TokenMeterService)
+    await fiber.dispose()
+    expect(ctx.get('tokenMeter')).toBeUndefined()
+  })
+})
+
+describe('TokenMeterService pricing', () => {
+  it('prices every built-in content shape and merge-extended blocks with one fixed heuristic', () => {
+    const service = meter({ contextWindow: 100 })
+    const blocks: ContentBlock[] = [
+      { type: 'text', text: 'abcd' },
+      { type: 'reasoning', text: 'ab' },
+      { type: 'tool-call', id: CallId('c'), name: 'read', arguments: '{"x":1}' },
+      {
+        type: 'tool-result',
+        toolCallId: CallId('c'),
+        content: [{ type: 'text', text: 'xy' }],
+        isError: false,
+      },
+      { type: 'future-block', payload: 'abcd' } as unknown as ContentBlock,
+    ]
+    const estimated = service.estimateMessage({ role: 'assistant', content: blocks })
+    expect(estimated).toBeGreaterThan(30)
+    expect(service.estimateMessage(textMessage('abcd'))).toBe(9)
+  })
+
+  it('returns a detached deeply immutable empty measurement', () => {
+    const service = meter()
+    const session = new Session(SessionId('empty'))
+    const result = service.measure(session)
+    expect(result).toEqual({
+      logRevision: 0,
+      baseline: { kind: 'none', tokens: 0 },
+      surfaceDeltaTokens: 0,
+      totalTokens: 0,
+      surfaceTokens: 0,
+      nodes: [],
+    })
+    expect(Object.isFrozen(result)).toBe(true)
+    expect(Object.isFrozen(result.baseline)).toBe(true)
+    expect(Object.isFrozen(result.nodes)).toBe(true)
+    expectSurfaceTotal(result)
+    expect(() => {
+      ;(result as { totalTokens: number }).totalTokens = 1
+    }).toThrow(TypeError)
+  })
+
+  it('keeps an earlier unified snapshot detached from later replay', () => {
+    const service = meter()
+    const session = new Session(SessionId('detached'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'first' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const snapshot = service.measure(session)
+    const snapshotCopy = structuredClone(snapshot)
+    expect(Object.isFrozen(snapshot.nodes)).toBe(true)
+    expect(Object.isFrozen(snapshot.nodes[0])).toBe(true)
+    expectSurfaceTotal(snapshot)
+    expect(() => {
+      ;(snapshot.nodes as Array<{ seq: number; tokens: number }>).push({ seq: 99, tokens: 1 })
+    }).toThrow(TypeError)
+    expect(() => {
+      ;(snapshot.nodes[0] as { seq: number; tokens: number }).tokens = 1
+    }).toThrow(TypeError)
+
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'second' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const advanced = service.measure(session)
+    expect(advanced.logRevision).toBe(2)
+    expect(advanced.nodes).toHaveLength(2)
+    expectSurfaceTotal(advanced)
+    expect(snapshot).toEqual(snapshotCopy)
+    expect(snapshot.logRevision).toBe(1)
+    expect(snapshot.nodes).toHaveLength(1)
+  })
+
+  it('prices header, prefix, tools, and surface when no reusable usage exists', () => {
+    const service = meter()
+    const session = new Session(SessionId('heuristic'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'question' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendHeader(session, header('deepseek-v4-flash', {
+      system: 'system',
+      messagePrefix: [textMessage('prefix')],
+      tools: [{ name: 'read', description: 'read', parameters: { type: 'object' } }],
+    }))
+    const result = service.measure(session)
+    expect(result.baseline.kind).toBe('estimated')
+    expect(result.totalTokens).toBeGreaterThan(result.surfaceTokens)
+    expect(result.logRevision).toBe(session.events.length)
+    expectSurfaceTotal(result)
+  })
+
+  it('keeps request-header overrides out of the returned surface', () => {
+    const service = meter()
+    const session = new Session(SessionId('override-surface'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'question' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+
+    const logged = service.measure(session)
+    const overridden = service.measure(session, header('another-model', {
+      system: 'large override '.repeat(100),
+    }))
+    expect(overridden.totalTokens).toBeGreaterThan(logged.totalTokens)
+    expect(overridden.surfaceTokens).toBe(logged.surfaceTokens)
+    expect(overridden.nodes).toEqual(logged.nodes)
+    expectSurfaceTotal(overridden)
+  })
+})
+
+describe('replay anchors and surface folds', () => {
+  const USAGE: TokenUsage = {
+    inputTokens: 20,
+    cacheReadTokens: 3,
+    cacheWriteTokens: 4,
+    outputTokens: 7,
+    reasoningTokens: 6,
+  }
+
+  it('uses disjoint provider usage and signed durable-output rewrites', () => {
+    const service = meter()
+    const session = new Session(SessionId('usage'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'before' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendSuccessfulCall(session, header('deepseek-v4-flash'), {
+      providerText: 'short',
+      durableText: 'a much longer rewritten durable assistant answer',
+      usage: USAGE,
+    })
+    const result = service.measure(session)
+    expect(result.baseline).toMatchObject({ kind: 'usage', tokens: 34, usage: USAGE })
+    expect(result.surfaceDeltaTokens).toBeGreaterThan(0)
+    expect(result.totalTokens).toBe(34 + result.surfaceDeltaTokens)
+    expect(() => {
+      ;((result.baseline as { usage: { inputTokens: number } }).usage.inputTokens) = 1
+    }).toThrow(TypeError)
+  })
+
+  it('selects a heuristic anchor when provider usage would undercut its scale', () => {
+    const service = meter()
+    const session = new Session(SessionId('low-usage-anchor'))
+    const system = 'system context'
+    const requestHeader = header('deepseek-v4-flash', { system })
+    appendSuccessfulCall(session, requestHeader, {
+      providerText: 'abcd'.repeat(512),
+      usage: { inputTokens: 20, outputTokens: 7 },
+    })
+
+    const anchored = service.measure(session)
+    expect(anchored.baseline.kind).toBe('estimated')
+    const assistant = anchored.nodes[0]!.seq
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'short' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }, {
+      surfaceOp: { op: 'replace', start: assistant, end: assistant },
+      sourceEventSeqs: [assistant],
+    })
+
+    const shrunken = service.measure(session)
+    expect(27 + shrunken.surfaceDeltaTokens).toBeLessThan(0)
+    expect(shrunken.totalTokens).toBeGreaterThan(0)
+    expect(shrunken.totalTokens).toBe(service.measure(
+      session,
+      header('different-model', { system }),
+    ).totalTokens)
+  })
+
+  it('uses an estimated anchor when provider usage is absent', () => {
+    const service = meter()
+    const session = new Session(SessionId('missing-usage'))
+    appendSuccessfulCall(session, header('deepseek-v4-flash', { system: 's' }), {
+      providerText: 'provider',
+      durableText: 'rewritten',
+    })
+    const anchored = service.measure(session)
+    expect(anchored.baseline.kind).toBe('estimated')
+    expect(anchored.surfaceDeltaTokens).toBe(0)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'later' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const advanced = service.measure(session)
+    expect(advanced.surfaceDeltaTokens).toBeGreaterThan(0)
+  })
+
+  it('distinguishes explicit empty provenance from absent legacy provenance', () => {
+    const explicit = new Session(SessionId('explicit-empty'))
+    const legacy = new Session(SessionId('legacy-absent'))
+    appendSuccessfulCall(explicit, header('deepseek-v4-flash'), {
+      durableText: 'listener injected text',
+      providerText: '',
+      usage: USAGE,
+      provenance: 'empty',
+    })
+    appendSuccessfulCall(legacy, header('deepseek-v4-flash'), {
+      durableText: 'listener injected text',
+      providerText: '',
+      usage: USAGE,
+      provenance: 'absent',
+    })
+    const service = meter()
+    expect(service.measure(explicit).surfaceDeltaTokens).toBeGreaterThan(0)
+    expect(service.measure(legacy).surfaceDeltaTokens).toBe(0)
+  })
+
+  it('keeps only the latest successful request anchor across model switches', () => {
+    const service = meter({ contextWindow: 1_000 })
+    const session = new Session(SessionId('switch'))
+    const alphaHeader = header('alpha', { system: 'same envelope' })
+    appendSuccessfulCall(session, alphaHeader, { usage: USAGE, providerText: 'alpha' })
+    expect(service.measure(session).baseline).toMatchObject({ kind: 'usage', tokens: 34 })
+
+    appendSuccessfulCall(session, header('beta'), {
+      turn: 1,
+      step: 2,
+      usage: { inputTokens: 100, outputTokens: 50 },
+      providerText: 'beta response',
+    })
+    expect(service.measure(session).baseline).toMatchObject({ kind: 'usage', tokens: 150 })
+
+    appendHeader(session, alphaHeader)
+    const switchedBack = service.measure(session)
+    expect(switchedBack.baseline.kind).toBe('estimated')
+    expect(switchedBack.surfaceDeltaTokens).toBe(0)
+  })
+
+  it('invalidates usage for any canonical envelope change or explicit override', () => {
+    const service = meter()
+    const session = new Session(SessionId('envelope'))
+    const anchoredHeader = header('deepseek-v4-flash', { system: 'one' })
+    appendSuccessfulCall(session, anchoredHeader, { usage: USAGE })
+    expect(service.measure(session, { ...anchoredHeader, tools: [] }).baseline.kind).toBe('usage')
+    expect(service.measure(session, header('deepseek-v4-flash', { system: 'two' })).baseline.kind)
+      .toBe('estimated')
+    expect(service.measure(session, header('deepseek-v4-pro', { system: 'one' })).baseline.kind)
+      .toBe('estimated')
+    expect(service.measure(session, {
+      ...anchoredHeader,
+      config: { ...anchoredHeader.config, temperature: 0.2 },
+    }).baseline.kind).toBe('estimated')
+    expect(service.measure(session, {
+      ...anchoredHeader,
+      messagePrefix: [textMessage('prefix')],
+    }).baseline.kind).toBe('estimated')
+    expect(service.measure(session, {
+      ...anchoredHeader,
+      tools: [{ name: 'read', description: 'read', parameters: { type: 'object' } }],
+    }).baseline.kind).toBe('estimated')
+  })
+
+  it('folds the latest full header snapshot into the effective envelope', () => {
+    const session = new Session(SessionId('header-snapshot'))
+    appendHeader(session, header('deepseek-v4-flash'))
+    session.append('request/header', {
+      header: header('deepseek-v4-pro'),
+      reason: 'change',
+    })
+    const result = meter().measure(session)
+    expect(result.baseline.kind).toBe('estimated')
+    expect(result.logRevision).toBe(2)
+  })
+
+  it('replays seeded append and replace operations with signed deltas', () => {
+    const service = meter()
+    const original = new Session(SessionId('surface-original'))
+    appendSuccessfulCall(original, header('deepseek-v4-flash'), {
+      usage: USAGE,
+      providerText: 'long provider answer '.repeat(100),
+    })
+    original.append('user/message', {
+      content: [{ type: 'text', text: 'new tail' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const seeded = new Session(SessionId('surface-seeded'), original.events)
+    const before = service.measure(seeded)
+    expect(before.nodes).toHaveLength(2)
+    expect(before.surfaceDeltaTokens).toBeGreaterThan(0)
+    expectSurfaceTotal(before)
+
+    const first = seeded.surface.nodes[0]!
+    seeded.append('user/message', {
+      content: [{ type: 'text', text: 'replacement' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }, { surfaceOp: { op: 'replace', start: first, end: first }, sourceEventSeqs: [first] })
+    const after = service.measure(seeded)
+    expect(after.nodes).toHaveLength(2)
+    expect(after.nodes[0]!.seq).toBe(seeded.events.length - 1)
+    expect(after.logRevision).toBe(seeded.events.length)
+    expect(Object.isFrozen(after.nodes)).toBe(true)
+    expect(Object.isFrozen(after.nodes[0])).toBe(true)
+    expect(after.surfaceDeltaTokens).toBeLessThan(0)
+    expectSurfaceTotal(after)
+    expect(before.nodes).toHaveLength(2)
+    expect(before.logRevision).toBe(original.events.length)
+    expect(before.surfaceDeltaTokens).toBeGreaterThan(0)
+  })
+
+  it('prices an empty assistant surface anchor as zero', () => {
+    const session = new Session(SessionId('empty-assistant'))
+    appendSuccessfulCall(session, header('deepseek-v4-flash'), {
+      providerText: '',
+      durableText: '',
+      provenance: 'empty',
+    })
+    const measurement = meter().measure(session)
+    const assistant = session.events.find(event => event.type === 'assistant/message')!
+    expect(measurement.nodes).toEqual([{ seq: assistant.seq, tokens: 0 }])
+    expect(measurement.surfaceTokens).toBe(0)
+    expectSurfaceTotal(measurement)
+  })
+})
+
+describe('malformed replay and listener lifecycle', () => {
+  function expectRepeatedFailure(service: TokenMeterService, session: Session, pattern: RegExp): void {
+    expect(() => service.measure(session)).toThrow(pattern)
+    expect(() => service.measure(session)).toThrow(pattern)
+  }
+
+  it('rejects an assistant without its step boundary transactionally', () => {
+    const session = new Session(SessionId('bad-step'))
+    appendHeader(session, header('deepseek-v4-flash'))
+    session.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'bad' }],
+    }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    expectRepeatedFailure(meter(), session, /no matching step\/start/)
+  })
+
+  it('clears completed step boundaries and rejects overlapping or late step events', () => {
+    const overlapping = new Session(SessionId('overlapping-step'))
+    overlapping.append('step/start', { turn: 1, step: 1 })
+    overlapping.append('step/start', { turn: 1, step: 2 })
+    expectRepeatedFailure(
+      meter(),
+      overlapping,
+      /arrived before turn 1\/step 1 ended/,
+    )
+
+    const late = new Session(SessionId('late-assistant'))
+    late.append('step/start', { turn: 1, step: 1 })
+    appendHeader(late, header('deepseek-v4-flash'))
+    late.append('step/end', { turn: 1, step: 1 })
+    late.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+      turn: 1,
+      step: 1,
+      content: [],
+    }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    expectRepeatedFailure(
+      meter(),
+      late,
+      /no matching step\/start/,
+    )
+
+    const mismatchedEnd = new Session(SessionId('mismatched-end'))
+    mismatchedEnd.append('step/start', { turn: 1, step: 1 })
+    mismatchedEnd.append('step/end', { turn: 1, step: 2 })
+    expectRepeatedFailure(
+      meter(),
+      mismatchedEnd,
+      /step\/end .* no matching step\/start/,
+    )
+  })
+
+  it('rejects invalid assistant provenance', () => {
+    const cases: Array<{
+      name: string
+      appendSource(session: Session): number[]
+      pattern: RegExp
+    }> = [
+      {
+        name: 'non-chunk',
+        appendSource(session) {
+          return [session.append('user/message', {
+            content: [{ type: 'text', text: 'x' }],
+            source: { kind: 'user' },
+          }, { surfaceOp: 'append' }).seq]
+        },
+        pattern: /is not assistant\/chunk/,
+      },
+      {
+        name: 'wrong-step',
+        appendSource(session) {
+          return [session.append('assistant/chunk', {
+            turn: 1,
+            step: 2,
+            chunk: { type: 'finish', reason: { kind: 'stop' } },
+          }).seq]
+        },
+        pattern: /belongs to another step/,
+      },
+    ]
+    for (const testCase of cases) {
+      const session = new Session(SessionId(`bad-source-${testCase.name}`))
+      session.append('step/start', { turn: 1, step: 1 })
+      appendHeader(session, header('deepseek-v4-flash'))
+      const sourceEventSeqs = testCase.appendSource(session)
+      session.append('assistant/message', {
+        provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+        turn: 1,
+        step: 1,
+        content: [{ type: 'text', text: 'bad' }],
+        usage: { inputTokens: 1, outputTokens: 1 },
+      }, { surfaceOp: 'append', sourceEventSeqs })
+      expect(() => meter().measure(session)).toThrow(testCase.pattern)
+    }
+  })
+
+  it('rejects repeated and non-earlier assistant provenance', () => {
+    const duplicate = new Session(SessionId('duplicate-source'))
+    duplicate.append('step/start', { turn: 1, step: 1 })
+    appendHeader(duplicate, header('deepseek-v4-flash'))
+    const source = duplicate.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'finish', reason: { kind: 'stop' } },
+    }).seq
+    appendUnchecked(duplicate, {
+      type: 'assistant/message',
+      seq: duplicate.seq,
+      time: 0,
+      data: {
+        provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+        turn: 1,
+        step: 1,
+        content: [],
+        usage: { inputTokens: 1, outputTokens: 0 },
+      },
+      surfaceOp: 'append',
+      sourceEventSeqs: [source, source],
+    })
+    expect(() => meter().measure(duplicate)).toThrow(/repeats source seq/)
+
+    const future = new Session(SessionId('future-source'))
+    future.append('step/start', { turn: 1, step: 1 })
+    appendHeader(future, header('deepseek-v4-flash'))
+    appendUnchecked(future, {
+      type: 'assistant/message',
+      seq: future.seq,
+      time: 0,
+      data: {
+        provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+        turn: 1,
+        step: 1,
+        content: [],
+        usage: { inputTokens: 1, outputTokens: 0 },
+      },
+      surfaceOp: 'append',
+      sourceEventSeqs: [99],
+    })
+    expect(() => meter().measure(future)).toThrow(/is not earlier/)
+  })
+
+  it('does not partially apply a malformed assistant replacement', () => {
+    const session = new Session(SessionId('transactional-replace'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'head' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendHeader(session, header('deepseek-v4-flash'))
+    const head = session.events[0]!.seq
+    session.append('assistant/message', {
+      provenance: { provider: 'mock', model: 'deepseek-v4-flash' },
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'replacement' }],
+    }, { surfaceOp: { op: 'replace', start: head, end: head }, sourceEventSeqs: [head] })
+    expectRepeatedFailure(
+      meter(),
+      session,
+      /no matching step\/start/,
+    )
+  })
+
+  it('rejects corrupt replacement ranges without advancing the replay cursor', () => {
+    const session = new Session(SessionId('bad-replace'))
+    const head = session.append('user/message', {
+      content: [{ type: 'text', text: 'head' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' }).seq
+    appendUnchecked(session, {
+      type: 'user/message',
+      seq: session.seq,
+      time: 0,
+      data: {
+        content: [{ type: 'text', text: 'bad' }],
+        source: { kind: 'user' },
+      },
+      surfaceOp: { op: 'replace', start: 99, end: 99 },
+      sourceEventSeqs: [head],
+    })
+    expectRepeatedFailure(meter(), session, /invalid current range/)
+  })
+
+  it('handles earlier-reader catch-up, eager observation, and service reload', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    let activeMeter: TokenMeterService | undefined
+    const revisions: number[] = []
+    ctx.on('session/event', (session) => {
+      if (activeMeter !== undefined) revisions.push(activeMeter.measure(session).logRevision)
+    })
+    const firstFiber = await ctx.plugin(TokenMeterService)
+    activeMeter = ctx.tokenMeter
+    const session = ctx.sessions.create(SessionId('listener-order'))
+    activeMeter.measure(session)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'one' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(revisions).toEqual([1])
+    expect(activeMeter.measure(session).logRevision).toBe(1)
+
+    await firstFiber.dispose()
+    const secondFiber = await ctx.plugin(TokenMeterService)
+    activeMeter = ctx.tokenMeter
+    expect(activeMeter.measure(session).logRevision).toBe(1)
+    await secondFiber.dispose()
+  })
+})

packages/llm/token-meter/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    }
+  ]
+}

packages/mcp/mcp-client/tests/fixture-server.ts

@@ -2,7 +2,7 @@
  * Minimal MCP server over stdio for e2e testing of the dsh-mcp-client plugin.
  * Registers controlled tools with predictable behavior for asserting edge cases.
  *
- * Run: node --import tsx fixture-server.ts
+ * Run: node fixture-server.ts
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'

packages/mcp/mcp-client/tests/mcp-client.e2e.ts

@@ -26,9 +26,7 @@ import { apply } from '@deepseek-ai/dsh-mcp-client/src/index.ts'
 import { publicToolName } from '@deepseek-ai/dsh-mcp-client/src/tools.ts'
 import type { Config } from '@deepseek-ai/dsh-mcp-client'
 
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 const fixtureServerPath = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
-const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 // Resolve package-local .bin for pnpm-hoisted MCP server binaries.
 const packageDir = fileURLToPath(new URL('..', import.meta.url))
@@ -86,8 +84,8 @@ describe('fixture server — controlled scenarios', () => {
     transport: 'stdio',
     serverName: 'fixture',
     command: process.execPath,
-    args: ['--import', tsxLoader, fixtureServerPath],
-    env: { TSX_TSCONFIG_PATH: repoTsconfig },
+    args: [fixtureServerPath],
+    env: {},
     cwd: packageDir,
     toolCallTimeoutMs: 15_000,
   }
@@ -170,8 +168,8 @@ describe('fixture server — duplicate serverName', () => {
       transport: 'stdio',
       serverName: 'dup',
       command: process.execPath,
-      args: ['--import', tsxLoader, fixtureServerPath],
-      env: { TSX_TSCONFIG_PATH: repoTsconfig },
+      args: [fixtureServerPath],
+      env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
     }
@@ -191,8 +189,8 @@ describe('fixture server — disposal', () => {
       transport: 'stdio',
       serverName: 'fixture',
       command: process.execPath,
-      args: ['--import', tsxLoader, fixtureServerPath],
-      env: { TSX_TSCONFIG_PATH: repoTsconfig },
+      args: [fixtureServerPath],
+      env: {},
       cwd: packageDir,
       toolCallTimeoutMs: 15_000,
     })

packages/sdk/helper/package.json

@@ -33,7 +33,6 @@
   },
   "devDependencies": {
     "@deepseek-ai/dsh-brand": "workspace:^",
-    "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-hooks-claude": "workspace:^",
     "@deepseek-ai/dsh-hooks-codex": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",

packages/sdk/helper/src/features/builtin/index.ts

@@ -5,7 +5,6 @@
  * @module @deepseek-ai/dsh-helper/features/builtin
  */
 
-import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 import type { Config as ClaudeHooksConfig } from '@deepseek-ai/dsh-hooks-claude'
 import type { Config as CodexHooksConfig } from '@deepseek-ai/dsh-hooks-codex'
 import type { Config as JsonlConfig } from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -19,16 +18,6 @@ import { AppFeature } from './app.ts'
 import { ProviderFeature } from './provider.ts'
 import { SpineFeature } from './spine.ts'
 
-const compactPreset = {
-  contextWindow: 128_000,
-  thresholdRatio: 0.8,
-  retainTokens: 20_480,
-  summarizationProvider: '',
-  summarizationModel: '',
-  maxTokens: 8_192,
-  compactionRetries: 1,
-} satisfies BasicCompactConfig
-
 /**
  * Build and definition-check the complete builtin set for one project profile.
  * @param profile - project context used to validate conditional contributions.
@@ -275,12 +264,18 @@ config:
         id: 'basic',
         label: 'Basic compaction',
         default: true,
-        resources: [{
-          kind: 'npm-cordis-config-entry',
-          id: 'compact-basic',
-          package: '@deepseek-ai/dsh-compact-basic',
-          config: compactPreset,
-        }],
+        resources: [
+          {
+            kind: 'npm-cordis-config-entry',
+            id: 'token-meter',
+            package: '@deepseek-ai/dsh-token-meter',
+          },
+          {
+            kind: 'npm-cordis-config-entry',
+            id: 'compact-basic',
+            package: '@deepseek-ai/dsh-compact-basic',
+          },
+        ],
       }],
     },
     {

packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts

@@ -6,7 +6,7 @@ import { isAbsolute, join, relative, resolve } from 'node:path'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
-import { encodeSegment, logPath, scanLog, sessionDir } from '../src/format.ts'
+import { encodeSegment, logPath, scanLog, sessionDir, toHeaderLine } from '../src/format.ts'
 import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts'
 import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts'
 
@@ -194,6 +194,40 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
     expect(loaded.events).toEqual(log) // chunks preserved, contiguous seqs
   })
 
+  it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
+    const m = meta('legacy-header-delta', '/legacy')
+    const path = logPath(root, m.cwd, m.id)
+    await mkdir(sessionDir(root, m.cwd), { recursive: true })
+    await writeFile(path, [
+      JSON.stringify(toHeaderLine(m)),
+      JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }),
+      JSON.stringify({ type: 'request/header-delta', seq: 1, time: 2, data: { config: { model: 'legacy' } } }),
+      JSON.stringify({ type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }),
+      '',
+    ].join('\n'))
+
+    await expect(ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported legacy request\/header-delta event at seq 1/)
+  })
+
+  it('rejects a stored v0 full header carrying the legacy fallback reason', async () => {
+    const m = meta('legacy-header-fallback', '/legacy')
+    const path = logPath(root, m.cwd, m.id)
+    await mkdir(sessionDir(root, m.cwd), { recursive: true })
+    await writeFile(path, [
+      JSON.stringify(toHeaderLine(m)),
+      JSON.stringify({
+        type: 'request/header',
+        seq: 0,
+        time: 1,
+        data: { header: { config: { model: 'legacy' } }, reason: 'fallback' },
+      }),
+      '',
+    ].join('\n'))
+
+    await expect(ctx.sessionPersistence.load(m.id))
+      .rejects.toThrow(/unsupported legacy request\/header reason "fallback" at seq 0/)
+  })
+
   it('persists a forked child seed through the existing session write path', async () => {
     const source = ctx.sessions.create(SessionId('persist-parent'), { meta: { cwd: '/workspace' } })
     appendClosedTurn(source)

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -153,6 +153,42 @@ describe('scanRows', () => {
 })
 
 describe('SessionPersistenceSqlite: durability and crash semantics', () => {
+  it('rejects a stored v0 log containing a legacy request/header-delta event', async () => {
+    const path = await freshDbPath()
+    const m = meta('legacy-header-delta', '/legacy')
+    const db = openDatabase(path, 'wal')
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    const insert = db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
+    insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }))
+    insert.run(m.id, 1, 'request/header-delta', 2, JSON.stringify({ config: { model: 'legacy' } }))
+    insert.run(m.id, 2, 'turn/end', 3, JSON.stringify({ turn: 1, reason: { kind: 'completed' } }))
+    db.close()
+
+    const mounted = await backend(path)
+    await expect(mounted.ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported legacy request\/header-delta event at seq 1/)
+    await mounted.dispose()
+  })
+
+  it('rejects a stored v0 full header carrying the legacy fallback reason', async () => {
+    const path = await freshDbPath()
+    const m = meta('legacy-header-fallback', '/legacy')
+    const db = openDatabase(path, 'wal')
+    db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)')
+      .run(m.id, m.version, m.createdAt, m.cwd ?? null)
+    db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)')
+      .run(m.id, 0, 'request/header', 1, JSON.stringify({
+        header: { config: { model: 'legacy' } },
+        reason: 'fallback',
+      }))
+    db.close()
+
+    const mounted = await backend(path)
+    await expect(mounted.ctx.sessionPersistence.load(m.id))
+      .rejects.toThrow(/unsupported legacy request\/header reason "fallback" at seq 0/)
+    await mounted.dispose()
+  })
+
   it('has no independent per-session log location', async () => {
     const { ctx, dispose } = await backend()
     expect(ctx.sessionPersistence.locate(meta('sqlite-location'))).toBeUndefined()

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -118,6 +118,20 @@ function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly Sessio
     })
 }
 
+/** Reject events from an obsolete v0 vocabulary that this build cannot replay. */
+function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId): void {
+  const legacyType: string = 'request/header-delta'
+  const legacy = events.find(event => event.type === legacyType)
+  if (legacy !== undefined) {
+    throw new Error(`session "${id}" contains unsupported legacy request/header-delta event at seq ${legacy.seq}`)
+  }
+  const fallback = events.find(event => event.type === 'request/header'
+    && (event.data as { reason?: string }).reason === 'fallback')
+  if (fallback !== undefined) {
+    throw new Error(`session "${id}" contains unsupported legacy request/header reason "fallback" at seq ${fallback.seq}`)
+  }
+}
+
 /**
  * Owns the backend-agnostic session write-path orchestration. A backend
  * constructs one (`new PersistenceCoordinator(ctx, this)`), implements
@@ -207,6 +221,11 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   }
 
   private async appendCore(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
+    // Every append route converges here: the public service, live write-behind
+    // drains, and HMR seed/suffix adoption. Keep vocabulary rejection at that
+    // shared boundary so a stale JavaScript plugin cannot persist an event that
+    // this same backend will refuse to load.
+    assertSupportedEvents(events, id)
     if (events.length === 0) return
     let state = this.states.get(id)
     if (state === undefined) state = await this.adopt(id) // calls loadCore, not load
@@ -241,6 +260,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     if (stored === undefined) throw new Error(`session "${id}" not found`)
     const { meta, events, tornMarker } = stored
     this.assertVersion(meta)
+    assertSupportedEvents(events, id)
 
     // Preserve complete interrupted events and synthesize only missing closers.
     const closers = interruptedTurnClosers(events)
@@ -509,6 +529,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   private async adoptLivePrefix(session: Session, seed: readonly SessionEvent[], stored: StoredPrefix<TornMarker>): Promise<void> {
     const { meta, events, tornMarker } = stored
     this.assertVersion(meta)
+    assertSupportedEvents(events, session.header.id)
     if (!seedCoversPrefix(seed, events)) {
       throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`)
     }

packages/session-persistence/session-persistence/tests/persistence.spec.ts

@@ -12,6 +12,26 @@ import { runCoordinatorContract, type CoordinatorFixture } from './coordinator-c
 /** The durable store shape: materialized sessions only (no lazy entries). */
 type MemoryStore = Map<string, { meta: SessionHeader; events: SessionEvent[] }>
 
+/** An obsolete event fixture that emulates an untyped pre-change producer. */
+function legacyHeaderDelta(seq = 0): SessionEvent {
+  return {
+    type: 'request/header-delta',
+    seq,
+    time: 1,
+    data: { config: { model: 'legacy' } },
+  } as unknown as SessionEvent
+}
+
+/** An obsolete full-header reason fixture from the removed delta codec. */
+function legacyFallbackHeader(seq = 0): SessionEvent {
+  return {
+    type: 'request/header',
+    seq,
+    time: 1,
+    data: { header: { config: { model: 'legacy' } }, reason: 'fallback' },
+  } as unknown as SessionEvent
+}
+
 /** Optional plugin config: an EXTERNAL store shared across backend instances. */
 interface MemoryConfig { store?: MemoryStore }
 
@@ -432,6 +452,64 @@ describe('SessionPersistence service registration', () => {
     await fiber.dispose()
   })
 
+  it('rejects a legacy header delta from a pre-change live producer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence)
+    const session = ctx.sessions.create(SessionId('legacy-live'), { meta: { cwd: '/legacy' } })
+    // Model the runtime shape available to JavaScript or a hot-loaded plugin
+    // compiled against the obsolete event vocabulary.
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+    expect(() => appendLegacy('request/header-delta', { config: { model: 'legacy' } }))
+      .toThrow(/unsupported legacy request\/header-delta format/)
+    expect(session.events).toHaveLength(0)
+    await fiber.dispose()
+  })
+
+  it('rejects a legacy fallback header buffered by a pre-change live producer', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence)
+    const session = ctx.sessions.create(SessionId('legacy-fallback-live'), { meta: { cwd: '/legacy' } })
+    const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent
+
+    expect(() => appendLegacy('request/header', legacyFallbackHeader().data))
+      .toThrow('unsupported legacy request/header reason "fallback"')
+    expect(session.events).toHaveLength(0)
+    await fiber.dispose()
+  })
+
+  it('rejects a legacy stored prefix during live HMR adoption', async () => {
+    const id = SessionId('legacy-hmr')
+    const m = meta(id, '/legacy')
+    const legacy = legacyHeaderDelta()
+    const store: MemoryStore = new Map([[id, { meta: m, events: [legacy] }]])
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    // A current live session cannot carry the obsolete event in its seed, but
+    // HMR still has to identify the persisted prefix as unsupported rather than
+    // treating it as an ordinary live-prefix collision.
+    const session = ctx.sessions.create(id, { meta: { cwd: '/legacy' } })
+    const fiber = await ctx.plugin(MemoryPersistence, { store })
+
+    await expect(ctx.sessions.flush(session))
+      .rejects.toThrow(/unsupported legacy request\/header-delta event at seq 0/)
+    await Promise.allSettled([fiber.dispose()])
+  })
+
+  it('rejects a stored legacy fallback header during load', async () => {
+    const id = SessionId('legacy-fallback-load')
+    const m = meta(id, '/legacy')
+    const store: MemoryStore = new Map([[id, { meta: m, events: [legacyFallbackHeader()] }]])
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(MemoryPersistence, { store })
+
+    await expect(ctx.sessionPersistence.load(id))
+      .rejects.toThrow('unsupported legacy request/header reason "fallback" at seq 0')
+    await fiber.dispose()
+  })
+
   it('retires all coordinator bookkeeping for disposed sessions', async () => {
     const ctx = new Context()
     await ctx.plugin(SessionStore)

packages/session-query/session-query/src/tracing.ts

@@ -162,7 +162,7 @@ function analyzeEventLog(
       { cause: error },
     )
   }
-  const current = new Set(folded.nodes.map(node => node.seq))
+  const current = new Set(folded.nodes)
   const replacedBy = new Map<number, number>()
   const replacedEventSeqs = new Map<number, number[]>()
   for (const replacement of folded.replacements) {

packages/subagent/subagent-acp/package.json

@@ -35,6 +35,7 @@
   "devDependencies": {
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
     "@deepseek-ai/dsh-subagent": "workspace:^",
     "@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
     "@cordisjs/plugin-loader": "^1.0.0-rc.5",

packages/subagent/subagent-acp/tests/mock-acp-server.ts

@@ -2,8 +2,8 @@
  * Minimal no-network ACP child process for keyless backend tests. Environment variables script its
  * text and stop reason, a cancel-cooperative or cancel-ignoring hang, permission requests, and a
  * readiness marker. Disposal fixtures can delay an EOF flush, ignore EOF but exit and mark
- * SIGTERM, or trap SIGTERM to require SIGKILL. The specs spawn this non-test module under tsx with
- * an explicit tsconfig, mirroring real example boot.
+ * SIGTERM, or trap SIGTERM to require SIGKILL. The specs run this protocol-only fixture directly
+ * with Node's type stripping; it imports no harness code or workspace paths.
  * @module @deepseek-ai/dsh-subagent-acp/tests/mock-acp-server
  */
 

packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import SubagentService from '@deepseek-ai/dsh-subagent'
+import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 import * as acp from '../src/index.ts'
 
 /**
@@ -17,9 +18,22 @@ import * as acp from '../src/index.ts'
 // The real acp-agent example: its bin + cordis.yml (the live DeepSeek config).
 const binScript = fileURLToPath(new URL('../../../examples/acp-demo/src/bin.ts', import.meta.url))
 const exampleConfig = fileURLToPath(new URL('../../../../examples/acp-agent/cordis.yml', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
+// How to launch the child acp-agent (src via tsx / lib via plain node, per DSH_EXAMPLE_MODE).
+// buildChildEnv scrubs ambient creds but keeps these extras, so the model key is
+// forwarded explicitly; TSX_TSCONFIG_PATH is added by the resolver in src mode only.
+const childLaunch = resolveExampleLaunch({
+  srcBin: binScript,
+  configArgs: ['--config', exampleConfig],
+  tsconfigPath: repoTsconfig,
+  env: {
+    ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {},
+    ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {},
+    DSH_PERMISSION_MODE: 'danger-full-access',
+  },
+})
+
 /** The ACP backend ignores the parent, but the seam requires one. */
 const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent
 
@@ -40,18 +54,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive
     await ctx.plugin(SubagentService)
     await ctx.plugin(acp, {
       providerName: 'acp',
-      command: process.execPath,
-      args: ['--import', tsxLoader, binScript, '--config', exampleConfig],
+      command: childLaunch.command,
+      args: childLaunch.args,
       cwd: workdir,
       permission: 'reject',
-      // The child harness needs the key to reach the model; forward it
-      // explicitly (buildChildEnv scrubs ambient creds but keeps these extras).
-      env: {
-        ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {},
-        ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {},
-        TSX_TSCONFIG_PATH: repoTsconfig,
-        DSH_PERMISSION_MODE: 'danger-full-access',
-      },
+      env: childLaunch.env as Record<string, string>,
     })
 
     const run = await ctx.subagents.start('acp', {
@@ -76,17 +83,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive
     await ctx.plugin(SubagentService)
     await ctx.plugin(acp, {
       providerName: 'acp',
-      command: process.execPath,
-      args: ['--import', tsxLoader, binScript, '--config', exampleConfig],
+      command: childLaunch.command,
+      args: childLaunch.args,
       cwd: workdir,
       // The child needs to act (run bash), so approve its permission prompts.
       permission: 'allow',
-      env: {
-        ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {},
-        ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {},
-        TSX_TSCONFIG_PATH: repoTsconfig,
-        DSH_PERMISSION_MODE: 'danger-full-access',
-      },
+      env: childLaunch.env as Record<string, string>,
     })
 
     const run = await ctx.subagents.start('acp', {

packages/subagent/subagent-acp/tests/subagent-acp.spec.ts

@@ -21,8 +21,6 @@ import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DI
  */
 
 const mockServer = fileURLToPath(new URL('./mock-acp-server.ts', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 
 /** A throwaway parent Agent — the ACP backend ignores it, but the seam requires one. */
 const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent
@@ -46,11 +44,9 @@ async function setup(mockEnv: SetupEnv = {}, permission: 'allow' | 'reject' = 'r
   await ctx.plugin(acp, {
     providerName: 'acp',
     command: process.execPath,
-    args: ['--import', tsxLoader, mockServer],
+    args: [mockServer],
     permission,
-    // The mock-server scripting vars must reach the child; TSX_TSCONFIG_PATH lets
-    // tsx resolve @deepseek-ai/* from a child cwd outside the repo.
-    env: { ...mockEnv, TSX_TSCONFIG_PATH: repoTsconfig },
+    env: mockEnv,
   })
   return ctx
 }
@@ -197,10 +193,10 @@ describe('dsh-subagent-acp', () => {
     try {
       const spec: AcpRunSpec = {
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         cwd: process.cwd(),
         permission: 'reject',
-        env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig },
+        env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready },
         // Short on BOTH tiers: the trap ignores EOF and SIGTERM, so dispose must
         // burn the EOF window, then the SIGTERM window, then SIGKILL — keep each
         // small so the whole ladder finishes well within the 4000ms bound.
@@ -240,7 +236,7 @@ describe('dsh-subagent-acp', () => {
     try {
       const spec: AcpRunSpec = {
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         cwd: process.cwd(),
         permission: 'reject',
         // MOCK_HANG so the prompt never resolves on its own — we tear down a live
@@ -249,7 +245,7 @@ describe('dsh-subagent-acp', () => {
         // wider grace.
         env: {
           MOCK_HANG: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready,
-          MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400', TSX_TSCONFIG_PATH: repoTsconfig,
+          MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400',
         },
         disposeEofGraceMs: 2000,
         disposeGraceMs: 50,
@@ -280,12 +276,12 @@ describe('dsh-subagent-acp', () => {
     try {
       const spec: AcpRunSpec = {
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         cwd: process.cwd(),
         permission: 'reject',
         env: {
           MOCK_HANG: '1', MOCK_IGNORE_EOF: '1', MOCK_TEXT: 'x',
-          MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, TSX_TSCONFIG_PATH: repoTsconfig,
+          MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm,
         },
         // Tiny EOF grace so the ignored-EOF window elapses fast, then SIGTERM.
         disposeEofGraceMs: 150,
@@ -404,9 +400,9 @@ describe('dsh-subagent-acp', () => {
       await ctx.plugin(acp, {
         providerName: 'acp',
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         permission: 'reject',
-        env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig },
+        env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready },
         disposeEofGraceMs: 150,
         disposeGraceMs: 150,
       })
@@ -455,10 +451,10 @@ describe('dsh-subagent-acp', () => {
       request(),
       {
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         cwd: process.cwd(),
         permission: 'reject',
-        env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig },
+        env: { MOCK_CRASH_ON_PROMPT: '1' },
         disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS,
         disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
         onError: (error, stopReason) => { errors.push({ message: error.message, stopReason }) },
@@ -493,10 +489,10 @@ describe('dsh-subagent-acp', () => {
       request(),
       {
         command: process.execPath,
-        args: ['--import', tsxLoader, mockServer],
+        args: [mockServer],
         cwd: process.cwd(),
         permission: 'reject',
-        env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig },
+        env: { MOCK_CRASH_ON_PROMPT: '1' },
         disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS,
         disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
         onError: () => { throw new Error('sink boom') },

packages/subagent/subagent-acp/tsconfig.json

@@ -28,6 +28,9 @@
     },
     {
       "path": "../subagent-subprocess"
+    },
+    {
+      "path": "../../support/loader-smoke"
     }
   ]
 }

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).
 

packages/support/acp-snapshot/package.json

@@ -23,7 +23,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@agentclientprotocol/sdk": "0.25.1",
-    "tsx": "^4.22.4",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:*",
     "vitest": "^4.1.8"
   },
   "peerDependencies": {

packages/support/acp-snapshot/src/harness.ts

@@ -11,7 +11,6 @@ import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, delimiter } from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { Readable, Writable } from 'node:stream'
 import {
   ClientSideConnection,
@@ -23,12 +22,7 @@ import {
   type RequestPermissionResponse,
   type SessionNotification,
 } from '@agentclientprotocol/sdk'
-
-// Resolve tsx's ESM loader to an ABSOLUTE path once: the child runs with its
-// cwd in a temp dir OUTSIDE the repo, where a bare `--import tsx` would not
-// resolve from node_modules. import.meta.resolve gives this package's tsx
-// regardless of the child cwd.
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
 
 /**
  * The agent composition a scenario runs against: which bin to boot and which
@@ -37,8 +31,10 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
  * them from its own `import.meta.url`.
  */
 export interface AgentUnderTest {
-  /** The agent bin entry (e.g. `packages/examples/acp-demo/src/bin.ts`), run unbuilt via tsx. */
+  /** The agent bin's SOURCE entry (e.g. `packages/examples/acp-demo/src/bin.ts`); the `lib` bin is derived from it. */
   binScript: string
+  /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */
+  libBinScript?: string | undefined
   /**
    * The example's live `cordis.yml`. Under `DSH_SNAPSHOT=replay` the bin swaps
    * it for the sibling `cordis.snapshot.yml` (the keyless replay overlay), so
@@ -47,10 +43,8 @@ export interface AgentUnderTest {
   configPath: string
   /**
    * The repo-root tsconfig whose `paths` map resolves the unbuilt workspace
-   * imports. Passed to the child as `TSX_TSCONFIG_PATH`: tsx finds a tsconfig
-   * by searching UP from the child's cwd — a temp dir outside the repo — so
-   * without the explicit pin the dsh-* imports fail before the bin writes a
-   * byte.
+   * imports in `src` mode (passed to the child as `TSX_TSCONFIG_PATH`). Ignored
+   * in `lib` mode, where the example resolves plugins through real `exports`.
    */
   tsconfigPath: string
 }
@@ -184,25 +178,32 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
     if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) {
       await cp(opts.workspaceDir, cwd, { recursive: true })
     }
-    const env: NodeJS.ProcessEnv = {
-      ...process.env,
-      TSX_TSCONFIG_PATH: opts.agent.tsconfigPath,
-      DSH_SNAPSHOT: opts.mode,
-      DSH_SNAPSHOT_FILE: opts.fixtureFile,
-      DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
-      DSH_SNAPSHOT_SPILL_ROOT: spillRoot,
-      DSH_HOME: join(cwd, '.dsh'),
-      DSH_AGENTS_HOME: join(cwd, '.agents'),
-      ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
-      ...opts.childFiles !== undefined && opts.childFiles.length > 0
-        ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) }
-        : {},
-    }
+    // Boot the agent in the environment's mode (DSH_EXAMPLE_MODE): `src` runs the
+    // source bin under tsx with the paths map; `lib` runs the built bin under plain
+    // Node, resolving plugins through the example's workspace node_modules → lib.
+    const launch = resolveExampleLaunch({
+      srcBin: opts.agent.binScript,
+      libBin: opts.agent.libBinScript,
+      configArgs: ['--config', opts.configPath ?? opts.agent.configPath],
+      tsconfigPath: opts.agent.tsconfigPath,
+      env: {
+        DSH_SNAPSHOT: opts.mode,
+        DSH_SNAPSHOT_FILE: opts.fixtureFile,
+        DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
+        DSH_SNAPSHOT_SPILL_ROOT: spillRoot,
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+        ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
+        ...opts.childFiles !== undefined && opts.childFiles.length > 0
+          ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) }
+          : {},
+      },
+    })
 
     child = spawn(
-      process.execPath,
-      ['--import', tsxLoader, opts.agent.binScript, '--config', opts.configPath ?? opts.agent.configPath],
-      { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] },
+      launch.command,
+      launch.args,
+      { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] },
     )
 
     child.stderr.setEncoding('utf8')

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
-}

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)
       }
     })
 

packages/support/acp-snapshot/tests/fixtures/record-suite/rec-pin/tool-schemas.golden.json

@@ -8,5 +8,5 @@
       }
     }
   ],
-  "deltas": []
+  "changes": []
 }

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 } }
     ]
   }]

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}}

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

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"
+        }
+      }
+    ]
+  ]
 }

packages/support/acp-snapshot/tests/harness.spec.ts

@@ -14,10 +14,12 @@ import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness
  * assertions read plain `rawStdout`.
  */
 
+const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url))
 const AGENT: AgentUnderTest = {
-  binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  binScript: fakeAgent,
+  libBinScript: fakeAgent,
   // The fake bin ignores its config argv; any real path documents the shape.
-  configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  configPath: fakeAgent,
   tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)),
 }
 

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)

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,
@@ -34,9 +32,11 @@ import {
  * spec once with `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1`, then review and commit the resulting tree.
  */
 
+const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url))
 const AGENT = {
-  binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
-  configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)),
+  binScript: fakeAgent,
+  libBinScript: fakeAgent,
+  configPath: fakeAgent,
   tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)),
 }
 
@@ -45,7 +45,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 +76,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 +127,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 +264,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 +307,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/)
   })
 })
 

packages/support/acp-snapshot/tsconfig.json

@@ -7,5 +7,7 @@
   "include": [
     "src"
   ],
-  "references": []
+  "references": [
+    { "path": "../loader-smoke" }
+  ]
 }

packages/support/invariants/README.md

@@ -32,6 +32,7 @@ Session log (per session):
 - **steps nest in turns** — `step/start` opens a step in the open turn; `step/end` closes the matching step.
 - **chunks belong to an open step** — `step/start` precedes its `assistant/chunk`s.
 - **a `tool/result` needs a prior `tool/call`** — but NOT the converse: a `tool/call` may have no result (a thrown tool-execution pipeline step ends the turn with no `tool/result`, which is legal).
+- **provenance sources are valid and unambiguous** — `sourceEventSeqs` contains unique earlier known seqs; only `assistant/message` may carry an explicit empty list, which denotes a known empty provider stream rather than absent legacy provenance.
 
 Agent status (per agent):
 
@@ -39,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'`).
 

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

packages/support/invariants/tests/invariants.spec.ts

@@ -487,13 +487,17 @@ describe('surface contract under the invariants composition', () => {
     // no throw — well-formed replace op
   })
 
-  it('rejects empty sourceEventSeqs', async () => {
+  it('accepts known-empty assistant provenance and rejects empty provenance elsewhere', async () => {
     const { ctx } = await setup()
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
     expect(() => {
       session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [] })
-    }).toThrow(/must not be empty/)
+    }).not.toThrow()
+    expect(() => {
+      session.append('user/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    }).toThrow(/must not be empty except on assistant\/message/)
   })
 
   it('rejects duplicate sourceEventSeqs', async () => {
@@ -609,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).
@@ -700,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()

packages/support/loader-smoke/README.md

@@ -1,10 +1,10 @@
 # `@deepseek-ai/dsh-loader-smoke`
 
-Shared subprocess harness for keyless example smokes that boot the real stdio-agent bin and a real `cordis.yml` through the Cordis Loader. A test supplies absolute bin/config/tsconfig paths, optional environment overrides, and stdin lines; `runLoaderSmoke` owns the isolated cwd, DSH homes, tsx path resolution, 30-second process deadline, captured diagnostics, forced kill, EOF, and cleanup.
+Shared subprocess harness for tests that boot an app and `cordis.yml` through the Cordis Loader. `resolveExampleLaunch` selects local `src` mode (tsx and root tsconfig paths) or CI `lib` mode (plain Node and package exports) from an explicit mode or `DSH_EXAMPLE_MODE`.
 
-Successful runs return stdout and stderr only after a zero exit. Non-zero exits and deadlines reject with both captured streams. `LOADER_SMOKE_TEST_TIMEOUT_MS` leaves Vitest enough room for the process-owned diagnostic timeout to fire first.
+`runLoaderSmoke` owns the isolated cwd, DSH homes, stdin, diagnostics, deadline, termination, and cleanup. It returns both streams after a zero exit and rejects with both streams on failure.
 
-This is support-tier test infrastructure, not product API. The consumers are the Loader-path smokes under `examples/{echo-agent,coding-agent,cordis-agent}`.
+This is support-tier test infrastructure, not product API.
 
 ## Model Experience
 
@@ -12,6 +12,6 @@ None, as this test-only harness boots example processes and inspects their strea
 
 ## Known Limitations and Deferred Work
 
-- **Only the unbuilt tsx/Loader path is exercised** — built-bin artifacts remain the responsibility of their separate e2e smokes.
+- **Built mode requires a prior build** — the config must also resolve every named package upward through `examples/node_modules`.
 - **Captured stdout and stderr are unbounded** — a runaway child can consume memory until the deadline kills it.
 - **Timeout kills only the direct child** — a process tree spawned by a faulty fixture can outlive the smoke and needs external cleanup.

packages/support/loader-smoke/src/index.ts

@@ -2,6 +2,14 @@
  * Shared subprocess harness for keyless example smokes that boot a real
  * `cordis.yml` through the stdio-agent bin and Cordis Loader.
  *
+ * It also owns the mode-aware launch resolver every example subprocess harness shares
+ * ({@link resolveExampleLaunch}): booting an example bin from TypeScript source under `tsx` (the
+ * zero-build dev path, resolving `@deepseek-ai/dsh-*` / `@cordisjs/*` through the tsconfig `paths`
+ * map) or from built `lib/` under plain Node (resolving bare packages through real `exports`, as an
+ * installed consumer does, while Node type-strips relative example-local TypeScript plugins).
+ * Consolidating that spawn glue here retires the copies in the ACP snapshot harness and the example
+ * e2e drivers (the `TODO(acp-test-harness)`).
+ *
  * @module @deepseek-ai/dsh-loader-smoke
  */
 
@@ -9,26 +17,125 @@ import { spawn } from 'node:child_process'
 import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
 
 const DEFAULT_PROCESS_TIMEOUT_MS = 30_000
-const TSX_LOADER = fileURLToPath(import.meta.resolve('tsx'))
 
 /** Vitest deadline that leaves room for the subprocess-owned 30-second diagnostic timeout. */
 export const LOADER_SMOKE_TEST_TIMEOUT_MS = DEFAULT_PROCESS_TIMEOUT_MS + 15_000
 
+/** Which artifact an example bin is booted from: unbuilt `src` via tsx, or built `lib` via plain Node. */
+export type ExampleMode = 'src' | 'lib'
+
+/** Environment variable selecting the mode; CI and pre-push set it to `lib`, dev leaves it unset (`src`). */
+export const EXAMPLE_MODE_ENV = 'DSH_EXAMPLE_MODE'
+
+/**
+ * Parse an {@link ExampleMode} from a raw string, defaulting to `src` when absent so an unset
+ * environment reproduces the dev/tsx behavior. Throws on any other value rather than silently
+ * falling back, so a typo in a gate's env fails loud.
+ * @param raw - the raw value; defaults to `process.env.DSH_EXAMPLE_MODE`.
+ * @returns the validated mode.
+ */
+export function resolveExampleMode(raw: string | undefined = process.env[EXAMPLE_MODE_ENV]): ExampleMode {
+  switch (raw) {
+    case undefined:
+    case '':
+    case 'src':
+      return 'src'
+    case 'lib':
+      return 'lib'
+    default:
+      throw new Error(`${EXAMPLE_MODE_ENV} must be 'src' or 'lib', got ${JSON.stringify(raw)}.`)
+  }
+}
+
+/** Inputs to {@link resolveExampleLaunch}. */
+export interface ExampleLaunchOptions {
+  /** Absolute path to the example bin's TypeScript source entry (`<pkg>/src/bin.ts`); the `lib` bin is derived from it. */
+  readonly srcBin: string
+  /** Explicit plain-Node entry for `lib` mode; test fixtures may point this at Node-type-strippable TypeScript. */
+  readonly libBin?: string | undefined
+  /** Arguments passed after the bin — the config, positional (`[configPath]`) or flagged (`['--config', configPath]`). */
+  readonly configArgs?: readonly string[]
+  /** The mode to launch in; defaults to {@link resolveExampleMode} of the environment. */
+  readonly mode?: ExampleMode
+  /** Absolute repo tsconfig whose `paths` map resolves unbuilt workspace imports. Required in `src` mode, ignored in `lib`. */
+  readonly tsconfigPath?: string
+  /** Prepend `--expose-internals` (the Cordis Loader's bare-plugin resolver needs it for some bins); defaults to `false`. */
+  readonly exposeInternals?: boolean
+  /** Extra environment entries the mode-specific ones layer over; the caller then merges the result over `process.env`. */
+  readonly env?: NodeJS.ProcessEnv
+}
+
+/** The resolved spawn: `spawn(command, args, { env: { ...process.env, ...env } })`. */
+export interface ExampleLaunch {
+  /** The executable to spawn — always the current Node binary. */
+  readonly command: string
+  /** Node flags, the resolved bin, then the caller's `configArgs`. */
+  readonly args: string[]
+  /** Mode-specific environment (`TSX_TSCONFIG_PATH` in `src`, nothing added in `lib`) layered over the caller's `env`. */
+  readonly env: NodeJS.ProcessEnv
+}
+
+/** Derive the built-lib bin (`<pkg>/lib/<name>.js`) from a source bin (`<pkg>/src/<name>.ts`). */
+function toLibBin(srcBin: string): string {
+  const markerLength = '/src/'.length
+  const cut = Math.max(srcBin.lastIndexOf('/src/'), srcBin.lastIndexOf('\\src\\'))
+  if (cut === -1) {
+    throw new Error(`resolveExampleLaunch: expected a "/src/" segment or Windows equivalent in bin path ${JSON.stringify(srcBin)}.`)
+  }
+  const separator = srcBin.slice(cut, cut + 1)
+  const tail = srcBin.slice(cut + markerLength).replace(/\.ts$/, '.js')
+  return `${srcBin.slice(0, cut)}${separator}lib${separator}${tail}`
+}
+
+/**
+ * Resolve how to spawn an example bin in the selected mode.
+ *
+ * `src` yields `node [--expose-internals] --import <tsx> <srcBin> <configArgs>` with `TSX_TSCONFIG_PATH`
+ * set so the tsconfig `paths` map resolves workspace imports to source. `lib` yields
+ * `node [--expose-internals] <libBin> <configArgs>` under plain Node with no tsx and no paths map, so
+ * bare package plugins resolve through real package `exports` into built `lib/`; relative example-local
+ * TypeScript plugins remain source files loaded through Node's built-in type stripping. Bare resolution
+ * requires the config to live below a workspace that declares its `cordis.yml` package dependencies.
+ *
+ * @param options - the source bin, config arguments, mode, and environment.
+ * @returns the command, argument vector, and mode-specific environment to spawn with.
+ */
+export function resolveExampleLaunch(options: ExampleLaunchOptions): ExampleLaunch {
+  const mode = options.mode ?? resolveExampleMode()
+  const configArgs = options.configArgs ?? []
+  const flags = options.exposeInternals === true ? ['--expose-internals'] : []
+  const env: NodeJS.ProcessEnv = { ...options.env }
+
+  if (mode === 'src') {
+    if (options.tsconfigPath === undefined) {
+      throw new Error("resolveExampleLaunch: 'src' mode needs tsconfigPath for the workspace paths map.")
+    }
+    const tsxLoader = import.meta.resolve('tsx')
+    env.TSX_TSCONFIG_PATH = options.tsconfigPath
+    return { command: process.execPath, args: [...flags, '--import', tsxLoader, options.srcBin, ...configArgs], env }
+  }
+
+  return { command: process.execPath, args: [...flags, options.libBin ?? toLibBin(options.srcBin), ...configArgs], env }
+}
+
 /** Inputs that vary between real-Loader example smokes. */
 export interface LoaderSmokeOptions {
   /** Human-readable example name used in failure diagnostics. */
   readonly label: string
   /** Prefix for the isolated temporary process cwd. */
   readonly tempDirPrefix: string
-  /** Absolute stdio-agent bin path. */
+  /** Absolute stdio-agent bin SOURCE path (`<pkg>/src/bin.ts`); the `lib` bin is derived from it. */
   readonly binScript: string
+  /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */
+  readonly libBinScript?: string | undefined
   /** Absolute real Loader config path. */
   readonly configPath: string
-  /** Absolute repo tsconfig path used for unbuilt workspace-package resolution. */
+  /** Absolute repo tsconfig path used for unbuilt workspace-package resolution (required in `src` mode). */
   readonly tsconfigPath: string
+  /** Boot from source via tsx (`src`) or built lib via plain Node (`lib`); defaults to the environment's mode. */
+  readonly mode?: ExampleMode
   /** Environment overrides layered over the parent and isolated DSH homes. */
   readonly env?: Readonly<NodeJS.ProcessEnv>
   /** Lines written to stdin before EOF; omitted means immediate EOF. */
@@ -48,30 +155,29 @@ export interface LoaderSmokeResult {
 /**
  * Boot one real Loader tree from an isolated cwd, write the requested stdin
  * script, close stdin, and await a clean exit. The helper owns process kill and
- * temp-directory cleanup on every outcome.
- * @param options - example paths, environment, stdin, and diagnostic identity.
+ * temp-directory cleanup on every outcome, and picks src/lib via {@link resolveExampleLaunch}.
+ * @param options - example paths, mode, environment, stdin, and diagnostic identity.
  * @returns captured stdout and stderr after a zero exit.
  */
 export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<LoaderSmokeResult> {
   const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix))
   const processTimeoutMs = options.processTimeoutMs ?? DEFAULT_PROCESS_TIMEOUT_MS
+  const launch = resolveExampleLaunch({
+    srcBin: options.binScript,
+    libBin: options.libBinScript,
+    configArgs: [options.configPath],
+    ...options.mode !== undefined ? { mode: options.mode } : {},
+    tsconfigPath: options.tsconfigPath,
+    exposeInternals: true,
+    env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env },
+  })
   try {
     return await new Promise((resolve, reject) => {
-      const child = spawn(
-        process.execPath,
-        ['--expose-internals', '--import', TSX_LOADER, options.binScript, options.configPath],
-        {
-          cwd,
-          env: {
-            ...process.env,
-            DSH_HOME: join(cwd, '.dsh'),
-            DSH_AGENTS_HOME: join(cwd, '.agents'),
-            ...options.env,
-            TSX_TSCONFIG_PATH: options.tsconfigPath,
-          },
-          stdio: ['pipe', 'pipe', 'pipe'],
-        },
-      )
+      const child = spawn(launch.command, launch.args, {
+        cwd,
+        env: { ...process.env, ...launch.env },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
       let stdout = ''
       let stderr = ''
       let deferredFailure: Error | undefined

packages/support/loader-smoke/tests/example-launch.spec.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  EXAMPLE_MODE_ENV,
+  resolveExampleLaunch,
+  resolveExampleMode,
+} from '@deepseek-ai/dsh-loader-smoke'
+
+const SRC_BIN = '/repo/packages/examples/stdio-demo/src/bin.ts'
+const TSCONFIG = '/repo/tsconfig.json'
+
+const originalMode = process.env[EXAMPLE_MODE_ENV]
+afterEach(() => {
+  if (originalMode === undefined) Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV)
+  else process.env[EXAMPLE_MODE_ENV] = originalMode
+})
+
+describe('resolveExampleMode', () => {
+  it('defaults absent/empty/src to src', () => {
+    Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV)
+    expect(resolveExampleMode()).toBe('src')
+    expect(resolveExampleMode('')).toBe('src')
+    expect(resolveExampleMode('src')).toBe('src')
+  })
+
+  it('accepts lib', () => {
+    expect(resolveExampleMode('lib')).toBe('lib')
+  })
+
+  it('throws on any other value', () => {
+    expect(() => resolveExampleMode('prod')).toThrow(/must be 'src' or 'lib'/)
+  })
+
+  it('reads the environment when no argument is given', () => {
+    process.env[EXAMPLE_MODE_ENV] = 'lib'
+    expect(resolveExampleMode()).toBe('lib')
+    Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV)
+    expect(resolveExampleMode()).toBe('src')
+  })
+})
+
+describe('resolveExampleLaunch', () => {
+  it('src mode: --import tsx on the source bin with the tsconfig paths env', () => {
+    const { command, args, env } = resolveExampleLaunch({
+      srcBin: SRC_BIN,
+      configArgs: ['./cordis.yml'],
+      mode: 'src',
+      tsconfigPath: TSCONFIG,
+    })
+    expect(command).toBe(process.execPath)
+    expect(args).toContain('--import')
+    expect(args).toContain(SRC_BIN)
+    expect(args[args.length - 1]).toBe('./cordis.yml')
+    expect(args).not.toContain('--expose-internals')
+    expect(env.TSX_TSCONFIG_PATH).toBe(TSCONFIG)
+  })
+
+  it('src mode: throws without a tsconfig path', () => {
+    expect(() => resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'src' })).toThrow(/needs tsconfigPath/)
+  })
+
+  it('lib mode: plain node on the derived lib bin, no tsx and no paths env', () => {
+    const { args, env } = resolveExampleLaunch({
+      srcBin: SRC_BIN,
+      configArgs: ['--config', './cordis.yml'],
+      mode: 'lib',
+      env: { DSH_HOME: '/tmp/home' },
+    })
+    expect(args).not.toContain('--import')
+    expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js')
+    expect(args.slice(-2)).toEqual(['--config', './cordis.yml'])
+    expect(env.TSX_TSCONFIG_PATH).toBeUndefined()
+    expect(env.DSH_HOME).toBe('/tmp/home')
+  })
+
+  it('lib mode: uses an explicit plain-Node bin when provided', () => {
+    const fixture = '/repo/fixture.ts'
+    const { args } = resolveExampleLaunch({ srcBin: fixture, libBin: fixture, mode: 'lib' })
+    expect(args).toContain(fixture)
+  })
+
+  it('prepends --expose-internals when requested', () => {
+    const { args } = resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'lib', exposeInternals: true })
+    expect(args[0]).toBe('--expose-internals')
+  })
+
+  it('lib mode: rewrites only the last /src/ segment', () => {
+    const { args } = resolveExampleLaunch({
+      srcBin: '/repo/src/packages/examples/acp-demo/src/bin.ts',
+      mode: 'lib',
+    })
+    expect(args).toContain('/repo/src/packages/examples/acp-demo/lib/bin.js')
+  })
+
+  it('lib mode: derives the built bin from a Windows source path', () => {
+    const { args } = resolveExampleLaunch({
+      srcBin: String.raw`D:\repo\src\packages\examples\acp-demo\src\bin.ts`,
+      mode: 'lib',
+    })
+    expect(args).toContain(String.raw`D:\repo\src\packages\examples\acp-demo\lib\bin.js`)
+  })
+
+  it('lib mode: throws when the bin has no /src/ segment', () => {
+    expect(() => resolveExampleLaunch({ srcBin: '/repo/lib/bin.js', mode: 'lib' })).toThrow(/"\/src\/" segment/)
+  })
+
+  it('defaults the mode from the environment', () => {
+    process.env[EXAMPLE_MODE_ENV] = 'lib'
+    const { args } = resolveExampleLaunch({ srcBin: SRC_BIN })
+    expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js')
+  })
+})

packages/support/loader-smoke/tests/loader-smoke.spec.ts

@@ -16,6 +16,7 @@ describe('runLoaderSmoke', () => {
       binScript: fixture('success'),
       configPath,
       tsconfigPath,
+      mode: 'src',
       env: { LOADER_SMOKE_MARKER: 'present' },
       stdinLines: ['one', 'two'],
     })
@@ -43,6 +44,7 @@ describe('runLoaderSmoke', () => {
       label: 'failure fixture',
       tempDirPrefix: 'loader-smoke-fail-',
       binScript: fixture('fail'),
+      libBinScript: fixture('fail'),
       configPath,
       tsconfigPath,
     })).rejects.toThrow('failure fixture exited 7. stdout:\n\nstderr:\nfixture failed')
@@ -53,6 +55,7 @@ describe('runLoaderSmoke', () => {
       label: 'hanging fixture',
       tempDirPrefix: 'loader-smoke-hang-',
       binScript: fixture('hang'),
+      libBinScript: fixture('hang'),
       configPath,
       tsconfigPath,
       processTimeoutMs: 100,

packages/ui/user-approval/README.md

@@ -6,7 +6,7 @@ Each request must belong to an open agent turn. The service appends a paired `ap
 
 Answerers are `approval/request` waterfall listeners. Return an outcome to answer for an owned agent or call `next()` to delegate. Agent-scoped listeners receive only that agent's requests; compose one terminal answerer per deployment because sibling listener order is not a policy priority mechanism. The ACP bridge is the shipped human answerer.
 
-`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice whose header marker distinguishes user changes from operator/config changes.
+`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice, attributed to the user when the override follows the last `request/header` and to operator/config otherwise.
 
 The tools pipeline routes `ask` decisions through this seam and fails closed when it is absent; the sandboxed bash tool also uses it for escalated retries. The ACP bridge is the shipped human answerer for calls it owns. Audit events remain log-only, so the model sees only the asking consumer's result. See the [approval-seam RFC](../../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md) and [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md).
 

packages/ui/user-approval/src/index.ts

@@ -63,7 +63,7 @@ declare module '@deepseek-ai/dsh-session' {
      * from the prompt section and the narrator's notices). The LAST such
      * event is the session's override ({@link effectiveApprovalPolicy});
      * who asked for it is derivable from position (an event after the log's
-     * last `request/header*` was a runtime switch by the user).
+     * last `request/header` was a runtime switch by the user).
      */
     'approval/policy': { policy: ApprovalPolicy }
   }
@@ -258,7 +258,7 @@ export class ApprovalService extends Service {
     // narrated no later than the next step. What each session was last told
     // is in-memory with a log-derived fallback (the folded header's system
     // text), so restarts lose nothing. Attribution is positional: an
-    // override event after the log's last `request/header*` was a runtime
+    // override event after the log's last `request/header` was a runtime
     // switch by the user; otherwise the configured default moved under the
     // session (operator/config).
     const narrated = new WeakMap<Agent['session'], ApprovalPolicy>()
@@ -271,7 +271,7 @@ export class ApprovalService extends Service {
         const event = events[index] as (typeof events)[number]
         if (overrideIndex < 0 && event.type === 'approval/policy') {
           overrideIndex = index
-        } else if (headerIndex < 0 && (event.type === 'request/header' || event.type === 'request/header-delta')) {
+        } else if (headerIndex < 0 && event.type === 'request/header') {
           headerIndex = index
         }
       }