Merge remote-tracking branch 'origin/master' into codex/truncated-design

# Conflicts:
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	docs/tool-catalog.md
#	examples/acp-agent/README.md
#	packages/README.md
#	packages/bash/bash/README.md
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	packages/support/acp-snapshot/src/harness.ts
#	pnpm-lock.yaml
#	scripts/gen-doc-graphs.ts
#	scripts/gen-tool-catalog.ts
#	scripts/type-equiv.manifest.json

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

@@ -1,15 +1,16 @@
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
-import { defineAcpSnapshotSuite, type Scenario } from '@deepseek-ai/dsh-acp-snapshot'
+import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from '@deepseek-ai/dsh-acp-snapshot'
 
 /**
  * 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
+ * (golden + re-persisted-log diffs, record/refresh 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.
+ * `pnpm run test:snapshot:record` re-records model transcripts against the real
+ * API; `pnpm run test:snapshot:refresh` rewrites current replay goldens keyless.
+ * See the package README (packages/support/acp-snapshot) and the snapshot RFC,
+ * docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
  */
 
 // The dsh-acp-agent bin (the demo:acp entry), this example's cordis.yml, and
@@ -21,17 +22,37 @@ const AGENT = {
   tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
 }
 
+// The Code Mode overlay configs (include-patched variants of cordis.yml; the
+// replay swap resolves each one's sibling `*cordis.snapshot.yml`).
+const CODE_MODE_CONFIG = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url))
+const BOTH_MODE_CONFIG = fileURLToPath(new URL('../both-mode.cordis.yml', import.meta.url))
+
+function snapshotModeFromEnv(value: string | undefined): SnapshotSuiteOptions['mode'] {
+  switch (value) {
+    case undefined:
+    case '':
+    case 'replay':
+      return 'replay'
+    case 'record':
+      return 'record'
+    case 'refresh':
+      return 'refresh'
+    default:
+      throw new Error(`unknown DSH_SNAPSHOT mode: ${value}`)
+  }
+}
+
 const SCENARIOS: Scenario[] = [
   { name: 'handshake', hasModelTurn: false, recorded: false },
   { name: 'reject-extra-dirs', hasModelTurn: false, recorded: false },
-  // 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.
+  // text-turn is the pinned-header scenario: the minimal single text turn.
+  // Its system-prompt.golden.md and JSONL tool list pin the composed header.
   { name: 'text-turn', hasModelTurn: true, recorded: true, pinsHeader: true },
   { name: 'tool-call-turn', hasModelTurn: true, recorded: true },
   { name: 'bash-spill', hasModelTurn: true, recorded: false },
   { name: 'fs-terminal-card', hasModelTurn: true, recorded: true },
   { name: 'todo-plan', hasModelTurn: true, recorded: true },
+  { name: 'skill-load', hasModelTurn: true, recorded: false, pinsHeader: true, headerClass: 'skill' },
   { name: 'workspace-edit', hasModelTurn: true, recorded: true },
   { name: 'fs-read', hasModelTurn: true, recorded: true },
   { name: 'fs-write', hasModelTurn: true, recorded: true },
@@ -51,6 +72,10 @@ const SCENARIOS: Scenario[] = [
   { name: 'subagent-multi', hasModelTurn: true, recorded: true, childSessions: 2 },
   { name: 'subagent-fork', hasModelTurn: true, recorded: true, childSessions: 1 },
   { name: 'subagent-mixed', hasModelTurn: true, recorded: true, childSessions: 2 },
+  // The workflow tool: the model writes a one-child orchestration script; the
+  // child runs as a spawn subagent under the worker-thread engine (its session is the
+  // child fixture), and the tool result carries the script's return value.
+  { name: 'workflow-run', hasModelTurn: true, recorded: true, childSessions: 1 },
   // Hook matrix — one scenario per hook point × its headline Decision outcome,
   // across BOTH bridges (Claude `hooks.json`, Codex `codex-hooks.json`, seeded in
   // workspace/). The block scenarios need no model call: a UserPromptSubmit hook
@@ -90,11 +115,18 @@ const SCENARIOS: Scenario[] = [
   { name: 'hook-codex-posttool-block', hasModelTurn: true, recorded: true },
   { name: 'hook-codex-posttool-context', hasModelTurn: true, recorded: true },
   { name: 'hook-codex-stop-continue', hasModelTurn: true, recorded: true },
+  // Code Mode: the registry in `mode: code` — the wire tool list collapses to
+  // [run_code], the tools:sdk section rides in the prompt, and the program's
+  // tool calls land as tool/code-dispatch events. Each mode boots its own
+  // overlay config, composes a different header by construction, and
+  // therefore pins its own class.
+  { name: 'code-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'code', configPath: CODE_MODE_CONFIG },
+  { name: 'both-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'both', configPath: BOTH_MODE_CONFIG },
 ]
 
 defineAcpSnapshotSuite({
   agent: AGENT,
   snapshotsDir: join(dirname(fileURLToPath(import.meta.url)), 'snapshots'),
   scenarios: SCENARIOS,
-  mode: process.env.DSH_SNAPSHOT === 'record' ? 'record' : 'replay',
+  mode: snapshotModeFromEnv(process.env.DSH_SNAPSHOT),
 })