@catheadowl/dsh-eval 0.2.0 → 0.3.0

package/bin/dsh-review.mjs

@@ -1,154 +1,179 @@
-#!/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 }
+if (!options.dryRun) {
+  try {
+    const resolved = resolveDshCliChain({ repoFlag: options.repo, configRepo: config.repo })
+    cli = { cliPath: resolved.cli }
+  } 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,
+      runs: options.runs,
+      timeoutMs: options.timeoutMs,
+      keepPluginRows: options.keepPluginRows,
+    })
+    const output = writeMaterialized(experiment, result, {
+      adapter: 'dsh-headless',
+      profile,
+      runs: result.runs,
+      // Machine-readable boundary accounting per run: `checked` (the request
+      // headers were inspected) vs `not-executed` (no session artifact, so the
+      // reviewer's tool face was never verified) — the report and run-N.txt
+      // carry the same fact in prose (EVAL-021).
+      toolBoundaries: result.attempts.map(attempt => ({
+        run: attempt.index,
+        status: attempt.result?.toolValidation?.status ?? 'not-reported',
+        ...(attempt.result?.traceGap === undefined ? {} : { reason: attempt.result.traceGap }),
+      })),
+    }, 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. A run whose tool
+      // boundary was never verified says so at the TOP of this file: it is
+      // what a grader opens first, and its answer is the fallback one.
+      const boundaryNotice = payload.toolValidation?.status === 'not-executed'
+        ? `[tool-boundary: NOT EXECUTED — ${payload.traceGap ?? 'no session trace materialized'}]\n\n`
+        : ''
+      if (payload.answer !== undefined) writeFileSync(join(output, `run-${attempt.index}.txt`), boundaryNotice + payload.answer, 'utf8')
+      else if (payload.stdout !== undefined) writeFileSync(join(output, `run-${attempt.index}.txt`), boundaryNotice + 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/experimental.md

@@ -20,16 +20,17 @@ import { resolveDshCliChain } from '@catheadowl/dsh-eval/experimental'
 | `stageProfileStore` | 把真实 profile store junction 感知地暂存进沙箱 home（沙箱机制） |
 | `buildOverlayYaml` | 由片段拼装 dsh overlay YAML（整段发射器） |
 | `overlayDisableRows` | 生成 `disabled: true` 的行禁用 overlay 片段 |
-| `parseSessionLog` | 解析一条未压缩 JSONL session artifact 为 `{ header, events }` |
+| `parseSessionLog` | 解析一条未压缩 JSONL session artifact 为 `{ header, events }`；header 的 `version` 戳不在已知代际集合内即抛错 |
 | `buildTrace` | 把 session 事件投影为 matcher 使用的 trace 对象 |
-| `loadTraceDir` | 从 run 目录装载并解析 trace（无日志时返回 `undefined`） |
+| `collectSessionTrace` | 收集一个 run 的 trace 与「为什么没有 trace」的 seam 诊断：返回 `{ trace, gap }`，`gap` 文案含实际候选文件名与代际嫌疑（唯一的收集入口） |
+| `KNOWN_SESSION_FORMAT_VERSIONS` | 本包接受的 session 格式代际集合（`parseSessionLog` 的准入面；宿主新增代际时与本包重验同步） |
 | `executeReviewExperiment` | 用给定 executor 执行抽象 review 实验 |
 | `materializeReviewExperiment` | 把实验定义物化为产物目录 |
 | `renderObservationSections` | 标准 observation renderer（自定义 executor 用） |
 | `OBSERVATIONS_PLACEHOLDER` | prompt 中的观测占位符常量（必须恰好出现一次） |
 | `createDshHeadlessReviewExecutor` | 构造 dsh headless review executor |
 | `runDshReviewExperiment` | 端到端跑一个 dsh review 实验 |
-| `validateToolBoundary` | 校验 trace 满足 turn-close 工具边界契约 |
+| `validateToolBoundary` | 校验 trace 满足 turn-close 工具边界契约；结果带 `status`（`checked` / `not-executed`），无 trace 时**不是**通过 |
 | `renderToolBoundaryEvidence` | 渲染边界校验的机器可读证据 |
 
 新公开能力先进本入口；稳定后经明确决策才升入包根入口（升入即接受 semver 义务）。

package/docs/host-wiring.md

@@ -1,5 +1,5 @@
 ---
-description: 安装与宿主接线——dsh-llm peer 的三形解析结局与 junction 步骤、构建 CLI 与 profile/凭证/spawn 三类运行前置
+description: 安装与宿主接线——dsh-llm peer 的三形解析结局与 junction 步骤、构建 CLI 与 profile/凭证/spawn 三类运行前置、本包对宿主 session seam 的四处硬断言及其执法面（artifact 代际命名 / header 代际戳 / 拼接帧容器 / snapshotEvents 读取面），以及 mock 模式依赖的宿主 LLM adapter 线上契约（prepareCall，自带覆写对 peer 实例代差免疫）。
 ---
 
 # 安装与宿主接线
@@ -56,11 +56,36 @@ node -e "console.log(require('fs').existsSync('node_modules/@deepseek-ai/dsh/lib
 
 `false` = 解析层缺 CLI：先把上述 junction 重建为指向宿主检出；仍 `false` 则宿主检出未构建（先构建宿主）。这类 junction 维护是机器相关的开发环境事务，不入库，由各开发环境自行承接（同上文 peer 接线的 gitignore 纪律）。behavior 与 review 的真实运行都从定位到的 CLI spawn dsh 本体。
 
+## 宿主 session seam：本包硬断言的四处，坏了多是具名失败
+
+behavior 与 review 的证据都取自**真实 dsh 会话的产物与进程内日志**，因此本包直接断言宿主的几处 session seam。它们随宿主演进时不会有编译期提示，所以每一处都配一行**执法面**（表里的符号就是）；宿主检出更新后、动本包引用它们的文档前，先按本节对源码重新验证：
+
+| 断言 | 宿主依据 | 本包执法面 | 坏了长什么样 |
+|---|---|---|---|
+| 会话 artifact 按**格式代**命名：v0 是 `session.jsonl`，之后每代带小写数字（当前 `session.v3.jsonl`）；`compression: none` 时无 `.zstd` 后缀 | `session-persistence-jsonl/src/format.ts` 的 `generationLogFilename`，配 `core/session/src/types.ts` 的 `SESSION_FORMAT_VERSION` | `isSessionLogFilename`（命名判定）+ `collectSessionTrace`（收集）⇒ behavior 失败文案 / review 记账里的 `traceGap` | 只按 v0 名收集 ⇒ 一条日志都收不到；失败文案列出**实际扫到的候选文件名**并写明「宿主 artifact 命名可能已换代」，不再只报 `no session trace materialized` |
+| 会话 header 的 `version` 戳是宿主对逻辑代际的声明（当前 v3） | 同上；已发布的代际链见 `session-format-catalog/src/generated.ts`（codecs v0–v3、`currentVersion: 3`） | `KNOWN_SESSION_FORMAT_VERSIONS`（`parseSessionLog` 入口准入） | 未知代际 ⇒ 解析当场拒绝并报出版本号（`session header version vN is not a known generation`），不再把各投影字段静默降级成空数组 |
+| 会话日志是**拼接帧容器**（宿主默认 zstd），须逐帧扫描 | `session-persistence-jsonl/src/zstd.ts` 的帧扫描 | eval overlay 固定 `compression: none` + `packChunks: false`（`src/overlay.mjs`） | 整文件一次解压 ⇒ `ZSTD_error_prefix_unknown`（第二帧魔数被当输入） |
+| 进程内读 durable 事件的 API 是 `Session#snapshotEvents()`（不可变冻结快照）；早期的 `session.events` getter 已被删除 | `core/session/src/index.ts` 的 `snapshotEvents` | driver 行（`src/driver/multi-turn-driver.mjs`）直接调用，没有回退路径 | 属性访问得到 `undefined` ⇒ 进程内消费者抛 `agent.session.events is not iterable`，整个 headless run 直接死 |
+
+命名行与代际行的读取面由本包的 eval overlay 固定（`compression: none` + `packChunks: false`），所以每轮 run 的 artifact 是**明文逐事件**布局；命名判定、代际准入与收集入口都在 `src/trace.mjs`（`isSessionLogFilename` / `KNOWN_SESSION_FORMAT_VERSIONS` / `collectSessionTrace`），behavior runner 与 review adapter 共用同一个收集入口，缺 artifact 时各自把 `traceGap` 带进失败文案与产物记账。帧容器行走 overlay 固定；最后一行是 driver 行读日志时直接依赖的方法。
+
+> **维护触发器**：宿主 session 格式、持久化命名或 `Session` 读取面变更 ⇒ 先按上表对 vendored 检出重新验证断言，再更新本篇与引用它们的源码/认知。前两行现在是**机械的**——命名或代际戳变了，跑一条 case 就红在具名文案上（候选文件名 / 版本号）；后两行仍只有真跑一条 case 才会暴露。
+
+### 宿主 LLM adapter 线上契约（mock 模式专用）
+
+mock 模式经 `eval-mock-llm` 插件（`src/mock/mock-adapter.mjs`）注册 `EvalMockAdapter`，它 `extends` 的 `LlmAdapter` 基类解析自**本包的 peer 实例**——该实例可以落后于驱动它的宿主运行时（实测：宿主 0.1.5-rc.2 的 LLM 服务对已注册 adapter 新增 `registration.adapter.prepareCall(...)` 调用面时，本地 peer 还是 0.0.1-rc.1，继承面缺失，全部 mock run 死在启动期）。因此适配器**自带** `prepareCall` 覆写、不依赖继承面在不在：形状镜像宿主基类默认契约（`PreparedAdapterCall`——`{ model: resolveModel(...), stream: options => this.stream(options) }`，model 元数据与派发入口绑定同一代适配器）。
+
+| 断言 | 宿主依据 | 本包执法面 | 坏了长什么样 |
+|---|---|---|---|
+| 宿主 LLM 服务经 `prepareCall` 派发每次模型调用：adapter 级 `prepareCall(provider, model, signal)` 返回 `{ model, stream }`（一次性句柄，防 HMR 混代） | `packages/llm/llm/src/index.ts` 的 `registration.adapter.prepareCall(...)` 调用与 `LlmAdapter` 基类（`PreparedAdapterCall`） | `EvalMockAdapter` 自带 `prepareCall` 覆写（`src/mock/mock-adapter.mjs`）——真跑一条 mock case 即红在具名错误串上 | mock run 空转：无 session 事件、workspace 未落、final text 空，stderr 带 `registration.adapter.<method> is not a function` |
+
+> **维护触发器**：宿主 adapter 线上契约演进（新增/改签名线上方法）⇒ 先对宿主 `packages/llm/llm/src/index.ts` 重验 `EvalMockAdapter` 的自带面（`prepareCall` / `resolveModel` / `stream` 的形状与语义），再同 commit 改本节与 `src/mock/mock-adapter.mjs`。
+
 ## 环境面：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)）。
+- 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）、投影普查（trace.census）与 toolCallStep/textStep 脚本构件
 ---
 
 # Trace matchers 与 mock helpers
@@ -18,6 +18,8 @@ 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 文本（无则 `''` = 派发了但没答） |
+| `census` | 投影普查（只报数，不判定）：`{ eventTypeCounts, projectionLengths, projectionSkipped: { main, children }, projectionFieldGaps, subagent: { mainLogDescriptorEvents, supportedDescriptors, children } }`。语义见下「投影普查」节；手搓 trace（不经 `buildTrace`）时可为 `undefined` |
 | `sessions` / `sessionId` | 原始解析结果 `{ header, events }[]` 与主 session id |
 
 `runEvalCase` 返回的 `result.trace` 即此形状（无 session 日志时为 `undefined`；字段语义见 [runner-api.md](runner-api.md)）。
@@ -43,6 +45,37 @@ 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` 原始日志自行投影。
+
+## 投影普查（`trace.census`）
+
+宽松投影（tolerant reader）的补救面：宿主事件 payload 演进时 `buildTrace` 不抛错，只把字段填成空值或丢掉整条记录。空投影会让负向断言真空通过——`toolNotCalled`、`userMessageTextExcludes`、以及 `subagentDispatchCount` / `subagentCompletedCount` 的 `expected === 0` 档都判 ok。**普查只报数，不判定**：它让「宿主日志里本来就没有这类事件」与「有事件但投影丢掉了」在报告里可分，是否降级由人判读。
+
+三个信号，对应三种坏法：
+
+| 信号 | 看什么 |
+|---|---|
+| 主 session 事件（`eventTypeCounts` / `projectionLengths` / `projectionSkipped.main`） | 主日志（`buildTrace` 的投影输入）逐事件类型计数（任何类型，含插件扩展类型）；五个投影的长度；以及**每个投影上「计数 − 长度 > 0」的差额**（`projectionSkipped.main`，按投影字段名）——记录被丢了的档 |
+| **字段级缺口**（`projectionFieldGaps`） | 记录**留住了但字段读不到**的事件，按缺什么计数：`toolCallWithoutName` / `toolCallWithoutCallId` / `toolResultWithoutCallId` / `headerWithoutSystem` / `headerWithoutToolNames`。`tool/call`、`tool/result`、`request/header` 是 1:1 投影（计数 − 长度恒为 0），宿主搬字段时只在这里可见。**不计数**：`request/header` 的 `tools` 数组整个缺失（与真空列表投影一致） |
+| 子会话（`census.subagent`） | `subagentChildren` 的输入面：`children[]` 逐条给该子日志的 `subagent/descriptor` 事件数、其中 `version === 3` 的条数（`supportedDescriptors`，**数事件不是数子会话**）**以及折叠出的身份**（`label` / `mode` / `provider`）；`projectionSkipped.children` 两个身份计数——`withoutIdentity`（三项全缺）与 `withoutLabel`（`label` 缺，哪怕 mode/provider 有）。`mainLogDescriptorEvents` 是**主日志自己**的 `subagent/descriptor` 事件数（现宿主把 descriptor 写进子日志，这个数通常为 0）。**子日志不是主日志**，`eventTypeCounts` 不统计它们 |
+
+判读要点：
+
+- **差额 ≠ 缺陷**。`assistant/message`、`user/message` 的**空文本消息是设计上整条丢弃**（保护「组装文本」投影语义），这类差额属合法，普查不替你做白名单；
+- **两类信号别混**：`projectionSkipped.main` 看「记录被丢了」，`projectionFieldGaps` 看「记录在、字段没了」。后者正是 `toolNotCalled` 最危险的形态——调用记录还在、`name` 为 `undefined`，`nameMatches` 对任何 matcher 都不命中，负向断言照绿；
+- **身份缺失型降级**：某子日志 `descriptorEvents > 0` 而 `supportedDescriptors === 0`，即它进了 `subagentChildren` 但身份全空；但**只要 `label` 缺**（`withoutLabel`），按 label 匹配的 `*Count(label, 0)` 就会真空通过——哪怕 `supportedDescriptors` 看起来健康、mode/provider 都在。两个计数分开报就是为了这个档；
+- **子会话集合是启发式**：`subagentChildren` 收「header 带 `parentSession`」的日志，而宿主对 fork/resume/seed 日志也写这个字段——它们会以「无身份子记录」出现在普查里。这是集合的性质，不是本次降级（日志层无法复现宿主的 agent 链所有权判定）；
+- 只出现在**运行面**：`--format json` 的每条 case 记录（`census` 字段，pass 与 fail 都带；**无 trace 的记录没有**）与 `.runs/<id>/trace.json` 的 `trace.census`；**文本输出零新增**（逐字节输出契约不动），失败文案也不带计数。
+
 ## Mock script helpers
 
 - `toolCallStep(name, args)`：一步「模型调工具」，结束于 tool-calls；