Merge remote-tracking branch 'origin/master' into jsonl-packed-chunk-rows

Master removed the stdio demo (#702c8cc30) — accept the deletion; this branch's packChunks passthrough survives in acp-demo (auto-merged), and cli-demo/tui-demo arrived from master without one (the follow-up snapshot PR decides which demos expose the switch). Generated catalogs regenerated over merged sources; the hand-written session.md durability paragraph re-weaves this branch's lossless-encoding wording with master's invariant- companion sentence.
2026-07-22 15:46:12 +08:00
parent 3869f2ce17 4267076407
commit 3922e956db
1242 changed files with 57560 additions and 15291 deletions
--- a/packages/support/README.md
+++ b/packages/support/README.md
@@ -10,4 +10,4 @@ Packages that exist to serve development, testing, and the examples rather than
 | `loader-smoke/` | Shared real-Loader subprocess harness for keyless example smokes | (library — imported by example e2e suites) |
 | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) |

-`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
+`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `agent-loop-testkit` centralizes the mandatory service spine for hand-built AgentLoop tests without owning their loop or scenario. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the ACP subprocess/client boundary plus the snapshot harness, normalizers, and suite machinery, while `loader-smoke` owns the parallel real-Loader launch boundary used by keyless example e2e suites. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -4,10 +4,10 @@ The ACP snapshot suite kit: the shared machinery behind the keyless snapshot tie

 Four layers, importable separately:

- **`launchAcpTestAgent` (launcher)** — boots an unbuilt ACP agent from a temp cwd, pins tsx to the repo tsconfig, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through its startup lifecycle, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
- **`runScenario` (harness)** — boots the real agent bin as a subprocess via tsx (unbuilt, Loader path), drives it over ACP JSON-RPC stdio from a deterministic `input.json` script, tees raw stdout for the expected-output and purity checks, and harvests every persisted session JSONL (parent + subagent children, primary-first) after a graceful stdin-EOF shutdown. Parameterized by `AgentUnderTest` (`binScript`, `configPath`, `tsconfigPath` — absolute paths; the subprocess cwd is a temp dir outside the repo). Startup failures preserve captured agent stderr in the rejected diagnostic.
- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.expected.md` plus `tool-schemas.expected.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.
+- **`launchAcpTestAgent` (launcher)** — boots a source agent under tsx or a built `lib` agent under plain Node from a temp cwd, connects the SDK client over a raw-byte stdout tee, collects session updates and stderr, surfaces asynchronous spawn failures through startup, fails closed on unhandled permission requests, and owns graceful or signalled shutdown. Shutdown waits for process exit, inherited stdio closure, and ACP parser exhaustion before resolving or propagating a child error, so captures are complete and callers can remove owned paths after either outcome. When Windows accepts forced termination but publishes its exit marker asynchronously, shutdown gives that marker a bounded grace before treating fallback refusal as a second failure. Snapshot and ordinary e2e suites share this process boundary; a test supplies only agent paths, cwd, environment overrides, and any permission policy.
+- **`runScenario` (harness)** — drives ACP JSON-RPC stdio from a deterministic `input.json` script through the launcher, tees raw stdout for the expected-output and purity checks, and harvests every persisted raw JSONL session log (parent and subagent children, primary-first) after graceful stdin EOF. `AgentUnderTest` supplies absolute `binScript`, optional `libBinScript`, `configPath`, and `tsconfigPath` paths because the subprocess cwd is outside the repo. Startup failures preserve captured agent stderr in the rejected diagnostic.
+- **Normalizers** — pure functions turning the two captured surfaces into stable text: `normalizeStdout` (JSON-RPC ids → first-seen sequence; UUIDs/cwd → tokens; cwd-rooted separators selected as canonical `/` or host-native; `session_info_update.updatedAt` → `{{updatedAt}}`; doubles as the stdout-purity check), `normalizeSessionLog` (times zeroed, `seq` kept, the same cwd-path policy), `scrubSystemPrompts` (prompt text → `{{system}}`), `scrubToolSchemas` (schema bulk → `{{tools}}`), and `scrubRequestHeaders` (all header bulk → `{{system}}`/`{{tools}}`/`{{messagePrefix}}` outside each pin, structure kept — [pinned-header Agent Note](../../../.agents/notes/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **`defineAcpSnapshotSuite` (factory)** — registers the whole describe/it tree for a scenario table: per-scenario expected-output and re-persisted-log comparisons, record/refresh fixture write-back, rejection of structured `UNKNOWN_TOOL` results, the per-header-class pin (`system-prompt.expected.md` plus `tool-schemas.expected.json`) with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL prompt/schema-scrubbed, non-pinning fixtures fully header-scrubbed). Refresh preserves existing volatile fields by event position and gives a newly inserted `session/title` its preceding event's time, so feature-driven insertions do not churn the remainder of a fixture. Each scenario directory's `session.jsonl` plus contiguous `session.<n>.jsonl` siblings are the ordered primary/child inventory; the scenario table does not duplicate their count. Must be called at vitest collection time.

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

@@ -38,6 +38,8 @@ defineAcpSnapshotSuite({

 A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.expected.md` and the corresponding full tool-schema sequence in generated `tool-schemas.expected.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.

+Every scenario compares `stdout.expected.jsonl` with cwd-rooted separators canonicalized to `/`. On Windows, `pinsNativeWindowsStdout` additionally compares the complete `stdout.expected.windows.jsonl` after the shared expected output and requires that sidecar exactly when enabled. A scenario whose driven behavior needs POSIX process semantics (e.g. cancelling a live bash call kills a detached process group) declares `posixOnly`, which skips its run test on Windows while the fixture guards keep covering its committed files everywhere.
+
 The example also ships a `cordis.snapshot.yml` replay overlay next to its `cordis.yml` (the bin swaps them under `DSH_SNAPSHOT=replay` — [single-source replay config Agent Note](../../../.agents/notes/implemented/testing/2026-07-04-single-source-acp-replay-config.md)); replay fixtures are served by [`dsh-llm-replay`](../llm-replay/README.md), which this package points at via the `DSH_SNAPSHOT_*` env vars it sets on the child. `pnpm run test:snapshot:record` calls the live LLM and rewrites the recorded scenarios' model fixtures; `pnpm run test:snapshot:refresh` stays keyless, runs the replay overlay, and rewrites stdout, comparable session-log expected outputs, and each pin's prompt and tool-schema sidecars from the committed model scripts. Fixture roles, record/replay/refresh semantics, and scenario-table fields are documented on `Scenario` and in the [snapshot Agent Note](../../../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md).

 Constraints: `suite.ts` imports vitest, so the package entry is importable only inside a vitest run (the launcher, harness, and normalizers have no such dependency but ship from the same entry). ACP-specific by design — the launcher speaks the SDK's `ClientSideConnection`. Permission round-trips are scriptable: `InputScript.permissionAnswers` is a FIFO queue of option-kind selections (`allow_once`, `reject_once`, …) the client maps to the agent-issued `optionId` at answer time; an absent or exhausted queue answers `cancelled`, and a kind the request never offered rejects the run (the agent is answered `cancelled`, so a tolerant agent cannot absorb the scenario bug). Session config options are scriptable too: the `setConfigOption` step switches a knob over `session/set_config_option`, and `setConfigOptionExpectError` asserts the bridge rejects an unknown id or out-of-vocabulary value (the error frame stays in the transcript).
@@ -53,4 +55,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work

 - **Session harvest requires raw JSONL mode** — `runScenario` collects persisted `.jsonl` logs, so snapshot configs set `persistenceCompression: 'none'`; compressed JSONL and SQLite compositions have no snapshot-harvest path.
- **The subprocess boots the unbuilt tsx/Loader path only** — the built-bin artifact is guarded by the separate `built-bin` e2e smokes, never by this tier.
+- **Built mode requires current artifacts** — run `pnpm run build` before selecting `DSH_EXAMPLE_MODE=lib`; source mode remains the zero-build path.
--- a/packages/support/acp-snapshot/package.json
+++ b/packages/support/acp-snapshot/package.json
@@ -11,11 +11,16 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
@@ -27,9 +32,11 @@
    "vitest": "^4.1.8"
  },
  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -18,8 +18,9 @@

 import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { tmpdir } from 'node:os'
-import { join, delimiter } from 'node:path'
+import { basename, dirname, join, delimiter } from 'node:path'
 import {
  ClientSideConnection,
  PROTOCOL_VERSION,
@@ -41,12 +42,15 @@ export type { AgentUnderTest } from './launcher.ts'
 * the client observes the selected update (`agent_message_chunk` by default),
 * then cancels and awaits completion. A named `waitForToolCallUpdate` keeps the
 * step open for a terminal tool update that may follow the prompt response.
+ * `promptAndWaitForAgentMessage` arms an exact text-chunk waiter before sending
+ * the prompt, then keeps the application live until that later update arrives.
 */
 export type InputStep =
  | { op: 'initialize'; terminalOutput?: boolean }
  | { op: 'newSession' }
  | { op: 'newSessionExpectError'; additionalDirectories?: string[] }
  | { op: 'prompt'; text: string }
+  | { op: 'promptAndWaitForAgentMessage'; text: string; waitForText: string }
  | { op: 'promptExpectError'; text: string }
  | {
    op: 'promptAndCancel'
@@ -149,6 +153,23 @@ export interface RunOptions {
  configPath?: string
 }

+/**
+ * Derive one stable, fixed-length spill root owned by this scenario.
+ * Windows uses a two-character-shorter root because drive resolution adds its drive prefix.
+ * @param fixtureFile - The scenario fixture whose parent directory provides the stable identity.
+ * @param platform - the host platform, injectable for unit coverage.
+ * @returns the root-relative snapshot spill directory.
+ */
+export function snapshotSpillRoot(
+  fixtureFile: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const scenario = basename(dirname(fixtureFile))
+  const key = createHash('sha256').update(scenario).digest('hex').slice(0, 9)
+  const root = platform === 'win32' ? '/t' : '/tmp'
+  return `${root}/dsh-acp-snap-${key}`
+}
+
 /**
 * Run a scenario end-to-end against a freshly-spawned subprocess. Owns the
 * child and its temp dirs; always tears them down. Returns the captured stdout
@@ -163,7 +184,9 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
  const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
  // Fixed path length: spill-policy budgets the preview against the REAL path
  // before stdout normalization, so tmpdir() length differences churn expected outputs.
-  const spillRoot = '/tmp/dsh-acp-snapshot-spill'
+  // Scenario ownership also matters: replay runs concurrently, and one teardown
+  // must never delete another scenario's in-flight full-output recovery file.
+  const spillRoot = snapshotSpillRoot(opts.fixtureFile)
  // Everything past the temp-dir creation is followed by failure-safe cleanup,
  // so a failure in workspace seeding, spawn, or any step never leaks resources.
  let launched: LaunchedAcpTestAgent | undefined
@@ -331,6 +354,15 @@ async function runStep(
      await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
      return
    }
+    case 'promptAndWaitForAgentMessage': {
+      const sessionId = getSessionId()
+      if (sessionId === undefined) throw new Error('snapshot-harness: promptAndWaitForAgentMessage before newSession')
+      const updateDone = waitForUpdate(update => update.sessionUpdate === 'agent_message_chunk'
+        && update.content.type === 'text' && update.content.text === step.waitForText)
+      await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
+      await updateDone
+      return
+    }
    case 'promptExpectError': {
      const sessionId = getSessionId()
      if (sessionId === undefined) throw new Error('snapshot-harness: promptExpectError before newSession')
--- a/packages/support/acp-snapshot/src/index.ts
+++ b/packages/support/acp-snapshot/src/index.ts
@@ -37,10 +37,14 @@ export {
  scrubRequestHeaders,
  scrubSystemPrompts,
  scrubToolSchemas,
+  type CwdPathMode,
  type NormalizeContext,
+  type NormalizeOptions,
 } from './normalize.ts'
 export {
  defineAcpSnapshotSuite,
+  refreshFixtureReplacements,
+  stabilizeRefreshLog,
  type Scenario,
  type SnapshotSuiteOptions,
 } from './suite.ts'
--- a/packages/support/acp-snapshot/src/invariant.ts
+++ b/packages/support/acp-snapshot/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-acp-snapshot`.
+ * @module @deepseek-ai/dsh-acp-snapshot/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-acp-snapshot'
+
+/** Cordis companion plugin name. */
+export const name = 'acp-snapshot-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event stream or mutable data;
+ * consuming test suites exercise its behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/support/acp-snapshot/src/launcher.ts
+++ b/packages/support/acp-snapshot/src/launcher.ts
@@ -21,6 +21,8 @@ import {
 } from '@agentclientprotocol/sdk'
 import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'

+const EXIT_MARKER_GRACE_MS = 250
+
 /** The source/built agent entry, leaf config, and workspace tsconfig an ACP test boots. */
 export interface AgentUnderTest {
  /** The agent source bin entry (for example `packages/examples/acp-demo/src/bin.ts`). */
@@ -231,6 +233,15 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
        return
      }

+      const propagateFailureAfterDrain = async (): Promise<never> => {
+        await drained
+        closeUpdateStream()
+        throw failure
+      }
+      // Windows implements the supported signal names as forced termination. The exit markers
+      // may therefore arrive after the error wins the race above but before fallback begins.
+      if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain()
+
      // An `error` after spawn is not an exit edge: in particular, a failed
      // signal can leave the subprocess live. Force termination, await the
      // already-observed exit edge, and only then propagate the child error so
@@ -240,6 +251,10 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
      child.once('error', observeFallbackError)
      if (!child.kill('SIGKILL')) {
        child.off('error', observeFallbackError)
+        // A successful earlier signal may win between the live check and this fallback call.
+        // In that case `kill()` correctly reports no process to signal; the original child error
+        // remains the shutdown result once inherited stdio and callbacks have drained.
+        if (!isRunning(child) || await exitMarkerWithinGrace(exited)) return propagateFailureAfterDrain()
        closeUpdateStream()
        throw new AggregateError(
          [failure, new Error('Fallback SIGKILL was not accepted by the child process')],
@@ -258,9 +273,7 @@ export function launchAcpTestAgent(options: AcpTestLaunchOptions): LaunchedAcpTe
          'ACP test agent failed and fallback termination was refused',
        )
      }
-      await drained
-      closeUpdateStream()
-      throw failure
+      return propagateFailureAfterDrain()
    },
  }
 }
@@ -270,6 +283,17 @@ function waitForExit(child: ChildProcessWithoutNullStreams): Promise<void> {
  return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
 }

+/** Give an accepted Windows termination request a bounded window to publish its exit marker. */
+function exitMarkerWithinGrace(exited: Promise<void>): Promise<boolean> {
+  return Promise.race([
+    exited.then(() => true),
+    new Promise<false>((resolve) => {
+      const timer = setTimeout(() => { resolve(false) }, EXIT_MARKER_GRACE_MS)
+      timer.unref()
+    }),
+  ])
+}
+
 /** Whether the child still lacks either OS termination marker. */
 function isRunning(child: ChildProcessWithoutNullStreams): boolean {
  return child.exitCode === null && child.signalCode === null
--- a/packages/support/acp-snapshot/src/normalize.ts
+++ b/packages/support/acp-snapshot/src/normalize.ts
@@ -11,20 +11,35 @@ const CWD = '{{cwd}}'
 const SYSTEM = '{{system}}'
 const TOOLS = '{{tools}}'
 const MESSAGE_PREFIX = '{{messagePrefix}}'
+const UPDATED_AT = '{{updatedAt}}'
+
+/** A cwd-rooted path after volatile cwd replacement, through its last separator-delimited segment. */
+const CWD_ROOTED_PATH_RE = /\{\{cwd\}\}(?:[\\/][^\s<>"'`]+)+/g
+const PATH_TAG_RE = /(<path>)([^<]*)(<\/path>)/g
+const ADDITIONAL_INSTRUCTIONS_PATH_RE = /(Additional instructions from: )([^\r\n]+)/g

 /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
 const LOCAL_SPILL_PATH_RE = new RegExp(
-  String.raw`\{\{cwd\}\}/\.spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
+  String.raw`\{\{cwd\}\}[\\/]\.spill[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
  + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`,
  'g',
 )
 const SNAPSHOT_SPILL_PATH_RE = new RegExp(
-  String.raw`/tmp/dsh-acp-snapshot-spill/session-[0-9a-f]{12}/[0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
+  String.raw`(?:[A-Za-z]:)?[\\/](?:tmp|t)[\\/](?:dsh-acp-snap-[0-9a-f]{9}|dsh-acp-snapshot-spill)[\\/]session-[0-9a-f]{12}[\\/][0-9a-f]{12}-([A-Za-z0-9._~-]+?)`
  + String.raw`(?=\. Use read with offset/limit|[\s)]|$)`,
  'g',
 )

+/** Convert separators only inside generated path-bearing text markers. */
+function canonicalizeEmbeddedPaths(value: string): string {
+  return value
+    .replace(PATH_TAG_RE, (_match, open: string, path: string, close: string) =>
+      `${open}${path.replaceAll('\\', '/')}${close}`)
+    .replace(ADDITIONAL_INSTRUCTIONS_PATH_RE, (_match, prefix: string, path: string) =>
+      `${prefix}${path.replaceAll('\\', '/')}`)
+}
+
 /** Inputs the normalizers need to recognize a run's volatile values. */
 export interface NormalizeContext {
  /** The session id(s) the run issued — replaced with `{{sessionId}}`. */
@@ -33,13 +48,28 @@ export interface NormalizeContext {
  cwd: string
 }

+/** How cwd-rooted path separators are represented after the cwd is tokenized. */
+export type CwdPathMode = 'canonical' | 'native'
+
+/** Optional controls shared by stdout and session-log normalization. */
+export interface NormalizeOptions {
+  /** Use `/` for shared goldens, or preserve captured separators for a platform-specific golden. */
+  cwdPathMode?: CwdPathMode
+}
+
 /** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */
-function scrubString(value: string, ctx: NormalizeContext): string {
+function scrubString(value: string, ctx: NormalizeContext, cwdPathMode: CwdPathMode): string {
  let out = value
  // cwd first (longest, most specific), then explicit session ids, then any
  // residual UUID (covers ids that appear in places we didn't enumerate).
  out = out.split(ctx.cwd).join(CWD)
  out = out.split(`/private${CWD}`).join(CWD)
+  if (cwdPathMode === 'canonical') {
+    // Restrict separator conversion to paths rooted at the cwd token. A global
+    // backslash rewrite would corrupt regexes, commands, and model-authored text.
+    out = out.replace(CWD_ROOTED_PATH_RE, path => path.replaceAll('\\', '/'))
+    out = canonicalizeEmbeddedPaths(out)
+  }
  out = out.replace(LOCAL_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`)
  out = out.replace(SNAPSHOT_SPILL_PATH_RE, (_match, name: string) => `{{spillLocator:${name}}}`)
  for (const id of ctx.sessionIds) out = out.split(id).join(SESSION_ID)
@@ -48,12 +78,15 @@ function scrubString(value: string, ctx: NormalizeContext): string {
 }

 /** Recursively scrub a parsed JSON value (strings replaced; structure kept). */
-function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
-  if (typeof value === 'string') return scrubString(value, ctx)
-  if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx))
+function scrubValue(value: unknown, ctx: NormalizeContext, cwdPathMode: CwdPathMode, key?: string): unknown {
+  if (typeof value === 'string') {
+    const scrubbed = scrubString(value, ctx, cwdPathMode)
+    return cwdPathMode === 'canonical' && key === 'path' ? scrubbed.replaceAll('\\', '/') : scrubbed
+  }
+  if (Array.isArray(value)) return value.map(v => scrubValue(v, ctx, cwdPathMode))
  if (value !== null && typeof value === 'object') {
    const out: Record<string, unknown> = {}
-    for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx)
+    for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx, cwdPathMode, k)
    return out
  }
  return value
@@ -67,9 +100,15 @@ function scrubValue(value: unknown, ctx: NormalizeContext): unknown {
 *
 * @param rawStdout The captured stdout bytes, decoded utf8.
 * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
 * @returns The normalized NDJSON transcript, one frame per line.
 */
-export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string {
+export function normalizeStdout(
+  rawStdout: string,
+  ctx: NormalizeContext,
+  options: NormalizeOptions = {},
+): string {
+  const cwdPathMode = options.cwdPathMode ?? 'canonical'
  const lines = rawStdout.split('\n').filter(line => line.trim().length > 0)
  // Map each distinct JSON-RPC id (request/response correlate by id) to a stable
  // sequence number, in first-seen order, so id churn doesn't perturb the expected output.
@@ -85,7 +124,9 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
    if ('id' in frame && frame.id !== undefined && frame.id !== null) {
      frame.id = stableId(frame.id)
    }
-    return scrubValue(frame, ctx) as Record<string, unknown>
+    const update = (frame.params as { update?: Record<string, unknown> } | undefined)?.update
+    if (update?.sessionUpdate === 'session_info_update') update.updatedAt = UPDATED_AT
+    return scrubValue(frame, ctx, cwdPathMode) as Record<string, unknown>
  })
  return frames.map(f => JSON.stringify(f)).join('\n') + '\n'
 }
@@ -101,9 +142,15 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
 *
 * @param rawLog The raw session `.jsonl` content.
 * @param ctx The run's volatile values to scrub.
+ * @param options Separator output controls; shared canonical paths are the default.
 * @returns The normalized JSONL log, one record per line.
 */
-export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string {
+export function normalizeSessionLog(
+  rawLog: string,
+  ctx: NormalizeContext,
+  options: NormalizeOptions = {},
+): string {
+  const cwdPathMode = options.cwdPathMode ?? 'canonical'
  const lines = rawLog.split('\n').filter(line => line.trim().length > 0)
  const records = lines.map((line) => {
    const record = JSON.parse(line) as Record<string, unknown>
@@ -128,7 +175,7 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri
        if ('durationMs' in data) data.durationMs = 0
      }
    }
-    return scrubValue(record, ctx) as Record<string, unknown>
+    return scrubValue(record, ctx, cwdPathMode) as Record<string, unknown>
  })
  return records.map(r => JSON.stringify(r)).join('\n') + '\n'
 }
--- a/packages/support/acp-snapshot/src/suite.ts
+++ b/packages/support/acp-snapshot/src/suite.ts
@@ -21,6 +21,7 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import { type AgentUnderTest, type HarvestedLog, type InputScript, runScenario } from './harness.ts'
 import {
+  type CwdPathMode,
  type NormalizeContext,
  normalizeSessionLog,
  normalizeStdout,
@@ -35,6 +36,9 @@ const SYSTEM_PROMPT_SNAPSHOT = 'system-prompt.expected.md'
 /** The structured tool-schema snapshot beside each header-pinning fixture. */
 const TOOL_SCHEMAS_SNAPSHOT = 'tool-schemas.expected.json'

+/** The optional full Windows-native stdout transcript. */
+const WINDOWS_STDOUT_SNAPSHOT = 'stdout.expected.windows.jsonl'
+
 /** Stable session-log token standing in for the sidecar's initial schemas. */
 const TOOLS_TOKEN = '{{tools}}'

@@ -100,6 +104,61 @@ export interface Scenario {
   * {@link headerClass}.
   */
  configPath?: string
+  /**
+   * Whether Windows additionally compares stdout with native separators against
+   * `stdout.expected.windows.jsonl`. The shared canonical stdout expected output is still
+   * compared on every platform, and the fixture guard requires this sidecar
+   * exactly when the option is set.
+   */
+  pinsNativeWindowsStdout?: boolean
+  /**
+   * Whether the driven behavior needs POSIX process semantics the harness
+   * cannot exercise on Windows (e.g. cancelling a live bash tool call kills a
+   * detached process group). The scenario's run test is skipped on Windows;
+   * its fixtures stay guarded on every platform.
+   */
+  posixOnly?: boolean
+}
+
+/**
+ * Whether a scenario's run test is skipped for this mode and host: record mode
+ * skips authored (non-`recorded`) scenarios, and {@link Scenario.posixOnly}
+ * scenarios skip on Windows.
+ *
+ * @param scenario The scenario whose run test is being registered.
+ * @param recording Whether the suite runs in record mode.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @returns True when the scenario's run test must not execute.
+ */
+export function scenarioSkipped(
+  scenario: Scenario,
+  recording: boolean,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  if (recording && !scenario.recorded) return true
+  return scenario.posixOnly === true && platform === 'win32'
+}
+
+/** One stdout expected output selected for a platform run. */
+interface StdoutExpectedVariant {
+  file: string
+  cwdPathMode: CwdPathMode
+}
+
+/**
+ * Select the shared stdout expected output plus any platform-native assertion declared by a scenario.
+ *
+ * @param scenario The scenario whose stdout contract is being selected.
+ * @param platform The running Node platform, injectable for unit coverage.
+ * @returns The ordered expected-output variants: shared canonical first, then optional Windows native.
+ */
+export function stdoutExpectedVariants(
+  scenario: Scenario,
+  platform: NodeJS.Platform = process.platform,
+): StdoutExpectedVariant[] {
+  const canonical: StdoutExpectedVariant = { file: 'stdout.expected.jsonl', cwdPathMode: 'canonical' }
+  if (platform !== 'win32' || scenario.pinsNativeWindowsStdout !== true) return [canonical]
+  return [canonical, { file: WINDOWS_STDOUT_SNAPSHOT, cwdPathMode: 'native' }]
 }

 /** One suite's inputs: the agent to boot, where its fixtures live, and its scenario table. */
@@ -420,8 +479,21 @@ export function stabilizeRefreshLog(fresh: string, existing: string, replacement
  for (const { from, to } of replacements) stable = stable.split(from).join(to)
  const existingRecords = parseJsonlRecords(existing)
  const records = parseJsonlRecords(stable)
+  let existingIndex = 0
+  let previousEventTime: unknown
  for (let i = 0; i < records.length; i++) {
-    preserveFixtureVolatiles(records[i] as Record<string, unknown>, existingRecords[i])
+    const record = records[i] as Record<string, unknown>
+    const existingRecord = existingRecords[existingIndex]
+    const insertedTitle = record.type === 'session/title' && existingRecord?.type !== 'session/title'
+    if (insertedTitle) {
+      /* v8 ignore next -- a title is turn-enclosed, so a preceding event time exists in every valid fixture. */
+      if (typeof previousEventTime !== 'number') throw new Error('acp-snapshot: inserted title has no preceding event time')
+      record.time = previousEventTime
+    } else {
+      preserveFixtureVolatiles(record, existingRecord)
+      existingIndex += 1
+    }
+    if (typeof record.time === 'number') previousEventTime = record.time
  }
  return records.map(record => JSON.stringify(record)).join('\n') + '\n'
 }
@@ -466,8 +538,9 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
  scenarioSuite('snapshot scenarios', () => {
    for (const scenario of scenarios) {
      // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the `authored` ones
-      // (sidecar-driven errors/cancel) are never re-recorded.
-      it.skipIf(RECORDING && !scenario.recorded)(`snapshot: ${scenario.name} matches the expected outputs`, async ({ expect }) => {
+      // (sidecar-driven errors/cancel) are never re-recorded. `posixOnly` scenarios skip on
+      // Windows, where their process semantics cannot be driven.
+      it.skipIf(scenarioSkipped(scenario, RECORDING))(`snapshot: ${scenario.name} matches the expected outputs`, async ({ expect }) => {
        const dir = join(snapshotsDir, scenario.name)
        const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
        const overrideFile = join(dir, 'replay.override.json')
@@ -571,11 +644,13 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {
          }
        }

-        const stdout = normalizeStdout(result.rawStdout, ctx)
-        if (REFRESHING) {
-          await writeFile(join(dir, 'stdout.expected.jsonl'), stdout)
+        for (const expected of stdoutExpectedVariants(scenario)) {
+          const stdout = normalizeStdout(result.rawStdout, ctx, { cwdPathMode: expected.cwdPathMode })
+          if (REFRESHING) {
+            await writeFile(join(dir, expected.file), stdout)
+          }
+          await expect(stdout, `${expected.file} mismatch`).toMatchFileSnapshot(join(dir, expected.file))
        }
-        await expect(stdout).toMatchFileSnapshot(join(dir, 'stdout.expected.jsonl'))

        // A model turn always produces a log worth comparing; a hook scenario can
        // produce one without a model turn (a `rejected` turn carrying `hook/*`).
@@ -662,10 +737,14 @@ export function defineAcpSnapshotSuite(options: SnapshotSuiteOptions): void {

    it('every registered scenario has its required fixture files', async () => {
      // Every scenario needs input, stdout, a primary session fixture, and matching optional sidecars.
-      for (const { name, overridden, pinsHeader } of scenarios) {
+      for (const { name, overridden, pinsHeader, pinsNativeWindowsStdout } of scenarios) {
        const dir = join(snapshotsDir, name)
        expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
        expect(existsSync(join(dir, 'stdout.expected.jsonl')), `${name}/stdout.expected.jsonl`).toBe(true)
+        expect(
+          existsSync(join(dir, WINDOWS_STDOUT_SNAPSHOT)),
+          `${name}/${WINDOWS_STDOUT_SNAPSHOT} presence must match \`pinsNativeWindowsStdout\``,
+        ).toBe(pinsNativeWindowsStdout === true)
        expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
        expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json presence must match \`overridden\``)
          .toBe(overridden === true)
--- a/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
+++ b/packages/support/acp-snapshot/tests/fixtures/fake-acp-agent.ts
@@ -152,6 +152,7 @@ async function handlePrompt(id: number | string): Promise<void> {
      mode: process.env.DSH_SNAPSHOT,
      override: process.env.DSH_SNAPSHOT_OVERRIDE ?? null,
      childFiles: process.env.DSH_SNAPSHOT_CHILD_FILES ?? null,
+      spillRoot: process.env.DSH_SNAPSHOT_SPILL_ROOT ?? null,
    })}`)
  }
  if (behavior.echoWorkspace === true) {
@@ -299,7 +300,10 @@ function flushLogsAndExit(): void {
      `setTimeout(() => process.stdout.write(${JSON.stringify(`${frame}\n`)}), 50)`,
      `setTimeout(() => process.stderr.write(${JSON.stringify('late inherited stderr\n')}), 75)`,
    ].join(';')
-    spawn(process.execPath, ['-e', code], { stdio: ['ignore', 1, 2] }).unref()
+    spawn(process.execPath, ['-e', code], {
+      detached: true,
+      stdio: ['ignore', 'inherit', 'inherit'],
+    }).unref()
  }
  process.exit(0)
 }
--- a/packages/support/acp-snapshot/tests/harness.spec.ts
+++ b/packages/support/acp-snapshot/tests/harness.spec.ts
@@ -5,7 +5,7 @@ import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness.ts'
+import { runScenario, snapshotSpillRoot, type AgentUnderTest, type InputStep } from '../src/harness.ts'
 import { launchAcpTestAgent } from '../src/launcher.ts'

 const fsControl = vi.hoisted(() => ({ cleanupFailure: undefined as Error | undefined }))
@@ -60,6 +60,24 @@ async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: s

 const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }]

+it('keeps scenario-owned snapshot spill root length stable across platforms', () => {
+  const fixtureFile = '/fixtures/scenario/session.jsonl'
+  const posix = snapshotSpillRoot(fixtureFile, 'linux')
+  const windows = snapshotSpillRoot(fixtureFile, 'win32')
+  expect(posix).toMatch(/^\/tmp\/dsh-acp-snap-[0-9a-f]{9}$/)
+  expect(windows).toMatch(/^\/t\/dsh-acp-snap-[0-9a-f]{9}$/)
+  expect(windows.length + 2).toBe(posix.length)
+})
+
+function environmentEcho(rawStdout: string): Record<string, unknown> {
+  const frames = rawStdout.trim().split('\n')
+    .map(line => JSON.parse(line) as { params?: { update?: { content?: { text?: unknown } } } })
+  const text = frames.map(frame => frame.params?.update?.content?.text)
+    .find(value => typeof value === 'string' && value.startsWith('env:'))
+  if (typeof text !== 'string') throw new Error('fake ACP agent did not echo its environment')
+  return JSON.parse(text.slice('env:'.length)) as Record<string, unknown>
+}
+
 describe('runScenario', () => {
  it('surfaces an asynchronous child spawn failure through startup and close', async () => {
    const { dir } = await scenario({})
@@ -134,6 +152,9 @@ describe('runScenario', () => {
      update.sessionUpdate === 'agent_message_chunk'
      && update.content.type === 'text'
      && update.content.text === 'late inherited stdout')
+    // Arm rejection handling before close may exhaust the stream; the later assertion still
+    // observes the original promise and turns a missing inherited frame into the test failure.
+    void lateUpdate.catch(() => undefined)

    await launched.close()

@@ -171,6 +192,97 @@ describe('runScenario', () => {
    }
  })

+  it('preserves the child error when the requested signal sets an exit marker', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed as the child exited'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      expect(signal).toBe('SIGTERM')
+      originalKill('SIGKILL')
+      Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGTERM' })
+      return true
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
+  it('preserves the child error when the requested signal publishes its exit marker later', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed before the delayed exit marker'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      expect(signal).toBe('SIGTERM')
+      setTimeout(() => { originalKill('SIGKILL') }, 10)
+      return true
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenCalledOnce()
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
+  it('preserves the child error when fallback refusal races with an exit marker', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('signal failed while the child exited'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      if (signal === 'SIGTERM') return true
+      originalKill('SIGKILL')
+      Object.defineProperty(launched.child, 'signalCode', { configurable: true, enumerable: true, writable: true, value: 'SIGKILL' })
+      return false
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL')
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
+  it('preserves the child error after accepted fallback termination drains', async () => {
+    const { dir } = await scenario({})
+    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
+    await launched.spawned
+
+    const childFailure = Object.assign(new Error('requested signal failed before fallback'), { code: 'EPERM' })
+    const originalKill = launched.child.kill.bind(launched.child)
+    const kill = vi.spyOn(launched.child, 'kill').mockImplementation((signal) => {
+      if (signal === 'SIGTERM') return true
+      return originalKill('SIGKILL')
+    })
+    try {
+      launched.child.emit('error', childFailure)
+      await expect(launched.close('SIGTERM')).rejects.toBe(childFailure)
+      expect(kill).toHaveBeenNthCalledWith(1, 'SIGTERM')
+      expect(kill).toHaveBeenNthCalledWith(2, 'SIGKILL')
+    } finally {
+      kill.mockRestore()
+      if (launched.child.exitCode === null && launched.child.signalCode === null) originalKill('SIGKILL')
+    }
+  })
+
  it('rejects promptly when fallback termination emits an error', async () => {
    const { dir } = await scenario({})
    const launched = launchAcpTestAgent({ agent: AGENT, cwd: dir })
@@ -285,7 +397,11 @@ describe('runScenario', () => {
    expect(result.sessionLogs[0]?.createdAt).toBe(42)
    expect(result.sessionLogs[0]?.content).toContain('turn/start')
    // The harvested log embeds the run's REAL temp cwd (template-substituted).
-    expect(result.sessionLogs[0]?.content).toContain(result.cwd)
+    // The cwd is JSON-encoded in the log line, so compare the parsed field
+    // rather than substring-matching a raw path (which breaks when the path
+    // separator is escaped inside JSON text on Windows).
+    const sessionLine = result.sessionLogs[0]?.content.split('\n').find(l => l.includes('"type":"session"')) ?? '{}'
+    expect((JSON.parse(sessionLine) as { cwd?: string }).cwd).toBe(result.cwd)
  })

  it('forwards override/child fixture paths into the child env and captures stderr', { timeout: 20_000 }, async () => {
@@ -306,7 +422,33 @@ describe('runScenario', () => {
    expect(result.stderr).toContain('fake bin booted')
    expect(result.rawStdout).toContain('replay.override.json')
    // Child paths ride one env var, joined with the platform delimiter.
-    expect(result.rawStdout).toContain(JSON.stringify(childFiles.join(delimiter)).slice(1, -1))
+    // Parse the fake bin's env-probe chunk rather than substring-matching a
+    // JSON-encoded path (the escaping breaks raw-substring compares on Windows).
+    const envChunk = result.rawStdout.split('\n')
+      .map(l => l.trim())
+      .filter(l => l.length > 0)
+      .map(l => JSON.parse(l) as { params?: { update?: { content?: { text?: string } } } })
+      .find(f => f.params?.update?.content?.text?.startsWith('env:'))
+    const env = JSON.parse((envChunk?.params?.update?.content?.text ?? 'env:{}').slice('env:'.length)) as {
+      childFiles: string | null
+    }
+    expect(env.childFiles).toBe(childFiles.join(delimiter))
+  })
+
+  it('gives concurrent scenarios distinct equal-length spill roots', { timeout: 20_000 }, async () => {
+    const [first, second] = await Promise.all([scenario({ echoEnv: true }), scenario({ echoEnv: true })])
+    const results = await Promise.all([first, second].map(({ fixtureFile }) => runScenario(
+      { steps: [...boot, { op: 'prompt', text: 'env?' }] },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )))
+    const roots = results.map(result => environmentEcho(result.rawStdout).spillRoot)
+    expect(roots.every(root => typeof root === 'string')).toBe(true)
+    expect(new Set(roots).size).toBe(2)
+    expect((roots[0] as string).length).toBe((roots[1] as string).length)
+    expect(roots).toEqual([
+      snapshotSpillRoot(first.fixtureFile),
+      snapshotSpillRoot(second.fixtureFile),
+    ])
  })

  it('seeds the workspace dir into the temp cwd before the run', { timeout: 20_000 }, async () => {
@@ -334,6 +476,21 @@ describe('runScenario', () => {
    expect(result.rawStdout.indexOf('thinking about it')).toBeLessThan(result.rawStdout.indexOf('cancelled'))
  })

+  it('promptAndWaitForAgentMessage keeps the app live through a matching later update', { timeout: 20_000 }, async () => {
+    const { fixtureFile } = await scenario({ prompt: 'respond' })
+    const result = await runScenario(
+      {
+        steps: [...boot, {
+          op: 'promptAndWaitForAgentMessage',
+          text: 'go',
+          waitForText: 'thinking about it',
+        }],
+      },
+      { agent: AGENT, mode: 'replay', fixtureFile },
+    )
+    expect(result.rawStdout).toContain('thinking about it')
+  })
+
  it('promptAndCancel can bracket cancellation with tool-call updates', { timeout: 20_000 }, async () => {
    const { fixtureFile } = await scenario({
      prompt: 'hang-until-cancel',
@@ -443,6 +600,7 @@ describe('runScenario', () => {

  it.each([
    [{ op: 'prompt', text: 'x' }, /prompt before newSession/],
+    [{ op: 'promptAndWaitForAgentMessage', text: 'x', waitForText: 'later' }, /promptAndWaitForAgentMessage before newSession/],
    [{ op: 'promptExpectError', text: 'x' }, /promptExpectError before newSession/],
    [{ op: 'promptAndCancel', text: 'x' }, /promptAndCancel before newSession/],
    [{ op: 'cancel' }, /cancel before newSession/],
--- a/packages/support/acp-snapshot/tests/normalize.spec.ts
+++ b/packages/support/acp-snapshot/tests/normalize.spec.ts
@@ -44,6 +44,56 @@ describe('normalizeStdout', () => {
    expect(out).not.toContain(ctx.sessionIds[0] as string)
  })

+  it('canonicalizes only cwd-rooted path separators', () => {
+    const windowsCtx: NormalizeContext = {
+      sessionIds: [],
+      cwd: String.raw`C:\Users\runner\AppData\Local\Temp\acp-snapshot`,
+    }
+    const raw = JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'session/update',
+      params: {
+        path: `${windowsCtx.cwd}\\nested\\proof.txt`,
+        regex: String.raw`\d+\w+`,
+        command: String.raw`printf "\\n"`,
+      },
+    })
+    const frame = JSON.parse(normalizeStdout(raw, windowsCtx)) as {
+      params: { path: string; regex: string; command: string }
+    }
+    expect(frame.params).toEqual({
+      path: '{{cwd}}/nested/proof.txt',
+      regex: String.raw`\d+\w+`,
+      command: String.raw`printf "\\n"`,
+    })
+  })
+
+  it('canonicalizes generated relative path fields and text markers without rewriting other text', () => {
+    const raw = JSON.stringify({
+      path: String.raw`nested\AGENTS.md`,
+      content: String.raw`<path>.\nested\task.txt</path>
+Additional instructions from: nested\AGENTS.md`,
+      regex: String.raw`\d+\w+`,
+    })
+    const frame = JSON.parse(normalizeStdout(raw, { sessionIds: [], cwd: '/unused' })) as {
+      path: string
+      content: string
+      regex: string
+    }
+    expect(frame).toEqual({
+      path: 'nested/AGENTS.md',
+      content: '<path>./nested/task.txt</path>\nAdditional instructions from: nested/AGENTS.md',
+      regex: String.raw`\d+\w+`,
+    })
+  })
+
+  it('can preserve native cwd-rooted separators for a platform golden', () => {
+    const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` }
+    const raw = JSON.stringify({ path: `${windowsCtx.cwd}\\nested\\proof.txt` })
+    const frame = JSON.parse(normalizeStdout(raw, windowsCtx, { cwdPathMode: 'native' })) as { path: string }
+    expect(frame.path).toBe(String.raw`{{cwd}}\nested\proof.txt`)
+  })
+
  it('scrubs a stray UUID not in the known list', () => {
    const raw = JSON.stringify({ jsonrpc: '2.0', method: 'x', params: { id: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' } })
    expect(normalizeStdout(raw, ctx)).toContain('{{sessionId}}')
@@ -55,6 +105,24 @@ describe('normalizeStdout', () => {
    expect(out).not.toContain('"id"')
  })

+  it('stabilizes the timestamp carried by session title updates', () => {
+    const raw = JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'session/update',
+      params: {
+        sessionId: ctx.sessionIds[0],
+        update: {
+          sessionUpdate: 'session_info_update',
+          title: 'Stable title',
+          updatedAt: '2026-07-20T17:03:13.689Z',
+        },
+      },
+    })
+    const out = normalizeStdout(raw, ctx)
+    expect(out).toContain('"updatedAt":"{{updatedAt}}"')
+    expect(out).not.toContain('2026-07-20T17:03:13.689Z')
+  })
+
  it('throws on a non-JSON stdout line (the purity check)', () => {
    const raw = `${JSON.stringify({ jsonrpc: '2.0', id: 1 })}\noops a log leaked\n`
    expect(() => normalizeStdout(raw, ctx)).toThrow()
@@ -139,6 +207,48 @@ describe('normalizeSessionLog', () => {
    expect(out).not.toContain('/tmp/dsh-acp-snapshot-spill')
  })

+  it('scrubs scenario-owned snapshot spill paths', () => {
+    const ev = JSON.stringify({
+      type: 'tool/result', seq: 2, time: 5,
+      data: {
+        content: [{
+          type: 'text',
+          text: 'Full formatted result stored at: /tmp/dsh-acp-snap-012345678/session-c22bc3f1d2af/8a7b6c5d4e3f-bash.txt. Use read with offset/limit, or grep this path to search within it.',
+        }],
+      },
+    })
+    const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx)
+    expect(out).toContain('{{spillLocator:bash.txt}}')
+    expect(out).not.toContain('/tmp/dsh-acp-snap-012345678')
+  })
+
+  it('scrubs scenario-owned snapshot spill paths with Windows drive and separators', () => {
+    const ev = JSON.stringify({
+      type: 'tool/result', seq: 2, time: 5,
+      data: {
+        content: [{
+          type: 'text',
+          text: String.raw`Full formatted result stored at: C:\t\dsh-acp-snap-012345678\session-c22bc3f1d2af\8a7b6c5d4e3f-bash.txt. Use read with offset/limit, or grep this path to search within it.`,
+        }],
+      },
+    })
+    const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx)
+    expect(out).toContain('{{spillLocator:bash.txt}}')
+    expect(out).not.toContain('C:\\t\\dsh-acp-snap-012345678')
+  })
+
+  it('shares cwd-rooted path handling with stdout normalization', () => {
+    const windowsCtx: NormalizeContext = { sessionIds: [], cwd: String.raw`C:\work\snapshot` }
+    const ev = JSON.stringify({
+      type: 'tool/result', seq: 2, time: 5,
+      data: { path: `${windowsCtx.cwd}\\nested\\proof.txt` },
+    })
+    expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx))
+      .toContain('{{cwd}}/nested/proof.txt')
+    expect(normalizeSessionLog(`${header({ cwd: windowsCtx.cwd })}\n${ev}\n`, windowsCtx, { cwdPathMode: 'native' }))
+      .toContain(String.raw`{{cwd}}\\nested\\proof.txt`)
+  })
+
  it('scrubs the session id in the header', () => {
    const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx)
    expect(out).toContain('{{sessionId}}')
--- a/packages/support/acp-snapshot/tests/suite.spec.ts
+++ b/packages/support/acp-snapshot/tests/suite.spec.ts
@@ -15,9 +15,11 @@ import {
  normalizedToolSchemas,
  parseToolSchemasSnapshot,
  refreshFixtureReplacements,
+  scenarioSkipped,
  sessionFixtureNames,
  restorePinnedToolSchemas,
  stabilizeRefreshLog,
+  stdoutExpectedVariants,
  unknownToolCallIds,
 } from '../src/suite.ts'

@@ -230,6 +232,48 @@ describe('sessionFixtureNames', () => {
  })
 })

+describe('stdoutExpectedVariants', () => {
+  const scenario: Scenario = {
+    name: 'windows-native',
+    hasModelTurn: true,
+    recorded: true,
+    pinsNativeWindowsStdout: true,
+  }
+
+  it('adds the native sidecar after the shared golden on Windows', () => {
+    expect(stdoutExpectedVariants(scenario, 'win32')).toEqual([
+      { file: 'stdout.expected.jsonl', cwdPathMode: 'canonical' },
+      { file: 'stdout.expected.windows.jsonl', cwdPathMode: 'native' },
+    ])
+  })
+
+  it('keeps only the shared golden on other platforms or without the declaration', () => {
+    expect(stdoutExpectedVariants(scenario, 'linux')).toEqual([
+      { file: 'stdout.expected.jsonl', cwdPathMode: 'canonical' },
+    ])
+    expect(stdoutExpectedVariants({ ...scenario, pinsNativeWindowsStdout: false }, 'win32')).toEqual([
+      { file: 'stdout.expected.jsonl', cwdPathMode: 'canonical' },
+    ])
+  })
+})
+
+describe('scenarioSkipped', () => {
+  const authored: Scenario = { name: 'authored', hasModelTurn: true, recorded: false }
+  const posix: Scenario = { name: 'posix-cancel', hasModelTurn: true, recorded: false, posixOnly: true }
+
+  it('skips authored scenarios only while recording', () => {
+    expect(scenarioSkipped(authored, true, 'linux')).toBe(true)
+    expect(scenarioSkipped(authored, false, 'linux')).toBe(false)
+  })
+
+  it('skips posixOnly scenarios on Windows and nowhere else', () => {
+    expect(scenarioSkipped(posix, false, 'win32')).toBe(true)
+    expect(scenarioSkipped(posix, false, 'linux')).toBe(false)
+    expect(scenarioSkipped(posix, false, 'darwin')).toBe(false)
+    expect(scenarioSkipped(authored, false, 'win32')).toBe(false)
+  })
+})
+
 describe('fixtureContext', () => {
  it('reads the fixture header id and cwd', () => {
    const ctx = fixtureContext('{"type":"session","id":"abc","cwd":"/rec"}\n{"type":"turn/start"}\n')
@@ -407,6 +451,36 @@ describe('refreshFixtureReplacements', () => {
 })

 describe('stabilizeRefreshLog', () => {
+  it('aligns volatile times across a newly inserted log event', () => {
+    const fresh = [
+      '{"type":"session","id":"same","createdAt":200}',
+      '{"type":"turn/start","seq":0,"time":21}',
+      '{"type":"user/message","seq":1,"time":22}',
+      '{"type":"session/title","seq":2,"time":999}',
+      '{"type":"step/start","seq":3,"time":1000}',
+      '{"type":"request/header","seq":4,"time":1001}',
+      '',
+    ].join('\n')
+    const existing = [
+      '{"type":"session","id":"same","createdAt":100}',
+      '{"type":"turn/start","seq":0,"time":11}',
+      '{"type":"user/message","seq":1,"time":12}',
+      '{"type":"step/start","seq":2,"time":13}',
+      '{"type":"request/header","seq":3,"time":14}',
+      '',
+    ].join('\n')
+
+    expect(stabilizeRefreshLog(fresh, existing, [])).toBe([
+      '{"type":"session","id":"same","createdAt":100}',
+      '{"type":"turn/start","seq":0,"time":11}',
+      '{"type":"user/message","seq":1,"time":12}',
+      '{"type":"session/title","seq":2,"time":12}',
+      '{"type":"step/start","seq":3,"time":13}',
+      '{"type":"request/header","seq":4,"time":14}',
+      '',
+    ].join('\n'))
+  })
+
  it('keeps volatile fixture fields while preserving fresh meaningful payloads', () => {
    const fresh = [
      '{"type":"session","id":"new-child","createdAt":200,"cwd":"/new","parentSession":"new-parent","seedLength":1}',
--- a/packages/support/acp-snapshot/tsconfig.json
+++ b/packages/support/acp-snapshot/tsconfig.json
@@ -8,6 +8,11 @@
    "src"
  ],
  "references": [
-    { "path": "../loader-smoke" }
+    {
+      "path": "../loader-smoke"
+    },
+    {
+      "path": "../../support/invariants"
+    }
  ]
 }
--- a/packages/support/agent-loop-testkit/package.json
+++ b/packages/support/agent-loop-testkit/package.json
@@ -11,11 +11,16 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
@@ -23,6 +28,7 @@
  "license": "BSD-3-Clause",
  "peerDependencies": {
    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -32,6 +38,7 @@
  "devDependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/support/agent-loop-testkit/src/invariant.ts
+++ b/packages/support/agent-loop-testkit/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-agent-loop-testkit`.
+ * @module @deepseek-ai/dsh-agent-loop-testkit/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop-testkit'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-loop-testkit-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event stream or mutable data;
+ * consuming test suites exercise its behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/support/agent-loop-testkit/tsconfig.json
+++ b/packages/support/agent-loop-testkit/tsconfig.json
@@ -28,6 +28,9 @@
    },
    {
      "path": "../../core/tools"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -1,65 +1,83 @@
 # dsh-invariants

-Runtime event-contract assertions intended for development diagnostics. This pure-listener plugin checks relationships among session events, agent states, scoped dispatches, and model requests; it does not own or change product behavior.
+Configurable registry service for package-owned runtime invariant checks. The root plugin registers `ctx.invariants`; it contains no product checks or product-package imports. Every workspace package publishes a `./invariant` companion that registers its exact npm package name.

-The plugin has no environment guard: it is active wherever it is registered. The default [`dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md) bundle mounts it unconditionally; a custom composition can omit it when the runtime cost is undesirable. It doubles as executable documentation of the event taxonomy — the assertions *are* the contract.
+## Service: `InvariantService` (`ctx.invariants`)

-Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The invariants plugin checks the remaining cross-record and cross-seam rules that Session does not own.
+```ts
+interface Config {
+  enabled?: boolean
+  package_allowlist?: string[]
+  package_blocklist?: string[]
+}
+```

-Session-log assertions run during Cordis `internal/dispatch`, while `Session.append()` is resolving the `session/event` callback snapshot but before it pushes the candidate into the log. A valid transition is staged by exact event identity and applied to the live trace only when that same committed event reaches the plugin's contained post-commit listener. A later internal dispatch check can therefore veto without advancing either the log or the invariant trace, while ordinary `session/event` observer failures remain observe-only.
+Defaults are `enabled: true`, `package_allowlist: []`, and `package_blocklist: []`. A package is selected only when the service is enabled, the allowlist is empty or at least one allowlist pattern matches its full npm name, and no blocklist pattern matches. Blocklist matches therefore override allowlist matches.

-## Plugin
+Each entry is a case-sensitive JavaScript regular-expression source compiled with `new RegExp(pattern)`. Matching is unanchored unless the source supplies `^` and `$`; `/pattern/flags` syntax is not parsed. Blank, whitespace-padded, invalid, or duplicate entries within one list fail service startup. A valid pattern may match no currently loaded package so later loading and HMR remain deterministic.

-A functional plugin — register the module namespace (this is what loading by name in `cordis.yml` does):
+`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name, including when filters keep its installer inactive, and returns its disposer. An enabled contribution runs in a dedicated child Cordis fiber. The installer can declare its required service surface through `installer.inject` and receives `fail(message)`, which throws an `InvariantError` bound to the registering package. Synchronous or asynchronous installer completion is joined before registration succeeds; failure disposes the child and releases ownership atomically.
+
+The service owns every registration fiber, while the returned disposer also belongs to the companion fiber. Unloading either side removes listeners, trace state, and the reservation. A companion can therefore reload and register the same package name without retaining its previous state. Session-backed companions rebuild their baseline from durable events; live-only companions observe operations that begin after reload.
+
+`InvariantError` extends `Error`, carries stable `code: 'INVARIANT'`, and exposes the owning `packageName` without adding a product dependency to the service.
+
+Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
+
+## Package companions
+
+Publication and registration are exhaustive; runtime assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event relationship or relevant mutable-data relationship. Confirming a required method, plugin name, injection, effect, or fixed pure-function result is a type, load, or unit-test concern rather than a runtime invariant.
+
+When no plausible runtime relationship exists, the companion uses an empty installer with a package-specific leading `No runtime invariant:` comment explaining why. This is common for pure utilities, thin implementations whose behavior is already observed through their seam, composition-only packages, binaries, persistence adapters whose contracts require crash/round-trip tests, and test-support packages. The explanation must be revisited when the owner gains mutable state or an event protocol.
+
+The current executable companions protect these relationships:
+
+| Companion | Checks |
+|---|---|
+| `dsh-session`, `dsh-agent`, `dsh-scope`, `dsh-agent-loop` | Session enclosure and call/result trace, agent-status transitions, scoped subjects, and model-request reconstruction. |
+| `dsh-llm`, `dsh-llm-retry`, `dsh-tools`, `dsh-system-prompt` | Stream grammar, durable retry position and bounds, tool-pipeline stages and frozen results, and authoritative prompt-assembly data. |
+| `dsh-compact`, `dsh-hook-protocol`, `dsh-sandbox-policy` | Durable compaction and hook pairing, compaction metadata, and sandbox-mode vocabulary. |
+| `dsh-fs`, `dsh-subagent`, `dsh-workflow` | Filesystem event identity, provider/child pairing, and workflow/agent lifecycle identity. |
+| `dsh-goal`, `dsh-goal-session` | Durable goal source/content agreement, revision and lifecycle transitions, timestamps, sequential admitted rounds, and reconstructed continuation prompts. |
+| `dsh-permission`, `dsh-user-approval` | Active-preset references and approval asked/decided audit pairing. |
+| `dsh-tasks`, `dsh-tool-todo` | Task snapshot lifecycle/ownership fields and durable whole-list todo structure. |
+| `dsh-time-context` | Durable clock readings agree with the session's open turn and next pre-step position and elapsed baseline; rendered time parses and does not postdate its event. |
+
+The root entrypoint of each owner remains independent of diagnostics. Loading the service alone installs no product checks, and loading a companion without the service waits on its declared `invariants` injection.
+
+`pnpm run verify-package-invariants` discovers all workspace packages. It rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, TypeScript-reference, or bundle wiring. This source rule is a minimum ownership check; focused tests prove each executable companion's semantics.
+
+## Composition

 ```ts
 import type { Context } from 'cordis'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'

 declare const ctx: Context

-await ctx.plugin(Invariants)
+ctx.plugin(InvariantService, {
+  enabled: true,
+  package_allowlist: ['^@deepseek-ai/dsh-'],
+  package_blocklist: ['^@deepseek-ai/dsh-agent-loop$'],
+})
+ctx.plugin(SessionInvariant)
 ```

-`inject`: `['sessions']` — it reads `ctx.sessions.list()` at apply time to rebuild trace state for sessions that already exist, so a hot reload mid-turn does not falsely reject the next event. The oracle listeners are explicitly global so pre-commit staging and post-commit application keep the same audience even if the plugin is mounted under a scoped context; their cleanup still belongs to that mounting fiber. The plugin has no configuration.
+The standard agent spine mounts the service and its four core stateful companions. Custom compositions explicitly add companions for other loaded packages whose contracts they want checked; filters can disable or select registrations without changing package entrypoints.

-## Invariants asserted
-
-Session log (per session):
-
- **`seq` strictly increases** — the spine of replay equivalence.
- **turns pair and nest** — `turn/start` opens a turn, `turn/end` closes the matching one; no overlapping turns.
- **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.
- **an appended `tool/result` needs a prior `tool/call`** — fresh `surfaceOp: 'append'` results name the open step and consume its pending call. A Session-validated replacement is a turn-enclosed rewrite, not another execution. A `tool/call` may still have no result when the execution pipeline throws.
-
-Agent status (per agent):
-
- **legal transitions only** — `idle↔running` and `(idle|running)→disposed`. A no-op transition (`setStatus` dedups, so it never fires) and leaving the terminal `disposed` state are violations.
-
-Model requests (on `llm/stream`):
-
- **a loop-built request is exactly what the log reconstructs** — a frozen request with a live `sessionId` (the loop-built marker; hand-built one-shots like compaction's summarize are unfrozen and skipped) must carry frozen `messages` deep-equal to the derivation over the log prefix strictly before the in-flight step's `step/start` (rebuilt through a FRESH `Session`, so the live cache cannot vouch for itself — and boundary-correct: content logged after `step/start` legitimately belongs to the next request), and every non-content field must equal the latest logged `request/header` (see [the reconstructability Agent Note](../../../.agents/notes/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'`).
-
-## Why runtime assertions remain useful
-
-Session enforces the per-record storage boundary at runtime, where a cast cannot bypass it. Pervasive `DeepReadonly<SessionEvent>` types would add noise across consumers without expressing relationships such as turn/step nesting, subject-correct scoped dispatch, or equality between a request and its log reconstruction. This plugin checks those relationships wherever it is mounted while `dsh-session` keeps history immutable in every composition. See [source-owned session immutability and dev-mode invariants](../../../.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
-
-## Seeded sessions
-
-A seeded or forked session arrives with events already in its log because construction does not emit `session/event` for each seed record. `Session` validates, snapshots, and freezes every seed record before accepting it; on `session/created`, this plugin replays the accepted log only to rebuild and check its relational trace state.
+Every ordinary Vitest topology mounts an explicitly enabled service and the current test package's companion. Focused suites cover valid and invalid observations for executable companions, while one exhaustive topology mounts all companions to prove registration and disposal wiring.

 ## Model Experience

-None, as this observer only validates events and frozen requests and never rewrites prompts, schemas, messages, or streams.
+None, as the service and companions observe runtime events and mutable snapshots without altering prompts, messages, schemas, streams, or tool results.

 #### KV Cache effect

-None; this package neither assembles nor sends a provider request.
+None; invariant checks do not assemble or send provider requests.

 ## Known Limitations and Deferred Work

- **The request-reconstructability assertion covers loop-built requests only** — hand-built one-shots (e.g. compaction's summarize call) carry no live `sessionId` marker and are skipped.
- **Merge-extended event families get no family-specific assertions** — `compact/*` lock pairing and `hook/*` invoked/result pairing are not checked here; only the core turn/step/chunk/tool-result contract is.
+- Request reconstruction covers requests explicitly marked by the loop before freezing; direct one-shot LLM calls remain outside that marker contract even when callers freeze them or attach a session id.
+- Live-only lifecycle companions cannot reconstruct operations that began before their own reload. Standard and test compositions mount them before the corresponding operations begin.
+- Regular-expression filters are fixed for the service lifetime; changing them requires ordinary Cordis plugin reload.
--- a/packages/support/invariants/package.json
+++ b/packages/support/invariants/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-invariants",
-  "description": "Runtime event-contract assertions for DeepSeek Harness development diagnostics",
+  "description": "Registry service for package-owned DeepSeek Harness runtime invariants",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -11,32 +11,28 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-scope": "^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-agent": "workspace:^",
-    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-scope": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-subagent": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-user-approval": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -1,419 +1,200 @@
 /**
- * Runtime listeners that fail loudly when cross-event contracts are broken:
- * turn and step nesting, scoped dispatch, status transitions, and request
- * reconstruction. The plugin has no environment guard and is active wherever
- * mounted, including the default `dsh-agent-spine-demo` bundle; custom compositions
- * may omit it. Sessions own immutable, surface-valid event storage; this plugin
- * checks only relationships that event acceptance cannot express.
+ * Configurable registry for package-owned runtime invariant contributions.
+ * Every workspace package registers checks from a `./invariant` companion;
+ * ordinary package entrypoints stay independent of diagnostics.
+ *
 * @module @deepseek-ai/dsh-invariants
 */

-import type { Context } from 'cordis'
-import { carrierKeyOf, isScopeCarrier } from '@deepseek-ai/dsh-scope'
-import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
-import type { CallId, GenerateOptions } from '@deepseek-ai/dsh-llm'
-import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
-import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { scopedSubjectResolverFor } from './scoped-events.generated.ts'
+import { Context, Service } from 'cordis'
+import type { Inject } from 'cordis'
+import z from 'schemastery'
+import type Schema from 'schemastery'

-export const name = 'invariants'
-export const inject = ['sessions']
-
-/**
- * Thrown when a harness event-contract invariant is violated. Extends
- * {@link HarnessError} (`code: 'INVARIANT'`) so a violation is routable like
- * any other harness failure.
- */
-export class InvariantError extends HarnessError {
-  constructor(message: string) {
-    super(`invariant violated: ${message}`, 'INVARIANT')
-    this.name = 'InvariantError'
-  }
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+  /** Global switch; defaults to `true`. */
+  readonly enabled?: boolean
+  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+  readonly package_allowlist?: string[]
+  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+  readonly package_blocklist?: string[]
 }

-/** Per-session bookkeeping for the session-log invariants. */
-interface SessionTrace {
-  /** Highest `seq` seen so far (must strictly increase). */
-  lastSeq: number
-  /** Open turn number, or null between turns. */
-  openTurn: number | null
-  /** Open step within the current turn, or null between steps. */
-  openStep: number | null
-  /** The next turn number expected in this session log. */
-  nextTurn: number
-  /** The next step number expected within the open turn. */
-  nextStep: number
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+export type InvariantFailure = (message: string) => never
+
+/** Install one package's checks into the registration's child context. */
+export interface InvariantInstaller {
  /**
-   * Tool-call ids issued in the OPEN step awaiting a result. Cleared at
-   * `step/end` — a result must arrive in the same step as its call.
+   * Install the package contribution.
+   * @param ctx - child context owned by this invariant registration.
+   * @param fail - reporter bound to the registering package name.
+   * @returns nothing, or a promise settling after asynchronous checks finish.
   */
-  pendingCalls: Set<CallId>
+  (ctx: Context, fail: InvariantFailure): void | Promise<void>
+  /** Services the child installer fiber may access. */
+  readonly inject?: Inject
 }

-/** One accepted event's deferred mutation of a live session trace. */
-interface SessionTraceTransition {
-  /** Scalar state after the event commits. */
-  scalars: Pick<SessionTrace, 'lastSeq' | 'openTurn' | 'openStep' | 'nextTurn' | 'nextStep'>
-  /** The event's mutation of the open step's pending call set. */
-  pendingCalls:
-    | { kind: 'none' }
-    | { kind: 'add' | 'delete'; callId: CallId }
-    | { kind: 'clear' }
+/** Internal effect shape used to join child startup before a companion loads. */
+interface PendingInvariantRegistration extends PromiseLike<() => void> {
+  (): void | Promise<void>
 }

-/** Assert that a step-scoped event names the currently open turn and step. */
-function requireOpenStep(trace: SessionTrace, kind: string, turn: number, step: number): void {
-  if (trace.openTurn !== turn || trace.openStep !== step) {
-    throw new InvariantError(
-      `${kind} names turn ${turn}/step ${step} but open is turn ${trace.openTurn}/step ${trace.openStep}`,
-    )
+/** Thrown when a package-owned runtime invariant is violated. */
+export class InvariantError extends Error {
+  /** Stable machine-readable invariant failure code. */
+  readonly code = 'INVARIANT' as const
+  /** Full npm package name that owns the violated invariant. */
+  readonly packageName: string
+
+  /**
+   * Construct a package-attributed invariant failure.
+   * @param packageName - full npm package name that registered the check.
+   * @param message - violated contract, without the standard error prefix.
+   */
+  constructor(packageName: string, message: string) {
+    super(`invariant violated by "${packageName}": ${message}`)
+    this.name = 'InvariantError'
+    this.packageName = packageName
  }
 }

-/** Validate one candidate event without mutating the committed session trace. */
-function validateEvent(trace: SessionTrace, event: SessionEvent): SessionTraceTransition {
-  // seq is strictly monotonic — the spine of replay equivalence. lastSeq
-  // starts at -1, so the first event (seq 0) passes.
-  if (event.seq <= trace.lastSeq) {
-    throw new InvariantError(`seq must strictly increase: saw ${event.seq} after ${trace.lastSeq}`)
-  }
-  let openTurn = trace.openTurn
-  let openStep = trace.openStep
-  let nextTurn = trace.nextTurn
-  let nextStep = trace.nextStep
-  let pendingCalls: SessionTraceTransition['pendingCalls'] = { kind: 'none' }
-
-  // Boundary/step-scoped events have explicit cases; every OTHER event type —
-  // including plugin-added (merge-extensible) SessionEventMap keys — is caught
-  // by the `default` and must be turn-enclosed (the turn-enclosure Agent Note). No assertNever: an
-  // unknown variant is valid, not a compile error.
-  switch (event.type) {
-    case 'turn/start': {
-      if (trace.openTurn !== null) {
-        throw new InvariantError(`turn/start ${event.data.turn} while turn ${trace.openTurn} is still open`)
-      }
-      // Current sessions replay full logs, so numbering starts at 1 and remains
-      // contiguous. If a future compaction/fork stores a partial log, it must
-      // seed `nextTurn` from retained metadata before this check runs.
-      if (event.data.turn !== trace.nextTurn) {
-        throw new InvariantError(`turn/start expected turn ${trace.nextTurn}, got ${event.data.turn}`)
-      }
-      openTurn = event.data.turn
-      nextStep = 1
-      break
-    }
-    case 'turn/end': {
-      if (trace.openTurn !== event.data.turn) {
-        throw new InvariantError(`turn/end ${event.data.turn} does not match open turn ${trace.openTurn}`)
-      }
-      if (trace.openStep !== null) {
-        throw new InvariantError(`turn/end ${event.data.turn} while step ${trace.openStep} is still open`)
-      }
-      openTurn = null
-      nextTurn += 1
-      break
-    }
-    case 'step/start': {
-      if (trace.openTurn !== event.data.turn) {
-        throw new InvariantError(`step/start in turn ${event.data.turn} but open turn is ${trace.openTurn}`)
-      }
-      if (trace.openStep !== null) {
-        throw new InvariantError(`step/start ${event.data.step} while step ${trace.openStep} is still open`)
-      }
-      // Steps are checked under the same full-log assumption as turns above.
-      if (event.data.step !== trace.nextStep) {
-        throw new InvariantError(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`)
-      }
-      openStep = event.data.step
-      break
-    }
-    case 'step/end': {
-      requireOpenStep(trace, 'step/end', event.data.turn, event.data.step)
-      // A result must arrive in the step that issued the call; orphan calls
-      // (a step that errored before its result) do not carry to the next step.
-      pendingCalls = { kind: 'clear' }
-      openStep = null
-      nextStep += 1
-      break
-    }
-    case 'assistant/chunk': {
-      requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step)
-      break
-    }
-    case 'assistant/message': {
-      requireOpenStep(trace, 'assistant/message', event.data.turn, event.data.step)
-      break
-    }
-    case 'tool/call': {
-      requireOpenStep(trace, 'tool/call', event.data.turn, event.data.step)
-      pendingCalls = { kind: 'add', callId: event.data.callId }
-      break
-    }
-    case 'tool/result': {
-      // Session has already validated a provenance-backed content rewrite.
-      // It is durable turn work, not a second execution of the original call.
-      if (event.surfaceOp !== 'append') {
-        if (trace.openTurn === null) {
-          throw new InvariantError(
-            'tool/result surface replacement appended outside any open turn',
-          )
-        }
-        break
-      }
-      requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step)
-      // A result needs a prior matching call in the same step. (The converse
-      // does NOT hold: a call may have no result — a throwing tool-execution
-      // pipeline step ends the turn with no tool/result, which is legal.)
-      const syntheticInterrupted = event.data.isError && event.data.error?.code === 'interrupted'
-      if (!trace.pendingCalls.has(event.data.callId) && !syntheticInterrupted) {
-        throw new InvariantError(`tool/result for ${event.data.callId} with no prior tool/call in this step`)
-      }
-      pendingCalls = { kind: 'delete', callId: event.data.callId }
-      break
-    }
-    // Turn-enclosure (the turn-enclosure Agent Note): EVERY session event not handled by a boundary
-    // case above must sit inside an open turn. The durable session log uses the
-    // turn as its commit/replay boundary (the JSONL backend treats anything
-    // after the last turn/end as a crash tail), so a bare event between turns is
-    // silently dropped on reload. The loop records queued user messages after
-    // turn/start, and an idle agent.inject() wraps its context/message in a
-    // one-shot turn. A `default`
-    // (not an enumerated list) is deliberate: SessionEventMap is
-    // merge-extensible, so a PLUGIN-added event type appended while idle must
-    // also fail here rather than fall through and be dropped on resume.
-    default: {
-      if (trace.openTurn === null) {
-        throw new InvariantError(`${event.type} appended outside any open turn (every event must be turn-enclosed)`)
-      }
-      break
-    }
-  }
-  return {
-    scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
-    pendingCalls,
+declare module 'cordis' {
+  interface Context {
+    invariants: InvariantService
  }
 }

-/** Apply one already-validated transition after its event commits. */
-function applyTransition(trace: SessionTrace, transition: SessionTraceTransition): void {
-  Object.assign(trace, transition.scalars)
-  switch (transition.pendingCalls.kind) {
-    case 'none':
-      break
-    case 'add':
-      trace.pendingCalls.add(transition.pendingCalls.callId)
-      break
-    case 'delete':
-      trace.pendingCalls.delete(transition.pendingCalls.callId)
-      break
-    case 'clear':
-      trace.pendingCalls.clear()
-      break
-    /* v8 ignore next -- validateEvent produces this closed transition union */
-    default:
-      assertNever(transition.pendingCalls, 'session trace pending-call transition')
-  }
+/** Compile and validate one package-filter list. */
+function compilePatterns(field: 'package_allowlist' | 'package_blocklist', values: readonly string[]): RegExp[] {
+  const seen = new Set<string>()
+  return values.map((value) => {
+    if (value.length === 0 || value.trim() !== value) {
+      throw new Error(`invariants: ${field} entries must be non-blank and have no surrounding whitespace`)
+    }
+    if (seen.has(value)) {
+      throw new Error(`invariants: ${field} contains duplicate regex ${JSON.stringify(value)}`)
+    }
+    seen.add(value)
+    try {
+      return new RegExp(value)
+    } catch (cause) {
+      throw new Error(`invariants: ${field} contains invalid regex ${JSON.stringify(value)}`, { cause })
+    }
+  })
 }

-/** Validate and apply one event while rebuilding an already-committed log. */
-function replayEvent(trace: SessionTrace, event: SessionEvent): void {
-  applyTransition(trace, validateEvent(trace, event))
-}
-
-/** Allow an initial observation, idle/running transitions, and terminal disposal; reject repeats and leaving disposed. */
-function checkTransition(from: AgentStatus | undefined, to: AgentStatus): void {
-  if (from === undefined) return
-  if (from === to) {
-    throw new InvariantError(`agent/status repeated ${to} (no-op transition)`)
-  }
-  if (from === 'disposed') {
-    throw new InvariantError(`agent/status left terminal state disposed → ${to}`)
-  }
-}
-
-/**
- * Register the runtime invariants. Contributions are effect-scoped, so
- * disposing the plugin fiber removes all listeners (HMR-safe). On (re-)apply
- * the trace state is rebuilt by replaying each existing session's log, so a
- * hot reload mid-turn does not falsely reject the next event.
- *
- * @param ctx - Cordis context that receives the invariant listeners.
- */
-export function apply(ctx: Context): void {
-  const traces = new WeakMap<Session, SessionTrace>()
-  const stagedTransitions = new WeakMap<SessionEvent, {
-    session: Session
-    trace: SessionTrace
-    transition: SessionTraceTransition
-  }>()
-  // Agent status has no stored history to replay; the first observation after
-  // (re-)apply seeds the baseline, so a reload never produces a false positive.
-  const lastStatus = new WeakMap<Agent, AgentStatus>()
-
-  const freshTrace = (): SessionTrace => ({
-    lastSeq: -1,
-    openTurn: null,
-    openStep: null,
-    nextTurn: 1,
-    nextStep: 1,
-    pendingCalls: new Set(),
+/** Package-owned invariant registry with global and regex-based selection. */
+export class InvariantService extends Service {
+  static Config: Schema<Config> = z.object({
+    enabled: z.boolean().default(true),
+    package_allowlist: z.array(z.string()).default([]),
+    package_blocklist: z.array(z.string()).default([]),
  })

-  /** Build (or rebuild) a session's trace by replaying its whole log. */
-  const seedSession = (session: Session): SessionTrace => {
-    const trace = freshTrace()
-    traces.set(session, trace)
-    for (const event of session.events) {
-      replayEvent(trace, event)
-    }
-    return trace
+  private readonly enabled: boolean
+  private readonly ownerCtx: Context
+  private readonly packageAllowlist: readonly RegExp[]
+  private readonly packageBlocklist: readonly RegExp[]
+  private readonly registrations = new Set<string>()
+
+  /**
+   * Create and install the invariant registry.
+   * @param ctx - Cordis context that owns the service.
+   * @param config - global enablement and package-name regex filters.
+   */
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, 'invariants')
+    this.ownerCtx = ctx
+    this.enabled = config.enabled ?? true
+    this.packageAllowlist = compilePatterns('package_allowlist', config.package_allowlist ?? [])
+    this.packageBlocklist = compilePatterns('package_blocklist', config.package_blocklist ?? [])
  }

-  // Every store-created session (the only kind that emits session/event) is
-  // seeded first — via ctx.sessions.list() at apply or session/created — so the
-  // fallback is a defensive guard, never hit in practice.
-  /* v8 ignore next -- traceFor's fallback: session/event always follows a seed */
-  const traceFor = (session: Session): SessionTrace => traces.get(session) ?? seedSession(session)
+  /** Return whether one full package name passes the configured filters. */
+  private selected(packageName: string): boolean {
+    if (!this.enabled) return false
+    if (this.packageAllowlist.length > 0
+      && !this.packageAllowlist.some(pattern => pattern.test(packageName))) return false
+    return !this.packageBlocklist.some(pattern => pattern.test(packageName))
+  }

-  // Rebuild state for sessions that already exist at (re-)apply time — HMR
-  // reload starts a fresh fiber, and a mid-turn session would otherwise look
-  // like it began with a stray chunk/step-end.
-  for (const session of ctx.sessions.list()) seedSession(session)
-
-  // A newly created session may arrive seeded/forked (the constructor copies
-  // the seed WITHOUT emitting session/event), so replay its log here too.
-  ctx.on('session/created', (session) => { seedSession(session) }, { global: true })
-
-  ctx.on('session/event', (session, event) => {
-    // Session resolves dispatch before committing, so internal/dispatch has
-    // already staged this exact event. A later dispatch veto skips every
-    // session/event callback and therefore leaves the live trace unchanged.
-    const staged = stagedTransitions.get(event)
-    /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
-    if (staged === undefined || staged.session !== session) {
-      throw new InvariantError('session/event reached publication without matching pre-commit validation')
+  /**
+   * Register one package's invariant installer. The package name is reserved
+   * even when filtering disables its checks. Enabled installers run in a child
+   * fiber; failure disposes that fiber and releases the reservation.
+   * @param packageName - full npm package name that owns the contribution.
+   * @param installer - listener or startup-check installer for the child context.
+   * @returns an effect-scoped disposer for the registration.
+   */
+  register(packageName: string, installer: InvariantInstaller): () => void {
+    if (packageName.length === 0 || packageName.trim() !== packageName || /\s/.test(packageName)) {
+      throw new Error('invariants: packageName must be non-blank and contain no whitespace')
    }
-    stagedTransitions.delete(event)
-    applyTransition(staged.trace, staged.transition)
-  }, { global: true })
-
-  ctx.on('agent/status', (agent, status) => {
-    checkTransition(lastStatus.get(agent), status)
-    lastStatus.set(agent, status)
-  }, { global: true })
-
-  // --- Scoped-dispatch invariants (the agent-scoping seam) ---------------
-  //
-  // Every scope-filtered event family must dispatch with a scope carrier
-  // (scopeTarget) whose key IS the subject the event's arguments name —
-  // a dispatch without one silently reverts that event to global delivery
-  // (agent-scoped listeners over-hear foreign agents), and a mis-keyed one
-  // delivers to the wrong agent's listeners. `internal/dispatch` fires
-  // synchronously before listener delivery, so a violation throws at the
-  // dispatching call site. The generated table maps each family to the unique
-  // payload path whose Program type matches the real scopeTarget routing key;
-  // `null` means the key is external to the payload, so only carrier presence
-  // can be asserted.
-  ctx.on('internal/dispatch', (_mode, name, args, thisArg) => {
-    const subjectOf = scopedSubjectResolverFor(name)
-    if (subjectOf === undefined) return
-    if (!isScopeCarrier(thisArg)) {
-      throw new InvariantError(
-        `"${name}" is a scope-filtered event but was dispatched without a scope carrier — `
-        + 'pass scopeTarget(base, subject) as the dispatch thisArg (agent events: use agentEvents(ctx, agent))')
-    }
-    if (subjectOf !== null && carrierKeyOf(thisArg) !== subjectOf(args)) {
-      throw new InvariantError(
-        `"${name}" was dispatched with a scope carrier keyed to a DIFFERENT subject than its arguments name — `
-        + 'the carrier key and the event\'s subject must be the same object (use agentEvents(ctx, agent))')
-    }
-    if (name === 'session/event') {
-      const [session, event] = args as [Session, SessionEvent]
-      const trace = traceFor(session)
-      const transition = validateEvent(trace, event)
-      // The exact event identity reaches the contained post-commit listener.
-      // A later internal/dispatch listener may still veto; because validation
-      // is pure, abandoning this weakly keyed transition does not advance the
-      // committed trace or retain the session.
-      stagedTransitions.set(event, { session, trace, transition })
-    }
-  }, { global: true })
-
-  // Request-reconstruction cross-check (the reconstructability Agent Note): a
-  // loop-built request — frozen envelope + live sessionId is the marker; a
-  // hand-built one-shot (compaction summarize) is unfrozen and skipped — must
-  // be EXACTLY what the session log reconstructs:
-  //
-  // - messages: the folded header's session prefix (messagePrefix — the
-  //   `agent/session-prefix` product, logged on the header because no
-  //   session event carries it) followed by the
-  //   derivation over the log prefix strictly before the in-flight step's
-  //   `step/start` (the reconstruction boundary). The derivation is compared
-  //   against a FRESH Session built over that prefix — the same projection
-  //   code with zero shared state, so the live cache under test cannot vouch
-  //   for itself. Boundary-correct by construction: content appended after
-  //   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
-  //   dispatch, so the fold already covers this request.
-  //
-  // Registered with `prepend: true` so a short-circuiting llm/stream listener
-  // (the replay adapter returns its chunks without calling next()) cannot
-  // silence the check by registering first. Prepend beats APPEND-registered
-  // listeners only — two prepended listeners have no defined mutual order
-  // (cordis unshift) — which is fine: correctness rests on the seq-bounded
-  // fold below, never on listener timing.
-  ctx.on('llm/stream', (options: GenerateOptions, next) => {
-    if (options.sessionId === undefined || !Object.isFrozen(options)) return next()
-    // GenerateOptions types sessionId as Branded<'SessionId'>, which IS
-    // SessionId (dsh-llm cannot import it without a cycle) — no cast needed.
-    const session = ctx.sessions.get(options.sessionId)
-    if (!session) return next()
-    if (!Object.isFrozen(options.messages)) {
-      throw new InvariantError('a loop-built request must carry a frozen messages array')
+    if (this.registrations.has(packageName)) {
+      throw new Error(`invariants: package "${packageName}" is already registered`)
    }

-    const events = session.events
-    // seq === index (checked above), so the last step/start's seq bounds the
-    // prefix directly. The in-flight step's step/start is necessarily the
-    // last one: the loop cannot open another step while this call streams.
-    let boundary = -1
-    for (let i = events.length - 1; i >= 0; i -= 1) {
-      if (events[i]?.type === 'step/start') {
-        boundary = i
-        break
-      }
-    }
-    if (boundary === -1) {
-      throw new InvariantError('a loop-built request with no step/start in its session log')
-    }
-    const header = foldRequestHeader(events)
-    if (header === undefined) {
-      throw new InvariantError('a loop-built request with no request/header event in its session log')
-    }
-    const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary)))
-    // The reconstruction equation: the folded header's session prefix, then
-    // the boundary derivation — the loop
-    // logs the header event BEFORE dispatch, so the fold already covers this
-    // request's prefix. JSON equality is sound here: both sides are
-    // structuredClones produced by the same projection/build code path, so key
-    // insertion order matches when the values do.
-    const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
-    if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
-      throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
-    }
+    // Service method tracing binds `this.ctx` to the caller. This explicit
+    // origin keeps registrations and their child fibers owned by the service;
+    // companion disposal is covered independently by the returned disposer.
+    const ctx = this.ownerCtx
+    const registrations = this.registrations
+    registrations.add(packageName)

-    const headerMatches = options.model === header.config.model
-      && options.system === header.system
-      && options.temperature === header.config.temperature
-      && options.maxTokens === header.config.maxTokens
-      && JSON.stringify(options.stop) === JSON.stringify(header.config.stop)
-      && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? [])
-    if (!headerMatches) {
-      throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the folded request header`)
+    let registration: PendingInvariantRegistration
+    try {
+      registration = ctx.effect(async () => {
+        if (!this.selected(packageName)) {
+          return () => {
+            registrations.delete(packageName)
+          }
+        }
+
+        const installInvariant = (childCtx: Context) => (
+          installer(childCtx, (message): never => {
+            throw new InvariantError(packageName, message)
+          })
+        )
+        try {
+          const child = ctx.plugin(installer.inject === undefined
+            ? installInvariant
+            : Object.assign(installInvariant, { inject: installer.inject }))
+
+          try {
+            await child
+          } catch (error) {
+            await child.dispose()
+            throw error
+          }
+
+          return async () => {
+            try {
+              await child.dispose()
+            } finally {
+              registrations.delete(packageName)
+            }
+          }
+        } catch (error) {
+          registrations.delete(packageName)
+          throw error
+        }
+      }, `invariants.register(${JSON.stringify(packageName)})`)
+    } catch (error) {
+      registrations.delete(packageName)
+      throw error
    }
-    return next()
-  }, { global: true, prepend: true })
+    // Cordis attaches setup thenability and async teardown to this callable;
+    // the service seam intentionally exposes only the conventional disposer.
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- the extra runtime shape stays private.
+    return registration
+  }
 }
+
+export default InvariantService
--- a/packages/support/invariants/src/invariant.ts
+++ b/packages/support/invariants/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-invariants`.
+ * @module @deepseek-ai/dsh-invariants/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-invariants'
+
+/** Cordis companion plugin name. */
+export const name = 'invariants-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: registration ownership and child lifecycle are the service's mutation
+ * boundary itself; observing them from the same registry would only duplicate its implementation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/support/invariants/src/scoped-events.generated.ts
+++ b/packages/support/invariants/src/scoped-events.generated.ts
@@ -1,71 +0,0 @@
-/**
- * Generated scoped-event routing-subject resolvers for dsh-invariants.
- * Do not edit by hand; run `pnpm run gen-scoped-events`.
- *
- * @module @deepseek-ai/dsh-invariants/scoped-events.generated
- */
-
-import type { Events } from 'cordis'
-import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type {} from '@deepseek-ai/dsh-agent'
-import type {} from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-subagent'
-import type {} from '@deepseek-ai/dsh-system-prompt'
-import type {} from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-user-approval'
-
-type ScopedEventName = {
-  [K in keyof Events]: ThisParameterType<Events[K]> extends Scoped<object> ? K : never
-}[keyof Events]
-
-type ScopedSubjectResolver = (args: readonly unknown[]) => unknown
-
-function adapt<K extends ScopedEventName>(
-  resolver: (args: Parameters<Events[K]>) => unknown,
-): ScopedSubjectResolver {
-  return args => resolver(args as Parameters<Events[K]>)
-}
-
-const scopedSubjectResolvers = Object.freeze({
-  'agent/created': adapt<'agent/created'>(args => args[0]),
-  'agent/disposed': adapt<'agent/disposed'>(args => args[0]),
-  'agent/error': adapt<'agent/error'>(args => args[0]),
-  'agent/post-step': adapt<'agent/post-step'>(args => args[0]),
-  'agent/pre-step': adapt<'agent/pre-step'>(args => args[0]),
-  'agent/prompt-submit': adapt<'agent/prompt-submit'>(args => args[0]),
-  'agent/queued': adapt<'agent/queued'>(args => args[0]),
-  'agent/request': adapt<'agent/request'>(args => args[0]),
-  'agent/request-error': adapt<'agent/request-error'>(args => args[0]),
-  'agent/session-prefix': adapt<'agent/session-prefix'>(args => args[0]),
-  'agent/session-start': adapt<'agent/session-start'>(args => args[0]),
-  'agent/status': adapt<'agent/status'>(args => args[0]),
-  'agent/step-result': adapt<'agent/step-result'>(args => args[0]),
-  'agent/turn-continuation': adapt<'agent/turn-continuation'>(args => args[0]),
-  'agent/turn-stop': adapt<'agent/turn-stop'>(args => args[0]),
-  'approval/request': adapt<'approval/request'>(args => args[0].agent),
-  'session/created': null,
-  'session/disposed': null,
-  'session/event': null,
-  'session/flush': null,
-  'subagent/end': null,
-  'subagent/start': null,
-  'system-prompt/assemble': adapt<'system-prompt/assemble'>(args => args[1].scope),
-  'tools/execute': adapt<'tools/execute'>(args => args[0].agent),
-  'tools/post-execute': adapt<'tools/post-execute'>(args => args[0].agent),
-  'tools/pre-execute': adapt<'tools/pre-execute'>(args => args[0].agent),
-  'tools/result': adapt<'tools/result'>(args => args[0].agent),
-} as const satisfies Readonly<Record<ScopedEventName, ScopedSubjectResolver | null>>)
-
-const scopedSubjectResolverIndex: Readonly<Record<string, ScopedSubjectResolver | null>> = scopedSubjectResolvers
-
-/**
- * Resolve the routing key named by one scoped event payload. A null
- * resolver means the payload cannot expose its external routing key, so the
- * invariant checks carrier presence only.
- * @param event - runtime Cordis event name.
- * @returns the generated subject resolver, null for presence-only,
- *   or undefined when the event is not scope-filtered.
- */
-export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {
-  return scopedSubjectResolverIndex[event]
-}
--- a/packages/support/invariants/tests/invariants.spec.ts
+++ b/packages/support/invariants/tests/invariants.spec.ts
@@ -1,964 +0,0 @@
-import { describe, expect, it, vi } from 'vitest'
-import { Context } from 'cordis'
-import { createScope, scopeTarget } from '@deepseek-ai/dsh-scope'
-import { CallId } from '@deepseek-ai/dsh-llm'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
-import { InvariantError } from '@deepseek-ai/dsh-invariants'
-
-/** A Context with the session store and the invariants plugin registered. */
-async function setup() {
-  const ctx = new Context()
-  await ctx.plugin(SessionStore)
-  const fiber = await ctx.plugin(Invariants)
-  return { ctx, fiber }
-}
-
-/** A minimal Agent stand-in for agent/status emission. */
-function mockAgent(id: string): Agent {
-  return { id } as unknown as Agent
-}
-
-describe('session-log invariants', () => {
-  it('keeps pre-commit staging and post-commit application global when mounted under a scope', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    let scopedCtx!: Context
-    await ctx.plugin(Object.assign((inner: Context) => {
-      scopedCtx = createScope(inner, {}).ctx
-    }, { inject: ['sessions'] }))
-    await scopedCtx.plugin(Invariants)
-    const globalSession = ctx.sessions.create(SessionId('global-under-scoped-invariants'))
-
-    expect(() => {
-      globalSession.append('turn/start', {
-        turn: 1,
-        trigger: { kind: 'message', source: { kind: 'user' } },
-      })
-      globalSession.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    }).not.toThrow()
-  })
-
-  it('accepts a well-formed turn/step/tool sequence', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-      session.append('step/start', { turn: 1, step: 1 })
-      session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' }] }, { surfaceOp: 'append' })
-      session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
-      session.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
-      session.append('step/end', { turn: 1, step: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    }).not.toThrow()
-  })
-
-  it('does not advance the trace when a later internal-dispatch listener vetoes', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create(SessionId('dispatch-veto-rollback'))
-    let veto = true
-    ctx.on('internal/dispatch', (_mode, name) => {
-      if (name !== 'session/event' || !veto) return
-      veto = false
-      throw new Error('later dispatch veto')
-    })
-
-    expect(() => session.append('turn/start', {
-      turn: 1,
-      trigger: { kind: 'message', source: { kind: 'user' } },
-    })).toThrow('later dispatch veto')
-    expect(session.events).toEqual([])
-
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    }).not.toThrow()
-    expect(session.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-  })
-
-  it('applies the committed transition after a prepended observer throws', async () => {
-    const { ctx } = await setup()
-    const warnings: string[] = []
-    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
-    const session = ctx.sessions.create(SessionId('postcommit-peer'))
-    ctx.on('session/event', () => { throw new Error('hostile observer') }, { prepend: true })
-
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    }).not.toThrow()
-    expect(session.events.map(event => event.type)).toEqual(['turn/start', 'turn/end'])
-    expect(warnings).toEqual([
-      'session "postcommit-peer": session/event listener threw: Error: hostile observer',
-      'session "postcommit-peer": session/event listener threw: Error: hostile observer',
-    ])
-  })
-
-  it('rejects a non-monotonic seq (replay spine)', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    // Session.append enforces seq-contiguity at the source, so drive the
-    // invariants seq check directly via session/event with a regressing seq.
-    ctx.emit(scopeTarget(session, undefined), 'session/event', session, { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } } as never)
-    expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, { type: 'turn/end', seq: 0, time: 2, data: { turn: 1, reason: { kind: 'completed' } } } as never) })
-      .toThrow(/seq must strictly increase/)
-  })
-
-  it('rejects a turn/start while another turn is open', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
-      .toThrow(/turn 1 is still open/)
-  })
-
-  it('rejects a turn/end that does not match the open turn', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('turn/end', { turn: 2, reason: { kind: 'completed' } }))
-      .toThrow(/does not match open turn 1/)
-  })
-
-  it('rejects a step/start outside its declared turn', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('step/start', { turn: 2, step: 1 })).toThrow(/open turn is 1/)
-  })
-
-  it('rejects a step/end that does not match the open step', 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('step/end', { turn: 1, step: 2 })).toThrow(/open is turn 1\/step 1/)
-  })
-
-  it('rejects an assistant/chunk outside an open step', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'x' } }))
-      .toThrow(/open is turn 1\/step null/)
-  })
-
-  it('rejects a message event appended outside any open turn (turn-enclosure)', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    // No turn open: every message-bearing event must be turn-enclosed (the turn-enclosure Agent Note).
-    expect(() => session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' }))
-      .toThrow(/outside any open turn/)
-    expect(() => session.append('context/message', { content: [{ type: 'text', text: 'ctx' }], source: { kind: 'user' } }, { surfaceOp: 'append' }))
-      .toThrow(/outside any open turn/)
-  })
-
-  it('rejects steering and plugin-added events appended outside any open turn', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    // steering/message is turn-scoped: outside a turn it would land past the
-    // commit boundary and be dropped on resume (the turn-enclosure Agent Note).
-    expect(() => session.append('steering/message', { turn: 1, content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }, { surfaceOp: 'append' }))
-      .toThrow(/outside any open turn/)
-    // A PLUGIN-added (merge-extensible) event type is caught by the default too.
-    // Cast through `any`: 'compaction/marker' is not in SessionEventType (it's
-    // merge-extensible), so the typed append() won't accept it. The test verifies
-    // the runtime default-branch turn-enclosure check.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-return
-    expect(() => (session.append as any)('compaction/marker', { foo: 'bar' }))
-      .toThrow(/outside any open turn/)
-  })
-
-  it('accepts message events once a turn is open', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' }))
-      .not.toThrow()
-  })
-
-  it('rejects a tool/result with no prior tool/call', 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('tool/result', { turn: 1, step: 1, callId: CallId('ghost'), content: [], isError: false }, { surfaceOp: 'append' }))
-      .toThrow(/no prior tool\/call/)
-  })
-
-  it('keeps fresh tool-result appends open-step and pending-call checked', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => session.append('tool/result', {
-      turn: 1,
-      step: 1,
-      callId: CallId('closed'),
-      content: [],
-      isError: false,
-    }, { surfaceOp: 'append' })).toThrow(/open is turn 1\/step null/)
-  })
-
-  it('allows a synthetic interrupted tool/result from crash repair without a prior tool/call event', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('step/start', { turn: 1, step: 1 })
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [
-        { type: 'tool-call', id: CallId('crashed'), name: 'bash', arguments: '{}' },
-      ] }, { surfaceOp: 'append' })
-      session.append('tool/result', {
-        turn: 1,
-        step: 1,
-        callId: CallId('crashed'),
-        content: [{ type: 'text', text: 'interrupted' }],
-        isError: true,
-        error: { name: 'InterruptedError', code: 'interrupted' },
-      }, { surfaceOp: 'append' })
-      session.append('step/end', { turn: 1, step: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
-    }).not.toThrow()
-  })
-
-  it('allows a tool/call with no matching tool/result (thrown waterfall ends the step)', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('step/start', { turn: 1, step: 1 })
-      session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
-      session.append('step/end', { turn: 1, step: 1 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } })
-    }).not.toThrow()
-  })
-
-  it('holds seeded sessions to the contract on session/created', async () => {
-    const { ctx } = await setup()
-    // A seq-contiguous, serializable seed (so it passes Session's constructor
-    // validation) that nonetheless violates turn nesting — a second turn/start
-    // while the first turn is still open — must be rejected by the invariants
-    // plugin when it replays the seed on session/created.
-    const badSeed = [
-      { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-      { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-    ]
-    expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(InvariantError)
-  })
-
-  it('tracks turns per session independently', async () => {
-    const { ctx } = await setup()
-    const a = ctx.sessions.create(SessionId('a'))
-    const b = ctx.sessions.create(SessionId('b'))
-    a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    // b is a fresh session — its own turn/start must not see a's open turn.
-    expect(() => b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })).not.toThrow()
-  })
-
-  it('accepts multiple steps in a turn and consecutive turns', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    expect(() => {
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('step/start', { turn: 1, step: 1 })
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
-      session.append('step/end', { turn: 1, step: 1 })
-      session.append('step/start', { turn: 1, step: 2 })
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 2, content: [] }, { surfaceOp: 'append' })
-      session.append('step/end', { turn: 1, step: 2 })
-      session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-      session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
-    }).not.toThrow()
-  })
-
-  it('rejects a skipped turn number', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    expect(() => session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }))
-      .toThrow(/expected turn 2, got 3/)
-  })
-
-  it('rejects a skipped step number within a turn', 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 })
-    session.append('step/end', { turn: 1, step: 1 })
-    expect(() => session.append('step/start', { turn: 1, step: 3 }))
-      .toThrow(/expected step 2 in turn 1, got 3/)
-  })
-
-  it('rejects a turn/end while a step is still open', 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('turn/end', { turn: 1, reason: { kind: 'completed' } }))
-      .toThrow(/while step 1 is still open/)
-  })
-
-  it('rejects a step/start while a step is still open', 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('step/start', { turn: 1, step: 2 })).toThrow(/while step 1 is still open/)
-  })
-
-  it('rejects a tool/result satisfying a call from a previous step', 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 })
-    session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
-    // step ends with the call unresolved — pendingCalls is cleared.
-    session.append('step/end', { turn: 1, step: 1 })
-    session.append('step/start', { turn: 1, step: 2 })
-    expect(() => session.append('tool/result', { turn: 1, step: 2, callId: CallId('c1'), content: [], isError: false }, { surfaceOp: 'append' }))
-      .toThrow(/no prior tool\/call in this step/)
-  })
-
-  it('rejects an assistant/message naming the wrong step', 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: 2, content: [] }, { surfaceOp: 'append' }))
-      .toThrow(/open is turn 1\/step 1/)
-  })
-})
-
-describe('HMR state rebuild', () => {
-  it('rebuilds trace state for a session that exists at (re-)apply time', async () => {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    const first = await ctx.plugin(Invariants)
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('step/start', { turn: 1, step: 1 })
-    await first.dispose()
-
-    // Re-apply mid-step: the new fiber must reconstruct the open boundaries from the log.
-    await ctx.plugin(Invariants)
-    expect(() => session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } }))
-      .not.toThrow()
-    // Rebuild must not disable later violations.
-    expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
-      .toThrow(/turn 1 is still open/)
-  })
-})
-
-describe('session immutability', () => {
-  it('always freezes appended event data without the invariants plugin', () => {
-    const session = new Session(SessionId('appended'))
-    const event = session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(Object.isFrozen(event)).toBe(true)
-    expect(Object.isFrozen(event.data)).toBe(true)
-    expect(Object.isFrozen(event.data.content)).toBe(true)
-    expect(Object.isFrozen(event.data.content[0])).toBe(true)
-    expect(Object.isFrozen(session.events)).toBe(true)
-    expect(() => { (event.data.content[0] as { text: string }).text = 'HACKED' }).toThrow()
-  })
-
-  it('always freezes seeded events without the invariants plugin', () => {
-    const seed = [
-      { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-      { type: 'user/message' as const, seq: 1, time: 0, data: { content: [{ type: 'text' as const, text: 'seeded' }], source: { kind: 'user' as const } }, surfaceOp: 'append' as const },
-    ]
-    const session = new Session(SessionId('seeded'), seed)
-    expect(Object.isFrozen(seed[0])).toBe(false)
-    expect(Object.isFrozen(session.events)).toBe(true)
-    expect(Object.isFrozen(session.events[0])).toBe(true)
-    expect(Object.isFrozen(session.events[0]?.data)).toBe(true)
-    expect(Object.isFrozen(session.events[1]?.data)).toBe(true)
-  })
-
-  it('snapshots and freezes descendants of a shallow-frozen caller value', () => {
-    const session = new Session(SessionId('shallow-frozen'))
-    const innerContent: { type: 'text'; text: string }[] = [{ type: 'text', text: 'inner' }]
-    const block = Object.freeze({ type: 'tool-result' as const, toolCallId: CallId('c1'), content: innerContent, isError: false })
-    const event = session.append('user/message', { content: [block], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    const logged = event.data.content[0] as { content: { type: 'text'; text: string }[] }
-    expect(Object.isFrozen(innerContent)).toBe(false)
-    expect(Object.isFrozen(logged.content)).toBe(true)
-    expect(Object.isFrozen(logged.content[0])).toBe(true)
-    innerContent[0]!.text = 'caller mutation'
-    expect(logged.content[0]!.text).toBe('inner')
-    expect(() => { logged.content.push({ type: 'text', text: 'mutation' }) }).toThrow()
-  })
-})
-
-describe('agent status invariants', () => {
-  it('accepts legal transitions: idle→running→idle and →disposed', async () => {
-    const { ctx } = await setup()
-    const agent = mockAgent('a1')
-    expect(() => {
-      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
-      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
-      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
-      ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
-    }).not.toThrow()
-  })
-
-  it('accepts running→disposed', async () => {
-    const { ctx } = await setup()
-    const agent = mockAgent('a2')
-    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed') }).not.toThrow()
-  })
-
-  it('rejects a no-op transition', async () => {
-    const { ctx } = await setup()
-    const agent = mockAgent('a3')
-    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running') }).toThrow(/no-op transition/)
-  })
-
-  it('rejects leaving the terminal disposed state', async () => {
-    const { ctx } = await setup()
-    const agent = mockAgent('a4')
-    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle') }).toThrow(/left terminal state disposed/)
-  })
-
-  it('tracks status per agent independently', async () => {
-    const { ctx } = await setup()
-    const a = mockAgent('a5')
-    const b = mockAgent('b5')
-    ctx.emit(scopeTarget(a, a), 'agent/status', a, 'running')
-    // b's first observation is independent of a.
-    expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow()
-  })
-})
-
-describe('HMR safety', () => {
-  it('removes all listeners when the plugin fiber is disposed', async () => {
-    const { ctx, fiber } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-
-    await fiber.dispose()
-
-    // After disposal the plugin's assertions are gone, so an event that would
-    // violate the open-turn rule passes. Session still owns immutability.
-    const event = session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(Object.isFrozen(event)).toBe(true)
-    // A no-op status transition no longer throws either.
-    const agent = mockAgent('hmr')
-    ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle') }).not.toThrow()
-  })
-
-  it('InvariantError carries a stable code', () => {
-    const err = new InvariantError('seq must strictly increase')
-    expect(err).toBeInstanceOf(Error)
-    expect(err.name).toBe('InvariantError')
-    expect(err.code).toBe('INVARIANT')
-    expect(err.message).toBe('invariant violated: seq must strictly increase')
-  })
-
-  it('does not leak listeners across dispose', async () => {
-    const { ctx, fiber } = await setup()
-    await fiber.dispose()
-    const spy = vi.fn()
-    ctx.on('session/event', spy)
-    const session = ctx.sessions.create()
-    session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    // The spy proves events still flow after plugin disposal. Session, not the
-    // disposed listener, freezes the accepted record.
-    expect(spy).toHaveBeenCalledOnce()
-    expect(Object.isFrozen(session.events[0])).toBe(true)
-  })
-})
-
-describe('surface contract under the invariants composition', () => {
-  async function toolResultRewriteFixture(openRewriteTurn = true) {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const unrelated = session.append('user/message', {
-      content: [{ type: 'text', text: 'request' }],
-      source: { kind: 'user' },
-    }, { surfaceOp: 'append' })
-    session.append('step/start', { turn: 1, step: 1 })
-    session.append('tool/call', {
-      turn: 1,
-      step: 1,
-      callId: CallId('rewrite'),
-      name: 'echo',
-      arguments: '{}',
-    })
-    const originalData = {
-      turn: 1,
-      step: 1,
-      callId: CallId('rewrite'),
-      content: [{ type: 'text' as const, text: 'original' }],
-      isError: true,
-      error: { name: 'ExitError', code: 'EXIT_1' },
-      meta: { presentation: { kind: 'terminal', output: 'full output' } },
-      futureField: { nested: ['preserve', 1] },
-    }
-    const original = session.append('tool/result', originalData, { surfaceOp: 'append' })
-    session.append('step/end', { turn: 1, step: 1 })
-    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
-    if (openRewriteTurn) {
-      session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
-    }
-    return { session, unrelated, original }
-  }
-
-  it('accepts well-formed surface metadata', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    // Events must be turn-enclosed and step-scoped events need an open step.
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('step/start', { turn: 1, step: 1 })
-    expect(() => {
-      session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
-    }).not.toThrow()
-  })
-
-  it('accepts replace surface op', 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 })
-    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [2] })
-    // no throw — well-formed replace op
-  })
-
-  it('treats a provenance-backed tool-result replacement as a turn-enclosed rewrite', async () => {
-    const { session, original } = await toolResultRewriteFixture()
-
-    expect(() => session.append('tool/result', {
-      ...original.data,
-      content: [{ type: 'text', text: 'pruned' }],
-    }, {
-      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
-      sourceEventSeqs: [original.seq],
-    })).not.toThrow()
-  })
-
-  it('rejects a tool-result replacement outside a turn', async () => {
-    const { session, original } = await toolResultRewriteFixture(false)
-
-    expect(() => session.append('tool/result', {
-      ...original.data,
-      content: [{ type: 'text', text: 'pruned' }],
-    }, {
-      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
-      sourceEventSeqs: [original.seq],
-    })).toThrow(/outside any open turn/)
-  })
-
-  it('rejects a tool-result replacement targeting an unrelated current node', async () => {
-    const { session, unrelated, original } = await toolResultRewriteFixture()
-    expect(() => session.append('tool/result', {
-      ...original.data,
-      content: [{ type: 'text', text: 'forged' }],
-    }, {
-      surfaceOp: { op: 'replace', start: unrelated.seq, end: unrelated.seq },
-      sourceEventSeqs: [unrelated.seq],
-    })).toThrow(/must target a current tool\/result/)
-  })
-
-  it('rejects a multi-node tool-result replacement even with complete provenance', async () => {
-    const { session, unrelated, original } = await toolResultRewriteFixture()
-    expect(() => session.append('tool/result', {
-      ...original.data,
-      content: [{ type: 'text', text: 'forged' }],
-    }, {
-      surfaceOp: { op: 'replace', start: unrelated.seq, end: original.seq },
-      sourceEventSeqs: [unrelated.seq, original.seq],
-    })).toThrow(/must rewrite exactly one current node/)
-  })
-
-  it.each([
-    ['callId', { callId: CallId('forged') }],
-    ['turn', { turn: 2 }],
-    ['step', { step: 2 }],
-    ['error', { error: { name: 'ExitError', code: 'DIFFERENT' } }],
-    ['meta', { meta: { presentation: { kind: 'generic' } } }],
-    ['future data', { futureField: { nested: ['changed'] } }],
-  ])('rejects a content rewrite with altered %s', async (_label, altered) => {
-    const { session, original } = await toolResultRewriteFixture()
-    expect(() => session.append('tool/result', {
-      ...original.data,
-      ...altered,
-      content: [{ type: 'text', text: 'pruned' }],
-    }, {
-      surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
-      sourceEventSeqs: [original.seq],
-    })).toThrow(/may change only content/)
-  })
-
-  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: [] })
-    }).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 () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1, 1] })
-    }).toThrow(/must not contain duplicates/)
-  })
-
-  it('rejects sourceEventSeqs referencing the event itself (self-reference)', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) // seq 0
-    // The next event is seq 1. Referencing its own seq fails on "must reference
-    // earlier events" (the check order is: earlier first, then unknown).
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
-    }).toThrow(/must reference earlier/)
-  })
-
-  it('accepts sourceEventSeqs referencing a valid earlier event', async () => {
-    // Session seqs are contiguous, so every non-negative ref below the current
-    // seq necessarily names an existing earlier event.
-    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 })
-    // seqs so far: 0, 1. The next event at seq 2 references seq 1 → valid.
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [1] })
-    }).not.toThrow()
-  })
-
-  it('rejects sourceEventSeqs referencing a far-future seq', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create()
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [99] })
-    }).toThrow(/must reference earlier/)
-  })
-
-  it('rejects a replace whose start is positioned after its end on the surface', 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 })
-    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
-    // Reversed range: start seq 3 is at a later surface position than end seq 2.
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 3, end: 2 }, sourceEventSeqs: [2, 3] })
-    }).toThrow(/is after end seq 2/)
-  })
-
-  it('rejects a replace whose sourceEventSeqs omits a shadowed surface node', 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 })
-    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 shadows surface nodes [2, 3] but records provenance for only [2].
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'sum' }] }, { surfaceOp: { op: 'replace', start: 2, end: 3 }, sourceEventSeqs: [2] })
-    }).toThrow(/must include every shadowed surface node; missing 3/)
-  })
-
-  it('accepts a replace whose sourceEventSeqs covers every shadowed surface node', 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 })
-    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
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'sum' }] }, { surfaceOp: { op: 'replace', start: 2, end: 3 }, sourceEventSeqs: [2, 3] })
-    }).not.toThrow()
-  })
-
-  it('rejects a replace naming a start seq that is not on the surface', 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 })
-    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
-    // seq 1 (step/start) is a real earlier event but never entered the surface.
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] })
-    }).toThrow(/start seq 1 not found in surface/)
-  })
-
-  it('rejects a replace naming an end seq that is not on the surface', 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 })
-    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
-    // start (2) is on the surface but end (99) never entered it.
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 99 }, sourceEventSeqs: [2] })
-    }).toThrow(/end seq 99 not found in surface/)
-  })
-
-  it('rejects a replace whose range is reversed in surface position after a prior replace reordered it', 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 })
-    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 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).
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 3, end: 4 }, sourceEventSeqs: [3, 4] }) // seq 5
-    }).toThrow(/is after end seq 4/)
-  })
-
-  it('accepts a replace whose start seq exceeds its end seq when the surface position order is valid', 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 })
-    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 becomes [4, 3], so the
-    // head seq (4) is numerically GREATER than the tail seq (3): the surface is
-    // not seq-ordered. A replace spanning start=4 (pos 0) … end=3 (pos 1) is
-    // valid positionally and must be accepted even though start seq > end seq.
-    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
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 4, end: 3 }, sourceEventSeqs: [4, 3] }) // seq 5
-    }).not.toThrow()
-  })
-
-  it('rejects a replace that omits sourceEventSeqs entirely', 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 })
-    session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
-    // A replace with no sourceEventSeqs records no provenance for the node it shadows.
-    expect(() => {
-      session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: { op: 'replace', start: 2, end: 2 } })
-    }).toThrow(/must include every shadowed surface node; missing 2/)
-  })
-
-  it('catches an incomplete-provenance replace on the load/seed path', async () => {
-    const { ctx } = await setup()
-    const badSeed = [
-      { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-      { type: 'step/start' as const, seq: 1, time: 0, data: { turn: 1, step: 1 } },
-      { type: 'user/message' as const, seq: 2, time: 0, data: { content: [{ type: 'text' as const, text: 'a' }], source: { kind: 'user' as const } }, surfaceOp: 'append' as const },
-      { type: 'user/message' as const, seq: 3, time: 0, data: { content: [{ type: 'text' as const, text: 'b' }], source: { kind: 'user' as const } }, surfaceOp: 'append' as const },
-      { type: 'assistant/message' as const, seq: 4, time: 0, data: { turn: 1, step: 1, content: [{ type: 'text' as const, text: 'sum' }], provenance: { provider: 'mock', model: 'mock' } }, surfaceOp: { op: 'replace' as const, start: 2, end: 3 }, sourceEventSeqs: [2] },
-    ]
-    expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(/must include every shadowed surface node; missing 3/)
-  })
-
-})
-
-describe('request-reconstruction cross-check (llm/stream)', () => {
-  /** Session with a boundary: one derivable user message, an open step, and the header event the loop would have logged. */
-  async function requestSetup() {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create(SessionId('req-check'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    const boundary = session.deriveMessages()
-    session.append('step/start', { turn: 1, step: 1 })
-    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
-    return { ctx, session, boundary }
-  }
-
-  /** Dispatch the llm/stream waterfall with a stub core, collecting the check's verdict. */
-  function dispatch(ctx: Context, options: unknown): void {
-    // The invariants listener runs synchronously at dispatch time (its checks
-    // precede next()); the stub core just yields nothing.
-    void ctx.waterfall('llm/stream', options as never, () => (async function* () {})() as never)
-  }
-
-  it('passes a frozen request that equals the boundary derivation + the folded header', async () => {
-    const { ctx, session, boundary } = await requestSetup()
-    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
-    expect(() => { dispatch(ctx, options) }).not.toThrow()
-  })
-
-  it('is boundary-correct: content logged after step/start is legitimately absent from this request', async () => {
-    const { ctx, session, boundary } = await requestSetup()
-    // An agent/request-window inject: lands in the log after the boundary,
-    // belongs to the NEXT request. A current-surface comparison would
-    // false-fire here; the seq-bounded rebuild must not.
-    session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
-    const options = Object.freeze({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
-    expect(() => { dispatch(ctx, options) }).not.toThrow()
-  })
-
-  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', { 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()
-    // …a request that DROPPED the logged prefix diverges…
-    const bare = Object.freeze({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })
-    expect(() => { dispatch(ctx, bare) }).toThrow(/diverges from the boundary derivation/)
-    // …and so does one that misplaced it (prefix sent after the history).
-    const misplaced = Object.freeze({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })
-    expect(() => { dispatch(ctx, misplaced) }).toThrow(/diverges from the boundary derivation/)
-  })
-
-  it('rejects a frozen request whose messages diverge from the boundary derivation', async () => {
-    const { ctx, session, boundary } = await requestSetup()
-    const messages = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }]
-    const options = Object.freeze({ model: 'm', messages: Object.freeze(messages), sessionId: session.id })
-    expect(() => { dispatch(ctx, options) }).toThrow(/diverges from the boundary derivation/)
-  })
-
-  it('rejects a frozen request whose fields diverge from the folded header', async () => {
-    const { ctx, session, boundary } = await requestSetup()
-    const options = Object.freeze({ model: 'other', messages: Object.freeze(boundary), sessionId: session.id })
-    expect(() => { dispatch(ctx, options) }).toThrow(/diverges from the folded request header/)
-  })
-
-  it('rejects a loop-built request with no header event or no step/start in its log', async () => {
-    const { ctx } = await setup()
-    const session = ctx.sessions.create(SessionId('req-bare'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    const bare = Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: session.id })
-    expect(() => { dispatch(ctx, bare) }).toThrow(/no step\/start/)
-
-    session.append('step/start', { turn: 1, step: 1 })
-    expect(() => { dispatch(ctx, bare) }).toThrow(/no request\/header event/)
-  })
-
-  it('rejects a frozen request carrying an unfrozen messages array', async () => {
-    const { ctx, session, boundary } = await requestSetup()
-    const options = Object.freeze({ model: 'm', messages: [...boundary], sessionId: session.id })
-    expect(() => { dispatch(ctx, options) }).toThrow(/frozen messages array/)
-  })
-
-  it('skips hand-built (unfrozen) requests — compaction summarize is out of scope', async () => {
-    const { ctx, session } = await requestSetup()
-    // Unfrozen envelope + arbitrary messages: a direct one-shot call.
-    const options = { model: 'summarizer', messages: [{ role: 'user', content: [{ type: 'text', text: 'summarize!' }] }], sessionId: session.id }
-    expect(() => { dispatch(ctx, options) }).not.toThrow()
-  })
-
-  it('skips requests without a sessionId or with an unknown session', async () => {
-    const { ctx } = await requestSetup()
-    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]) })) }).not.toThrow()
-    expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: SessionId('ghost') })) }).not.toThrow()
-  })
-})
-
-describe('request cross-check ordering (prepend)', () => {
-  it('runs ahead of a short-circuiting llm/stream listener registered before it', async () => {
-    // Replay short-circuits without next(), so the check prepends ahead of ordinary listeners;
-    // correctness still comes from its sequence-bounded rebuild, not listener timing.
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    ctx.on('llm/stream', () => (async function* () {})() as never) // short-circuits, no next()
-    await ctx.plugin(Invariants)
-
-    const session = ctx.sessions.create(SessionId('prepend-check'))
-    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
-    session.append('step/start', { turn: 1, step: 1 })
-    session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
-
-    const divergent = Object.freeze({
-      model: 'm',
-      messages: Object.freeze([{ role: 'user', content: [{ type: 'text', text: 'phantom' }] }]),
-      sessionId: session.id,
-    })
-    expect(() => {
-      void ctx.waterfall('llm/stream', divergent as never, () => (async function* () {})() as never)
-    }).toThrow(/diverges from the boundary derivation/)
-  })
-})
-
-describe('scoped-dispatch invariants', () => {
-  async function scopedCtx() {
-    const ctx = new Context()
-    await ctx.plugin(SessionStore)
-    await ctx.plugin(Invariants)
-    return ctx
-  }
-
-  it('rejects a scoped-family dispatch without a carrier (teaching error)', async () => {
-    const ctx = await scopedCtx()
-    const agent = { id: 'a1' } as unknown as Agent
-    expect(() => { ctx.emit('agent/error', agent, 1, 0, new Error('x')) })
-      .toThrow(/dispatched without a scope carrier/)
-  })
-
-  it('accepts a matching carrier and rejects a mismatched one for EVERY agent-subject event', async () => {
-    const ctx = await scopedCtx()
-    // Real Session objects keep the synthetic Agent handles structurally valid.
-    const agent = { id: 'a1', session: new Session(SessionId('a1-s')) } as unknown as Agent
-    const other = { id: 'a2', session: new Session(SessionId('a2-s')) } as unknown as Agent
-    // One dispatch per table row keeps every subject extractor covered: the
-    // matching carrier passes, the foreign-keyed one throws.
-    const rows: [string, unknown[]][] = [
-      ['agent/created', [agent]],
-      ['agent/disposed', [agent]],
-      ['agent/status', [agent, 'idle']],
-      ['agent/queued', [agent, [], { source: { kind: 'user' }, steering: false }]],
-      ['agent/session-start', [agent, 'startup']],
-      ['agent/pre-step', [agent, 1, 1, new AbortController().signal]],
-      ['agent/prompt-submit', [agent, [], { kind: 'user' }, () => Promise.resolve({ kind: 'allow' })]],
-      ['agent/request', [agent, 1, 1, { model: 'm' }, () => Promise.resolve({ model: 'm' })]],
-      ['agent/session-prefix', [agent, [], new AbortController().signal, () => Promise.resolve([])]],
-      ['agent/step-result', [agent, 1, 1, { role: 'assistant', content: [] }, () => Promise.resolve({ role: 'assistant', content: [] })]],
-      ['agent/turn-continuation', [agent, 1, { action: 'stop' }, () => Promise.resolve({ action: 'stop' })]],
-      ['agent/turn-stop', [agent, 1]],
-      ['agent/error', [agent, 1, 0, new Error('x')]],
-      ['approval/request', [{ agent, toolName: 'echo' }, () => Promise.resolve('unavailable')]],
-      ['tools/pre-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ kind: 'allow' })]],
-      ['tools/execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ content: [], isError: false })]],
-      ['tools/post-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }, () => Promise.resolve({ kind: 'accept' })]],
-      ['tools/result', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }]],
-    ]
-    for (const [event, args] of rows) {
-      const subject = agent
-      expect(() => { (ctx.emit as (...a: unknown[]) => void)(scopeTarget(agent, subject), event, ...args) },
-        `${event} with matching carrier`).not.toThrow()
-      expect(() => { (ctx.emit as (...a: unknown[]) => void)(scopeTarget(agent, other), event, ...args) },
-        `${event} with foreign carrier`).toThrow(/DIFFERENT subject/)
-    }
-  })
-
-  it('rejects a carrier keyed to a different subject than the arguments name', async () => {
-    const ctx = await scopedCtx()
-    const agent = { id: 'a1' } as unknown as Agent
-    const other = { id: 'a2' } as unknown as Agent
-    expect(() => { ctx.emit(scopeTarget(agent, other), 'agent/error', agent, 1, 0, new Error('x')) })
-      .toThrow(/keyed to a DIFFERENT subject/)
-    // The correct spelling passes.
-    expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/error', agent, 1, 0, new Error('x')) })
-      .not.toThrow()
-  })
-
-})
--- a/packages/support/invariants/tests/service.spec.ts
+++ b/packages/support/invariants/tests/service.spec.ts
@@ -0,0 +1,310 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context, Service } from 'cordis'
+import InvariantService, {
+  InvariantError,
+  type Config,
+} from '@deepseek-ai/dsh-invariants'
+
+declare module 'cordis' {
+  interface Context {
+    invariantProbe: InvariantProbeService
+  }
+
+  interface Events {
+    'invariants-test/ping'(): void
+  }
+}
+
+class InvariantProbeService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'invariantProbe')
+  }
+}
+
+interface RuntimeRegistration extends PromiseLike<() => void> {
+  (): void | Promise<void>
+}
+
+interface InstalledRegistration {
+  dispose(): Promise<void>
+}
+
+function runtimeRegistration(registration: () => void): RuntimeRegistration {
+  return registration as RuntimeRegistration
+}
+
+async function setup(config: Config = {}): Promise<{ ctx: Context; fiber: Awaited<ReturnType<Context['plugin']>> }> {
+  const ctx = new Context()
+  const fiber = await ctx.plugin(InvariantService, config)
+  return { ctx, fiber }
+}
+
+async function registerProbe(
+  ctx: Context,
+  packageName: string,
+  probe: () => void,
+): Promise<InstalledRegistration> {
+  const registration = runtimeRegistration(ctx.invariants.register(packageName, (child) => {
+    child.on('invariants-test/ping', probe, { global: true })
+  }))
+  await registration
+  return {
+    async dispose() { await registration() },
+  }
+}
+
+describe('InvariantService selection', () => {
+  it('applies defaults when constructed directly without schema normalization', async () => {
+    const ctx = new Context()
+    const service = new InvariantService(ctx)
+    const probe = vi.fn()
+    const registration = runtimeRegistration(service.register('@deepseek-ai/dsh-session', (child) => {
+      child.on('invariants-test/ping', probe, { global: true })
+    }))
+    await registration
+    ctx.emit('invariants-test/ping')
+    expect(probe).toHaveBeenCalledOnce()
+    await registration()
+  })
+
+  it('enables registrations by default and treats empty lists as admit-all and exclude-none', async () => {
+    for (const config of [{}, { package_allowlist: [], package_blocklist: [] }]) {
+      const { ctx } = await setup(config)
+      const probe = vi.fn()
+      await registerProbe(ctx, '@deepseek-ai/dsh-session', probe)
+      ctx.emit('invariants-test/ping')
+      expect(probe).toHaveBeenCalledOnce()
+    }
+  })
+
+  it('disables every installer while still reserving package ownership', async () => {
+    const { ctx } = await setup({ enabled: false })
+    const probe = vi.fn()
+    const registration = await registerProbe(ctx, '@deepseek-ai/dsh-session', probe)
+    expect(() => ctx.invariants.register('@deepseek-ai/dsh-session', () => {}))
+      .toThrow(/already registered/)
+    ctx.emit('invariants-test/ping')
+    expect(probe).not.toHaveBeenCalled()
+    await registration.dispose()
+  })
+
+  it('uses unanchored, case-sensitive JavaScript regex sources', async () => {
+    const unanchored = await setup({ package_allowlist: ['session'] })
+    const unanchoredProbe = vi.fn()
+    await registerProbe(unanchored.ctx, '@deepseek-ai/dsh-session-extra', unanchoredProbe)
+    unanchored.ctx.emit('invariants-test/ping')
+    expect(unanchoredProbe).toHaveBeenCalledOnce()
+
+    const anchored = await setup({ package_allowlist: ['^@deepseek-ai/dsh-session$'] })
+    const anchoredProbe = vi.fn()
+    await registerProbe(anchored.ctx, '@deepseek-ai/dsh-session-extra', anchoredProbe)
+    anchored.ctx.emit('invariants-test/ping')
+    expect(anchoredProbe).not.toHaveBeenCalled()
+
+    const caseSensitive = await setup({ package_allowlist: ['Session'] })
+    const caseProbe = vi.fn()
+    await registerProbe(caseSensitive.ctx, '@deepseek-ai/dsh-session', caseProbe)
+    caseSensitive.ctx.emit('invariants-test/ping')
+    expect(caseProbe).not.toHaveBeenCalled()
+  })
+
+  it('lets the blocklist override an allowlist match', async () => {
+    const { ctx } = await setup({
+      package_allowlist: ['^@deepseek-ai/dsh-'],
+      package_blocklist: ['session'],
+    })
+    const sessionProbe = vi.fn()
+    const agentProbe = vi.fn()
+    await registerProbe(ctx, '@deepseek-ai/dsh-session', sessionProbe)
+    await registerProbe(ctx, '@deepseek-ai/dsh-agent', agentProbe)
+    ctx.emit('invariants-test/ping')
+    expect(sessionProbe).not.toHaveBeenCalled()
+    expect(agentProbe).toHaveBeenCalledOnce()
+  })
+
+  it('accepts zero-match patterns for packages registered later', async () => {
+    const { ctx } = await setup({ package_allowlist: ['^@later/invariants$'] })
+    const now = vi.fn()
+    const later = vi.fn()
+    await registerProbe(ctx, '@deepseek-ai/dsh-session', now)
+    await registerProbe(ctx, '@later/invariants', later)
+    ctx.emit('invariants-test/ping')
+    expect(now).not.toHaveBeenCalled()
+    expect(later).toHaveBeenCalledOnce()
+  })
+
+  it('allows the same source in both lists and applies blocklist precedence', async () => {
+    const { ctx } = await setup({ package_allowlist: ['agent'], package_blocklist: ['agent'] })
+    const probe = vi.fn()
+    await registerProbe(ctx, '@deepseek-ai/dsh-agent', probe)
+    ctx.emit('invariants-test/ping')
+    expect(probe).not.toHaveBeenCalled()
+  })
+})
+
+describe('InvariantService validation', () => {
+  it.each([
+    [{ package_allowlist: [''] }, /non-blank/],
+    [{ package_allowlist: [' '] }, /non-blank/],
+    [{ package_allowlist: [' session'] }, /surrounding whitespace/],
+    [{ package_blocklist: ['session '] }, /surrounding whitespace/],
+    [{ package_allowlist: ['session', 'session'] }, /duplicate regex/],
+    [{ package_blocklist: ['agent', 'agent'] }, /duplicate regex/],
+    [{ package_allowlist: ['['] }, /invalid regex/],
+    [{ package_blocklist: ['('] }, /invalid regex/],
+  ])('rejects malformed filter config %#', async (config, message) => {
+    await expect((async () => {
+      const ctx = new Context()
+      await ctx.plugin(InvariantService, config)
+    })()).rejects.toThrow(message)
+  })
+
+  it.each(['', ' ', ' package', 'pack age', 'package\n'])('rejects malformed package name %j', async (packageName) => {
+    const { ctx } = await setup()
+    expect(() => ctx.invariants.register(packageName, () => {})).toThrow(/packageName/)
+  })
+})
+
+describe('InvariantService lifecycle', () => {
+  it('honors the installer dependency surface in its child fiber', async () => {
+    const { ctx } = await setup()
+    await ctx.plugin(InvariantProbeService)
+    let registration!: RuntimeRegistration
+    await ctx.plugin({
+      inject: ['invariants', 'invariantProbe'],
+      apply(child: Context) {
+        const installer = Object.assign((installerCtx: Context) => {
+          expect(Object.keys(installerCtx.fiber.inject)).toContain('invariantProbe')
+          expect(Object.keys(installerCtx.fiber.store ?? {})).toContain('invariantProbe')
+          expect(installerCtx.invariantProbe).toBeInstanceOf(InvariantProbeService)
+        }, { inject: ['invariantProbe'] })
+        expect(installer.inject).toEqual(['invariantProbe'])
+        registration = runtimeRegistration(child.invariants.register('@deepseek-ai/dsh-probe', installer))
+        return Promise.resolve(registration)
+      },
+    })
+    await registration
+  })
+
+  it('attributes failures to the registering package with the stable code', async () => {
+    const { ctx } = await setup()
+    const registration = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-session', (child, fail) => {
+      child.on('invariants-test/ping', () => fail('seq must strictly increase'), { global: true })
+    }))
+    await registration
+    let caught: unknown
+    try {
+      ctx.emit('invariants-test/ping')
+    } catch (error) {
+      caught = error
+    }
+    expect(caught).toBeInstanceOf(InvariantError)
+    expect(caught).toMatchObject({
+      name: 'InvariantError',
+      code: 'INVARIANT',
+      packageName: '@deepseek-ai/dsh-session',
+      message: 'invariant violated by "@deepseek-ai/dsh-session": seq must strictly increase',
+    })
+  })
+
+  it('disposes the child fiber completely and permits HMR re-registration', async () => {
+    const { ctx } = await setup()
+    const first = vi.fn()
+    const firstRegistration = await registerProbe(ctx, '@deepseek-ai/dsh-session', first)
+    ctx.emit('invariants-test/ping')
+    await firstRegistration.dispose()
+    ctx.emit('invariants-test/ping')
+    expect(first).toHaveBeenCalledOnce()
+
+    const second = vi.fn()
+    await registerProbe(ctx, '@deepseek-ai/dsh-session', second)
+    ctx.emit('invariants-test/ping')
+    expect(first).toHaveBeenCalledOnce()
+    expect(second).toHaveBeenCalledOnce()
+  })
+
+  it('reserves ownership until asynchronous child disposal completes', async () => {
+    const { ctx } = await setup()
+    let finishDisposal!: () => void
+    const disposalBarrier = new Promise<void>((resolve) => { finishDisposal = resolve })
+    const registration = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-session', (child) => {
+      child.effect(() => async () => { await disposalBarrier })
+    }))
+    await registration
+
+    const disposing = registration()
+    expect(() => ctx.invariants.register('@deepseek-ai/dsh-session', () => {}))
+      .toThrow(/already registered/)
+    finishDisposal()
+    await disposing
+
+    const replacement = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-session', () => {}))
+    await replacement
+    await replacement()
+  })
+
+  it('rolls back listeners and ownership atomically when an installer fails', async () => {
+    const { ctx } = await setup()
+    const leaked = vi.fn()
+    const failed = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-session', (child) => {
+      child.on('invariants-test/ping', leaked, { global: true })
+      throw new Error('installer failed')
+    }))
+    await expect(Promise.resolve(failed)).rejects.toThrow('installer failed')
+    ctx.emit('invariants-test/ping')
+    expect(leaked).not.toHaveBeenCalled()
+
+    const retry = vi.fn()
+    await registerProbe(ctx, '@deepseek-ai/dsh-session', retry)
+    ctx.emit('invariants-test/ping')
+    expect(retry).toHaveBeenCalledOnce()
+  })
+
+  it('rolls back publication effects and ownership when child-fiber publication fails', async () => {
+    const { ctx } = await setup()
+    const leaked = vi.fn()
+    let rejectPublication = true
+    const stopRejecting = ctx.on('internal/plugin', (fiber) => {
+      if (!rejectPublication || fiber.uid === null) return
+      rejectPublication = false
+      fiber.ctx.on('invariants-test/ping', leaked, { global: true })
+      throw new Error('publication failed')
+    })
+
+    const failed = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-publication-probe', () => {}))
+    await expect(Promise.resolve(failed)).rejects.toThrow('publication failed')
+    ctx.emit('invariants-test/ping')
+    expect(leaked).not.toHaveBeenCalled()
+    stopRejecting()
+
+    const retry = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-publication-probe', () => {}))
+    await retry
+    await retry()
+  })
+
+  it('joins asynchronous checks and rolls back their effects on failure', async () => {
+    const { ctx } = await setup()
+    const leaked = vi.fn()
+    const failed = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-async-probe', async (child, fail) => {
+      child.on('invariants-test/ping', leaked, { global: true })
+      await Promise.resolve()
+      fail('asynchronous check failed')
+    }))
+    await expect(Promise.resolve(failed)).rejects.toThrow(/asynchronous check failed/)
+    ctx.emit('invariants-test/ping')
+    expect(leaked).not.toHaveBeenCalled()
+
+    const retry = runtimeRegistration(ctx.invariants.register('@deepseek-ai/dsh-async-probe', async () => {
+      await Promise.resolve()
+    }))
+    await retry
+    await retry()
+  })
+
+  it('releases a synchronous reservation if the service fiber is already inactive', async () => {
+    const { ctx, fiber } = await setup()
+    const service = ctx.invariants
+    await fiber.dispose()
+    expect(() => service.register('@deepseek-ai/dsh-session', () => {})).toThrow(/inactive/i)
+  })
+})
--- a/packages/support/invariants/tsconfig.json
+++ b/packages/support/invariants/tsconfig.json
@@ -15,28 +15,7 @@
      "path": "../../../vendor/cordis"
    },
    {
-      "path": "../../llm/llm"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/scope"
-    },
-    {
-      "path": "../../core/system-prompt"
-    },
-    {
-      "path": "../../ui/user-approval"
-    },
-    {
-      "path": "../../core/tools"
-    },
-    {
-      "path": "../../subagent/subagent"
+      "path": "../../../vendor/schemastery"
    }
  ]
 }
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -23,7 +23,7 @@ Replay keys every call by its calling session id (`GenerateOptions.sessionId`, s
 | `file` | string | `$DSH_SNAPSHOT_FILE` | Path to the primary (parent) `session.jsonl` fixture. Required (config or env). |
 | `overrideFile` | string | `$DSH_SNAPSHOT_OVERRIDE` | Optional path to a `ReplayEntry[]` sidecar that replaces the PRIMARY session's derived script. |
 | `childFiles` | string[] | `$DSH_SNAPSHOT_CHILD_FILES` (path-delimited) | Recorded subagent child-session logs for a nested scenario; empty for a single-session scenario. |
-| `providers` | `ReplayProviderConfig[]` | — | Optional replay-only provider and model catalog. Configured routes dispatch through the replay adapter and never perform provider I/O. |
+| `providers` | `ReplayProviderConfig[]` | — | Optional replay-only provider and model catalog. Each model may publish `contextWindow`; configured routes dispatch through the replay adapter and never perform provider I/O. |

 ```yaml
 - id: llm-replay
@@ -34,6 +34,7 @@ Replay keys every call by its calling session id (`GenerateOptions.sessionId`, s
        name: DeepSeek
        models:
          - id: deepseek-v4-flash
+            contextWindow: 128000
          - id: deepseek-v4-pro
  # file/overrideFile/childFiles default to $DSH_SNAPSHOT_FILE /
  # $DSH_SNAPSHOT_OVERRIDE / $DSH_SNAPSHOT_CHILD_FILES, set by the snapshot
--- a/packages/support/llm-replay/package.json
+++ b/packages/support/llm-replay/package.json
@@ -11,22 +11,29 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "cordis": "^4.0.0-rc.7"
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -11,7 +11,7 @@ import { delimiter as pathDelimiter } from 'node:path'
 import type { Context } from 'cordis'
 import { decodeStorageRecord } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelContext, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
 import { LlmAdapter, LlmError, assertNever } from '@deepseek-ai/dsh-llm'

 /**
@@ -32,6 +32,8 @@ export interface ReplayModelConfig {
  name?: string
  /** Optional selector description. */
  description?: string
+  /** Optional positive integer context capacity published by the replay adapter. */
+  contextWindow?: number
 }

 /** One provider route exposed by the replay adapter. */
@@ -262,6 +264,14 @@ class ReplayAdapter extends LlmAdapter {
    })))
  }

+  override resolveModelContext(provider: string, model: string): Promise<LlmModelContext | undefined> {
+    const configured = this.providers.get(provider)
+    /* v8 ignore next -- LlmService only asks about routes registered from this same map. */
+    if (configured === undefined) return Promise.resolve(undefined)
+    const contextWindow = configured.models?.find(candidate => candidate.id === model)?.contextWindow
+    return Promise.resolve(contextWindow === undefined ? undefined : { contextWindow })
+  }
+
  override stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    return this.replay(options)
  }
--- a/packages/support/llm-replay/src/invariant.ts
+++ b/packages/support/llm-replay/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-replay`.
+ * @module @deepseek-ai/dsh-llm-replay/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-replay'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-replay-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-only adapter consumes a fixed replay script; its stream grammar
+ * is checked by the LLM companion and fixture derivation tests.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -155,7 +155,7 @@ describe('deriveReplayScript', () => {
  it('keeps a finish-error chunk in the derived entry (replays naturally)', () => {
    const errChunks: StreamChunk[] = [
      { type: 'block-start', index: 0, blockType: 'text' },
-      { type: 'finish', reason: { kind: 'error', message: 'boom', code: 'X' } },
+      { type: 'finish', reason: { kind: 'error', failure: { message: 'boom', code: 'X' } } },
    ]
    const events = errChunks.map((c, i) => chunkEvent(i + 1, 1, 1, c))
    expect(deriveReplayScript(events)).toEqual([{ kind: 'chunks', chunks: errChunks }])
@@ -241,7 +241,7 @@ describe('installLlmReplay (through the real LlmService)', () => {
          id: 'deepseek',
          name: 'DeepSeek',
          models: [
-            { id: 'flash' },
+            { id: 'flash', contextWindow: 128_000 },
            { id: 'pro', name: 'Pro', description: 'Larger model' },
          ],
        },
@@ -258,6 +258,10 @@ describe('installLlmReplay (through the real LlmService)', () => {
      { provider: 'deepseek', id: 'pro', name: 'Pro', description: 'Larger model' },
    ])
    await expect(ctx.llm.listModels('empty')).resolves.toEqual([])
+    await expect(ctx.llm.resolveModelContext('deepseek', 'flash')).resolves.toEqual({ contextWindow: 128_000 })
+    await expect(ctx.llm.resolveModelContext('deepseek', 'pro')).resolves.toBeUndefined()
+    await expect(ctx.llm.resolveModelContext('deepseek', 'unlisted')).resolves.toBeUndefined()
+    await expect(ctx.llm.resolveModelContext('empty', 'unlisted')).resolves.toBeUndefined()
    expect(await drain(ctx.llm.stream({ provider: 'deepseek', model: 'pro', messages: [] }))).toEqual(TEXT_CHUNKS)

    dispose()
--- a/packages/support/llm-replay/tsconfig.json
+++ b/packages/support/llm-replay/tsconfig.json
@@ -19,6 +19,9 @@
    },
    {
      "path": "../../core/session"
+    },
+    {
+      "path": "../../support/invariants"
    }
  ]
 }
--- a/packages/support/loader-smoke/package.json
+++ b/packages/support/loader-smoke/package.json
@@ -11,11 +11,16 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
+    "lib/invariant.js",
    "lib/types/**/*.d.ts",
    "lib/types/**/*.d.ts.map",
    "src"
@@ -25,9 +30,11 @@
    "tsx": "^4.22.4"
  },
  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "cordis": "^4.0.0-rc.6"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
    "cordis": "^4.0.0-rc.6"
  }
 }
--- a/packages/support/loader-smoke/src/invariant.ts
+++ b/packages/support/loader-smoke/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-loader-smoke`.
+ * @module @deepseek-ai/dsh-loader-smoke/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-loader-smoke'
+
+/** Cordis companion plugin name. */
+export const name = 'loader-smoke-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event stream or mutable data;
+ * consuming test suites exercise its behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
--- a/packages/support/loader-smoke/tests/example-launch.spec.ts
+++ b/packages/support/loader-smoke/tests/example-launch.spec.ts
@@ -5,7 +5,7 @@ import {
  resolveExampleMode,
 } from '@deepseek-ai/dsh-loader-smoke'

-const SRC_BIN = '/repo/packages/examples/stdio-demo/src/bin.ts'
+const SRC_BIN = '/repo/packages/examples/tui-demo/src/bin.ts'
 const TSCONFIG = '/repo/tsconfig.json'

 const originalMode = process.env[EXAMPLE_MODE_ENV]
@@ -66,7 +66,7 @@ describe('resolveExampleLaunch', () => {
      env: { DSH_HOME: '/tmp/home' },
    })
    expect(args).not.toContain('--import')
-    expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js')
+    expect(args).toContain('/repo/packages/examples/tui-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')
@@ -106,6 +106,6 @@ describe('resolveExampleLaunch', () => {
  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')
+    expect(args).toContain('/repo/packages/examples/tui-demo/lib/bin.js')
  })
 })
--- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts
+++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts
@@ -37,8 +37,8 @@ describe('runLoaderSmoke', () => {
      marker: 'present',
      input: 'one\ntwo\n',
    })
-    expect(canonicalTempPath(output.dshHome)).toBe(`${canonicalTempPath(output.cwd)}/.dsh`)
-    expect(canonicalTempPath(output.agentsHome)).toBe(`${canonicalTempPath(output.cwd)}/.agents`)
+    expect(canonicalTempPath(output.dshHome)).toBe(canonicalTempPath(join(output.cwd, '.dsh')))
+    expect(canonicalTempPath(output.agentsHome)).toBe(canonicalTempPath(join(output.cwd, '.agents')))
    expect(result.stderr).toContain('fixture stderr')
    expect(existsSync(output.cwd)).toBe(false)
  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
--- a/packages/support/loader-smoke/tsconfig.json
+++ b/packages/support/loader-smoke/tsconfig.json
@@ -7,5 +7,9 @@
  "include": [
    "src"
  ],
-  "references": []
+  "references": [
+    {
+      "path": "../../support/invariants"
+    }
+  ]
 }