Merge remote-tracking branch 'origin/master' into codex/skill-system

examples/AGENTS.md

@@ -21,6 +21,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P
 |---|---|---|
 | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) |
 | `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified |
+| `cordis-agent` | `tests/keyless-smoke.e2e.ts` — boots the real tree incl. `@deepseek-ai/dsh-tool-cordis` by package name; the tool logic is unit-tested in `packages/cordis/tool-cordis` | `tests/cordis-tools.e2e.ts` — real model mounts a listener (tagged line fires), builds+calls its own tool, composes two mounts via provide/inject |
 | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written |
 
 See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design.

examples/README.md

@@ -19,6 +19,12 @@ A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + th
 
 Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
 
+## cordis-agent
+
+The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. The `ctx.fs`/`ctx.web` services ride along provider-only, as the capabilities those plugins build on.
+
+Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats.
+
 ## acp-agent
 
 An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.

examples/acp-agent/README.md

@@ -6,7 +6,7 @@ The DeepSeek Harness SDK agent demo exposed as an **Agent Client Protocol (ACP)*
 pnpm run demo:acp          # needs DEEPSEEK_API_KEY (repo-root .env or env)
 ```
 
-This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, and the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC.
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand), the swappable DeepSeek, bash, and filesystem backends, the model-facing `read`/`write`/`edit`/`subagent`/`subagent_fork`/`todo_write` tool entries, and the advisory `repeat-tool-guard` loop-hygiene plugin. The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC.
 
 ## stdout is the protocol
 

examples/acp-agent/composition.md

@@ -33,6 +33,8 @@ flowchart LR
   cfg --> plugin_acp_tool_subagent_fork
   plugin_acp_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
   cfg --> plugin_acp_tool_todo
+  plugin_acp_repeat_tool_guard["repeat-tool-guard<br/>@deepseek-ai/dsh-repeat-tool-guard"]
+  cfg --> plugin_acp_repeat_tool_guard
   plugin_acp_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
   cfg --> plugin_acp_fs_local
   plugin_acp_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
@@ -56,6 +58,7 @@ flowchart LR
 | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
 | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
 | `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `repeat-tool-guard` | `@deepseek-ai/dsh-repeat-tool-guard` |
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
 | `tool-fs` | `@deepseek-ai/dsh-tool-fs` |

examples/acp-agent/cordis.yml

@@ -86,6 +86,14 @@
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
 
+# The repeat-tool-call guard: advisory reminders (injected context, never a
+# block) when the model re-issues the same tool call with identical arguments;
+# defaults [3, 5, 8]. Loaded here so the snapshot tier exercises the reminder
+# transcript (the repeat-tool-guard scenario) — no other scenario repeats a
+# call three times, so it is inert everywhere else.
+- id: repeat-tool-guard
+  name: '@deepseek-ai/dsh-repeat-tool-guard'
+
 # Filesystem capability stack: local provider, read-before-write/edit policy
 # gate, then the model-facing read/write/edit tools. Relative filesystem paths
 # resolve from the server launch cwd; the documented Zed setup launches this

examples/acp-agent/tests/acp.e2e.ts

@@ -57,8 +57,8 @@ interface Spawned {
 }
 
 // TODO(acp-test-harness): this subprocess/client boot glue is duplicated with
-// hooks.e2e.ts and partly with snapshot-harness.ts. Extract one shared ACP test
-// launcher before the TSX/env/permission-stub details drift again.
+// hooks.e2e.ts and partly with dsh-acp-snapshot's harness. Migrate both e2e
+// files onto that launcher before the TSX/env/permission-stub details drift.
 function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawned {
   const child = spawn(
     process.execPath,
@@ -101,6 +101,46 @@ function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawn
 let spawned: Spawned | undefined
 let workdir: string | undefined
 
+function hasStdoutLine(out: string[]): boolean {
+  return out.join('').split('\n').some(line => line.trim().length > 0)
+}
+
+async function waitForStdoutLine(child: ChildProcessWithoutNullStreams, out: string[], stderr: string[], timeoutMs: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const cleanup = () => {
+      clearTimeout(timeout)
+      child.stdout.off('data', onData)
+      child.off('exit', onExit)
+      child.off('error', onError)
+    }
+    const pass = () => {
+      cleanup()
+      resolve()
+    }
+    const fail = (reason: string) => {
+      cleanup()
+      reject(new Error(`${reason}; stderr: ${stderr.join('')}`))
+    }
+    const onData = () => {
+      if (hasStdoutLine(out)) pass()
+    }
+    const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+      fail(`ACP child exited before emitting a stdout frame (code ${code ?? 'null'}, signal ${signal ?? 'null'})`)
+    }
+    const onError = (error: Error) => {
+      fail(`ACP child failed before emitting a stdout frame: ${error.message}`)
+    }
+    const timeout = setTimeout(() => {
+      fail(`ACP child did not emit a stdout frame within ${timeoutMs}ms`)
+    }, timeoutMs)
+
+    child.stdout.on('data', onData)
+    child.on('exit', onExit)
+    child.on('error', onError)
+    onData()
+  })
+}
+
 afterEach(async () => {
   if (spawned) {
     spawned.child.kill('SIGKILL')
@@ -129,16 +169,21 @@ describe('acp-agent over real stdio (no key required)', () => {
       stdio: ['pipe', 'pipe', 'pipe'],
     })
     const out: string[] = []
+    const stderr: string[] = []
     child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
     child.stdout.on('data', (c: string) => out.push(c))
+    child.stderr.on('data', (c: string) => stderr.push(c))
 
     // Send a single initialize request as a newline-delimited JSON-RPC frame.
     const req = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} } })
     child.stdin.write(req + '\n')
 
-    // Give it a moment to boot + reply, then inspect stdout.
-    await new Promise(r => setTimeout(r, 4000))
-    child.kill('SIGKILL')
+    try {
+      await waitForStdoutLine(child, out, stderr, 15_000)
+    } finally {
+      child.kill('SIGKILL')
+    }
 
     const lines = out.join('').split('\n').filter(l => l.trim().length > 0)
     expect(lines.length).toBeGreaterThan(0)

examples/acp-agent/tests/acp.snapshot.ts

@@ -1,70 +1,37 @@
-import { readFile, readdir, writeFile } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { describe, expect, it } from 'vitest'
-import { type HarvestedLog, type InputScript, runScenario } from './snapshot-harness.ts'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout } from './snapshot-normalize.ts'
+import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot'
 
 /**
- * ACP snapshot tests (REPLAY by default, keyless). Each scenario under
- * `snapshots/<name>/` ships an `input.json` (the client stdin script) and a
- * `session.jsonl` fixture; replay boots the real acp-agent subprocess, drives
- * it, and diffs the normalized stdout transcript against the committed
- * `stdout.golden.jsonl`. For model scenarios it ALSO checks the re-persisted
- * session log — against the `session.jsonl` fixture itself, not a separate
- * golden: the fixture doubles as the replay source (recorded scenarios) and the
- * expected produced log (both sides normalized before comparing).
- *
- * `pnpm run test:snapshot:record` (DSH_SNAPSHOT=record + -u) re-records the
- * `session.jsonl` fixtures against the real API and refreshes the stdout golden
- * in one pass.
+ * The acp-agent example's snapshot suite: the scenario table for
+ * `dsh-acp-snapshot`'s suite factory, which owns every compare/guard mechanic
+ * (golden + re-persisted-log diffs, record write-back, the pinned-header
+ * uniformity guard, the fixture guards). Fixtures live under `snapshots/<name>/`;
+ * `pnpm run test:snapshot:record` re-records the `recorded` scenarios against
+ * the real API. See the package README (packages/support/acp-snapshot) and the
+ * snapshot RFC, docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
  */
 
-const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
-const RECORDING = process.env.DSH_SNAPSHOT === 'record'
-
-/** A snapshot scenario and how its fixtures are produced. */
-interface Scenario {
-  name: string
-  /** Whether the scenario drives at least one model turn (so a JSONL golden applies). */
-  hasModelTurn: boolean
-  /**
-   * Whether the run persists a comparable session log to diff against the
-   * `session.jsonl` fixture. Defaults to {@link hasModelTurn} (a model turn
-   * always produces a log worth comparing). Set it independently for a scenario
-   * that produces a non-trivial log WITHOUT a model turn — e.g. a prompt blocked
-   * by a `UserPromptSubmit` hook, which opens a `rejected` turn carrying `hook/*`
-   * events but never calls the model.
-   */
-  comparesLog?: boolean
-  /**
-   * Whether `test:snapshot:record` regenerates this scenario's `session.jsonl`
-   * from the LIVE API. `recorded` scenarios are model-driven and reproducible;
-   * `authored` scenarios (a hand-written `replay.override.json` sidecar drives
-   * replay — e.g. a provider error or a cancel, which the live API can't be
-   * coaxed into deterministically — or a deterministic hook scenario whose
-   * derived empty script needs no sidecar) are NEVER re-recorded.
-   */
-  recorded: boolean
-  /**
-   * How many SUBAGENT child sessions this scenario records beyond the top-level
-   * one (0 for a single-session scenario). Each child rides in a sibling fixture
-   * `session.<n>.jsonl` (1-based); replay forwards them to `dsh-llm-replay` so
-   * each child session replays from its own script, and record mode writes the
-   * harvested child logs back to those files. Defaults to 0.
-   */
-  childSessions?: number
+// The dsh-acp-agent bin (the demo:acp entry), this example's cordis.yml, and
+// the repo-root tsconfig (four levels up from examples/acp-agent/tests) — all
+// ABSOLUTE: the subprocess cwd is a temp dir outside the repo.
+const AGENT = {
+  binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
+  configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+  tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
 }
 
 const SCENARIOS: Scenario[] = [
   { name: 'handshake', hasModelTurn: false, recorded: false },
   { name: 'reject-extra-dirs', hasModelTurn: false, recorded: false },
-  { name: 'text-turn', hasModelTurn: true, recorded: true },
+  // text-turn is the pinned-header scenario: the minimal single text turn,
+  // whose fixture is the ONE place the full system prompt + tool schemas are
+  // committed and compared verbatim.
+  { name: 'text-turn', hasModelTurn: true, recorded: true, pinsHeader: true },
   { name: 'tool-call-turn', hasModelTurn: true, recorded: true },
   { name: 'fs-terminal-card', hasModelTurn: true, recorded: true },
   { name: 'todo-plan', hasModelTurn: true, recorded: true },
-  { name: 'skill-load', hasModelTurn: true, recorded: false },
+  { name: 'skill-load', hasModelTurn: true, recorded: false, overridden: true, variesHeader: true },
   { name: 'workspace-edit', hasModelTurn: true, recorded: true },
   { name: 'fs-read', hasModelTurn: true, recorded: true },
   { name: 'fs-write', hasModelTurn: true, recorded: true },
@@ -73,8 +40,13 @@ const SCENARIOS: Scenario[] = [
   { name: 'fs-read-window', hasModelTurn: true, recorded: true },
   { name: 'fs-policy-reject', hasModelTurn: true, recorded: true },
   { name: 'multi-turn', hasModelTurn: true, recorded: true },
-  { name: 'error-finish', hasModelTurn: true, recorded: false },
-  { name: 'cancel', hasModelTurn: true, recorded: false },
+  { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true },
+  // Keyless, authored (like error-finish/cancel): deterministically forcing a
+  // LIVE model to repeat one call three times is not a stable recording, so
+  // the fixture scripts five identical todo_write calls and pins BOTH reminder
+  // tiers (gentle at 3, detailed at 5) as context/message in transcript and log.
+  { name: 'repeat-tool-guard', hasModelTurn: true, recorded: false },
+  { name: 'cancel', hasModelTurn: true, recorded: false, overridden: true },
   { name: 'subagent-spawn', hasModelTurn: true, recorded: true, childSessions: 1 },
   { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 },
   { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 },
@@ -120,138 +92,9 @@ const SCENARIOS: Scenario[] = [
   { name: 'hook-codex-stop-continue', hasModelTurn: true, recorded: true },
 ]
 
-/** The sibling child-fixture paths for a scenario (`session.1.jsonl` …). */
-function childFixturePaths(dir: string, childSessions: number): string[] {
-  return Array.from({ length: childSessions }, (_, i) => join(dir, `session.${i + 1}.jsonl`))
-}
-
-/**
- * Derive the {@link NormalizeContext} for a `session.jsonl` fixture from its own
- * header line (`{ type: 'session', id, cwd }`). A committed fixture carries the
- * session id and cwd of the run that harvested it — different from the live
- * replay run — so normalizing it against the live run's ctx would leave those
- * recorded values unscrubbed. Reading them from the header scrubs the fixture's
- * own id/cwd to the same `{{sessionId}}`/`{{cwd}}` tokens the replay output gets.
- * An authored fixture whose header is already normalized (`id:'{{sessionId}}'`,
- * `cwd:'{{cwd}}'`) yields those tokens as the volatile values, so scrubbing them
- * is an idempotent no-op. A header with no `cwd` falls back to a sentinel that
- * cannot occur in a log (NOT `''`, which `String.split` would match on every
- * character boundary and corrupt the output).
- */
-function fixtureContext(fixture: string): NormalizeContext {
-  const firstLine = fixture.split('\n').find(line => line.trim().length > 0) ?? '{}'
-  const header = JSON.parse(firstLine) as { id?: unknown; cwd?: unknown }
-  return {
-    sessionIds: typeof header.id === 'string' ? [header.id] : [],
-    cwd: typeof header.cwd === 'string' ? header.cwd : '\0no-cwd\0',
-  }
-}
-
-for (const scenario of SCENARIOS) {
-  describe(`snapshot: ${scenario.name}`, () => {
-    // In RECORD mode, only re-run the `recorded` (live-API) scenarios; the
-    // `authored` ones (sidecar-driven errors/cancel) are never re-recorded.
-    it.skipIf(RECORDING && !scenario.recorded)('matches the goldens', async () => {
-      const dir = join(SNAPSHOTS_DIR, scenario.name)
-      const input = JSON.parse(await readFile(join(dir, 'input.json'), 'utf8')) as InputScript
-      const overrideFile = join(dir, 'replay.override.json')
-      const workspaceDir = join(dir, 'workspace')
-      const childSessions = scenario.childSessions ?? 0
-      const result = await runScenario(input, {
-        mode: RECORDING ? 'record' : 'replay',
-        fixtureFile: join(dir, 'session.jsonl'),
-        ...existsSync(overrideFile) ? { overrideFile } : {},
-        // In REPLAY, forward the recorded child fixtures so each subagent session
-        // replays from its own script. In RECORD they are harvested, not read.
-        ...!RECORDING && childSessions > 0 ? { childFiles: childFixturePaths(dir, childSessions) } : {},
-        ...existsSync(workspaceDir) ? { workspaceDir } : {},
-      })
-
-      // Scrub every volatile id the run produced: the ACP server-issued session
-      // id plus every harvested log's recorded id (a subagent child id never
-      // surfaces over ACP, but it appears in the child's own log header). The
-      // normalizer's UUID catch-all covers any we don't enumerate.
-      const ctx: NormalizeContext = {
-        sessionIds: [
-          ...result.sessionId !== undefined ? [result.sessionId] : [],
-          ...result.sessionLogs.map(l => l.id),
-        ],
-        cwd: result.cwd,
-      }
-
-      // RECORD mode (recorded model scenarios only): persist the freshly-harvested
-      // logs back to their fixtures — the primary to session.jsonl, each child to
-      // session.<n>.jsonl in harvest order. `--update` refreshes the Vitest
-      // goldens but NOT these fixtures, so write them here.
-      if (RECORDING && scenario.recorded && scenario.hasModelTurn) {
-        expect(result.sessionLogs.length, 'record produced no session log to harvest').toBeGreaterThan(0)
-        expect(result.sessionLogs.length, `expected ${childSessions + 1} session logs (parent + children)`)
-          .toBe(childSessions + 1)
-        await writeFile(join(dir, 'session.jsonl'), (result.sessionLogs[0] as HarvestedLog).content)
-        for (let i = 1; i < result.sessionLogs.length; i++) {
-          await writeFile(join(dir, `session.${i}.jsonl`), (result.sessionLogs[i] as HarvestedLog).content)
-        }
-      }
-
-      await expect(normalizeStdout(result.rawStdout, ctx))
-        .toMatchFileSnapshot(join(dir, 'stdout.golden.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/*`).
-      const comparesLog = scenario.comparesLog ?? scenario.hasModelTurn
-      if (comparesLog) {
-        // The harvested logs (primary-first) must match their committed fixtures
-        // 1:1. Each side passes through normalizeSessionLog, scrubbed against ITS
-        // OWN volatile values — the live run's via `ctx`, the committed fixture's
-        // via its own header (a committed file cannot share the live run's ids).
-        expect(result.sessionLogs.length, 'this scenario must persist a session log').toBe(childSessions + 1)
-        const fixtureFiles = ['session.jsonl', ...Array.from({ length: childSessions }, (_, i) => `session.${i + 1}.jsonl`)]
-        for (let i = 0; i < fixtureFiles.length; i++) {
-          const harvested = (result.sessionLogs[i] as HarvestedLog).content
-          const fixture = await readFile(join(dir, fixtureFiles[i] as string), 'utf8')
-          expect(normalizeSessionLog(harvested, ctx), `${fixtureFiles[i]} mismatch`)
-            .toEqual(normalizeSessionLog(fixture, fixtureContext(fixture)))
-        }
-      }
-    })
-  })
-}
-
-describe('snapshot fixtures', () => {
-  it('every scenario directory is registered (no orphans)', async () => {
-    // toMatchFileSnapshot does not prune orphaned golden/fixture files, so a
-    // renamed/removed scenario could leave a stale dir that nothing exercises.
-    // Fail loud on any snapshots/<dir> not present in SCENARIOS.
-    const entries = await readdir(SNAPSHOTS_DIR, { withFileTypes: true })
-    const onDisk = entries.filter(e => e.isDirectory()).map(e => e.name).sort()
-    const registered = SCENARIOS.map(s => s.name).sort()
-    expect(onDisk).toEqual(registered)
-  })
-
-  it('every registered scenario has its required fixture files', async () => {
-    // Every scenario has an input script and an stdout golden. EVERY scenario
-    // also needs `session.jsonl`: the harness boots `llm-replay` with that path
-    // as the replay source for ALL scenarios (acp.snapshot.ts passes
-    // `fixtureFile: <dir>/session.jsonl` unconditionally), and `loadReplayScript`
-    // throws "fixture not found" when it is absent and no override replaces it.
-    // A no-model scenario ships a header-only `session.jsonl` (it derives to an
-    // empty script — no model call is made); a model scenario's fixture also
-    // doubles as the expected-log artifact the run is diffed against. An authored
-    // (non-`recorded`) model scenario additionally ships a `replay.override.json`
-    // sidecar for the throw/hang cases a derived script cannot express.
-    for (const { name, hasModelTurn, recorded, childSessions } of SCENARIOS) {
-      const dir = join(SNAPSHOTS_DIR, name)
-      expect(existsSync(join(dir, 'input.json')), `${name}/input.json`).toBe(true)
-      expect(existsSync(join(dir, 'stdout.golden.jsonl')), `${name}/stdout.golden.jsonl`).toBe(true)
-      expect(existsSync(join(dir, 'session.jsonl')), `${name}/session.jsonl`).toBe(true)
-      if (hasModelTurn && !recorded) {
-        expect(existsSync(join(dir, 'replay.override.json')), `${name}/replay.override.json`).toBe(true)
-      }
-      // A nested-agent scenario ships one child fixture per recorded subagent
-      // session (`session.1.jsonl` …), the replay source for that child session.
-      for (const childFixture of childFixturePaths(dir, childSessions ?? 0)) {
-        expect(existsSync(childFixture), childFixture).toBe(true)
-      }
-    }
-  })
+defineAcpSnapshotSuite({
+  agent: AGENT,
+  snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
+  scenarios: SCENARIOS,
+  mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
 })

examples/acp-agent/tests/snapshot-harness.ts

@@ -1,387 +0,0 @@
-/**
- * Shared harness for the ACP snapshot tests. A plain module (NOT a *.spec.ts /
- * *.snapshot.ts) so importing it never re-registers another file's tests.
- *
- * It boots the REAL examples/acp-agent subprocess via the cordis Loader (so the
- * export-shape bug class stays guarded — see docs/postmortem/0001), drives it
- * over real ACP JSON-RPC stdio with a deterministic input script, tees raw
- * stdout (for the golden + a purity check) into an SDK `ClientSideConnection`,
- * and — in record mode — harvests the persisted session JSONL after a graceful
- * shutdown flush. Two pure normalizers turn the captured stdout frames and the
- * session-log events into stable, snapshot-able text.
- *
- * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
- */
-
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
-import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, delimiter } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { Readable, Writable } from 'node:stream'
-import {
-  ClientSideConnection,
-  ndJsonStream,
-  PROTOCOL_VERSION,
-  type Agent as AcpAgent,
-  type Client,
-  type RequestPermissionRequest,
-  type RequestPermissionResponse,
-  type SessionNotification,
-} from '@agentclientprotocol/sdk'
-
-// The dsh-acp-agent bin (the demo:acp entry) and this example's cordis.yml.
-// The bin resolves its config-path arg from CWD and, under DSH_SNAPSHOT=replay,
-// swaps it for the sibling cordis.snapshot.yml. The child's cwd is a temp dir
-// OUTSIDE the repo, so pass the example config's ABSOLUTE path.
-const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
-const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// The repo-root tsconfig: dev/test run UNBUILT and the `@deepseek-ai/dsh-*`
-// imports resolve through its `paths` map. The child's cwd is a temp dir
-// OUTSIDE the repo, so tsx's upward search would miss it — point tsx at the
-// repo tsconfig explicitly (same fix the e2e harness uses). Repo root is four
-// levels up from this file (examples/acp-agent/tests).
-const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-
-/**
- * One step of a scenario's deterministic input script (`input.json`). The
- * harness interprets these in order. `newSession` captures the server-issued
- * (random) session id into a `{{sessionId}}` variable that later steps
- * reference, since a committed file cannot know the id in advance.
- *
- * `promptAndCancel` sends a prompt WITHOUT awaiting its response, waits until
- * the client observes the first streamed `agent_message_chunk` (so the emitted
- * frames deterministically precede the cancellation), then cancels the turn —
- * the only way to exercise a cancel deterministically (a plain `prompt` step
- * awaits the response, which a cancel/hang scenario would block on forever).
- */
-type InputStep =
-  | { op: 'initialize'; terminalOutput?: boolean }
-  | { op: 'newSession' }
-  | { op: 'newSessionExpectError'; additionalDirectories?: string[] }
-  | { op: 'prompt'; text: string }
-  | { op: 'promptExpectError'; text: string }
-  | { op: 'promptAndCancel'; text: string }
-  | { op: 'cancel' }
-
-/** A scenario's `input.json`: an ordered list of input steps. */
-export interface InputScript {
-  steps: InputStep[]
-}
-
-/** One harvested session log plus the identifying facts off its header line. */
-export interface HarvestedLog {
-  /** The recorded session id (header `id`). */
-  id: string
-  /** Session creation time (header `createdAt`) — the child-ordering key. */
-  createdAt: number
-  /** The parent session id, if this log is a subagent child (header `parentSession`). */
-  parentSession?: string
-  /** The full `.jsonl` file content. */
-  content: string
-}
-
-/** The result of running a scenario: raw stdout + the harvested session log(s). */
-export interface RunResult {
-  /** Raw stdout bytes (decoded utf8), every newline-delimited JSON-RPC frame. */
-  rawStdout: string
-  /** stderr (for diagnostics on failure). */
-  stderr: string
-  /** The session id the server issued (undefined if no session was created). */
-  sessionId?: string
-  /** The temp cwd the session ran in (the bash workspace). */
-  cwd: string
-  /**
-   * Every persisted session log harvested after the run, ordered primary-first:
-   * the top-level (parent) session — the one with no `parentSession` — then each
-   * subagent child by ascending `createdAt`. A single-session scenario harvests
-   * exactly one; a nested-agent scenario harvests the parent plus one per child.
-   */
-  sessionLogs: HarvestedLog[]
-}
-
-interface RunOptions {
-  /** `replay` (default, keyless) or `record` (real API, harvests the log). */
-  mode: 'replay' | 'record'
-  /** The recorded session JSONL fixture path (replay reads it; record writes near it). */
-  fixtureFile: string
-  /** Optional sidecar override path (replay). */
-  overrideFile?: string
-  /**
-   * Recorded SUBAGENT child-session fixture paths (replay). A nested-agent
-   * scenario ships one per child (`session.1.jsonl`, …); the harness forwards
-   * them to `dsh-llm-replay` via `$DSH_SNAPSHOT_CHILD_FILES` so each child
-   * session replays from its own recorded script. Empty for single-session
-   * scenarios. Ignored in record mode (children are harvested, not replayed).
-   */
-  childFiles?: string[]
-  /**
-   * Optional `<scenario>/workspace/` directory whose contents are copied into
-   * the temp cwd BEFORE the run — the standard way to seed files the agent
-   * operates on (a file to read, edit, or grep). Absent for scenarios that
-   * start from an empty workspace.
-   */
-  workspaceDir?: string
-}
-
-/**
- * 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
- * and (record mode) the harvested session-log path.
- */
-export async function runScenario(input: InputScript, opts: RunOptions): Promise<RunResult> {
-  const cwd = await mkdtemp(join(tmpdir(), 'acp-snap-cwd-'))
-  const sessionsRoot = await mkdtemp(join(tmpdir(), 'acp-snap-sessions-'))
-  // Everything past the temp-dir creation runs under a try/finally that always
-  // removes both dirs — so a failure in workspace seeding, spawn, or any step
-  // never leaks them (the "e2e tests own their resources" rule).
-  let child: ChildProcessWithoutNullStreams | undefined
-  let sessionId: string | undefined
-  let sessionLogs: HarvestedLog[] = []
-  const rawBuffers: Buffer[] = []
-  const stderrChunks: string[] = []
-  try {
-    // Seed the workspace if the scenario ships one (a file the agent reads/edits).
-    // Copied into the temp cwd so the agent's bash tools see it; the goldens
-    // normalize the cwd, so the seeded paths stay stable across runs.
-    if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) {
-      await cp(opts.workspaceDir, cwd, { recursive: true })
-    }
-    const env: NodeJS.ProcessEnv = {
-      ...process.env,
-      TSX_TSCONFIG_PATH: repoTsconfig,
-      DSH_SNAPSHOT: opts.mode,
-      DSH_SNAPSHOT_FILE: opts.fixtureFile,
-      DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot,
-      DSH_HOME: join(cwd, '.dsh'),
-      DSH_AGENTS_HOME: join(cwd, '.agents'),
-      ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {},
-      ...opts.childFiles !== undefined && opts.childFiles.length > 0
-        ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) }
-        : {},
-    }
-
-    child = spawn(
-      process.execPath,
-      ['--import', tsxLoader, binScript, configPath],
-      { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] },
-    )
-
-    child.stderr.setEncoding('utf8')
-    child.stderr.on('data', (c: string) => stderrChunks.push(c))
-
-    // Tee raw stdout: accumulate the bytes for the golden + purity check, and ALSO
-    // feed the same bytes to the SDK client through a passthrough. Buffer the raw
-    // bytes (not per-chunk utf8 strings) and decode once at the end, so a
-    // multibyte sequence split across two 'data' events can't corrupt the golden.
-    const passthrough = new Readable({ read() {} })
-    child.stdout.on('data', (buf: Buffer) => {
-      rawBuffers.push(buf)
-      passthrough.push(buf)
-    })
-    child.stdout.on('end', () => passthrough.push(null))
-
-    const stream = ndJsonStream(
-      Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
-      Readable.toWeb(passthrough) as ReadableStream<Uint8Array>,
-    )
-    // Watcher so a step can block until the client OBSERVES a particular
-    // session/update — used by promptAndCancel to pin frame order (send cancel
-    // only after the streamed agent_message_chunk has arrived, so those frames
-    // deterministically precede the cancelled prompt response).
-    const updateWaiters: { match: (u: SessionNotification['update']) => boolean; resolve: () => void }[] = []
-    const waitForUpdate = (match: (u: SessionNotification['update']) => boolean): Promise<void> =>
-      new Promise<void>(resolve => updateWaiters.push({ match, resolve }))
-
-    const makeClient = (_agent: AcpAgent): Client => ({
-      sessionUpdate(params: SessionNotification): Promise<void> {
-        for (let i = updateWaiters.length - 1; i >= 0; i--) {
-          const waiter = updateWaiters[i]
-          if (waiter !== undefined && waiter.match(params.update)) {
-            updateWaiters.splice(i, 1)
-            waiter.resolve()
-          }
-        }
-        return Promise.resolve()
-      },
-      requestPermission(_params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
-        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
-      },
-    })
-    const client = new ClientSideConnection(makeClient, stream)
-
-    for (const step of input.steps) {
-      await runStep(client, step, cwd, waitForUpdate, () => sessionId, (id) => { sessionId = id })
-    }
-    // Done driving: close stdin so the server disposes gracefully (flushing
-    // persistence) and exits. Then await exit so the harvested log is complete.
-    child.stdin.end()
-    await waitForExit(child)
-    // Harvest EVERY persisted log (parent + any subagent children) while the
-    // temp dirs still exist, ordered primary-first.
-    sessionLogs = await harvestSessionLogs(sessionsRoot)
-  } finally {
-    // Failure-safe teardown: kill a still-running child and drop the temp dirs
-    // even if seeding/spawn/a step/harvest threw, so a flaky run never leaks a
-    // process or dir. `child` is undefined only if spawn itself threw.
-    if (child !== undefined && child.exitCode === null && child.signalCode === null) {
-      child.kill('SIGKILL')
-      await waitForExit(child)
-    }
-    await rm(cwd, { recursive: true, force: true })
-    await rm(sessionsRoot, { recursive: true, force: true })
-  }
-
-  return {
-    rawStdout: Buffer.concat(rawBuffers).toString('utf8'),
-    stderr: stderrChunks.join(''),
-    cwd,
-    ...sessionId !== undefined ? { sessionId } : {},
-    sessionLogs,
-  }
-}
-
-/** Drive one input step over the client connection. */
-async function runStep(
-  client: ClientSideConnection,
-  step: InputStep,
-  cwd: string,
-  waitForUpdate: (match: (u: SessionNotification['update']) => boolean) => Promise<void>,
-  getSessionId: () => string | undefined,
-  setSessionId: (id: string) => void,
-): Promise<void> {
-  switch (step.op) {
-    case 'initialize':
-      await client.initialize({
-        protocolVersion: PROTOCOL_VERSION,
-        clientCapabilities: step.terminalOutput === true ? { _meta: { terminal_output: true } } : {},
-      })
-      return
-    case 'newSession': {
-      const { sessionId } = await client.newSession({ cwd, mcpServers: [] })
-      setSessionId(sessionId)
-      return
-    }
-    case 'newSessionExpectError': {
-      // The bridge rejects a session/new that widens the workspace scope
-      // (non-empty additionalDirectories / mcpServers — unimplemented). The SDK
-      // surfaces that as a rejected RPC; swallow it so the run completes and the
-      // error frame is captured in the transcript.
-      await client.newSession({
-        cwd,
-        mcpServers: [],
-        ...step.additionalDirectories !== undefined ? { additionalDirectories: step.additionalDirectories } : {},
-      }).then(
-        () => { throw new Error('snapshot-harness: expected session/new to be rejected but it succeeded') },
-        () => { /* expected: the bridge rejected the unsupported workspace scope */ },
-      )
-      return
-    }
-    case 'prompt': {
-      const sessionId = getSessionId()
-      if (sessionId === undefined) throw new Error('snapshot-harness: prompt before newSession')
-      await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
-      return
-    }
-    case 'promptExpectError': {
-      const sessionId = getSessionId()
-      if (sessionId === undefined) throw new Error('snapshot-harness: promptExpectError before newSession')
-      // The model fails this turn (a recorded provider error), so the bridge
-      // answers the prompt with a JSON-RPC error and the SDK rejects. That
-      // rejection IS the expected editor experience — swallow it so the run
-      // completes and the stdout transcript (the error frame) is captured.
-      await client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
-        .then(() => { throw new Error('snapshot-harness: expected the prompt to fail but it succeeded') },
-          () => { /* expected: the turn failed and the bridge returned an error */ })
-      return
-    }
-    case 'promptAndCancel': {
-      const sessionId = getSessionId()
-      if (sessionId === undefined) throw new Error('snapshot-harness: promptAndCancel before newSession')
-      // Dispatch the prompt WITHOUT awaiting (a hang fixture never resolves on
-      // its own). To pin frame order deterministically, wait until the client
-      // has OBSERVED the hang's streamed agent_message_chunk before cancelling —
-      // so those update frames always precede the cancelled prompt response in
-      // the transcript (without this, the late chunk and the response race; see
-      // the Codex review of commit 5). Then cancel and await the prompt, which
-      // the bridge settles as `cancelled` once the abort propagates.
-      const promptDone = client.prompt({ sessionId, prompt: [{ type: 'text', text: step.text }] })
-      await waitForUpdate(u => u.sessionUpdate === 'agent_message_chunk')
-      await client.cancel({ sessionId })
-      await promptDone
-      return
-    }
-    case 'cancel': {
-      const sessionId = getSessionId()
-      if (sessionId === undefined) throw new Error('snapshot-harness: cancel before newSession')
-      await client.cancel({ sessionId })
-      return
-    }
-    default:
-      throw new Error(`snapshot-harness: unknown input op ${JSON.stringify(step)}`)
-  }
-}
-
-/** Resolve once the child process exits (any code/signal). */
-function waitForExit(child: ChildProcessWithoutNullStreams): Promise<void> {
-  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve()
-  return new Promise<void>(resolve => child.once('exit', () => { resolve() }))
-}
-
-/**
- * Harvest EVERY persisted `.jsonl` session log under a sessions root, parse each
- * header line, and return them ordered primary-first: the top-level session (no
- * `parentSession`) leads, then each subagent child by ascending `createdAt`.
- *
- * The JSONL backend lays sessions out as `<root>/<cwd-bucket>/<encoded-id>.jsonl`
- * (one bucket per cwd), so a parent and its same-cwd in-process child land in
- * the SAME bucket — collecting all files across all buckets catches both (the
- * old first-match short-circuit silently dropped the child). Returns `[]` if no
- * log was produced (a no-session scenario).
- */
-async function harvestSessionLogs(root: string): Promise<HarvestedLog[]> {
-  let cwdDirs: string[]
-  try {
-    cwdDirs = await readdir(root)
-  } catch {
-    return []
-  }
-  const logs: HarvestedLog[] = []
-  for (const dir of cwdDirs) {
-    const sub = join(root, dir)
-    let files: string[]
-    try {
-      files = await readdir(sub)
-    } catch {
-      continue
-    }
-    for (const f of files) {
-      if (!f.endsWith('.jsonl')) continue
-      const content = await readFile(join(sub, f), 'utf8')
-      const firstLine = content.split('\n').find(line => line.trim().length > 0) ?? '{}'
-      const header = JSON.parse(firstLine) as { id?: unknown; createdAt?: unknown; parentSession?: unknown }
-      logs.push({
-        id: typeof header.id === 'string' ? header.id : '',
-        createdAt: typeof header.createdAt === 'number' ? header.createdAt : 0,
-        ...typeof header.parentSession === 'string' ? { parentSession: header.parentSession } : {},
-        content,
-      })
-    }
-  }
-  // Primary (no parentSession) first, then children by ascending createdAt. A
-  // scenario has exactly one top-level session. In the synchronous cut sibling
-  // children are created strictly sequentially, so their createdAt values are
-  // strictly ordered; the recordedId tiebreak only keeps a degenerate
-  // same-millisecond collision (unreachable here) deterministic. This harvest
-  // order must match the replay load order in dsh-llm-replay's loadSessionScripts
-  // so session.<n>.jsonl maps to the same child on record and replay — replay
-  // re-sorts childFiles by the same key, so the two stay consistent.
-  logs.sort((a, b) => {
-    const ap = a.parentSession === undefined ? 0 : 1
-    const bp = b.parentSession === undefined ? 0 : 1
-    return ap - bp || a.createdAt - b.createdAt || a.id.localeCompare(b.id)
-  })
-  return logs
-}

examples/acp-agent/tests/snapshot-normalize.spec.ts

@@ -1,110 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { type NormalizeContext, normalizeSessionLog, normalizeStdout } from '../tests/snapshot-normalize.ts'
-
-/**
- * Unit tests for the pure snapshot normalizers. Live as a *.spec.ts (runs in
- * the default unit gate) and import the harness-side normalizers directly.
- */
-
-const ctx: NormalizeContext = {
-  sessionIds: ['11111111-2222-3333-4444-555555555555'],
-  cwd: '/tmp/acp-snap-cwd-abc123',
-}
-
-describe('normalizeStdout', () => {
-  it('rewrites JSON-RPC ids to a stable first-seen sequence', () => {
-    const raw = [
-      JSON.stringify({ jsonrpc: '2.0', id: 42, method: 'initialize' }),
-      JSON.stringify({ jsonrpc: '2.0', id: 42, result: {} }),
-      JSON.stringify({ jsonrpc: '2.0', id: 99, method: 'session/new' }),
-    ].join('\n')
-    const out = normalizeStdout(raw, ctx)
-    expect(out).toContain('"id":1')
-    expect(out).toContain('"id":2')
-    expect(out).not.toContain('42')
-    expect(out).not.toContain('99')
-  })
-
-  it('scrubs the cwd and session id anywhere they appear', () => {
-    const raw = JSON.stringify({
-      jsonrpc: '2.0', method: 'session/update',
-      params: { sessionId: ctx.sessionIds[0], cwd: ctx.cwd, note: `at ${ctx.cwd}/x` },
-    })
-    const out = normalizeStdout(raw, ctx)
-    expect(out).toContain('{{sessionId}}')
-    expect(out).toContain('{{cwd}}')
-    expect(out).not.toContain(ctx.cwd)
-    expect(out).not.toContain(ctx.sessionIds[0] as string)
-  })
-
-  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}}')
-  })
-
-  it('leaves notification frames without an id untouched in id-space', () => {
-    const raw = JSON.stringify({ jsonrpc: '2.0', method: 'session/update', params: {} })
-    const out = normalizeStdout(raw, ctx)
-    expect(out).not.toContain('"id"')
-  })
-
-  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()
-  })
-
-  it('ignores blank lines', () => {
-    const raw = `\n${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'm' })}\n\n`
-    expect(() => normalizeStdout(raw, ctx)).not.toThrow()
-  })
-})
-
-describe('normalizeSessionLog', () => {
-  const header = (over: object) => JSON.stringify({ type: 'session', version: 0, id: 's', createdAt: 123, ...over })
-  const event = (over: object) => JSON.stringify({ type: 'turn/start', seq: 1, time: 999, data: { turn: 1 }, ...over })
-
-  it('zeroes the header createdAt', () => {
-    const out = normalizeSessionLog(`${header({})}\n`, ctx)
-    expect(out).toContain('"createdAt":0')
-    expect(out).not.toContain('123')
-  })
-
-  it('zeroes each event time but keeps seq', () => {
-    const out = normalizeSessionLog(`${header({})}\n${event({ seq: 7, time: 999 })}\n`, ctx)
-    expect(out).toContain('"time":0')
-    expect(out).toContain('"seq":7') // seq is deterministic — NOT scrubbed
-    expect(out).not.toContain('999')
-  })
-
-  it('scrubs cwd and session id deep inside event data', () => {
-    const ev = JSON.stringify({
-      type: 'tool/result', seq: 2, time: 5,
-      data: { content: [{ type: 'text', text: `wrote ${ctx.cwd}/proof.txt` }] },
-    })
-    const out = normalizeSessionLog(`${header({ cwd: ctx.cwd })}\n${ev}\n`, ctx)
-    expect(out).toContain('{{cwd}}')
-    expect(out).not.toContain(ctx.cwd)
-  })
-
-  it('scrubs the session id in the header', () => {
-    const out = normalizeSessionLog(`${header({ id: ctx.sessionIds[0] })}\n`, ctx)
-    expect(out).toContain('{{sessionId}}')
-  })
-
-  it('zeroes a hook/result durationMs (run-to-run noise) but keeps its decision', () => {
-    const ev = JSON.stringify({
-      type: 'hook/result', seq: 2, time: 5,
-      data: { turn: 1, point: 'UserPromptSubmit', handlerId: 'h', decision: 'block', exitCode: 2, durationMs: 37 },
-    })
-    const out = normalizeSessionLog(`${header({})}\n${ev}\n`, ctx)
-    expect(out).toContain('"durationMs":0')
-    expect(out).not.toContain('37')
-    expect(out).toContain('"decision":"block"') // the decision is the behavior — kept
-  })
-
-  it('leaves a non-hook event durationMs untouched (only hook/result is scrubbed)', () => {
-    const ev = JSON.stringify({ type: 'tool/result', seq: 2, time: 5, data: { durationMs: 88 } })
-    const out = normalizeSessionLog(`${header({})}\n${ev}\n`, ctx)
-    expect(out).toContain('"durationMs":88')
-  })
-})

examples/acp-agent/tests/snapshot-normalize.ts

@@ -1,112 +0,0 @@
-/**
- * Pure normalizers for the ACP snapshot goldens. They replace the
- * non-deterministic values in the two captured surfaces — the stdout JSON-RPC
- * transcript and the persisted session JSONL — with stable tokens, so a golden
- * compare reflects behavior, not run-to-run noise. Kept dependency-free and
- * side-effect-free so they unit-test trivially.
- *
- * Scrubbed: `randomUUID()` session ids → `{{sessionId}}`; the temp `mkdtemp`
- * cwd → `{{cwd}}` (it appears in terminal-card `_meta` and the log header);
- * JSON-RPC request `id` → a stable per-transcript sequence; the log's per-event
- * `time` (epoch ms) and header `createdAt` → 0; a `hook/result` event's
- * `durationMs` (wall-clock hook runtime) → 0. NOT scrubbed: the log's `seq`
- * (deterministic — `seq = log.length`, part of the event-log contract).
- *
- * See docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
- */
-
-const SESSION_ID = '{{sessionId}}'
-const CWD = '{{cwd}}'
-
-/** 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
-
-/** Inputs the normalizers need to recognize a run's volatile values. */
-export interface NormalizeContext {
-  /** The session id(s) the run issued — replaced with `{{sessionId}}`. */
-  sessionIds: string[]
-  /** The temp cwd the run used — replaced with `{{cwd}}`. */
-  cwd: string
-}
-
-/** Replace cwd, session ids, and any stray UUID with stable tokens in a string. */
-function scrubString(value: string, ctx: NormalizeContext): 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)
-  for (const id of ctx.sessionIds) out = out.split(id).join(SESSION_ID)
-  out = out.replace(UUID_RE, SESSION_ID)
-  return out
-}
-
-/** 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))
-  if (value !== null && typeof value === 'object') {
-    const out: Record<string, unknown> = {}
-    for (const [k, v] of Object.entries(value)) out[k] = scrubValue(v, ctx)
-    return out
-  }
-  return value
-}
-
-/**
- * Normalize a raw stdout transcript (newline-delimited JSON-RPC frames) into a
- * stable golden in the SAME shape as the wire: one compact JSON frame per line
- * (NDJSON), with the JSON-RPC `id` rewritten to a per-transcript sequence
- * (1, 2, 3, …) and all volatile strings scrubbed. Throws if any non-empty line
- * is not valid JSON — that doubles as the stdout-purity check (no logger leaked
- * onto the protocol).
- */
-export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): string {
-  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 golden.
-  const idSeq = new Map<string, number>()
-  const stableId = (id: unknown): number => {
-    const key = JSON.stringify(id)
-    let n = idSeq.get(key)
-    if (n === undefined) { n = idSeq.size + 1; idSeq.set(key, n) }
-    return n
-  }
-  const frames = lines.map((line) => {
-    const frame = JSON.parse(line) as Record<string, unknown>
-    if ('id' in frame && frame.id !== undefined && frame.id !== null) {
-      frame.id = stableId(frame.id)
-    }
-    return scrubValue(frame, ctx) as Record<string, unknown>
-  })
-  return frames.map(f => JSON.stringify(f)).join('\n') + '\n'
-}
-
-/**
- * Normalize a session JSONL log into a stable golden: the header line's
- * volatile fields (`createdAt`, `id`, `cwd`) and every event's `time` are
- * zeroed/scrubbed, all volatile strings scrubbed, and `seq` is LEFT INTACT
- * (deterministic by contract). Output is JSONL in the same shape as the input —
- * one compact record per line.
- */
-export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): string {
-  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>
-    // Header line: { type: 'session', createdAt, id, cwd, … }.
-    if (record.type === 'session') {
-      if ('createdAt' in record) record.createdAt = 0
-    } else if ('time' in record) {
-      // Event line: zero the epoch-ms timestamp; keep seq (deterministic).
-      record.time = 0
-      // A hook/result carries the hook's wall-clock runtime (`data.durationMs`),
-      // which is run-to-run noise like `time` — zero it so the golden reflects
-      // the hook's decision/exit, not how long the shell took.
-      if (record.type === 'hook/result' && record.data !== null && typeof record.data === 'object') {
-        const data = record.data as Record<string, unknown>
-        if ('durationMs' in data) data.durationMs = 0
-      }
-    }
-    return scrubValue(record, ctx) as Record<string, unknown>
-  })
-  return records.map(r => JSON.stringify(r)).join('\n') + '\n'
-}

examples/acp-agent/tests/snapshots/fs-policy-reject/stdout.golden.jsonl

@@ -137,7 +137,7 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" use"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" with"}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" perl"}}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" awk"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" to"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" replace"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" \""}}}}
@@ -152,7 +152,7 @@
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" the"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" file"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"."}}}}
-{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_SvvpTh6bWybYXoO77NHg8535","title":"perl -0pi -e 's/blue/green/g' settings.txt","kind":"execute","status":"in_progress","rawInput":"perl -0pi -e 's/blue/green/g' settings.txt","content":[{"type":"content","content":{"type":"text","text":"Replace blue with green in settings.txt"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_00_SvvpTh6bWybYXoO77NHg8535","title":"awk '{gsub(/blue/,\"green\")}1' settings.txt > settings.tmp && mv settings.tmp settings.txt","kind":"execute","status":"in_progress","rawInput":"awk '{gsub(/blue/,\"green\")}1' settings.txt > settings.tmp && mv settings.tmp settings.txt","content":[{"type":"content","content":{"type":"text","text":"Replace blue with green in settings.txt"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_00_SvvpTh6bWybYXoO77NHg8535","status":"completed","content":[{"type":"content","content":{"type":"text","text":"```console\n(no output)\n```"}}]}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":"The"}}}}
 {"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_thought_chunk","content":{"type":"text","text":" bash"}}}}

examples/acp-agent/tests/snapshots/repeat-tool-guard/input.json

@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Write the todo list 'watch the kettle boil' five times in a row without changing it, then reply DONE." }
+  ]
+}

examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl

@@ -0,0 +1,70 @@
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":0,"cwd":"{{cwd}}"}
+{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Write the todo list 'watch the kettle boil' five times in a row without changing it, then reply DONE."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"call_1","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":11,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"callId":"call_1","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
+{"type":"step/end","seq":13,"time":0,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":14,"time":0,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"call_2","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":20,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[15,16,17,18,19],"surfaceOp":"append"}
+{"type":"tool/call","seq":21,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":22,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":23,"time":0,"data":{"turn":1,"step":2,"callId":"call_2","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[21],"surfaceOp":"append"}
+{"type":"step/end","seq":24,"time":0,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":25,"time":0,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"call_3","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":31,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[26,27,28,29,30],"surfaceOp":"append"}
+{"type":"tool/call","seq":32,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":33,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":34,"time":0,"data":{"turn":1,"step":3,"callId":"call_3","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[32],"surfaceOp":"append"}
+{"type":"context/message","seq":35,"time":0,"data":{"content":[{"type":"text","text":"You are repeating the exact same tool call with identical arguments. Carefully analyze the previous result before calling again: if the task is not complete, try a different approach or different arguments instead of repeating the call."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"step/end","seq":36,"time":0,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":37,"time":0,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"call_4","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":40,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":41,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":42,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":43,"time":0,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[38,39,40,41,42],"surfaceOp":"append"}
+{"type":"tool/call","seq":44,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":45,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":46,"time":0,"data":{"turn":1,"step":4,"callId":"call_4","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[44],"surfaceOp":"append"}
+{"type":"step/end","seq":47,"time":0,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":48,"time":0,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":50,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"call_5","name":"todo_write","argumentsDelta":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}
+{"type":"assistant/chunk","seq":51,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}}}
+{"type":"assistant/chunk","seq":52,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}}}
+{"type":"assistant/chunk","seq":53,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":54,"time":0,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}],"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[49,50,51,52,53],"surfaceOp":"append"}
+{"type":"tool/call","seq":55,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","name":"todo_write","arguments":"{\"todos\": [{\"content\": \"watch the kettle boil\", \"status\": \"in_progress\"}]}"}}
+{"type":"todo/write","seq":56,"time":0,"data":{"todos":[{"content":"watch the kettle boil","status":"in_progress"}]}}
+{"type":"tool/result","seq":57,"time":0,"data":{"turn":1,"step":5,"callId":"call_5","content":[{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}],"isError":false},"sourceEventSeqs":[55],"surfaceOp":"append"}
+{"type":"context/message","seq":58,"time":0,"data":{"content":[{"type":"text","text":"Repeated tool call detected:\n- tool: todo_write\n- consecutive_calls: 5\n- arguments: {\"todos\":[{\"content\":\"watch the kettle boil\",\"status\":\"in_progress\"}]}\nThe repeated calls are not making progress. Do not call this tool with these exact arguments again. Inspect the latest result and choose a different action, different arguments, or finish the task if enough evidence has been gathered."}],"source":{"kind":"plugin","plugin":"repeat-tool-guard"}},"surfaceOp":"append"}
+{"type":"step/end","seq":59,"time":0,"data":{"turn":1,"step":5}}
+{"type":"step/start","seq":60,"time":0,"data":{"turn":1,"step":6}}
+{"type":"assistant/chunk","seq":61,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"DONE."}}}
+{"type":"assistant/chunk","seq":63,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE."}}}}
+{"type":"assistant/chunk","seq":64,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":65,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":66,"time":0,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"DONE."}],"usage":{"inputTokens":10,"outputTokens":3}},"sourceEventSeqs":[61,62,63,64,65],"surfaceOp":"append"}
+{"type":"step/end","seq":67,"time":0,"data":{"turn":1,"step":6}}
+{"type":"turn/end","seq":68,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}

examples/acp-agent/tests/snapshots/repeat-tool-guard/stdout.golden.jsonl

@@ -0,0 +1,19 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_1","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_1","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_2","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_2","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_3","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_3","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_4","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_4","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"call_5","title":"Update todo list","kind":"other","status":"in_progress","rawInput":[{"content":"watch the kettle boil","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"plan","entries":[{"content":"watch the kettle boil","priority":"medium","status":"in_progress"}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"call_5","status":"completed","content":[{"type":"content","content":{"type":"text","text":"Updated todo list: 0 pending, 1 in progress, 0 completed."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"DONE."}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}

examples/coding-agent/tests/compaction.e2e.ts

@@ -43,8 +43,8 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     // A handful of files for the model to read, so multiple bash steps
     // accumulate surface nodes (tool calls + results) and grow the history past
     // the (deliberately tiny) window.
-    for (let i = 1; i <= 6; i++) {
-      await writeFile(join(workdir, `file${i}.txt`), `This is file number ${i}. `.repeat(40))
+    for (let i = 1; i <= 4; i++) {
+      await writeFile(join(workdir, `file${i}.txt`), `This is file number ${i}. `.repeat(50))
     }
 
     // Tiny window so a couple of steps crosses the threshold. The generation
@@ -55,21 +55,21 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     ctx = await codingHarness(workdir, {
       persona: SYSTEM_PROMPT,
       compact: {
-        contextWindow: 2400,
+        contextWindow: 2000,
         thresholdRatio: 0.5,
-        retainTokens: 500,
+        retainTokens: 400,
         summarizationModel: '',
-        maxTokens: 2048,
+        maxTokens: 1024,
         compactionRetries: 1,
       },
-      persistenceRoot: './.sessions',
+      persistenceRoot: join(workdir, '.sessions'),
     })
     const agent = ctx.agentLoop.create(AgentId('e2e-compaction'), { model: 'deepseek-v4-flash' })
 
     agent.send([{
       type: 'text',
-      text: 'Read file1.txt, file2.txt, file3.txt, file4.txt, file5.txt, and file6.txt one at a '
-        + 'time using cat (a separate bash command for each). After reading all six, tell me how '
+      text: 'Read file1.txt, file2.txt, file3.txt, and file4.txt one at a '
+        + 'time using cat (a separate bash command for each). After reading all four, tell me how '
         + 'many files you read and the number mentioned in file1.txt.',
     }])
     await waitForIdle(ctx, agent)
@@ -98,9 +98,9 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     expect(summaryData.shadowedSeqs.length).toBeGreaterThan(0)
 
     // The conversation survived compaction: the agent produced a final answer
-    // that reflects the work (it read six files).
+    // that reflects the work (it read four files).
     const answer = finalText(events).toLowerCase()
     expect(answer.length).toBeGreaterThan(0)
-    expect(answer).toMatch(/\b(6|six)\b/)
+    expect(answer).toMatch(/\b(4|four)\b/)
   }, 240_000)
 })

examples/coding-agent/tests/full-loop.e2e.ts

@@ -1,3 +1,6 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
 import { AgentId } from '@deepseek-ai/dsh-agent'
@@ -9,6 +12,7 @@ import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness.
  */
 
 let ctx: Context | undefined
+let workdir: string | undefined
 
 afterEach(async () => {
   // Always dispose the harness, even on failure/retry/timeout: agent-loop
@@ -16,11 +20,14 @@ afterEach(async () => {
   // process the model left behind.
   await ctx?.fiber.dispose()
   ctx = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
 })
 
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('full loop: real model + real bash tool', () => {
   it('runs a bash command on request and reports its output', async () => {
-    ctx = await codingHarness(process.cwd(), { persona: SYSTEM_PROMPT })
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-full-loop-e2e-'))
+    ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
     const agent = ctx.agentLoop.create(AgentId('e2e-loop'), { model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text: 'Run `echo e2e-ok` with the bash tool and tell me its exact output.' }])

examples/coding-agent/tests/todo-write.e2e.ts

@@ -1,3 +1,6 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
 import { AgentId } from '@deepseek-ai/dsh-agent'
@@ -10,15 +13,19 @@ import { codingHarness, TODO_SYSTEM_PROMPT, waitForIdle } from './harness.ts'
  */
 
 let ctx: Context | undefined
+let workdir: string | undefined
 
 afterEach(async () => {
   await ctx?.fiber.dispose()
   ctx = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
 })
 
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a plan', () => {
   it('appends a todo/write event with the model-produced task list', async () => {
-    ctx = await codingHarness(process.cwd(), { persona: TODO_SYSTEM_PROMPT })
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-todo-write-e2e-'))
+    ctx = await codingHarness(workdir, { persona: TODO_SYSTEM_PROMPT })
     const agent = ctx.agentLoop.create(AgentId('e2e-todo'), { model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text:

examples/cordis-agent/README.md

@@ -0,0 +1,33 @@
+# cordis-agent
+
+The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md).
+
+## Run it
+
+```sh
+# repo root .env (gitignored) or exported env:
+#   DEEPSEEK_API_KEY=sk-…
+#   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
+pnpm run demo:cordis
+```
+
+The intended demo is staged — verify the listener link first, then let the agent extend itself:
+
+```
+> Mount a plugin that listens to the 'agent/status' event and logs every status change, then run `echo hi` with bash.
+  [tool call] cordis_mount({"code": "return { name: 'status-logger', apply(ctx) { ctx.on('agent/status', (agent, status) => console.log('status →', status)) } }"})
+  [tool result] mounted dyn-1 (plugin "status-logger", state: active)
+  [tool call] bash({"command": "echo hi"})
+[cordis:dyn-1] status → …            ← the mounted listener firing, live
+> Now give yourself a reverse_text tool and use it on "harness".
+  [tool call] cordis_mount({"code": "return { name: 'reverse-text', inject: ['tools'], apply(ctx) { ctx.tools.register(harness.defineTool({ name: 'reverse_text', … })) } }"})
+  [tool call] reverse_text({"text": "harness"})   ← a tool the agent built for itself, one step earlier
+> Unmount both.
+  [tool call] cordis_unmount({"id": "dyn-1"})
+```
+
+Ask for `cordis_inspect` with `what: "api"` or `what: "events"` to see the generated service/event reference the agent writes plugin code against, and try two cooperating mounts (`ctx.provide` in one, `inject` in the other) to watch cordis park and revive the consumer.
+
+## End-to-end tests
+
+`tests/keyless-smoke.e2e.ts` boots the real `cordis.yml` through the Loader with a dummy key and asserts the banner + clean EOF exit (the export-shape / real-load-path guard, now across the package-name resolution). `tests/cordis-tools.e2e.ts` is the with-key smoke: a real model mounts a status listener (asserting the tagged console line actually fires — the world, not the agent's claim), builds itself a `reverse_text` tool and uses it, and composes two mounts via provide/inject. The tool logic itself is unit-tested in [`packages/cordis/tool-cordis`](../../packages/cordis/tool-cordis) under the per-file 100% coverage gate.

examples/cordis-agent/composition.md

@@ -0,0 +1,49 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Cordis Agent App Composition
+
+The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its own runtime and mount/unmount plugins into it.
+
+```mermaid
+flowchart LR
+  cfg["examples/cordis-agent<br/>cordis.yml"]
+  plugin_cordis_hmr["hmr<br/>@cordisjs/plugin-hmr"]
+  cfg --> plugin_cordis_hmr
+  plugin_cordis_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_cordis_llm_deepseek
+  plugin_cordis_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_cordis_bash
+  plugin_cordis_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_cordis_fs_local
+  plugin_cordis_web["web<br/>@deepseek-ai/dsh-web"]
+  cfg --> plugin_cordis_web
+  plugin_cordis_web_fetch_local["web-fetch-local<br/>@deepseek-ai/dsh-web-fetch-local"]
+  cfg --> plugin_cordis_web_fetch_local
+  plugin_cordis_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  cfg --> plugin_cordis_stdio_agent
+  plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_cordis_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_cordis_tool_cordis["tool-cordis<br/>@deepseek-ai/dsh-tool-cordis"]
+  cfg --> plugin_cordis_tool_cordis
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `hmr` | `@cordisjs/plugin-hmr` |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `web` | `@deepseek-ai/dsh-web` |
+| `web-fetch-local` | `@deepseek-ai/dsh-web-fetch-local` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` |
+
+Source config: [`examples/cordis-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.

examples/cordis-agent/cordis.yml

@@ -0,0 +1,83 @@
+# The cordis-agent plugin tree: the SELF-REFERENTIAL harness demo. Same spine
+# as coding-agent (DeepSeek V4 + local bash on @deepseek-ai/dsh-stdio-agent),
+# plus @deepseek-ai/dsh-tool-cordis, which gives the model three tools over the
+# live cordis runtime it is running inside: cordis_inspect (services / plugin
+# tree / tools / dynamic mounts / api / events), cordis_mount (evaluate
+# model-written code in a vm sandbox and mount the returned plugin under the
+# `cordis-dynamic` group), and cordis_unmount (dispose one mount by id).
+# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) — the
+# dsh-stdio-agent bin loads the gitignored repo-root .env first.
+#
+# Trust stance (docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md):
+# the mounted code gets the REAL ctx — the
+# vm sandbox only prevents accidental global pollution. Load the toolset as
+# deliberately as you would grant a bash tool.
+
+# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
+- id: hmr
+  name: '@cordisjs/plugin-hmr'
+  config:
+    root: ['.']
+
+# The DeepSeek adapter.
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-pro
+      - deepseek-v4-flash
+
+# Local bash executor for agent-core's tool-bash schema — gives the agent an
+# ordinary tool whose calls make the mounted listeners observably fire.
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    timeoutMs: 60000
+
+# Filesystem service for mounted plugins (ctx.fs) — the local provider only.
+# The model-facing read/write/edit tools stay unmounted on purpose: this demo
+# is about the agent building its own tools over the services.
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+# Web service for mounted plugins (ctx.web): the seam plus the anonymous local
+# fetch provider (keyless). No search provider is loaded — ctx.web search
+# calls fail loud until a deployment adds one.
+- id: web
+  name: '@deepseek-ai/dsh-web'
+
+- id: web-fetch-local
+  name: '@deepseek-ai/dsh-web-fetch-local'
+
+# The stdio chat app: the whole spine + front-door cluster, configured for the
+# self-referential demo driving a pre-created `main` agent.
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+    resumeSessionId: !!js process.env.RESUME_SESSION_ID
+    persistenceRoot: './.sessions'
+    welcome: 'cordis-agent ready. Ask it to inspect its runtime, mount a listener, or invent a tool for itself.'
+    persona: |
+      You are cordis-agent, a self-referential harness demo powered by the
+      {{model}} model.
+
+      You run INSIDE a cordis plugin runtime, and your cordis_* tools operate
+      on that live runtime: cordis_inspect to look around (its `api` and
+      `events` sections document the service methods, type shapes, and events
+      your plugin code can use), cordis_mount to add a plugin (an event
+      listener, a brand-new tool for yourself, or a service other mounts
+      inject), cordis_unmount to clean one up. In mounted code, NEVER use Node
+      built-ins (require/setTimeout/fetch) — use the runtime's cordis services
+      via inject: fs, web, bash, and timer (ctx.setTimeout). Prefer small
+      single-purpose plugins, prefer plain notification events over waterfall
+      events unless you intend to intercept, and unmount what you no longer
+      need. Report results briefly.
+
+# The self-referential cordis toolset (loaded after the app so ctx.tools exists).
+- id: tool-cordis
+  name: '@deepseek-ai/dsh-tool-cordis'

examples/cordis-agent/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "cordis-agent-example",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Runnable demo: the self-referential harness — an agent that inspects and modifies its own cordis runtime"
+}

examples/cordis-agent/tests/cordis-tools.e2e.ts

@@ -0,0 +1,156 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { cordisHarness, waitForIdle } from './harness.ts'
+
+/**
+ * With-key smoke for the self-referential cordis tools: a REAL model drives
+ * cordis_mount/cordis_unmount against the live context the test observes.
+ * World-verified, not self-reported: the mounted listener must actually WRITE
+ * its tagged console line, the self-made tool must actually EXIST in the
+ * registry and appear as a real `tool/call`, the cross-mount service must
+ * actually LAND in the reflect store. Key-gated (see vitest.e2e.config.ts).
+ */
+
+let ctx: Context | undefined
+
+afterEach(async () => {
+  vi.restoreAllMocks()
+  // Always dispose the harness, even on failure/retry/timeout: agent-loop
+  // teardown stops the loop, and disposing the tree unwinds every dynamic
+  // mount the model left behind.
+  await ctx?.fiber.dispose()
+  ctx = undefined
+})
+
+/** The tagged write-through lines (`[cordis:dyn-n] …`) captured by a console spy. */
+function taggedCalls(log: { mock: { calls: unknown[][] } }): unknown[][] {
+  return log.mock.calls.filter(call => typeof call[0] === 'string' && /^\[cordis:dyn-\d+\]$/.test(call[0]))
+}
+
+/** Model-facing text of one tool result, concatenated. */
+function resultText(result: { content: { type: string; text?: string }[] }): string {
+  return result.content.filter(block => block.type === 'text').map(block => block.text).join('')
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modifies its own runtime', () => {
+  it('mounts a status listener whose tagged output actually fires, then unmounts it', async () => {
+    ctx = await cordisHarness()
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    const agent = ctx.agentLoop.create(AgentId('cordis-e2e-listener'), { model: 'deepseek-v4-flash' })
+
+    agent.send([{
+      type: 'text',
+      text: 'Use cordis_mount to mount a plugin that listens to the \'agent/status\' '
+        + 'cordis event and logs every change with console.log. Reply "mounted" once done.',
+    }])
+    await waitForIdle(ctx, agent)
+
+    // The WORLD check: the turn's own running→idle transition must have driven
+    // the mounted listener through the tagged sandbox console.
+    expect(taggedCalls(log).length).toBeGreaterThan(0)
+    const mid = await ctx.tools.execute({
+      callId: CallId('verify-mounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' },
+    })
+    expect(resultText(mid)).toContain('dyn-')
+
+    agent.send([{ type: 'text', text: 'Now unmount the plugin you just mounted.' }])
+    await waitForIdle(ctx, agent)
+
+    const after = await ctx.tools.execute({
+      callId: CallId('verify-unmounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' },
+    })
+    expect(resultText(after)).toContain('(no dynamic plugins mounted)')
+  }, 120_000)
+
+  it('builds itself a reverse_text tool and actually calls it', async () => {
+    ctx = await cordisHarness()
+    const agent = ctx.agentLoop.create(AgentId('cordis-e2e-selftool'), { model: 'deepseek-v4-flash' })
+
+    agent.send([{
+      type: 'text',
+      text: 'Give yourself a new tool: use cordis_mount to mount a plugin with '
+        + 'inject ["tools"] that calls harness.registerTool(ctx, harness.defineTool({...})) '
+        + 'to register a tool named reverse_text with one required string parameter '
+        + '"text", returning the text reversed. Then CALL reverse_text with the '
+        + 'exact text "harness" and report its exact output.',
+    }])
+    await waitForIdle(ctx, agent)
+
+    // World checks: the tool exists in the registry, was invoked as a real
+    // tool call, and its RESULT (the self-made execute actually running) is the
+    // reversed string. The model's prose is not asserted — the tool result is
+    // the world; the summary sentence is just the self-report.
+    expect(ctx.tools.get('reverse_text')).toBeDefined()
+    const events = [...agent.session.events]
+    const calls = events.filter(event => event.type === 'tool/call')
+    expect(calls.some(event => event.data.name === 'cordis_mount')).toBe(true)
+    const reverseCalls = calls.filter(event => event.data.name === 'reverse_text')
+    expect(reverseCalls.length).toBeGreaterThan(0)
+    const reverseResults = events
+      .filter(event => event.type === 'tool/result')
+      .filter(event => reverseCalls.some(call => call.data.callId === event.data.callId))
+      .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text))
+    // On failure, surface what the model actually mounted and what the tool
+    // returned — an e2e failing at a distance is undebuggable without it.
+    const mountCode = calls
+      .filter(event => event.data.name === 'cordis_mount')
+      .map(event => event.data.arguments)
+      .join('\n---\n')
+    const trace = events.map((event) => {
+      switch (event.type) {
+        case 'tool/call': return `tool/call:${event.data.name}`
+        case 'tool/result': return `tool/result:${event.data.isError ? 'ERR:' + JSON.stringify(event.data.content).slice(0, 200) : 'ok'}`
+        case 'turn/end': return `turn/end:${JSON.stringify(event.data.reason)}`
+        default: return event.type
+      }
+    }).join('\n')
+    expect(
+      reverseResults.some(text => text.includes('ssenrah')),
+      `no reversed output in reverse_text results.\nresults: ${JSON.stringify(reverseResults)}\nmount code: ${mountCode}\ntrace:\n${trace}`,
+    ).toBe(true)
+  }, 120_000)
+
+  it('composes two mounts through provide/inject, and unmounting the provider parks the consumer', async () => {
+    ctx = await cordisHarness()
+    const agent = ctx.agentLoop.create(AgentId('cordis-e2e-compose'), { model: 'deepseek-v4-flash' })
+
+    agent.send([{
+      type: 'text',
+      text: 'Mount TWO separate plugins with cordis_mount. First a provider: apply calls '
+        + 'ctx.provide(\'shouter\', { shout: (s) => s.toUpperCase() }). Second a consumer with '
+        + 'inject ["shouter", "tools"] that registers (via harness.registerTool + harness.defineTool) '
+        + 'a tool named shout_text with one required string parameter "text" whose execute returns '
+        + 'ctx.shouter.shout(args.text) as a text content block. Then CALL shout_text with "quiet" '
+        + 'and report the exact output.',
+    }])
+    await waitForIdle(ctx, agent)
+
+    // World checks: the service is really in the store, the tool really ran.
+    expect(ctx.get('shouter')).toBeDefined()
+    expect(ctx.tools.get('shout_text')).toBeDefined()
+    const events = [...agent.session.events]
+    const shoutCalls = events
+      .filter(event => event.type === 'tool/call')
+      .filter(event => event.data.name === 'shout_text')
+    expect(shoutCalls.length).toBeGreaterThan(0)
+    const shoutResults = events
+      .filter(event => event.type === 'tool/result')
+      .filter(event => shoutCalls.some(call => call.data.callId === event.data.callId))
+      .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text))
+    expect(shoutResults.some(text => text.includes('QUIET'))).toBe(true)
+
+    agent.send([{ type: 'text', text: 'Now unmount ONLY the provider plugin (the one that provided shouter).' }])
+    await waitForIdle(ctx, agent)
+
+    // The consumer must have been parked by cordis itself: service gone,
+    // dependent tool unregistered, dynamic table naming the missing service.
+    expect(ctx.get('shouter')).toBeUndefined()
+    expect(ctx.tools.get('shout_text')).toBeUndefined()
+    const after = await ctx.tools.execute({
+      callId: CallId('verify-parked'), name: 'cordis_inspect', arguments: { what: 'dynamic' },
+    })
+    expect(resultText(after)).toContain('waiting for: shouter')
+  }, 120_000)
+})

examples/cordis-agent/tests/harness.ts

@@ -0,0 +1,46 @@
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
+
+/**
+ * Shared harness for the cordis-agent e2e suite: the agent spine with the real
+ * DeepSeek adapter and the real `@deepseek-ai/dsh-tool-cordis` plugin, so a
+ * live model can mount plugins into the very context the test observes. Lives
+ * outside the *.e2e.ts pattern so importing it never re-registers another
+ * file's tests.
+ */
+
+const PERSONA = 'You are cordis-agent, a self-referential harness demo. '
+  + 'Your cordis_* tools operate on the live cordis runtime you run inside: '
+  + 'cordis_inspect to look around, cordis_mount to add a plugin, cordis_unmount '
+  + 'to clean one up. Follow the tool descriptions exactly and report results briefly.'
+
+export async function cordisHarness(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt, { persona: PERSONA })
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await ctx.plugin(ToolCordis)
+  return ctx
+}
+
+export function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}

examples/cordis-agent/tests/keyless-smoke.e2e.ts

@@ -0,0 +1,94 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * Keyless Loader-path smoke for examples/cordis-agent: boot the REAL example
+ * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` —
+ * the cordis Loader, `unwrapExports`, the full plugin tree INCLUDING the
+ * `@deepseek-ai/dsh-tool-cordis` package resolved by name (whose `inject`
+ * would crash a collapsed export shape at load, see docs/postmortem/0001) —
+ * then close stdin with no prompt and assert the ready banner + a clean exit.
+ *
+ * No prompt is ever sent, so the model is NEVER called — that is why it runs
+ * without a real key: `llm-deepseek`'s apply() only requires a key to be
+ * PRESENT, and the absence of any prompt guarantees no network call. The
+ * with-key product proof lives in cordis-tools.e2e.ts.
+ */
+
+// The dsh-stdio-agent bin (the demo:cordis entry) and this example's cordis.yml.
+// The bin resolves its config-path arg from CWD; the test spawns from a temp
+// cwd, so we pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
+// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
+// the repo, so point it at the repo tsconfig (root is three levels up).
+const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+let child: ChildProcessWithoutNullStreams | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
+  child = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function bootAndEof(): Promise<{ stdout: string; code: number }> {
+  workdir = await mkdtemp(join(tmpdir(), 'cordis-smoke-'))
+  const cwd = workdir
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      process.execPath,
+      // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:cordis).
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
+      {
+        cwd,
+        env: {
+          ...process.env,
+          TSX_TSCONFIG_PATH: repoTsconfig,
+          // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots.
+          // No prompt is sent, so the adapter never streams — no network call.
+          DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      },
+    )
+    child = proc
+    let stdout = ''
+    let stderr = ''
+    proc.stdout.setEncoding('utf8')
+    proc.stdout.on('data', (chunk: string) => { stdout += chunk })
+    proc.stderr.setEncoding('utf8')
+    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
+
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL')
+      reject(new Error(`cordis-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 10_000)
+
+    proc.on('exit', (code) => {
+      clearTimeout(timer)
+      if (code === 0) resolve({ stdout, code })
+      else reject(new Error(`cordis-agent exited ${code}. stderr:\n${stderr}`))
+    })
+    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
+
+    // No prompt — just EOF, so the stdio UI exits without ever running a turn.
+    proc.stdin.end()
+  })
+}
+
+describe('cordis-agent keyless smoke (real cordis.yml via the Loader)', () => {
+  it('boots the full plugin tree incl. tool-cordis, prints its banner, and exits cleanly on EOF', async () => {
+    const { stdout, code } = await bootAndEof()
+    expect(code).toBe(0)
+    expect(stdout).toContain('cordis-agent ready.')
+  }, 15_000)
+})