@catheadowl/dsh-eval 0.1.0 → 0.2.1

package/docs/review.md

@@ -1,5 +1,5 @@
 ---
-description: comprehension review 指南——defineReviewExperiment 实验定义、sterile profile 盲评运行、.runs 产物与 review-report 判读模板、六条固化规则
+description: comprehension review 指南——defineReviewExperiment 实验定义、空白环境（默认禁树外插件行）盲评运行、.runs 产物与 review-report 判读模板、六条评审规则
 ---
 
 # Comprehension review
@@ -34,7 +34,7 @@ export default defineReviewExperiment({
 })
 ```
 
-抽象层公开 `defineReviewExperiment`、`materializeReviewExperiment`、`executeReviewExperiment` 与标准 observation renderer（`renderObservationSections`；prompt 里的观测占位符常量是 `OBSERVATIONS_PLACEHOLDER`，必须恰好出现一次）。自定义 executor 只需实现 `(task, context) => result`；接入其他 agent runtime 不需要改试验定义。
+抽象层公开 `defineReviewExperiment`（稳定根入口）。实验执行与渲染原语——`materializeReviewExperiment`、`executeReviewExperiment`、标准 observation renderer（`renderObservationSections`；prompt 里的观测占位符常量是 `OBSERVATIONS_PLACEHOLDER`，必须恰好出现一次）——在 `@catheadowl/dsh-eval/experimental` 逃生面（见 [experimental.md](experimental.md)，无兼容承诺）。自定义 executor 只需实现 `(task, context) => result`；接入其他 agent runtime 不需要改试验定义。结果契约上，报告消费 `result.answer`（对任务的回答；未提供时回落 `result.stdout`），`result.stderr` 落盘为每轮 transcript——自定义 executor 提供这两者即可获得同等的产物与报告行为。
 
 ## CLI
 
@@ -43,19 +43,21 @@ export default defineReviewExperiment({
 dsh-review --dry-run <experiment file or directory>
 
 dsh-review \
-  --profile <sterile-profile> \
+  --profile <profile> \
   --repo <deepseek-harness checkout> \
-  [--runs 5] [--timeout 300000] \
+  [--runs 5] [--timeout 300000] [--keep-plugin-rows] \
   <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`）。
+真实运行的 reviewer 会话默认在**空白环境**启动：适配器先照常暂存所选 profile，再枚举它组合出的**全部树外插件行**（`package.json` 的 `dsh.profile.bundles` 中非 `@deepseek-ai/*` 的 bundle 各自 patch 文件里的行，加上 profile 自有 `cordis.patch.yml` 的行），在 `--patch` overlay 里逐行禁用——宿主 profile 装了什么 gates/插件都与 reviewer 无关，可复现性不再依赖「本机 profile 恰好干净」。白名单保留 reviewer 起不来就无测可言的接线行（`agent-default-model`、`session-title-llm`、`system-prompt`、`session-persistence-jsonl`）；宿主模板工具行（`tool-fs`、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。
+**刻意复用宿主插件面**（例如要评审某插件自己的 gate 行为）：加 `--keep-plugin-rows`——跳过树外行枚举，仅保留静态工具禁用，宿主 gates 恢复运行。
+
+> 注意：无 `id` 的组合条目对 id 定位的禁用天然不可见（宿主 loader 语义），本包的树外 bundle 生态均为带 id 行形态；发现无 id 树外行时以工具边界校验 fail-loud 兜底。白名单是**按行名**无条件保留——若某树外 bundle 刻意以白名单名（如 `system-prompt`）insert 自己的行，该行不会被禁（威胁模型是本机自己的 profile，非对抗面）；此类泄漏同样由工具边界校验兜底。
 
 ## 产物
 
@@ -63,11 +65,12 @@ dsh-review \
 
 - `observations.md`：本次实时物化的可见证据；
 - `task.txt`：实际发给每位 reviewer 的完整任务；
-- `run-N.txt` / stderr / error：各次独立运行；
+- `run-N.txt`：该轮 reviewer 的**答案**——trace 推导（首条插件注入消息之前的最后一条 assistant 文本，抗回合尾部劫持），无 trace 时回落到 stdout 的最终消息；劫持发生时原始最终消息另存 `run-N.stdout.txt`；
+- `run-N.stderr.txt` / error：完整会话转录（判读回溯的 transcript 指针，报告每轮引用）/ 失败原因；
 - `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）。
+- `review-report.md`：判读报告骨架——机器字段自动填（experiment/adapter/ profile/runs、observations 指纹、rubric 位置、每轮 reviewer **答案**与 transcript 指针），三个 **人工判读栏目**留白待填：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`。

package/docs/rowconfig.md

@@ -0,0 +1,39 @@
+---
+description: rowConfig 边界契约——case 级按 loader 行 id 覆写行 config 的机制、整段替换语义与「重述所需键」义务、叶值形状限制、与 disableRows 的分工
+---
+
+# rowConfig：case 级行 config 覆写
+
+`rowConfig: Record<rowId, config对象>` 让一个 case 在**本次 run 的 overlay** 里覆写插件行的 config。框架对行 id 与键语义零内置知识（键由目标插件自定义），只做形状校验。典型用例是臂式实验：同一 case 跑两臂，差异臂用 `rowConfig: { prompt: { disabledProviders: ['<provider>'] } }` 关掉单个 provider，而不用 `disableRows` 禁掉整行（那会连工具面一起摘掉，制造混淆变量）。
+
+## 机制
+
+- 序列化为 overlay 条目 `- id: <row>` + `config:` 键值块（`buildOverlayYaml`），与 `session-persistence-jsonl` 重根、`persona`、`disableRows` 走同一条 per-run overlay 通道；
+- 取值优先级同 overlay 语义：覆盖 bundle/patch 层为该行声明的 config。
+
+## 整段替换语义（最大的坑）
+
+cordis patch 层的 config 覆写是**整段替换**，不是深合并：`rowConfig` 声明的键集合就是该行生效的**全部** config。行原本带的其他键（如 prompt 行的 `providerTimeoutMs` / `totalTimeoutMs` / `renderBudgetChars`）不会自动保留——**用到哪个键就在 rowConfig 里重述哪个**。这与「惰性只写差异」的直觉相反，是宿主 patch 语义的直接推论（参见 dsh 宿主文档对 patch 的说明：按 id 定位行、整段替换其 config）。
+
+## 形状限制
+
+- 叶值只支持**标量**（string / number / boolean）或**标量数组**（如 `disabledProviders: ['a', 'b']`，YAML flow 序列发射）；
+- 嵌套对象不支持（`validateRowConfig` 拒绝）——需要嵌套 config 的行请走自己的 profile patch，不进 case；
+- 校验双点：discovery 加载期与 `runEvalCase` 执行期同一份 `validateRowConfig`。
+
+## 与 disableRows 的分工
+
+| | `disableRows` | `rowConfig` |
+|---|---|---|
+| 效果 | 整行禁用（插件完全不装载） | 行照常装载，config 被覆写 |
+| 适用 | 该 case 不需要该插件的任何面 | 该 case 需要插件但想改其行为参数 |
+| 组合 | 同一行同时出现在两处是矛盾声明（禁用的行无 config 可言），避免 | |
+
+## 校验示例
+
+```js
+// 合法
+rowConfig: { prompt: { disabledProviders: ['breadcrumb-description-enricher'], totalTimeoutMs: 5000 } }
+// 非法：嵌套对象
+rowConfig: { prompt: { a: { b: 1 } } }   // validateRowConfig 拒绝
+```

package/docs/runner-api.md

@@ -0,0 +1,42 @@
+---
+description: 程序化 runner API——runEvalCase 的 options 契约（SDK 承诺）、EvalRunResult 字段、DSH_EVAL_KEEP_TMP 逃生、与 experimental 档 resolveDshCliChain 的跨档关系
+---
+
+# 程序化 runner API
+
+`runEvalCase` 从包根导入，是 SDK 稳定面的一部分（semver 承诺）：
+
+```js
+import { runEvalCase } from '@catheadowl/dsh-eval'
+
+const result = await runEvalCase(evalCase, { profile: 'headless', cliPath, mode: 'real' })
+```
+
+## options（SDK 承诺）
+
+| 键 | 类型 | 语义 |
+|---|---|---|
+| `profile` | `string` | 必填。承载被测插件的 dsh profile（沙箱会暂存其 store，不污染真实 home）。 |
+| `cliPath` | `string` | 编译好的 dsh CLI 入口（`apps/cli/lib/bin.js`）绝对路径；优先于 `dshRepoDir`。程序化取值见下节。 |
+| `mode` | `'real' \| 'mock'` | 覆写 case 自带的 mode；mock 需 `script.steps`。 |
+| `artifactsDir` | `string` | 提供则把 stdout/stderr/trace/session 日志拷贝到该目录（自动创建）。 |
+| `dshRepoDir` | `string` | **已弃用**：宿主 checkout 目录（从中拼出 CLI 路径）。下个 minor 删除——迁移到 `cliPath`。 |
+
+## `cliPath` 从哪来：跨档关系（读我）
+
+稳定档不提供 CLI 定位器；程序化解析走 experimental 档的 `resolveDshCliChain`（`import '@catheadowl/dsh-eval/experimental'`，见 [experimental.md](experimental.md)）。**该档无兼容承诺**：若你的脚本不能接受随 minor 跟进，可自行传入 `cliPath`（如来自你自己的部署清单），`runEvalCase` 不假设来源。
+
+## EvalRunResult 字段
+
+| 字段 | 语义 |
+|---|---|
+| `caseId` / `mode` / `task` | 回显 case 标识。 |
+| `exitCode` | headless CLI 退出码（0 = turn 完成）。 |
+| `timedOut` | 是否超时被杀。 |
+| `stdout` / `stderr` | CLI 原始输出（stdout 含最终 assistant 文本与启动 chatter）。 |
+| `trace` | session 事件投影（形状见 [matchers.md](matchers.md) 的 trace 形状表）；无日志时为 `undefined`。 |
+| `sessionLogs` | 清理前的原始 session artifact 文本数组。 |
+| `inspectError` | case 的 `inspect` 抛错时的错误文本。 |
+| `runDir` | 本次运行的沙箱目录——**默认清理**；设环境变量 `DSH_EVAL_KEEP_TMP=1` 保留（失败诊断用）。 |
+
+清理是全路径 `try/finally`：`prepare` 抛错、mock 校验失败、spawn 失败都会清理，真实 profile store 永不被污染。

package/package.json

@@ -1,10 +1,22 @@
 {
   "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",
+  "version": "0.2.1",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CatheadOwl/dsh-eval.git"
+  },
   "type": "module",
+  "packageManager": "pnpm@11.7.0",
   "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./experimental": "./src/experimental.mjs",
+    "./bin/dsh-eval": "./bin/dsh-eval.mjs",
+    "./bin/dsh-review": "./bin/dsh-review.mjs",
+    "./package.json": "./package.json"
+  },
   "peerDependencies": {
     "@deepseek-ai/dsh-llm": "*"
   },
@@ -20,12 +32,16 @@
     "src/",
     "docs/",
     "README.md",
+    "README.zh.md",
+    "CHANGELOG.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"
+    "verify:experimental": "node scripts/verify-experimental-face.mjs",
+    "verify:readme-i18n": "node scripts/verify-readme-i18n.mjs",
+    "prepack": "node scripts/verify-manifest-face.mjs && node scripts/verify-publish-readiness.mjs && node scripts/verify-readme-i18n.mjs && node scripts/verify-experimental-face.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 && node scripts/verify-readme-i18n.mjs && node scripts/verify-experimental-face.mjs"
   }
 }

package/src/adapters/dsh/review.mjs

@@ -1,192 +1,210 @@
-/** 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 })
-}
+/** dsh-headless execution adapter for model-independent review experiments. */
+
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { executeReviewExperiment } from '../../experiment/review.mjs'
+import { CLI_RELATIVE_PATH } from '../../cli.mjs'
+import { overlayDisableRows } from '../../overlay.mjs'
+import {
+  resolveRealDshHome, stageSandboxHome, stagedPluginRows, teardownSandbox, spawnHeadlessDsh,
+} from '../../sandbox.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`.
+ * A static supplementary guard on top of the blank-environment enumeration
+ * (host template tool rows never appear in `stagedPluginRows` — they are the
+ * sterile baseline, so their ids are enumerated here instead).  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',
+]
+
+/**
+ * Rows the reviewer session must KEEP even when an out-of-tree bundle or the
+ * profile patch touches them: model wiring and the session log — without
+ * these the reviewer cannot answer at all and the trace (tool boundary
+ * check, run artifacts) never materializes.  These ids are host-template
+ * rows; an out-of-tree patch row targeting one of them only overrides its
+ * config, so keeping it enabled stays safe.
+ */
+const REVIEW_REQUIRED_ROWS = new Set([
+  'agent-default-model',
+  'session-title-llm',
+  'system-prompt',
+  'session-persistence-jsonl',
+])
+
+/**
+ * Serialize the blank-environment overlay: disable every plugin row the
+ * staged profile composes beyond the host templates (`stagedPluginRows` —
+ * out-of-tree bundle rows + profile patch rows), UNION the static host tool
+ * rows, MINUS the model/session wiring the reviewer needs.  With
+ * `keepPluginRows` (explicit opt-in to study the host plugin face itself)
+ * the enumeration is skipped and only the static tool lockdown remains.
+ */
+function buildReviewOverlayYaml(pluginRows, { keepPluginRows }) {
+  const disabled = new Set(keepPluginRows ? [] : pluginRows)
+  for (const row of REVIEW_DISABLED_TOOL_ROWS) disabled.add(row)
+  for (const row of REVIEW_REQUIRED_ROWS) disabled.delete(row)
+  return overlayDisableRows([...disabled])
+}
+
+/** Resolve and validate the compiled dsh CLI entry point. */
+export function resolveDshCli(dshRepoDir) {
+  const repoDir = resolve(dshRepoDir)
+  const cli = join(repoDir, ...CLI_RELATIVE_PATH.split(/[\\/]/))
+  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 blank review environment in an isolated DSH_HOME
+ * (staging/teardown mechanics shared with the behavior runner via
+ * sandbox.mjs): the staged profile's every out-of-tree plugin row and every
+ * host model-facing tool row is disabled via overlay (blank =
+ * dsh-base/dsh-headless templates + model wiring, nothing else — regardless
+ * of what the host profile carries), and the tool boundary is validated
+ * after the run.
+ *
+ * @param {object} options
+ * @param {string} [options.profile='headless'] - the review profile (host
+ *   templates + whatever the host machine carries; plugin rows are disabled
+ *   by the overlay anyway).
+ * @param {Set<string>} [options.allowedTools] - tool names permitted in the reviewer's session (default: empty).
+ * @param {boolean} [options.keepPluginRows=false] - opt back into the host
+ *   profile's plugin face (e.g. to review a plugin's own gate behavior);
+ *   only the static tool lockdown remains.
+ */
+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()
+  const keepPluginRows = options.keepPluginRows ?? false
+
+  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 sandbox
+    // (sandbox.mjs) 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')
+    stageSandboxHome(options.dshHome ?? resolveRealDshHome(), dshHome, profile)
+    // Blank environment by DEFAULT (review-blank-environment TODO): disable
+    // every row the staged profile composes beyond the host templates, so a
+    // host profile carrying out-of-tree plugins (gates included) can no
+    // longer steer or crash the reviewer. `keepPluginRows` opts back into
+    // the host plugin face deliberately. Enumeration happens on the STAGED
+    // copy, after staging — the staged home is what actually boots.
+    const overlayPath = join(runDir, 'review-overlay.yml')
+    writeFileSync(overlayPath, buildReviewOverlayYaml(
+      stagedPluginRows(dshHome, profile),
+      { keepPluginRows },
+    ), 'utf8')
+
+    try {
+      const { stdout, stderr, exitCode, timedOut } = await spawnHeadlessDsh({
+        cli,
+        cliArgs: ['--profile', profile, '--patch', overlayPath, task],
+        cwd: options.cwd ?? runDir,
+        env: {
+          ...process.env,
+          ...options.env,
+          DSH_HOME: dshHome,
+          DSH_TELEMETRY_DISABLED: '1',
+        },
+        timeoutMs,
+      })
+
+      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
+        }
+        // The ANSWER to the task, not the last message: stdout carries the
+        // headless CLI's final assistant message — whatever the reviewer
+        // said LAST. If any tail interaction intervened (a turn-close gate
+        // splice that slipped past the blank environment, an infra
+        // complaint), stdout holds that instead of the analysis. The
+        // trace's answerText (last assistant text before the first
+        // plugin-sourced injection) IS the analysis; stdout remains the
+        // fallback for trace-less runs.
+        result.answer = trace.answerText !== '' ? trace.answerText : stdout
+      } else {
+        result.answer = stdout
+      }
+
+      return result
+    } finally {
+      teardownSandbox(runDir, { keep: process.env.DSH_REVIEW_KEEP_TMP === '1' })
+    }
+  }
+}
+
+/** 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 })
+}