@catheadowl/dsh-eval 0.1.0

package/docs/host-wiring.md

@@ -0,0 +1,71 @@
+---
+description: 安装与宿主接线——dsh-llm peer 的三形解析结局与 junction 步骤、构建 CLI 与 profile/凭证/spawn 三类运行前置
+---
+
+# 安装与宿主接线
+
+`@catheadowl/dsh-eval` 是 dsh 生态的开发期工具：它驱动真实 dsh headless 会话来评测 dsh 插件，因此对宿主有三类依赖——包管理面（peer）、运行面（构建好的 dsh CLI）、环境面（profile 与凭证）。
+
+## Install
+
+```bash
+npm i -D @catheadowl/dsh-eval
+# 或 pnpm add -D @catheadowl/dsh-eval
+```
+
+装好后 `node_modules/.bin` 里出现两个 CLI：`dsh-eval`（behavior case）与 `dsh-review`（comprehension review）。
+
+## peer 依赖：`@deepseek-ai/dsh-llm` 的接线契约
+
+本包声明 `peerDependencies: { "@deepseek-ai/dsh-llm": "*" }`——运行时由 dsh 宿主生态提供，包自身不携带。消费态解析有**三形结局**：
+
+1. **缺包形**（pnpm `file:` 安装态）：mock case 报 `ERR_MODULE_NOT_FOUND: Cannot find package '@deepseek-ai/dsh-llm'`，`imported from` 锚在 `node_modules/.pnpm/@catheadowl+dsh-eval.../` 内——上溯链止于虚拟 store 是本契约的特征指纹，不是本包缺陷。
+2. **古董 peer 形**（npm 安装态，更隐蔽）：npm ≥7 会**自动安装 peerDependencies**，而 `@deepseek-ai/dsh-llm` 的 registry `latest` dist-tag 停在 `0.0.1-rc.1`——与宿主现行 API 不兼容。症状：boot 报 `dsh: UNKNOWN: registration.adapter.prepareCall is not a function`，case exit 1、无 assistant 文本。装了错版本比没装更难排查。
+3. **正确形**：把 `node_modules/@deepseek-ai/dsh-llm` 替换为指向宿主 checkout 内对应包的目录链接（Windows junction），或安装时 `--legacy-peer-deps` 阻止自动装后再接。
+
+**接线步骤**（消费者根目录，Windows）：
+
+```powershell
+Remove-Item -Recurse -Force node_modules\@deepseek-ai\dsh-llm   # 若被自动装了
+New-Item -ItemType Junction -Path node_modules\@deepseek-ai\dsh-llm `
+  -Target <dsh checkout>\apps\cli\node_modules\@deepseek-ai\dsh-llm
+```
+
+**自诊断**：
+
+```bash
+node -e "import('@deepseek-ai/dsh-llm').then(() => console.log('ok'), e => console.log(e.code))"
+node -e "console.log(require('./node_modules/@deepseek-ai/dsh-llm/package.json').version)"
+```
+
+第一条打印 `ok` = 解析链通；第二条核对版本——若为 `0.0.1-rc.1` 即 registry 古董副本，按上节替换。接线是机器相关的部署前提，不入库（gitignore 或本地脚本承接）。
+
+## 运行面：构建好的 dsh CLI
+
+dsh CLI 的定位按以下顺序，先中先得：
+
+1. **显式 flag**：`--repo <host-checkout>`（检出须已构建，`apps/cli/lib/bin.js` 存在）；
+2. **解析层**：`node_modules/@deepseek-ai/dsh/lib/bin.js`（开发态由 junction 指到宿主检出，可用 relink 脚本从机器级 `DSH_REPO` 锚点重建；消费态由安装树提供）；
+3. **config `repo` 键**：legacy，已从各包入库 config 退役。
+
+三层全缺时 fail-loud（报错含占位符修法指引）。自诊断：
+
+```bash
+node -e "console.log(require('fs').existsSync('node_modules/@deepseek-ai/dsh/lib/bin.js'))"
+```
+
+`false` = 解析层缺 CLI：先跑 relink 重建 junction；仍 `false` 则宿主检出未构建（先构建宿主）。behavior 与 review 的真实运行都从定位到的 CLI spawn dsh 本体。
+
+## 环境面：profile 与插件安装
+
+- 被测插件须已装进所选 profile：`dsh plugin --profile <profile> add <插件目录>`；
+- 每条 behavior case 在隔离的临时 `DSH_HOME` 与 workspace 中启动 dsh，通过 `--patch` 把 session JSONL 定向到本次 run——不污染真实 profile store；
+- review 使用专用 sterile profile（详见 [review.md](review.md)）。
+
+## 凭证
+
+real 层的**模型凭证由 dsh 自行解析**——spawn 的是 dsh 本体，env 原样透传，真实 home 的托管凭证文档（`.credentials.yaml`）会被复制进暂存 home；**你的 dsh 能正常跑，real case 就能跑**。本包不做任何凭证配置，只在启动前做存在性探测（env 或托管文档任一可见）以决定 real case 是否 auto-skip。mock 与 review dry-run 完全不需要凭证。
+
+## spawn 要求
+
+real case 会以管道 stdio spawn 子 dsh CLI（headless 会话、子代理子运行时），因此需要一个能 spawn 子进程的运行面——受限沙箱里可能被拒（`spawn EPERM`），此时在宿主侧终端 / CI 跑即可。mock 与 review dry-run 不 spawn 子 CLI，无此约束。

package/docs/intent-cases.md

@@ -0,0 +1,39 @@
+---
+description: real 意图 case 规约——何时写的触发表、断言面最小化（toolCalled/toolCallArgs/inspect 守卫）、fixture 与门禁交互规避、凭证 auto-skip 与 CI 语义
+---
+
+# Real 意图 case 规约
+
+behavior real 断言「自然语言意图 → 工具选择与参数路由」，mock 断言「工具管线与写入 round-trip」：两层互补，不互相替代。
+
+## 何时写（触发表）
+
+满足任一条即值得写一条 real case：
+
+1. 注册了模型可见工具（happy path ≥1）；
+2. 目标存在等价手工路径（可对照）；
+3. 描述 steering 变更（模型可见输入面变了）；
+4. 分支由数据面状态分流（成对 case，各断一个分支）；
+5. 拒绝路径面向模型消费（remedy 委派边界——模型要读懂失败并转述）；
+6. 有误触发风险（负向 `toolNotCalled` case）。
+
+> 触发表的完整论证（依据与失败启发集）属于通用的意图面 e2e 方法论；本表即其 dsh 承载面的规范版，自足使用。
+
+## 断言面（最小化）
+
+- `toolCalled`（不是 `firstTool`——探索在前合法）+ `toolCallArgs` 子集（路由 payoff 在参数对）+ 语义关键时 `toolResultTextIncludes` 状态锚（如 `"status": "repaired"`）；
+- 不约束措辞与中间步骤——意图测试的模型措辞天然漂移，工具选择才是契约。
+
+## 守卫
+
+- `inspect` 守结果面 + 反捏造（不重建旧路径、不凭空造文件），不管模型走什么中间路径；
+- fixture 必须可区分（不同分支的 fixture 不能靠巧合区分）；
+- turn-close 门禁交互：见 [disablerows.md](disablerows.md)（case 级出口 `assistantTextIncludes`；splice 步骤与脚本本体的区分尚无框架级方案）。
+
+## CI 语义
+
+- 无凭证 auto-skip；CI 门禁用 `--fail-on-skip` 防「根本没跑但成功」。
+
+## 实例
+
+「同一意图 × 数据面分流」成对设计的可模仿形态：一组意图集检查（review 通道断言理解）配一组同意图的行为四连——repair / discovery / no-evidence / oldpath-missing（behavior 通道断言执行）——同一意图在两个数据面上分流成对，互为回归网。

package/docs/known-issues.md

@@ -0,0 +1,15 @@
+---
+description: 已知问题——real case 在 staged home 的 REQUEST_EXTENSION 失败（嫌疑 plugin-package-inventory-deepseek）及 disableRows 兜底
+---
+
+# 已知问题
+
+## real case 在 staged home 下 `REQUEST_EXTENSION` 失败（未解）
+
+**症状**：real behavior case 在暂存临时 `DSH_HOME` 里，首个模型调用即报 `REQUEST_EXTENSION` 类失败；mock 不受影响。
+
+**嫌疑**：宿主的 `plugin-package-inventory-deepseek` 插件 × staged 环境的包身份解析（staging 复制的 profile 让该插件的清单收集失败）。
+
+**框架侧兜底**：case 或 config 声明 `disableRows: ['plugin-package-inventory-deepseek']` 按行禁用该插件（机制见 [disablerows.md](disablerows.md)）。
+
+**追踪**：上游修复落地即删本条（不留僵尸条目）。

package/docs/matchers.md

@@ -0,0 +1,35 @@
+---
+description: trace matcher 与 mock helper 全集——工具面/文本面/输入面断言语义（toolCalled 到 userMessageTextIncludes）与 toolCallStep/textStep 脚本构件
+---
+
+# Trace matchers 与 mock helpers
+
+全部从包根导入：`import { toolCalled, … } from '@catheadowl/dsh-eval'`。
+
+断言对象是 dsh session 事件投影（`src/trace.mjs` 的 `EvalTrace`），不只是「模型产出」：`requestHeaders` 投影模型被挂载的工具与 system prompt（输入面），`userMessages` 投影 user-role 的模型可见输入面（任务 prompt、插件 steer、注入上下文）——这让 mock 能断言插件的**驱动级 steer**，而不只断工具选择或最终文本。
+
+## 工具面
+
+- `toolCalled(name)` / `toolNotCalled(name)`：工具被/未被调用（字符串或 RegExp）；
+- `firstTool(name)`：首个工具调用是它（慎用——探索在前合法，意图 case 通常用 `toolCalled`）；
+- `toolSequence(names)`：按序子序列；
+- `toolCallArgs(name, subset | predicate)`：参数子集匹配（或谓词，收 parsed 与 raw）；
+- `toolResultFor(name)`：匹配的调用有结果配对；
+- `toolResultIsError(name)` / `toolResultSucceeded(name)`：结果 `isError === true` / 不为 true；
+- `toolResultTextIncludes(name, substring)`：结果文本含子串。
+
+## 文本面
+
+- `finalTextIncludes(substring)` / `finalTextMatches(re)`：最后一个非空 assistant 文本（mock 层断言的是脚本终步的确定性文本）；
+- `assistantTextIncludes(substring)`：**任一** assistant 文本含子串——turn-close 门禁 splice 反馈步骤、`finalText*` 被截走时的 case 级出口。
+
+## 模型可见面（输入侧）
+
+- `systemPromptIncludes(substring)`：组装后的 system prompt 含子串；
+- `toolMounted(name)`：工具出现在某个 request/header 的挂载列表；
+- `userMessageTextIncludes(source, substring)` / `userMessageTextExcludes(source, substring)`：按 `source` 过滤的 `user/message` 文本含/不含子串。`source` 用字符串/RegExp 匹配 `plugin` 名（如 steer 生产方），或谓词取整个 `source`——steer 在持久化日志里没有专名事件（`agent.steer()` 落为 `user/message`），区分靠 `source`（插件 steer 为 `{ kind: 'plugin', plugin: '<id>' }`，任务 prompt 为 `{ kind: 'user' }`）。
+
+## Mock script helpers
+
+- `toolCallStep(name, args)`：一步「模型调工具」，结束于 tool-calls；
+- `textStep(text)`：一步「模型说话」，结束于 stop（turn 收束）。

package/docs/report.md

@@ -0,0 +1,27 @@
+---
+description: 机器可读报告结构——--format json / --report 的字段语义（环境锚点、per-case 三态 status、派生 summary 与退出码）
+---
+
+# 机器可读报告
+
+`--format json`：stdout 只输出一个 JSON 报告对象（过程与失败明细转 stderr），供 CI / 多插件聚合消费；`--report <file>`：在任一格式下额外把同一报告对象写入文件。报告构造在 `src/report.mjs`：
+
+```jsonc
+{
+  "tool": "dsh-eval",
+  "profile": "headless", "repo": "<absolute harness checkout>",
+  "mode": "mock", "failOnSkip": false,
+  "startedAt": "…", "finishedAt": "…",
+  "summary": { "selected": 1, "passed": 1, "failed": 0, "skipped": 0 },
+  "results": [
+    {
+      "id": "…", "file": "…", "mode": "mock", "status": "pass",
+      "exitCode": 0, "timedOut": false, "durationMs": 5000
+      // fail 时另有 failures[]、artifactsDir；skip 时另有 skipReason；
+      // case 文件加载失败/重复 id 这类文件级失败也进 results（无 mode 字段）
+    }
+  ]
+}
+```
+
+status 取值 `pass | fail | skip`；退出码与文本格式完全一致（同一 `reportExitCode` 派生）。默认 `--format text` 输出为人类可读进度行 + 汇总行。

package/docs/review.md

@@ -0,0 +1,77 @@
+---
+description: comprehension review 指南——defineReviewExperiment 实验定义、sterile profile 盲评运行、.runs 产物与 review-report 判读模板、六条固化规则
+---
+
+# Comprehension review
+
+理解评审回答 behavior matcher 无法回答的问题：**一个 fresh model 能否从插件输出理解含义和下一步**。「缺少应有提示」「字段容易误读」是设计缺口，不是固定字符串回归——刻意不用 trace matcher 自动化；反过来，行为层不负责评价自由文本设计。
+
+## 实验定义
+
+`<plugin>/eval/comprehension/<name>.review.mjs`：
+
+```js
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineReviewExperiment } from '@catheadowl/dsh-eval'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+export default defineReviewExperiment({
+  id: 'my-output-comprehension',
+  summary: 'Can a fresh model infer the next action?',
+  prompt: readFileSync(join(here, 'prompt.md'), 'utf8'),
+  rubric: join(here, 'rubric.md'),
+  defaultRuns: 3,
+  async observe() {
+    const liveOutput = await projectFrozenFixtureWithCurrentBuild()
+    return [{
+      heading: 'Scenarios',
+      entries: [{ heading: 'case-1', call: { path: 'x' }, json: liveOutput }],
+    }]
+  },
+})
+```
+
+抽象层公开 `defineReviewExperiment`、`materializeReviewExperiment`、`executeReviewExperiment` 与标准 observation renderer（`renderObservationSections`；prompt 里的观测占位符常量是 `OBSERVATIONS_PLACEHOLDER`，必须恰好出现一次）。自定义 executor 只需实现 `(task, context) => result`；接入其他 agent runtime 不需要改试验定义。
+
+## CLI
+
+```bash
+# dry-run 不要求 profile 或已构建 dsh CLI
+dsh-review --dry-run <experiment file or directory>
+
+dsh-review \
+  --profile <sterile-profile> \
+  --repo <deepseek-harness checkout> \
+  [--runs 5] [--timeout 300000] \
+  <experiment file or directory>
+```
+
+`--profile`/`--repo` 可来自 `dsh-eval.config.mjs`（见 README），flags 覆盖 config。
+
+## sterile profile 与工具边界
+
+真实运行使用**专用 sterile profile**（默认 `headless`，即宿主模板 `dsh-base` + `dsh-headless`，无树外插件）：适配器生成一份 `--patch` 覆盖层禁用所有宿主模型可见工具（`tool-fs`、`tool-fs-search`、shell、web、subagent 等），并把 cwd 指向空临时目录——reviewer 只能从物化的观测文本推理。运行后解析 session trace 的 `request/header` 事件做**工具边界校验**：发现任何非预期工具即视为 adapter failure（证据写入 `.runs/<id>/run-N.tool-boundary-evidence.json`）。
+
+> **运维前提**：profile staging 在真实 home 已有同名 profile 时**原样复制**（含已安装插件与 patch 层）。若本机 `headless` profile 装过树外插件，暂存后的 profile **不是无菌的**——工具边界校验会当场 fail-loud（这是设计的正确行为）。保持无菌：删掉本机 `headless` profile 让 boot 重建出厂模板，或指定一个确认无插件的 profile。
+
+## 产物
+
+落在 review 文件旁的 `.runs/<experiment id>/`：
+
+- `observations.md`：本次实时物化的可见证据；
+- `task.txt`：实际发给每位 reviewer 的完整任务；
+- `run-N.txt` / stderr / error：各次独立运行；
+- `run.json`：experiment、rubric、adapter、profile 与 run 数；
+- `review-report.md`：判读报告骨架——机器字段自动填（experiment/adapter/ profile/runs、observations 指纹、rubric 位置、每轮 reviewer 原文），三个 **人工判读栏目**留白待填：intentional design 命中项、新 red flag、下一步（改输出 / 改 rubric / 改 behavior case / 不处理）。刻意不做自动评分——review 层的价值在人工判断，报告只把判断物化成可归档、可对比的工程证据（dry-run 也会生成，runs 记 0）。
+
+## 从早期 eval 固化下来的六条规则
+
+1. **冻结输入，实时投影输出。** fixture 保存 raw SDK result、合成知识库或调用参数；`observe()` 必须调用当前构建产物。不要提交一份会随实现漂移的 projected-output 快照。
+2. **盲 prompt 与隐藏 rubric 分离。** `prompt.md` 只能含问题和 `{{EVAL_OBSERVATIONS}}`；答案键、预期 next action、intentional design 只在 `rubric.md`。
+3. **一次物化，多次独立评审。** 同一批运行共享完全相同的 task，避免把 fixture 波动误判成模型分歧；每次调用新的 headless 进程和隔离的临时 `DSH_HOME`，但暂存所选 profile 的配置与依赖链接。
+4. **主动标准化非语义噪声。** 临时绝对路径、时间戳等应在 plugin 的 observation projection 中替换或移除，同时保留真实字段名与语义。
+5. **显式登记 intentional design。** reviewer 提出的 red flag 只有不在该清单中时才是新发现，避免反复争论已接受取舍。
+6. **生成物不做 SSOT。** `.runs/` 只用于当次人工审阅，gitignore 使用无路径前缀的 `.runs/`，覆盖任意深度。

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@catheadowl/dsh-eval",
+  "description": "Agent eval framework over dsh headless runs: case runner, session-trace assertions, and a scripted mock-LLM layer for plugin intent tests.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.mjs",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "dsh-eval": "bin/dsh-eval.mjs",
+    "dsh-review": "bin/dsh-review.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "verify:publish": "node scripts/verify-publish-readiness.mjs",
+    "verify:face": "node scripts/verify-manifest-face.mjs",
+    "prepack": "node scripts/verify-manifest-face.mjs && node scripts/verify-publish-readiness.mjs",
+    "test": "node --test --test-isolation=none tests/trace.test.mjs tests/assertions.test.mjs tests/overlay.test.mjs tests/staging.test.mjs tests/runner.test.mjs tests/cli.test.mjs tests/discovery.test.mjs tests/review.test.mjs tests/report.test.mjs tests/config.test.mjs tests/review-report.test.mjs && node scripts/verify-publish-readiness.mjs && node scripts/verify-manifest-face.mjs"
+  }
+}

package/src/adapters/dsh/index.mjs

@@ -0,0 +1,7 @@
+/** Public dsh review adapter surface. */
+
+export {
+  createDshHeadlessReviewExecutor,
+  resolveDshCli,
+  runDshReviewExperiment,
+} from './review.mjs'

package/src/adapters/dsh/review.mjs

@@ -0,0 +1,192 @@
+/** dsh-headless execution adapter for model-independent review experiments. */
+
+import { spawn } from 'node:child_process'
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { executeReviewExperiment } from '../../experiment/review.mjs'
+import { stageProfileStore } from '../../runner.mjs'
+import { loadTraceDir } from '../../trace.mjs'
+import { validateToolBoundary, renderToolBoundaryEvidence } from '../../tool-validation.mjs'
+
+/**
+ * Model-facing tool rows every shipped dsh profile mounts from `dsh-base`.
+ * The overlay disables all host tool rows as a supplementary guard; the
+ * primary isolation comes from the sterile review profile (dsh-base +
+ * dsh-headless only, no out-of-tree plugins).  Post-run tool boundary
+ * validation (see `validateToolBoundary`) detects any residual drift.
+ */
+const REVIEW_DISABLED_TOOL_ROWS = [
+  'tool-bash',
+  'tool-pwsh',
+  'tool-jobs',
+  'tool-fs',
+  'tool-fs-search',
+  'tool-skill',
+  'tool-todo',
+  'tool-goal',
+  'tool-ralph',
+  'tool-str-replace-editor',
+  'tool-web',
+  'tool-subagent-control',
+  'tool-subagent-list-agents',
+  'tool-subagent',
+  'tool-subagent-fork',
+  'tool-subagent-report',
+  'tool-workflow',
+]
+
+/** Serialize the tool-less overlay: disable every host model-facing tool row. */
+function buildReviewOverlayYaml() {
+  return REVIEW_DISABLED_TOOL_ROWS.map((id) => `- id: ${id}\n  disabled: true\n`).join('\n')
+}
+
+/** Resolve and validate the compiled dsh CLI entry point. */
+export function resolveDshCli(dshRepoDir) {
+  const repoDir = resolve(dshRepoDir)
+  const cli = join(repoDir, 'apps', 'cli', 'lib', 'bin.js')
+  if (!existsSync(cli)) {
+    throw new Error(`no compiled dsh CLI at '${cli}' (build deepseek-harness first)`)
+  }
+  return cli
+}
+
+/** The CLI entry for an executor: explicit cliPath (C6 chain result) wins;
+ * otherwise fall back to the legacy repo form. Neither being set is a caller
+ * bug the CLI bins already catch — this guard serves direct API consumers. */
+function executorCli(options) {
+  if (options.cliPath !== undefined) return resolve(options.cliPath)
+  if (options.dshRepoDir !== undefined) return resolveDshCli(options.dshRepoDir)
+  throw new Error('review adapter needs a CLI location: pass cliPath (C6 chain result) or dshRepoDir')
+}
+
+/**
+ * Create an executor compatible with executeReviewExperiment.
+ *
+ * The executor boots a sterile review profile (default: the host's
+ * `headless` template, bundles = dsh-base + dsh-headless, no out-of-tree
+ * plugins) in an isolated DSH_HOME, disables every host tool row via
+ * overlay, and validates the tool boundary after the run.  `options.profile`
+ * must name a profile whose installed plugin set is empty or review-safe.
+ *
+ * @param {object} options
+ * @param {string} [options.profile='headless'] - the sterile review profile.
+ * @param {Set<string>} [options.allowedTools] - tool names permitted in the reviewer's session (default: empty).
+ */
+export function createDshHeadlessReviewExecutor(options) {
+  const cli = executorCli(options)
+  const profile = options.profile ?? 'headless'
+  if (typeof profile !== 'string' || profile.length === 0) {
+    throw new TypeError('dsh review adapter requires a profile')
+  }
+  const timeoutMs = options.timeoutMs ?? 300_000
+  const allowedTools = options.allowedTools ?? new Set()
+
+  return async function executeWithDsh(task) {
+    // A fresh process alone is not enough: dsh also stores settings, titles,
+    // and sessions below DSH_HOME. Reuse the behavior harness's proven profile
+    // staging strategy so every reviewer receives an isolated runtime state
+    // while retaining the selected profile's model config and plugin links.
+    const runDir = mkdtempSync(join(tmpdir(), 'dsh-review-'))
+    const dshHome = join(runDir, 'dsh-home')
+    const overlayPath = join(runDir, 'review-overlay.yml')
+    writeFileSync(overlayPath, buildReviewOverlayYaml(), 'utf8')
+    const realHome = options.dshHome
+      ?? ((process.env.DSH_HOME ?? '').trim() !== '' ? process.env.DSH_HOME : join(homedir(), '.dsh'))
+    mkdirSync(dshHome, { recursive: true })
+    const junctions = stageProfileStore(realHome, dshHome, profile)
+    const realCredentials = join(realHome, '.credentials.yaml')
+    if (existsSync(realCredentials)) {
+      const credentialsCopy = join(dshHome, '.credentials.yaml')
+      copyFileSync(realCredentials, credentialsCopy)
+      try { chmodSync(credentialsCopy, 0o600) } catch { /* best-effort */ }
+    }
+
+    try {
+      const child = spawn(process.execPath, [cli, '--profile', profile, '--patch', overlayPath, task], {
+        cwd: options.cwd ?? runDir,
+        env: {
+          ...process.env,
+          ...options.env,
+          DSH_HOME: dshHome,
+          DSH_TELEMETRY_DISABLED: '1',
+        },
+      })
+      let stdout = ''
+      let stderr = ''
+      child.stdout.on('data', chunk => { stdout += chunk })
+      child.stderr.on('data', chunk => { stderr += chunk })
+
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        child.kill('SIGTERM')
+      }, timeoutMs)
+      let exitCode
+      try {
+        exitCode = await new Promise((resolveExit, reject) => {
+          child.on('error', reject)
+          child.on('exit', code => resolveExit(code ?? 1))
+        })
+      } finally {
+        clearTimeout(timer)
+      }
+
+      const result = { stdout, stderr, exitCode, timedOut, profile, cli, runDir }
+      if (exitCode !== 0 || timedOut) {
+        const error = new Error(`dsh reviewer exited with code ${exitCode}${timedOut ? ' after timeout' : ''}`)
+        error.result = result
+        throw error
+      }
+
+      // Post-run tool boundary check: parse the session
+      // trace, verify no unexpected tools were mounted in the reviewer's
+      // session, fail the run on violation.  An absent session log skips
+      // the check gracefully (accepted fail-open).
+      // Validation inspects the main session only (buildTrace selects
+      // non-subagent logs); plugin tools leaking in a subagent session
+      // would not be caught — irrelevant in review where the overlay
+      // disables every subagent tool row.
+      const trace = loadTraceDir(join(dshHome, 'sessions'))
+      if (trace) {
+        const validation = validateToolBoundary(trace, { allowedTools })
+        result.toolValidation = validation
+        if (!validation.ok) {
+          // Attach evidence for the caller to persist (the adapter's
+          // runDir is ephemeral — removed by the finally block).  The
+          // bin writes this to `.runs/<id>/tool-boundary-evidence.json`.
+          result.toolBoundaryEvidence = renderToolBoundaryEvidence(validation, { runDir, profile })
+          const boundaryError = new Error(
+            `tool boundary violation: unexpected tools [${validation.unexpected.join(', ')}]`,
+          )
+          boundaryError.result = result
+          throw boundaryError
+        }
+      }
+
+      return result
+    } finally {
+      if (process.env.DSH_REVIEW_KEEP_TMP !== '1') {
+        for (const junction of junctions) {
+          try { unlinkSync(junction) } catch { /* already absent */ }
+        }
+        rmSync(runDir, { recursive: true, force: true })
+      }
+    }
+  }
+}
+
+/** Run a review experiment through fresh dsh headless processes. */
+export async function runDshReviewExperiment(experiment, options) {
+  const executor = createDshHeadlessReviewExecutor(options)
+  return executeReviewExperiment(experiment, executor, { runs: options.runs })
+}