@catheadowl/dsh-eval 0.2.0 → 0.2.1

package/bin/dsh-review.mjs

@@ -1,154 +1,166 @@
-#!/usr/bin/env node
-/**
- * Execute model-independent `*.review.mjs` experiments through dsh headless.
- *
- * Dry-run materializes live observations without touching dsh. Real runs write
- * the shared task plus each independent review answer beside the experiment:
- * `.runs/<experiment id>/`.
- */
-
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { materializeReviewExperiment } from '../src/experiment/review.mjs'
-import { runDshReviewExperiment } from '../src/adapters/dsh/review.mjs'
-import { discoverFiles } from '../src/discovery.mjs'
-import { loadEvalConfig } from '../src/config.mjs'
-import { resolveDshCliChain } from '../src/cli.mjs'
-import { renderReviewReport } from '../src/review-report.mjs'
-
-function usage(error) {
-  const message = [
-    'usage: dsh-review [--dry-run] [--runs N] [--profile NAME (default: headless) --repo DIR] [--timeout MS] <*.review.mjs or directories...>',
-    '       --profile/--repo may come from a dsh-eval.config.mjs found upward from cwd; flags override it.',
-  ].join('\n')
-  if (error) process.stderr.write(`${error}\n${message}\n`)
-  else process.stdout.write(`${message}\n`)
-  process.exit(error ? 2 : 0)
-}
-
-function parseArgs(argv) {
-  const options = { dryRun: false, runs: undefined, timeoutMs: undefined, profile: undefined, repo: undefined }
-  const paths = []
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    if (arg === '--dry-run') { options.dryRun = true; continue }
-    if (arg === '--runs') { options.runs = Number(argv[++index]); continue }
-    if (arg === '--profile') { options.profile = argv[++index]; continue }
-    if (arg === '--repo') { options.repo = argv[++index]; continue }
-    if (arg === '--timeout') { options.timeoutMs = Number(argv[++index]); continue }
-    if (arg === '-h' || arg === '--help') usage()
-    paths.push(arg)
-  }
-  if (paths.length === 0) usage('error: at least one review experiment path is required')
-  if (options.runs !== undefined && (!Number.isInteger(options.runs) || options.runs < 1)) usage('error: --runs must be a positive integer')
-  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) usage('error: --timeout must be a positive integer')
-  return { options, paths }
-}
-
-function discover(path) {
-  return discoverFiles(path, '.review.mjs')
-}
-
-async function loadExperiment(file) {
-  const module = await import(pathToFileURL(file).href)
-  const experiment = module.default
-  if (experiment?.kind !== 'review') {
-    throw new Error(`${file}: default export must come from defineReviewExperiment(...)`)
-  }
-  return { ...experiment, __file: file }
-}
-
-function artifactDir(experiment) {
-  return join(dirname(experiment.__file), '.runs', experiment.id)
-}
-
-function writeMaterialized(experiment, materialized, extra = {}, reviewResult = undefined) {
-  const output = artifactDir(experiment)
-  mkdirSync(output, { recursive: true })
-  writeFileSync(join(output, 'task.txt'), materialized.task, 'utf8')
-  writeFileSync(join(output, 'observations.md'), materialized.observations, 'utf8')
-  writeFileSync(join(output, 'run.json'), JSON.stringify({
-    experimentId: experiment.id,
-    summary: experiment.summary,
-    rubric: String(experiment.rubric),
-    ...extra,
-  }, null, 2), 'utf8')
-  writeFileSync(join(output, 'review-report.md'), renderReviewReport({
-    experiment,
-    result: reviewResult,
-    observations: materialized.observations,
-    adapter: extra.adapter,
-    profile: extra.profile,
-  }), 'utf8')
-  return output
-}
-
-const { options, paths } = parseArgs(process.argv.slice(2))
-
-// Config merge: flags win over a `dsh-eval.config.mjs` found
-// upward from cwd; profile falls back to the sterile default `headless`.
-const { config } = await loadEvalConfig(process.cwd())
-const profile = options.profile ?? config.profile ?? 'headless'
-// CLI resolution (C6): `--repo` flag > resolution layer (node_modules) >
-// config repo key (legacy). Dry-run never boots the CLI, so resolve lazily.
-let cli = { cliPath: undefined, repoDir: undefined }
-if (!options.dryRun) {
-  try {
-    const resolved = resolveDshCliChain({ repoFlag: options.repo, configRepo: config.repo })
-    cli = { cliPath: resolved.cli, repoDir: resolved.repo }
-  } catch (error) {
-    usage(`error: ${error.message}`)
-  }
-}
-
-for (const path of paths) {
-  if (!existsSync(resolve(path))) usage(`error: no such experiment path: ${path}`)
-}
-const files = paths.flatMap(path => discover(path)).sort()
-if (files.length === 0) usage('error: no *.review.mjs experiment files found')
-
-let failures = 0
-for (const file of files) {
-  let experiment
-  try {
-    experiment = await loadExperiment(file)
-    if (options.dryRun) {
-      const materialized = await materializeReviewExperiment(experiment)
-      const output = writeMaterialized(experiment, materialized, { adapter: null, dryRun: true })
-      process.stdout.write(`DRY  ${experiment.id}: ${output}\n`)
-      continue
-    }
-
-    process.stdout.write(`RUN  ${experiment.id} (${options.runs ?? experiment.defaultRuns} reviews)...\n`)
-    const result = await runDshReviewExperiment(experiment, {
-      profile,
-      cliPath: cli.cliPath,
-      dshRepoDir: cli.repoDir,
-      runs: options.runs,
-      timeoutMs: options.timeoutMs,
-    })
-    const output = writeMaterialized(experiment, result, {
-      adapter: 'dsh-headless',
-      profile,
-      runs: result.runs,
-    }, result)
-    for (const attempt of result.attempts) {
-      const payload = attempt.result ?? {}
-      if (payload.stdout !== undefined) writeFileSync(join(output, `run-${attempt.index}.txt`), payload.stdout, 'utf8')
-      if (payload.stderr) writeFileSync(join(output, `run-${attempt.index}.stderr.txt`), payload.stderr, 'utf8')
-      if (payload.toolBoundaryEvidence) writeFileSync(join(output, `run-${attempt.index}.tool-boundary-evidence.json`), payload.toolBoundaryEvidence, 'utf8')
-      if (!attempt.ok) {
-        failures += 1
-        writeFileSync(join(output, `run-${attempt.index}.error.txt`), attempt.error, 'utf8')
-        process.stderr.write(`FAIL ${experiment.id} run ${attempt.index}: ${attempt.error}\n`)
-      }
-    }
-    if (result.attempts.every(attempt => attempt.ok)) process.stdout.write(`DONE ${experiment.id}: ${output}\n`)
-  } catch (error) {
-    failures += 1
-    process.stderr.write(`FAIL ${file}: ${error.message}\n`)
-  }
-}
-
-process.exit(failures === 0 ? 0 : 1)
+#!/usr/bin/env node
+/**
+ * Execute model-independent `*.review.mjs` experiments through dsh headless.
+ *
+ * Dry-run materializes live observations without touching dsh. Real runs write
+ * the shared task plus each independent review answer beside the experiment:
+ * `.runs/<experiment id>/`.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { materializeReviewExperiment } from '../src/experiment/review.mjs'
+import { runDshReviewExperiment } from '../src/adapters/dsh/review.mjs'
+import { discoverFiles } from '../src/discovery.mjs'
+import { loadEvalConfig } from '../src/config.mjs'
+import { resolveDshCliChain } from '../src/cli.mjs'
+import { renderReviewReport } from '../src/review-report.mjs'
+
+function usage(error) {
+  const message = [
+    'usage: dsh-review [--dry-run] [--runs N] [--profile NAME (default: headless) --repo DIR] [--timeout MS] [--keep-plugin-rows] <*.review.mjs or directories...>',
+    '       --profile/--repo may come from a dsh-eval.config.mjs found upward from cwd; flags override it.',
+    '       blank environment by default: every out-of-tree plugin row in the staged profile is disabled;',
+    '       --keep-plugin-rows opts back into the host profile plugin face (e.g. reviewing a plugin\'s own gates).',
+  ].join('\n')
+  if (error) process.stderr.write(`${error}\n${message}\n`)
+  else process.stdout.write(`${message}\n`)
+  process.exit(error ? 2 : 0)
+}
+
+function parseArgs(argv) {
+  const options = { dryRun: false, runs: undefined, timeoutMs: undefined, profile: undefined, repo: undefined, keepPluginRows: false }
+  const paths = []
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--dry-run') { options.dryRun = true; continue }
+    if (arg === '--runs') { options.runs = Number(argv[++index]); continue }
+    if (arg === '--profile') { options.profile = argv[++index]; continue }
+    if (arg === '--repo') { options.repo = argv[++index]; continue }
+    if (arg === '--timeout') { options.timeoutMs = Number(argv[++index]); continue }
+    if (arg === '--keep-plugin-rows') { options.keepPluginRows = true; continue }
+    if (arg === '-h' || arg === '--help') usage()
+    paths.push(arg)
+  }
+  if (paths.length === 0) usage('error: at least one review experiment path is required')
+  if (options.runs !== undefined && (!Number.isInteger(options.runs) || options.runs < 1)) usage('error: --runs must be a positive integer')
+  if (options.timeoutMs !== undefined && (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1)) usage('error: --timeout must be a positive integer')
+  return { options, paths }
+}
+
+function discover(path) {
+  return discoverFiles(path, '.review.mjs')
+}
+
+async function loadExperiment(file) {
+  const module = await import(pathToFileURL(file).href)
+  const experiment = module.default
+  if (experiment?.kind !== 'review') {
+    throw new Error(`${file}: default export must come from defineReviewExperiment(...)`)
+  }
+  return { ...experiment, __file: file }
+}
+
+function artifactDir(experiment) {
+  return join(dirname(experiment.__file), '.runs', experiment.id)
+}
+
+function writeMaterialized(experiment, materialized, extra = {}, reviewResult = undefined) {
+  const output = artifactDir(experiment)
+  mkdirSync(output, { recursive: true })
+  writeFileSync(join(output, 'task.txt'), materialized.task, 'utf8')
+  writeFileSync(join(output, 'observations.md'), materialized.observations, 'utf8')
+  writeFileSync(join(output, 'run.json'), JSON.stringify({
+    experimentId: experiment.id,
+    summary: experiment.summary,
+    rubric: String(experiment.rubric),
+    ...extra,
+  }, null, 2), 'utf8')
+  writeFileSync(join(output, 'review-report.md'), renderReviewReport({
+    experiment,
+    result: reviewResult,
+    observations: materialized.observations,
+    adapter: extra.adapter,
+    profile: extra.profile,
+  }), 'utf8')
+  return output
+}
+
+const { options, paths } = parseArgs(process.argv.slice(2))
+
+// Config merge: flags win over a `dsh-eval.config.mjs` found
+// upward from cwd; profile falls back to the sterile default `headless`.
+const { config } = await loadEvalConfig(process.cwd())
+const profile = options.profile ?? config.profile ?? 'headless'
+// CLI resolution (C6): `--repo` flag > resolution layer (node_modules) >
+// config repo key (legacy). Dry-run never boots the CLI, so resolve lazily.
+let cli = { cliPath: undefined, repoDir: undefined }
+if (!options.dryRun) {
+  try {
+    const resolved = resolveDshCliChain({ repoFlag: options.repo, configRepo: config.repo })
+    cli = { cliPath: resolved.cli, repoDir: resolved.repo }
+  } catch (error) {
+    usage(`error: ${error.message}`)
+  }
+}
+
+for (const path of paths) {
+  if (!existsSync(resolve(path))) usage(`error: no such experiment path: ${path}`)
+}
+const files = paths.flatMap(path => discover(path)).sort()
+if (files.length === 0) usage('error: no *.review.mjs experiment files found')
+
+let failures = 0
+for (const file of files) {
+  let experiment
+  try {
+    experiment = await loadExperiment(file)
+    if (options.dryRun) {
+      const materialized = await materializeReviewExperiment(experiment)
+      const output = writeMaterialized(experiment, materialized, { adapter: null, dryRun: true })
+      process.stdout.write(`DRY  ${experiment.id}: ${output}\n`)
+      continue
+    }
+
+    process.stdout.write(`RUN  ${experiment.id} (${options.runs ?? experiment.defaultRuns} reviews)...\n`)
+    const result = await runDshReviewExperiment(experiment, {
+      profile,
+      cliPath: cli.cliPath,
+      dshRepoDir: cli.repoDir,
+      runs: options.runs,
+      timeoutMs: options.timeoutMs,
+      keepPluginRows: options.keepPluginRows,
+    })
+    const output = writeMaterialized(experiment, result, {
+      adapter: 'dsh-headless',
+      profile,
+      runs: result.runs,
+    }, result)
+    for (const attempt of result.attempts) {
+      const payload = attempt.result ?? {}
+      // run-N.txt is the reviewer's ANSWER (trace-derived, splice-proof),
+      // falling back to stdout for executors/trace-less runs; the raw final
+      // message stays in run-N.stdout.txt when it differs from the answer,
+      // the full session transcript in run-N.stderr.txt.
+      if (payload.answer !== undefined) writeFileSync(join(output, `run-${attempt.index}.txt`), payload.answer, 'utf8')
+      else if (payload.stdout !== undefined) writeFileSync(join(output, `run-${attempt.index}.txt`), payload.stdout, 'utf8')
+      if (payload.stdout !== undefined && payload.answer !== undefined && payload.stdout !== payload.answer) {
+        writeFileSync(join(output, `run-${attempt.index}.stdout.txt`), payload.stdout, 'utf8')
+      }
+      if (payload.stderr) writeFileSync(join(output, `run-${attempt.index}.stderr.txt`), payload.stderr, 'utf8')
+      if (payload.toolBoundaryEvidence) writeFileSync(join(output, `run-${attempt.index}.tool-boundary-evidence.json`), payload.toolBoundaryEvidence, 'utf8')
+      if (!attempt.ok) {
+        failures += 1
+        writeFileSync(join(output, `run-${attempt.index}.error.txt`), attempt.error, 'utf8')
+        process.stderr.write(`FAIL ${experiment.id} run ${attempt.index}: ${attempt.error}\n`)
+      }
+    }
+    if (result.attempts.every(attempt => attempt.ok)) process.stdout.write(`DONE ${experiment.id}: ${output}\n`)
+  } catch (error) {
+    failures += 1
+    process.stderr.write(`FAIL ${file}: ${error.message}\n`)
+  }
+}
+
+process.exit(failures === 0 ? 0 : 1)

package/docs/README.md

@@ -1,5 +1,5 @@
 ---
-description: dsh-eval 文档索引——安装与宿主接线、review、matcher 全集、disableRows/rowConfig 契约、intent case 规约、报告结构与已知问题的路由表
+description: dsh-eval 文档索引——安装与宿主接线、review、matcher 全集、disableRows/rowConfig/followups 契约、intent case 规约、报告结构与已知问题的路由表
 ---
 
 # dsh-eval · docs index
@@ -7,10 +7,11 @@ description: dsh-eval 文档索引——安装与宿主接线、review、matcher
 | 文档 | 主题 |
 |---|---|
 | [host-wiring.md](host-wiring.md) | 安装与宿主接线：peer 依赖（dsh-llm）、构建 CLI、profile、凭证、spawn 要求 |
-| [review.md](review.md) | comprehension review：实验定义、sterile profile、产物清单、六条评审规则 |
+| [review.md](review.md) | comprehension review：实验定义、空白环境 reviewer、产物清单、六条评审规则 |
 | [matchers.md](matchers.md) | trace matcher 与 mock helper 全集 |
 | [disablerows.md](disablerows.md) | `disableRows` 与 turn-close 门禁边界契约 |
 | [rowconfig.md](rowconfig.md) | `rowConfig` 行 config 覆写契约（整段替换语义、形状限制、与 disableRows 分工） |
+| [cross-turn.md](cross-turn.md) | `followups` 跨轮异步驱动契约（driver 行换装、子 agent settle 等待、mock 单 cursor 编排、有界重派断言） |
 | [intent-cases.md](intent-cases.md) | real 意图 case 规约：何时写、断言面、守卫、CI 语义 |
 | [report.md](report.md) | 机器可读报告（`--format json` / `--report`）结构 |
 | [runner-api.md](runner-api.md) | 程序化 runner API：`runEvalCase` options 契约、EvalRunResult 字段、跨档取 `cliPath` |

package/docs/cross-turn.md

@@ -0,0 +1,66 @@
+---
+description: followups 跨轮驱动契约——case 声明 followups 后 overlay 换装 eval 多轮 driver、后台子 agent 的 settle 等待语义、mock 脚本跨轮共享 cursor 的编排规则与 bounded-redispatch 断言面
+---
+
+# followups：跨轮异步驱动
+
+单轮 behavior case 的驱动模型覆盖不了 defer 自愈闭环：「turn 收尾派发 fork 子 agent → 子 agent 落盘修复 → **下一轮** stop 重扫转绿（或每轮一次有界重派）」。case 声明 `followups` 即启用跨轮驱动。
+
+## 为什么是 driver 行而不是 CLI resume
+
+实测定案（「跨轮异步修复驱动」FR 调研，见开发仓的 eval 状态板记录）：
+
+- headless runner 在主 agent 首次 idle 即退出，**进程退出会把 in-process 后台子 agent 当场 abort**（fire-and-forget 子 agent 存活窗口 = driver 的生命周期）；
+- dsh CLI 无 resume 表面（one task per invocation；resume 只在 cordis config 层）。
+
+因此 `followups` 的实现是 overlay 换装：disable `headless-runner` 行 + insert 本包的 `eval-multi-turn-driver`（`src/driver/multi-turn-driver.mjs`，file:// 挂载，与 mock adapter 同机制）。driver 语义：
+
+1. 以 case `task` 驱动 turn 1，等主 agent idle；
+2. 每个 followup 之前，**等待后台子 agent settle**（全局 `session/event` 投影：subagent 会话自 `turn/start` 起 pending、`turn/end` 止；空集后再过 250ms 静默宽限才放行；上限 `settleTimeoutMs`，默认 60s，超时报错退出）；
+3. 提交 followup（普通 user message）驱动下一轮；
+4. 最后一轮收尾后**同样等待一次 settle**——最后一轮的 turn close 也会派发（defer gate 每次失败 stop 都派 fixer），不等就会在退出时静默截断它们；「已派发 ⇒ 可观测结局」对每一轮成立；
+5. flush、按 headless 同款输出契约退出（最后一条非空 assistant 文本到 stdout；最后 turn `completed` → exit 0）。
+
+## case 声明
+
+```js
+export default {
+  id: 'gates-mock-defer-self-heal',
+  mode: 'mock',
+  disableRows: [],            // gate 交互 case 需显式装载 gates 行
+  task: '…turn 1 任务…',
+  followups: ['rescan now'],  // 每项 = 一个额外驱动轮
+  settleTimeoutMs: 30_000,    // 可选；等后台子 agent 的上限
+  script: { steps: [/* 跨轮共享 cursor，见下 */] },
+  expect: [/* matchers */],
+}
+```
+
+校验：`followups` 必须是非空 string[]；`settleTimeoutMs`（可选）必须是正有限数。仅声明 `settleTimeoutMs` 而无 `followups` 无效（不校验、不生效）。
+
+## mock 脚本编排：单 cursor 跨轮共享
+
+mock adapter 是单实例、单 cursor：**每次模型调用按序吃一步，不区分轮次与 会话**。跨轮 case 的 steps 是全运行编排——主 turn 步骤、子 agent 步骤、后续轮步骤交错排列：
+
+```js
+steps: [
+  textStep('turn 1 done'),          // 主 turn 1 收尾 → turn close 派发 fixer
+  textStep('fixer child answer'),   // fixer 子 agent 的首个（唯一）模型调用
+  textStep('turn 2 done'),          // followup 轮的收尾
+]
+```
+
+注意：turn-close blocking gate 的 splice 反馈步骤（见 [disablerows.md](disablerows.md)）同样消耗 cursor——编排跨轮脚本时先数清每轮会被 splice 几步。
+
+## 断言面
+
+- 派发与完成：`subagentDispatched` / `subagentCompleted`（见 [matchers.md](matchers.md) 派发面）；
+- **有界重派节律**：`subagentDispatchCount(matcher, expected)`——精确断言匹配 label 的派发总数（「每轮恰一次、N 轮共 N 次、不更多」）；
+- 跨轮重扫：`userMessages` 投影带全部轮次的 `user/message`，`userMessageTextIncludes` / `userMessageTextExcludes` 按 `source` 断言某轮是否被 gate steer（例如 turn 2 重扫转绿 → 无新的 gates steer）。
+
+## 边界
+
+- **settle 宽限是启发式，不是 barrier**：250ms 静默宽限可被「慢派发」击穿——若某插件的 turn-close 派发在主 agent idle 后 >250ms 才发出子 `turn/start`，driver 会空集放行、followup 先行（mock 面表现为脚本错步、通常 loud；real 面表现为轮次与子 agent 并发交叉）。宿主没有「派发完成」事件可用，这是对不存在信号的保守近似。
+- **时间预算叠加**：driver 的 settle 等待（默认每轮上限 60s）叠加在 case `timeoutMs`（runner 的 spawn 超时）之内。轮数 × settle 上限若超过 `timeoutMs`，先到的是 spawn 超时（结果 `timedOut`）而非 settle 报错——多轮 case 应按轮数放大 `timeoutMs`。
+- `subagentCompleted` 的「完成」以子会话产出非空 assistant 文本为准；被早夭 abort 的子日志可能不含 `subagent/descriptor`（label 投影为空）——见 matchers.md 派发面的早夭边界。要断言「每个派发都跑完」（而非任一跑完），用 `subagentCompletedCount`。
+- real 模式下 `followups` 同样可用（driver 不依赖 mock），但轮次内容非确定——real 意图 case 通常不需要它。

package/docs/host-wiring.md

@@ -60,7 +60,7 @@ node -e "console.log(require('fs').existsSync('node_modules/@deepseek-ai/dsh/lib
 
 - 被测插件须已装进所选 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)）。
+- review 默认空白环境：任意 profile 均可，树外插件行由 overlay 枚举禁用（详见 [review.md](review.md)）。
 
 ## 凭证
 

package/docs/known-issues.md

@@ -1,5 +1,5 @@
 ---
-description: 已知问题——real case 在 staged home 的 REQUEST_EXTENSION 失败（嫌疑 plugin-package-inventory-deepseek）及 disableRows 兜底
+description: 已知问题——real case 在 staged home 的 REQUEST_EXTENSION 失败（嫌疑 plugin-package-inventory-deepseek）、DSH file sandbox 下 dsh-review spawn EPERM 及 disableRows 兜底
 ---
 
 # 已知问题
@@ -13,3 +13,11 @@ description: 已知问题——real case 在 staged home 的 REQUEST_EXTENSION
 **框架侧兜底**：case 或 config 声明 `disableRows: ['plugin-package-inventory-deepseek']` 按行禁用该插件（机制见 [disablerows.md](disablerows.md)）。
 
 **追踪**：上游修复落地即删本条（不留僵尸条目）。
+
+## DSH file sandbox 下 `dsh-review` spawn headless 子进程 `EPERM`（未解）
+
+**症状**：在 DSH file sandbox（受限运行面）内运行 `dsh-review`，首次 spawn headless 子进程即报 `spawn EPERM`，escalated retry 后可运行。
+
+**定性**：沙箱运行面约束，非框架缺陷——沙箱拒绝 spawn 时换宿主侧终端或升级运行面即可（与本包维护规则「沙箱拒绝 spawn 时在宿主侧终端跑，不绕测试」同族）。登记供沙箱内调用方知晓。
+
+**追踪**：开发侧状态板按名登记为「2026-09-06 · dsh-review 沙箱 spawn EPERM 已知约束」（按名对齐）；运行面行为变化时同删。

package/docs/matchers.md

@@ -1,5 +1,5 @@
 ---
-description: trace matcher 与 mock helper 全集——工具面/文本面/输入面断言语义（toolCalled 到 userMessageTextIncludes）与 toolCallStep/textStep 脚本构件
+description: trace matcher 与 mock helper 全集——工具面/文本面/输入面/派发面断言语义（toolCalled 到 subagentCompletedCount）与 toolCallStep/textStep 脚本构件
 ---
 
 # Trace matchers 与 mock helpers
@@ -18,6 +18,7 @@ description: trace matcher 与 mock helper 全集——工具面/文本面/输
 | `finalText` | 最后一个组装 assistant 文本（无则 `''`） |
 | `userMessages` | `{ seq, source, text }[]`（`source` 原样透传：任务 prompt `{ kind: 'user' }`，插件 steer `{ kind: 'plugin', plugin }`） |
 | `requestHeaders` | `{ seq, reason, system, toolNames }[]`（组装后 system prompt + 挂载工具名） |
+| `subagentChildren` | `{ sessionId, parentSession, delegationDepth, label, mode, provider, assistantTexts, finalText }[]`——每个子 agent 独立 session 日志一条；身份（label/mode/provider）取子日志首条 version-3 的 `subagent/descriptor` 事件（镜像宿主 `foldSubagentDescriptor` 的首条权威语义），`finalText` 是子会话自己的最后一条非空 assistant 文本（无则 `''` = 派发了但没答） |
 | `sessions` / `sessionId` | 原始解析结果 `{ header, events }[]` 与主 session id |
 
 `runEvalCase` 返回的 `result.trace` 即此形状（无 session 日志时为 `undefined`；字段语义见 [runner-api.md](runner-api.md)）。
@@ -43,6 +44,17 @@ description: trace matcher 与 mock helper 全集——工具面/文本面/输
 - `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' }`）。
 
+## 派发面（子 agent）
+
+主 session 日志不含派发事件（宿主不向父 session 写），但子 agent 的独立 session 日志与主日志同 persistence root，随 run 一并被收集——派发面投影即来自这些子日志：
+
+- `subagentDispatched(label)`：至少一个子 agent 以匹配的 label 派发。`label` 用字符串/RegExp 匹配子会话的 `subagent/descriptor` label（如 `gates:fix:<gate>`、前缀 `/^gates:fix:/`），或谓词取整个子记录（可按 `mode`/`provider`/`delegationDepth` 匹配）；
+- `subagentCompleted(label)`：匹配的子 agent 产出了答案——其自身日志含至少一条非空 assistant 文本（不区分中止/正常收束：日志层无 subagent 完成事件，产出过文本即算）。只派发未应答（子日志存在但无产出）不通过。
+- `subagentDispatchCount(label, expected)`：匹配 label 的派发**总数**恰为 `expected`——有界重派节律断言（「每轮恰一次、不更多」），配合跨轮驱动（[cross-turn.md](cross-turn.md)）。
+- `subagentCompletedCount(label, expected)`：匹配 label 且**跑完**（产出非空 assistant 文本）的子 agent 恰为 `expected` 个。`subagentCompleted` 任一跑完即过；本 matcher 钉死每个派发的结局——「已派发 ⇒ 可观测结局」的跨轮 case 里，任一被截断的子 agent 都判负。
+
+边界：子会话产物（独立 JSONL）经 `subagentChildren` 记录进入断言面（身份 + 子自身文本）；子会话内部的工具调用**不**并入主投影的 `toolCalls`/`toolResults`（那属于主会话行为面），需要时经 `sessions` 原始日志自行投影。
+
 ## Mock script helpers
 
 - `toolCallStep(name, args)`：一步「模型调工具」，结束于 tool-calls；

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`，必须恰好出现一次）——在 `@catheadowl/dsh-eval/experimental` 逃生面（见 [experimental.md](experimental.md)，无兼容承诺）。自定义 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,9 +65,10 @@ 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）。
 
 ## 六条评审规则
 

package/package.json

@@ -1,9 +1,14 @@
 {
   "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.2.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",
@@ -28,6 +33,7 @@
     "docs/",
     "README.md",
     "README.zh.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {