@catheadowl/dsh-eval 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -8,6 +8,77 @@ All notable changes to `@catheadowl/dsh-eval` are documented here. Versions
 follow [Semantic Versioning](https://semver.org/); entries follow
 [Keep a Changelog](https://keepachangelog.com/) conventions.
 
+## [0.3.0] — 2026-09-13
+
+### Added
+
+- **Projection census** on every case that produced a session trace:
+  `census.eventTypeCounts` (the main session log's events per type),
+  `census.projectionLengths` (the five projection lengths) with
+  `census.projectionSkipped` naming where a count exceeds its projection length,
+  `census.projectionFieldGaps` naming the events that projected while a field
+  they carry went missing (the `tool/call` / `tool/result` / `request/header`
+  projections are 1:1, so a moved field never shows up as a length difference),
+  and `census.subagent` (the child logs behind `subagentChildren`: their
+  `subagent/descriptor` event counts, how many carry the supported descriptor
+  version, and the folded identity). The census reports numbers only and never
+  decides whether a difference is a defect — it makes "the host log carried no
+  such event" and "the projection dropped it" separable in `--format json` and
+  in `.runs/<id>/trace.json`. Cases with no trace carry no census.
+- Session-seam boundary assertions: `collectSessionTrace` reports which
+  candidate artifact files were actually present when no session trace
+  materializes (behavior failures name the host artifact naming instead of a
+  bare "no session trace materialized"), and `parseSessionLog` refuses a
+  `header.version` outside `KNOWN_SESSION_FORMAT_VERSIONS` with the version
+  number instead of projecting empty fields. `EvalRunResult.traceGap` carries
+  the diagnosis to the CLI failure text.
+
+### Removed
+
+- `loadTraceDir` (experimental): replaced by `collectSessionTrace`, which
+  returns the trace together with the reason none was built. Migrate
+  `loadTraceDir(root)` to `collectSessionTrace(root).trace`.
+- **`options.dshRepoDir`** on `runEvalCase` (and the same legacy option on
+  the review executor and `executeBehaviorExperiment`): the CLI location is
+  now `options.cliPath` only. **Migrating a case that trips this**: resolve
+  once with `resolveDshCliChain` (the `/experimental` export) and pass its
+  `cli` result as `cliPath` — the `dsh-eval` / `dsh-review` CLIs already do
+  this via `--repo`, the `node_modules` resolution layer, or the config
+  `repo` key.
+
+### Fixed
+
+- **Mock mode against host 0.1.5-rc.2: the scripted adapter now carries its
+  own `prepareCall`.** The host's LLM service dispatches every model call
+  through `registration.adapter.prepareCall(...)`, a wire-contract step the
+  adapter's inherited base class did not have — the base resolves from this
+  package's `@deepseek-ai/dsh-llm` peer instance, which lagged the host
+  runtime (0.0.1-rc.1 vs 0.1.5-rc.2), so every mock run died at startup with
+  `registration.adapter.prepareCall is not a function`. The override mirrors
+  the host base-class default (`{ model, stream }` bound to one adapter
+  generation), making the wire contract independent of the peer instance's
+  generation; the seam is now documented in `docs/host-wiring.md` with a
+  maintenance trigger.
+- `census.eventTypeCounts` counts prototype-named event types correctly: a
+  plug-in event type such as `constructor` or `__proto__` used to produce a
+  string-concatenated value or vanish from the map entirely, so a field named
+  like a count could hold a non-number.
+- Session-trace discovery follows the host's **format-generation artifact
+  names**: `session.jsonl` for v0 and `session.vN.jsonl` for later
+  generations (`session.v3.jsonl` on the current host). Matching only the v0
+  name made every behavior case fail with "no session trace materialized"
+  after the host bumped the session format.
+- The multi-turn driver reads the durable log through
+  `Session#snapshotEvents()`; the `session.events` getter it used was removed
+  upstream, so any case declaring `followups` aborted the headless run with
+  `agent.session.events is not iterable`.
+- Review runs no longer fail open when no session artifact materializes:
+  `validateToolBoundary` reports `status: 'not-executed'` (not a pass), the
+  executor result carries the gap, the report states
+  `tool boundary: NOT EXECUTED on run(s) N`, and both `run-N.txt` and
+  `run.json` record it — a review whose tool face was never verified no longer
+  reads as a normal one.
+
 ## [0.2.1] — 2026-09-09
 
 ### Added
@@ -52,6 +123,7 @@ follow [Semantic Versioning](https://semver.org/); entries follow
   `@deepseek-ai/dsh-llm` is a peerDependency provided by the host
   ecosystem.
 
+[0.3.0]: https://github.com/CatheadOwl/dsh-eval/releases/tag/v0.3.0
 [0.2.1]: https://github.com/CatheadOwl/dsh-eval/releases/tag/v0.2.1
 [0.2.0]: https://github.com/CatheadOwl/dsh-eval/releases/tag/v0.2.0
 [0.1.0]: https://github.com/CatheadOwl/dsh-eval/releases/tag/v0.1.0

package/bin/dsh-eval.mjs

@@ -11,9 +11,10 @@
  * A case path is a `*.eval.mjs` file or a directory scanned recursively for
  * them. Each file default-exports one case object (or an array of them):
  * `{ id, task, mode?: 'real'|'mock', expect: Matcher[], script?, persona?,
- * prepare?, timeoutMs? }`. Real cases skip when DEEPSEEK_API_KEY is absent;
- * the exit code is 1 when any run fails. Failures keep their artifacts under
- * `<case file dir>/.runs/<case id>/`.
+ * prepare?, timeoutMs? }`. Real cases skip when NO credential is visible —
+ * the env var DEEPSEEK_API_KEY OR the staged home's .credentials.yaml,
+ * either one counts. The exit code is 1 when any run fails. Failures keep
+ * their artifacts under `<case file dir>/.runs/<case id>/`.
  *
  * Output formats:
  * - `--format text` (default): unchanged human output on stdout/stderr.
@@ -134,7 +135,8 @@ function writeArtifacts(evalCase, result, mode) {
     writeFileSync(join(artifactsDir, 'stderr.txt'), result.stderr)
     writeFileSync(join(artifactsDir, 'trace.json'), JSON.stringify({
       caseId: evalCase.id, mode, task: evalCase.task,
-      exitCode: result.exitCode, timedOut: result.timedOut, trace: result.trace,
+      exitCode: result.exitCode, timedOut: result.timedOut,
+      traceGap: result.traceGap, trace: result.trace,
     }, undefined, 2))
     result.sessionLogs.forEach((text, index) => {
       writeFileSync(join(artifactsDir, `session-${index}.jsonl`), text)
@@ -233,7 +235,7 @@ for (const file of files.sort()) {
     const runStartedAt = Date.now()
     let result
     try {
-      result = await runEvalCase(evalCase, { profile, cliPath, dshRepoDir: repoDir, mode })
+      result = await runEvalCase(evalCase, { profile, cliPath, mode })
     } catch (error) {
       records.push(createCaseRecord({
         id: evalCase.id, file, mode, status: 'fail',
@@ -247,14 +249,19 @@ for (const file of files.sort()) {
 
     if (result.trace === undefined) {
       const artifactsDir = writeArtifacts(evalCase, result, mode)
+      // The runner's seam diagnosis (which candidate file names were actually
+      // collected, or which artifact was refused) IS the failure text: a bare
+      // "no session trace materialized" pointed readers at the parser while
+      // the real drift was the host's artifact naming (EVAL-019/EVAL-020).
+      const reason = `${result.traceGap ?? 'no session trace materialized'} (exit ${result.exitCode}${result.timedOut ? ', timed out' : ''})`
       records.push(createCaseRecord({
         id: evalCase.id, file, mode, status: 'fail',
-        failures: [`no session trace materialized (exit ${result.exitCode}${result.timedOut ? ', timed out' : ''})`],
+        failures: [reason],
         exitCode: result.exitCode, timedOut: result.timedOut,
         durationMs, artifactsDir,
       }))
       process.stderr.write(
-        `FAIL ${evalCase.id}: no session trace materialized (exit ${result.exitCode}${result.timedOut ? ', timed out' : ''})\n`
+        `FAIL ${evalCase.id}: ${reason}\n`
         + `     artifacts: ${artifactsDir}\n--- stderr ---\n${result.stderr}\n`,
       )
       continue
@@ -278,7 +285,8 @@ for (const file of files.sort()) {
       records.push(createCaseRecord({
         id: evalCase.id, file, mode, status: 'pass',
         exitCode: result.exitCode, timedOut: result.timedOut,
-        durationMs, ...(artifactsDir !== undefined ? { artifactsDir } : {}),
+        durationMs, ...(result.trace?.census !== undefined ? { census: result.trace.census } : {}),
+        ...(artifactsDir !== undefined ? { artifactsDir } : {}),
       }))
       say(`PASS ${evalCase.id}`)
     } else {
@@ -293,6 +301,7 @@ for (const file of files.sort()) {
         id: evalCase.id, file, mode, status: 'fail', failures: hint ? [...failures, hint] : failures,
         exitCode: result.exitCode, timedOut: result.timedOut,
         durationMs, artifactsDir,
+        ...(result.trace?.census !== undefined ? { census: result.trace.census } : {}),
       }))
       process.stderr.write(`FAIL ${evalCase.id} (exit ${result.exitCode}):\n${failures.map(f => `  - ${f}`).join('\n')}\n`)
       if (hint !== undefined) process.stderr.write(`  ! ${hint}\n`)

package/bin/dsh-review.mjs

@@ -95,11 +95,11 @@ 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 }
+let cli = { cliPath: undefined }
 if (!options.dryRun) {
   try {
     const resolved = resolveDshCliChain({ repoFlag: options.repo, configRepo: config.repo })
-    cli = { cliPath: resolved.cli, repoDir: resolved.repo }
+    cli = { cliPath: resolved.cli }
   } catch (error) {
     usage(`error: ${error.message}`)
   }
@@ -127,7 +127,6 @@ for (const file of files) {
     const result = await runDshReviewExperiment(experiment, {
       profile,
       cliPath: cli.cliPath,
-      dshRepoDir: cli.repoDir,
       runs: options.runs,
       timeoutMs: options.timeoutMs,
       keepPluginRows: options.keepPluginRows,
@@ -136,15 +135,29 @@ for (const file of files) {
       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.
-      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')
+      // 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')
       }

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,6 +56,31 @@ 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 <插件目录>`；

package/docs/matchers.md

@@ -1,5 +1,5 @@
 ---
-description: trace matcher 与 mock helper 全集——工具面/文本面/输入面/派发面断言语义（toolCalled 到 subagentCompletedCount）与 toolCallStep/textStep 脚本构件
+description: trace matcher 与 mock helper 全集——工具面/文本面/输入面/派发面断言语义（toolCalled 到 subagentCompletedCount）、投影普查（trace.census）与 toolCallStep/textStep 脚本构件
 ---
 
 # Trace matchers 与 mock helpers
@@ -19,6 +19,7 @@ description: trace matcher 与 mock helper 全集——工具面/文本面/输
 | `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)）。
@@ -55,6 +56,26 @@ description: trace matcher 与 mock helper 全集——工具面/文本面/输
 
 边界：子会话产物（独立 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；

package/docs/review.md

@@ -55,6 +55,8 @@ dsh-review \
 
 真实运行的 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`）。
 
+**校验没跑成也要记账**：收不到 session artifact（宿主 artifact 命名或会话格式换代是最常见的成因）时 `validateToolBoundary` 返回 `status: 'not-executed'` 而**不是**通过，适配器把该状态与 seam 诊断挂上执行结果；报告头写明 `tool boundary: NOT EXECUTED on run(s) N`，对应轮次的 `run-N.txt` 顶部与报告条目也各写一行原因，`run.json` 的 `toolBoundaries` 给机器读。这是有意的取向：**「没验证」必须看起来像没验证**——静默 fail-open 会让一份「工具边界从未检查过」的 review 产物读起来完全正常。
+
 **刻意复用宿主插件面**（例如要评审某插件自己的 gate 行为）：加 `--keep-plugin-rows`——跳过树外行枚举，仅保留静态工具禁用，宿主 gates 恢复运行。
 
 > 注意：无 `id` 的组合条目对 id 定位的禁用天然不可见（宿主 loader 语义），本包的树外 bundle 生态均为带 id 行形态；发现无 id 树外行时以工具边界校验 fail-loud 兜底。白名单是**按行名**无条件保留——若某树外 bundle 刻意以白名单名（如 `system-prompt`）insert 自己的行，该行不会被禁（威胁模型是本机自己的 profile，非对抗面）；此类泄漏同样由工具边界校验兜底。
@@ -65,9 +67,9 @@ dsh-review \
 
 - `observations.md`：本次实时物化的可见证据；
 - `task.txt`：实际发给每位 reviewer 的完整任务；
-- `run-N.txt`：该轮 reviewer 的**答案**——trace 推导（首条插件注入消息之前的最后一条 assistant 文本，抗回合尾部劫持），无 trace 时回落到 stdout 的最终消息；劫持发生时原始最终消息另存 `run-N.stdout.txt`；
+- `run-N.txt`：该轮 reviewer 的**答案**——trace 推导（首条插件注入消息之前的最后一条 assistant 文本，抗回合尾部劫持），无 trace 时回落到 stdout 的最终消息；劫持发生时原始最终消息另存 `run-N.stdout.txt`；工具边界校验未执行时，本条文件顶部先写一行 `[tool-boundary: NOT EXECUTED — <原因>]`（答案本身退回 stdout 的最终消息）；
 - `run-N.stderr.txt` / error：完整会话转录（判读回溯的 transcript 指针，报告每轮引用）/ 失败原因；
-- `run.json`：experiment、rubric、adapter、profile 与 run 数；
+- `run.json`：experiment、rubric、adapter、profile、run 数与每轮 `toolBoundaries` 记账（`checked` / `not-executed` + 原因）；
 - `review-report.md`：判读报告骨架——机器字段自动填（experiment/adapter/ profile/runs、observations 指纹、rubric 位置、每轮 reviewer **答案**与 transcript 指针），三个 **人工判读栏目**留白待填：intentional design 命中项、新 red flag、下一步（改输出 / 改 rubric / 改 behavior case / 不处理）。刻意不做自动评分——review 层的价值在人工判断，报告只把判断物化成可归档、可对比的工程证据（dry-run 也会生成，runs 记 0）。
 
 ## 六条评审规则

package/docs/runner-api.md

@@ -17,10 +17,9 @@ const result = await runEvalCase(evalCase, { profile: 'headless', cliPath, mode:
 | 键 | 类型 | 语义 |
 |---|---|---|
 | `profile` | `string` | 必填。承载被测插件的 dsh profile（沙箱会暂存其 store，不污染真实 home）。 |
-| `cliPath` | `string` | 编译好的 dsh CLI 入口（`apps/cli/lib/bin.js`）绝对路径；优先于 `dshRepoDir`。程序化取值见下节。 |
+| `cliPath` | `string` | 必填。编译好的 dsh CLI 入口（`apps/cli/lib/bin.js`）绝对路径（`resolveDshCliChain` 结果）。程序化取值见下节。 |
 | `mode` | `'real' \| 'mock'` | 覆写 case 自带的 mode；mock 需 `script.steps`。 |
 | `artifactsDir` | `string` | 提供则把 stdout/stderr/trace/session 日志拷贝到该目录（自动创建）。 |
-| `dshRepoDir` | `string` | **已弃用**：宿主 checkout 目录（从中拼出 CLI 路径）。下个 minor 删除——迁移到 `cliPath`。 |
 
 ## `cliPath` 从哪来：跨档关系（读我）
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.1",
+  "version": "0.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -42,6 +42,6 @@
     "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"
+    "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/cli-report.test.mjs tests/discovery.test.mjs tests/review.test.mjs tests/tool-validation.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,15 +1,14 @@
 /** dsh-headless execution adapter for model-independent review experiments. */
 
-import { existsSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { 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 { collectSessionTrace } from '../../trace.mjs'
 import { validateToolBoundary, renderToolBoundaryEvidence } from '../../tool-validation.mjs'
 
 /**
@@ -70,23 +69,14 @@ function buildReviewOverlayYaml(pluginRows, { keepPluginRows }) {
   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. */
+/** The CLI entry for an executor: the explicit cliPath (a `resolveDshCliChain`
+ * result). Its absence 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')
+  if (options.cliPath === undefined) {
+    throw new Error('review adapter needs options.cliPath (a resolveDshCliChain result)')
+  }
+  return resolve(options.cliPath)
 }
 
 /**
@@ -162,39 +152,43 @@ export function createDshHeadlessReviewExecutor(options) {
 
       // 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).
+      // session, fail the run on violation.  A missing session log does NOT
+      // skip the check silently: `validateToolBoundary` reports
+      // `status: 'not-executed'`, and the adapter carries that fact (plus the
+      // seam diagnosis) on the result so the report and run artifacts state
+      // that the boundary guarantee was not verified (EVAL-021).
       // 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
+      const { trace, gap } = collectSessionTrace(join(dshHome, 'sessions'))
+      const validation = validateToolBoundary(trace, { allowedTools })
+      result.toolValidation = validation
+      if (validation.status === 'not-executed') {
+        // `traceGap` mirrors the behavior runner's field name for the same
+        // seam diagnosis; the bin writes both into run-N.txt and the report.
+        result.traceGap = gap
+      }
+      if (validation.status === 'checked' && !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 (recorded by `traceGap` above).
+      result.answer = trace !== undefined && trace.answerText !== '' ? trace.answerText : stdout
 
       return result
     } finally {

package/src/driver/multi-turn-driver.mjs

@@ -60,7 +60,10 @@ function isSubagentSession(session) {
 function summarize(agent) {
   let text = ''
   let reason
-  for (const event of agent.session.events) {
+  // `snapshotEvents()` replaced the removed `session.events` getter upstream
+  // (5660f44d29); reading the dead property throws "agent.session.events is not
+  // iterable" and kills the whole headless run.
+  for (const event of agent.session.snapshotEvents()) {
     if (event.type === 'assistant/message') {
       const joined = event.data.message.content
         .filter(block => block.type === 'text')

package/src/experimental.mjs

@@ -16,7 +16,12 @@ export { stageProfileStore } from './sandbox.mjs'
 export { buildOverlayYaml, overlayDisableRows } from './overlay.mjs'
 
 // --- session-trace primitives ---
-export { parseSessionLog, buildTrace, loadTraceDir } from './trace.mjs'
+export {
+  parseSessionLog,
+  buildTrace,
+  collectSessionTrace,
+  KNOWN_SESSION_FORMAT_VERSIONS,
+} from './trace.mjs'
 
 // --- review experiment execution layer ---
 export {

package/src/mock/mock-adapter.mjs

@@ -40,6 +40,20 @@ class EvalMockAdapter extends LlmAdapter {
     }
   }
 
+  // Carried explicitly instead of inherited: this plugin's `LlmAdapter` base
+  // resolves from THIS package's peer instance, which can lag the host
+  // runtime that drives it (host 0.1.5-rc.2 grew `prepareCall` while the
+  // local peer was 0.0.1-rc.1 — the inherited face was missing and every mock
+  // run died at `registration.adapter.prepareCall is not a function`). The
+  // shape is the host base-class default: model metadata plus a dispatch
+  // entry bound to this same adapter generation.
+  async prepareCall(provider, model, signal) {
+    return {
+      model: await this.resolveModel(provider, model, signal),
+      stream: options => this.stream(options),
+    }
+  }
+
   async * stream(_options) {
     const step = this.steps[this.cursor]
     this.cursor += 1

package/src/report.mjs

@@ -30,6 +30,10 @@
  * @param {boolean} [parts.timedOut]
  * @param {number} [parts.durationMs] - wall time of the run, when it ran.
  * @param {string} [parts.artifactsDir] - where post-mortem artifacts landed, when written.
+ * @param {object} [parts.census] - the run trace's projection census
+ *   (`trace.census`), carried on both pass and fail records so a green case
+ *   whose evidence surface degraded is still inspectable after the fact.
+ *   Absent when no trace materialized.
  */
 export function createCaseRecord(parts) {
   const record = { id: parts.id, file: parts.file }
@@ -41,6 +45,7 @@ export function createCaseRecord(parts) {
   if (parts.timedOut !== undefined) record.timedOut = parts.timedOut
   if (parts.durationMs !== undefined) record.durationMs = parts.durationMs
   if (parts.artifactsDir !== undefined) record.artifactsDir = parts.artifactsDir
+  if (parts.census !== undefined) record.census = parts.census
   return record
 }
 

package/src/review-report.mjs

@@ -23,6 +23,29 @@ export function observationsFingerprint(observations) {
   return createHash('sha256').update(observations, 'utf8').digest('hex').slice(0, 16)
 }
 
+/**
+ * One-line statement of whether the tool boundary check RAN on the review
+ * runs. A run without a session artifact reports `status: 'not-executed'`;
+ * that must show up in the report header, because a review whose tool face was
+ * never verified is weaker evidence than one whose was (EVAL-021). Executors
+ * that do not validate at all (custom executors, dry runs) say so instead of
+ * implying a pass.
+ */
+function toolBoundarySummary(attempts) {
+  const skipped = attempts.filter(attempt => attempt.result?.toolValidation?.status === 'not-executed')
+  if (skipped.length > 0) {
+    return `NOT EXECUTED on run(s) ${skipped.map(attempt => attempt.index).join(', ')}`
+      + ' — no session artifact; the reviewer tool face was not verified (see the per-run notes)'
+  }
+  const checked = attempts.filter(attempt => attempt.result?.toolValidation?.status === 'checked')
+  if (attempts.length > 0 && checked.length === attempts.length) return 'checked on every run'
+  if (checked.length > 0) {
+    return `checked on ${checked.length} of ${attempts.length} run(s); the rest reported none`
+      + ' (failed before validation, or a non-verifying executor)'
+  }
+  return 'not reported by this executor'
+}
+
 /**
  * Render the review report markdown.
  *
@@ -54,6 +77,7 @@ export function renderReviewReport(parts) {
   lines.push(`- adapter: ${parts.adapter ?? 'none (dry run)'}`)
   if (parts.profile !== undefined) lines.push(`- profile: \`${parts.profile}\``)
   lines.push(`- runs: ${dry ? '0 (dry run — observations materialized only)' : result.runs}`)
+  if (!dry) lines.push(`- tool boundary: ${toolBoundarySummary(result.attempts)}`)
   lines.push(`- observations: \`observations.md\` (sha256:${observationsFingerprint(observations)})`)
   lines.push(`- rubric: ${rubric.includes('\n') ? '(inline string — see experiment definition)' : `\`${rubric}\``}`)
   lines.push('')
@@ -82,6 +106,13 @@ export function renderReviewReport(parts) {
           && attempt.result.answer !== attempt.result.stdout
         lines.push('')
         lines.push(`- transcript: \`run-${attempt.index}.stderr.txt\`${diverged ? ` (answer differs from the final message — see \`run-${attempt.index}.stdout.txt\`)` : ''}`)
+        if (attempt.result?.toolValidation?.status === 'not-executed') {
+          // The unverified-boundary fact rides the run it applies to, next to
+          // the answer it qualifies: this answer is stdout's final message
+          // (there was no trace to derive it from) and no request header was
+          // ever inspected for tool leakage.
+          lines.push(`- **tool-boundary check NOT EXECUTED**: ${attempt.result.traceGap ?? 'no session trace materialized'} — the answer above is stdout's final message, not a trace-derived answer.`)
+        }
       } else {
         lines.push(`### run ${attempt.index} — FAIL`)
         lines.push('')

package/src/runner.mjs

@@ -29,11 +29,11 @@
  * module is the orchestration only.
  */
 
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync, cpSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, cpSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { isAbsolute, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { loadTraceDir } from './trace.mjs'
+import { collectSessionTrace, listSessionLogFiles } from './trace.mjs'
 import { validateRowConfig, validateDisableRows, validateFollowups } from './discovery.mjs'
 import { CLI_RELATIVE_PATH } from './cli.mjs'
 import { buildOverlayYaml } from './overlay.mjs'
@@ -62,21 +62,18 @@ const FRAMEWORK_ROOT = fileURLToPath(new URL('..', import.meta.url))
  * @param {object} evalCase - the case under test.
  * @param {object} options
  * @param {string} options.profile - the dsh profile booting the run (plugin installed there).
- * @param {string} [options.dshRepoDir] - the deepseek-harness checkout (legacy CLI
- *   location; ignored when cliPath is given).
- * @deprecated options.dshRepoDir — pass the C6 chain result via cliPath
- *   instead; this legacy option is removed in the next minor release.
- * @param {string} [options.cliPath] - explicit compiled CLI entry (C6 chain result;
- *   takes precedence over dshRepoDir).
+ * @param {string} options.cliPath - the compiled dsh CLI entry (a
+ *   `resolveDshCliChain` result); required.
  * @param {'real' | 'mock'} [options.mode] - force a mode over the case's own.
  * @param {string} [options.artifactsDir] - copy stdout/stderr/trace/session logs here (created).
  * @returns {Promise<EvalRunResult>}
  */
 export async function runEvalCase(evalCase, options) {
   const mode = options.mode ?? evalCase.mode ?? 'real'
-  const binPath = options.cliPath !== undefined
-    ? resolve(options.cliPath)
-    : join(resolve(options.dshRepoDir), ...CLI_RELATIVE_PATH.split(/[\\/]/))
+  if (options.cliPath === undefined) {
+    throw new TypeError('runEvalCase needs options.cliPath (a resolveDshCliChain result)')
+  }
+  const binPath = resolve(options.cliPath)
   const timeoutMs = evalCase.timeoutMs ?? 180_000
 
   const runDir = mkdtempSync(join(tmpdir(), 'dsh-eval-'))
@@ -150,7 +147,7 @@ export async function runEvalCase(evalCase, options) {
       timeoutMs,
     })
 
-    const trace = loadTraceDir(sessionsRoot)
+    const { trace, gap: traceGap } = collectSessionTrace(sessionsRoot)
     const sessionLogs = collectSessionLogTexts(sessionsRoot)
 
     // Workspace assertions live HERE, before the run dir cleanup: a case's
@@ -184,7 +181,7 @@ export async function runEvalCase(evalCase, options) {
 
     return {
       caseId: evalCase.id, mode, task: evalCase.task, exitCode, timedOut,
-      stdout, stderr, trace, sessionLogs, inspectError, runDir,
+      stdout, stderr, trace, traceGap, sessionLogs, inspectError, runDir,
     }
   } finally {
     teardownSandbox(runDir, { keep: process.env.DSH_EVAL_KEEP_TMP === '1' })
@@ -193,22 +190,7 @@ export async function runEvalCase(evalCase, options) {
 
 /** Read every session artifact under the root as text (best-effort, pre-cleanup). */
 function collectSessionLogTexts(sessionsRoot) {
-  const texts = []
-  const walk = (dir) => {
-    let entries
-    try {
-      entries = readdirSync(dir, { withFileTypes: true })
-    } catch {
-      return
-    }
-    for (const entry of entries) {
-      const path = join(dir, entry.name)
-      if (entry.isDirectory()) walk(path)
-      else if (entry.name === 'session.jsonl') texts.push(readFileSync(path, 'utf8'))
-    }
-  }
-  walk(sessionsRoot)
-  return texts
+  return listSessionLogFiles(sessionsRoot).map(path => readFileSync(path, 'utf8'))
 }
 
 /**
@@ -221,6 +203,9 @@ function collectSessionLogTexts(sessionsRoot) {
  * @property {string} stdout - printed final assistant text (plus any startup chatter).
  * @property {string} stderr
  * @property {import('./trace.mjs').EvalTrace | undefined} trace
+ * @property {string | undefined} traceGap - why no trace was built (the host
+ *   session seam diagnosis from `collectSessionTrace`); `undefined` whenever
+ *   `trace` is defined. The CLI prints it as the failure text.
  * @property {string[]} sessionLogs - raw session artifact texts, pre-cleanup.
  * @property {string | undefined} inspectError - the case's `inspect` failure text, when it threw.
  * @property {string} runDir - removed unless DSH_EVAL_KEEP_TMP=1.

package/src/tool-validation.mjs

@@ -37,19 +37,27 @@ function collectMountedToolNames(trace) {
  * against the allowed set.  An empty allowed set (the review default)
  * means the reviewer must see no tools at all.
  *
- * @param {import('./trace.mjs').EvalTrace | undefined} trace - the parsed trace; `undefined` skips validation.
+ * The result is explicit about whether the check RAN: `status` is
+ * `'checked'` only when a trace was available, and `'not-executed'` when
+ * there was none. `ok` is true only for a checked boundary with no
+ * unexpected tool — a missing trace is NOT a pass, so callers must branch
+ * on `status` and account for the skip (see `createDshHeadlessReviewExecutor`
+ * and docs/review.md) instead of reading `ok` alone.
+ *
+ * @param {import('./trace.mjs').EvalTrace | undefined} trace - the parsed trace; `undefined` means the check could not run.
  * @param {{ allowedTools?: Set<string> }} [options]
- * @returns {{ ok: boolean, unexpected: string[], actual: string[], allowed: string[] }}
+ * @returns {{ status: 'checked' | 'not-executed', ok: boolean, unexpected: string[], actual: string[], allowed: string[] }}
  */
 export function validateToolBoundary(trace, options = {}) {
   const allowed = options.allowedTools ?? new Set()
   const allowedNames = [...allowed].sort()
   if (trace === undefined || trace === null) {
-    return { ok: true, unexpected: [], actual: [], allowed: allowedNames }
+    return { status: 'not-executed', ok: false, unexpected: [], actual: [], allowed: allowedNames }
   }
   const actual = collectMountedToolNames(trace)
   const unexpected = actual.filter(name => !allowed.has(name))
   return {
+    status: 'checked',
     ok: unexpected.length === 0,
     unexpected,
     actual,
@@ -61,7 +69,7 @@ export function validateToolBoundary(trace, options = {}) {
  * Render a diagnostic evidence document for a tool boundary failure.
  * Suitable for writing to `.runs/<id>/tool-boundary-evidence.json`.
  *
- * @param {{ ok: boolean, unexpected: string[], actual: string[], allowed: string[] }} validation
+ * @param {{ status: 'checked' | 'not-executed', ok: boolean, unexpected: string[], actual: string[], allowed: string[] }} validation
  * @param {{ runDir: string, profile: string }} context
  * @returns {string}
  */

package/src/trace.mjs

@@ -6,14 +6,53 @@
  * Event shapes follow `deepseek-harness/packages/core/session/src/types.ts`
  * (`SessionEventMap`); packed `*-chunks` storage rows are tolerated and
  * skipped — they only carry `assistant/chunk` deltas eval never asserts on.
+ *
+ * Both seam directions carry an explicit boundary: an artifact whose header
+ * stamp is not a known generation is refused here (`parseSessionLog`), and a
+ * collection that finds no artifact yields a named diagnosis rather than an
+ * unexplained `undefined` (`collectSessionTrace`). See docs/host-wiring.md.
  */
 
 import { readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, join } from 'node:path'
 
 /** Storage row types that pack `assistant/chunk` delta runs (see chunk-rows.ts). */
 const CHUNK_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks'])
 
+/** Projection field name per projected event type. */
+const PROJECTED_FIELD_BY_EVENT_TYPE = new Map([
+  ['tool/call', 'toolCalls'],
+  ['tool/result', 'toolResults'],
+  ['assistant/message', 'assistantTexts'],
+  ['user/message', 'userMessages'],
+  ['request/header', 'requestHeaders'],
+])
+
+/**
+ * Session format generations this parser accepts. Mirror of the generation
+ * chain the vendored host ships codecs for
+ * (`session-format-catalog/src/generated.ts`: codecs v0–v3,
+ * `currentVersion: 3` = `SESSION_FORMAT_VERSION` in
+ * `core/session/src/types.ts`). The projection is written and verified
+ * against the current generation; older ones parse tolerantly. A stamp
+ * outside this set means the host moved to a generation whose payload this
+ * projection was never verified against — fail at the seam instead of
+ * projecting empty fields, and bump this set only together with the
+ * re-verification the docs' maintenance trigger describes.
+ */
+export const KNOWN_SESSION_FORMAT_VERSIONS = new Set([0, 1, 2, 3])
+
+/** Known generations rendered for an error message: `v0, v1, v2, v3`. */
+function knownGenerationsLabel() {
+  return [...KNOWN_SESSION_FORMAT_VERSIONS].sort((a, b) => a - b).map(version => `v${version}`).join(', ')
+}
+
+/** One header version stamp, rendered compactly for a diagnostic. */
+function headerVersionLabel(version) {
+  if (typeof version === 'number') return `v${version}`
+  return `(${JSON.stringify(version ?? null)})`
+}
+
 /**
  * Parse one uncompressed JSONL session artifact.
  * @param {string} text - the artifact's full text (header line first).
@@ -24,6 +63,15 @@ export function parseSessionLog(text) {
   if (lines.length === 0) throw new Error('empty session log')
   const header = JSON.parse(lines[0])
   if (header.type !== 'session') throw new Error('first line is not a session header')
+  // Generation gate: the header stamp is the host's own declaration of the
+  // artifact's logical layout. An unknown one is a seam drift, not a parse
+  // detail — say so here rather than degrade every projection to empty.
+  if (!KNOWN_SESSION_FORMAT_VERSIONS.has(header.version)) {
+    throw new Error(
+      `session header version ${headerVersionLabel(header.version)} is not a known generation`
+      + ` (known: ${knownGenerationsLabel()}); the host session format may have changed generation`,
+    )
+  }
   const events = []
   for (const line of lines.slice(1)) {
     let record
@@ -90,30 +138,49 @@ function parseArguments(raw) {
 }
 
 /**
- * Project one subagent child log into an assertable record. The durable
- * identity (`label` / `mode` / `provider`) comes from the FIRST
- * `subagent/descriptor` event whose payload carries the descriptor version
- * this projection supports (3) — mirroring `foldSubagentDescriptor` in
- * `deepseek-harness/packages/subagent/subagent/src/descriptor.ts`, where the
- * establishing provider appends exactly one authoritative descriptor and
- * later events cannot rewrite it. Completion is the child's own last
- * assistant text — a child that produced none may have been dispatched but
- * never ran to an answer (turn/end reasons are not consulted).
+ * Fold one child log's descriptor events exactly once: the identity
+ * `projectChild` asserts on, plus the counts the census reports. Single source
+ * on purpose — `projectChild` and `censusForChild` must agree on which
+ * descriptor established the identity, and the "supported" predicate must match
+ * the fold (a log whose only descriptors are unsupported yields both an empty
+ * identity and `supportedDescriptors: 0`, which is the census signal).
+ * @param {{ events: object[] }} log - one parsed child log.
+ * @returns {{ label: string | undefined, mode: string | undefined, provider: string | undefined, descriptorEvents: number, supportedDescriptors: number }}
  */
-function projectChild(log) {
+function foldChildDescriptor(log) {
   let label
   let mode
   let provider
+  let descriptorEvents = 0
+  let supportedDescriptors = 0
   for (const event of log.events) {
     if (event.type !== 'subagent/descriptor') continue
+    descriptorEvents += 1
     const data = event.data
     if (data === null || typeof data !== 'object') continue
-    if (label !== undefined || mode !== undefined || provider !== undefined) break
+    if (data.version === 3) supportedDescriptors += 1
+    if (label !== undefined || mode !== undefined || provider !== undefined) continue
     if (data.version !== 3) continue
     if (typeof data.label === 'string') label = data.label
     if (typeof data.mode === 'string') mode = data.mode
     if (typeof data.provider === 'string') provider = data.provider
   }
+  return { label, mode, provider, descriptorEvents, supportedDescriptors }
+}
+
+/**
+ * Project one subagent child log into an assertable record. The durable
+ * identity (`label` / `mode` / `provider`) comes from the FIRST
+ * `subagent/descriptor` event whose payload carries the descriptor version
+ * this projection supports (3) — mirroring `foldSubagentDescriptor` in
+ * `deepseek-harness/packages/subagent/subagent/src/descriptor.ts`, where the
+ * establishing provider appends exactly one authoritative descriptor and
+ * later events cannot rewrite it. Completion is the child's own last
+ * assistant text — a child that produced none may have been dispatched but
+ * never ran to an answer (turn/end reasons are not consulted).
+ */
+function projectChild(log) {
+  const { label, mode, provider } = foldChildDescriptor(log)
   const assistantTexts = log.events
     .filter(event => event.type === 'assistant/message')
     .map(event => messageText(event.data.message))
@@ -130,6 +197,109 @@ function projectChild(log) {
   }
 }
 
+/**
+ * Count events by type, plug-in event types included (the only live registry is
+ * `SessionEventMap`, so no closed list exists).
+ * @param {object[]} events - parsed event records.
+ * @returns {Record<string, number>} count per event type, insertion-ordered.
+ */
+function countEventTypes(events) {
+  // Null-prototype accumulator: a plug-in event type may name an
+  // `Object.prototype` member (`constructor`, `toString`, `__proto__`), and
+  // `counts['constructor'] ?? 0` would otherwise read the inherited function
+  // and string-concatenate, while `__proto__` would be swallowed by its setter.
+  const counts = Object.create(null)
+  for (const event of events) {
+    if (typeof event?.type !== 'string') continue
+    counts[event.type] = (counts[event.type] ?? 0) + 1
+  }
+  return counts
+}
+
+/**
+ * Census for one candidate child log: whether its `subagent/descriptor`
+ * events exist, how many, and how many carry the supported descriptor
+ * version, plus the folded identity itself. `label` is the field the
+ * subagent-count matchers key on, so `label: undefined` with a non-zero
+ * `descriptorEvents` is exactly the shape whose `*Count(label, 0)` assertion
+ * is green only because there was nothing to match — the identity-loss
+ * degradation the census exists to make visible.
+ * @param {{ header: object, events: object[] }} log - one parsed child candidate.
+ * @returns {{ sessionId: string | undefined, parentSession: string | undefined, delegationDepth: number | undefined, descriptorEvents: number, supportedDescriptors: number, label: string | undefined, mode: string | undefined, provider: string | undefined }}
+ */
+function censusForChild(log) {
+  return {
+    sessionId: log.header.id,
+    parentSession: log.header.parentSession,
+    delegationDepth: log.header.delegationDepth,
+    ...foldChildDescriptor(log),
+  }
+}
+
+/**
+ * Projection census for one built trace (see {@link EvalTrace.census}).
+ * Numbers only: this reports what the raw logs contained against what the
+ * projections kept, and never decides whether the difference is a defect.
+ *
+ * Three signals, because one number cannot cover three shapes: length
+ * differences (`projectionSkipped.main`) see records the projection dropped,
+ * `projectionFieldGaps` sees records it kept while a field went missing
+ * (`tool/call` and friends project 1:1, so their count − length is structurally
+ * zero), and the subagent block sees the child-log data source, which no main-log
+ * count can reach.
+ *
+ * @param {object[]} events - the MAIN log's events (the projection input).
+ * @param {EvalTrace} trace - the built trace, read for projection lengths.
+ * @param {object[]} childLogs - candidate child logs entering `subagentChildren`.
+ * @param {Record<string, number>} projectionFieldGaps - gaps the projection loop
+ *   recorded while reading fields, keyed by what was missing.
+ * @returns {object} the census record.
+ */
+function buildCensus(events, trace, childLogs, projectionFieldGaps) {
+  const eventTypeCounts = countEventTypes(events)
+  const projectionLengths = {
+    toolCalls: trace.toolCalls.length,
+    toolResults: trace.toolResults.length,
+    assistantTexts: trace.assistantTexts.length,
+    userMessages: trace.userMessages.length,
+    requestHeaders: trace.requestHeaders.length,
+  }
+  const projectionSkipped = { main: {}, children: {} }
+  for (const [type, field] of PROJECTED_FIELD_BY_EVENT_TYPE) {
+    const missing = (eventTypeCounts[type] ?? 0) - projectionLengths[field]
+    if (missing > 0) projectionSkipped.main[field] = missing
+  }
+  const children = childLogs.map(censusForChild)
+  const supportedDescriptors = children.reduce((total, child) => total + child.supportedDescriptors, 0)
+  // Two degradation shapes, different signals: `withoutIdentity` is a child
+  // that folded no identity at all; `withoutLabel` is one that folded some
+  // identity but no label — the only field the `subagent*Count` matchers can
+  // match on, so its zero-count assertions are the vacuous ones.
+  //
+  // The child set is the parentSession heuristic (any log whose header carries
+  // `parentSession`, which the host also writes for fork/resume/seed logs), so a
+  // non-subagent fork log shows up here as an identity-less child. The census
+  // reports the set it was given; it cannot re-derive the host's agent-chain
+  // ownership check from a log alone.
+  const withoutIdentity = children.filter(
+    child => child.label === undefined && child.mode === undefined && child.provider === undefined,
+  ).length
+  const withoutLabel = children.filter(child => child.label === undefined).length
+  if (withoutIdentity > 0) projectionSkipped.children.withoutIdentity = withoutIdentity
+  if (withoutLabel > 0) projectionSkipped.children.withoutLabel = withoutLabel
+  return {
+    eventTypeCounts,
+    projectionLengths,
+    projectionSkipped,
+    projectionFieldGaps,
+    subagent: {
+      mainLogDescriptorEvents: eventTypeCounts['subagent/descriptor'] ?? 0,
+      supportedDescriptors,
+      children,
+    },
+  }
+}
+
 /**
  * Build one assertable trace from parsed session logs. Child sessions surface
  * only through the parent's tool events, so the MAIN log (no `origin:
@@ -146,20 +316,27 @@ export function buildTrace(logs) {
   const mains = logs.filter(log => log.header.origin !== 'subagent')
   const main = [...mains].sort((a, b) => b.events.length - a.events.length)[0]
   const events = main?.events ?? []
-  const subagentChildren = logs
+  const childLogs = logs
     .filter(log => log.header.origin === 'subagent' || log.header.parentSession !== undefined)
-    .map(projectChild)
+  const subagentChildren = childLogs.map(projectChild)
 
   const toolCalls = []
   const toolResults = []
   const assistantEntries = []
   const userMessages = []
   const requestHeaders = []
+  const gaps = {}
+  const recordGap = key => { gaps[key] = (gaps[key] ?? 0) + 1 }
   for (const event of events) {
     if (event.type === 'request/header') {
       // The assembled model request header: system prompt + mounted tool
       // schemas. What the model is told it can do and how — the "did my
       // plugin's section inject?" projection.
+      if (typeof event.data?.header?.system !== 'string') recordGap('headerWithoutSystem')
+      if (Array.isArray(event.data?.header?.tools)
+        && !event.data.header.tools.some(tool => typeof tool?.name === 'string')) {
+        recordGap('headerWithoutToolNames')
+      }
       requestHeaders.push({
         seq: event.seq,
         reason: event.data?.reason,
@@ -169,6 +346,8 @@ export function buildTrace(logs) {
           : [],
       })
     } else if (event.type === 'tool/call') {
+      if (typeof event.data?.name !== 'string') recordGap('toolCallWithoutName')
+      if (typeof event.data?.callId !== 'string') recordGap('toolCallWithoutCallId')
       toolCalls.push({
         seq: event.seq,
         turn: event.data.turn,
@@ -179,6 +358,7 @@ export function buildTrace(logs) {
         parsedArguments: parseArguments(event.data.arguments),
       })
     } else if (event.type === 'tool/result') {
+      if (typeof event.data?.message?.source?.callId !== 'string') recordGap('toolResultWithoutCallId')
       toolResults.push({
         seq: event.seq,
         turn: event.data.turn,
@@ -222,7 +402,7 @@ export function buildTrace(logs) {
     : assistantEntries.filter(entry => entry.seq < firstInjectionSeq)
   const answerText = answerEntries.at(-1)?.text ?? ''
 
-  return {
+  const result = {
     sessions: logs,
     sessionId: main?.header.id,
     toolCalls,
@@ -233,36 +413,118 @@ export function buildTrace(logs) {
     requestHeaders,
     subagentChildren,
     finalText: assistantTexts.at(-1) ?? '',
+    census: undefined,
   }
+  result.census = buildCensus(events, result, childLogs, gaps)
+  return result
+}
+
+/**
+ * Session artifact basenames: format v0 keeps `session.jsonl`, every later
+ * generation carries a `vN` component (`session.v3.jsonl` — the host's
+ * `generationLogFilename`). Matching the v0 name alone finds no trace at all
+ * once the host bumps the format, which surfaces as "no session trace
+ * materialized" rather than as a parse error.
+ */
+const SESSION_LOG_FILENAME = /^session(?:\.v\d+)?\.jsonl$/u
+
+/**
+ * Whether one file basename is a session JSONL artifact of any format generation.
+ * @param {string} name - the file basename to test.
+ * @returns {boolean} true for `session.jsonl` and `session.vN.jsonl`.
+ */
+export function isSessionLogFilename(name) {
+  return SESSION_LOG_FILENAME.test(name)
 }
 
-/** Recursively collect files named `name` under `dir`. */
-function collectFiles(dir, name, out = []) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+/** Recursively list files under `dir`; an unreadable directory contributes nothing. */
+function listFiles(dir, out = []) {
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
     const path = join(dir, entry.name)
-    if (entry.isDirectory()) collectFiles(path, name, out)
-    else if (entry.name === name) out.push(path)
+    if (entry.isDirectory()) listFiles(path, out)
+    else out.push(path)
   }
   return out
 }
 
 /**
- * Load every session log under a persistence root and build one trace.
+ * Every session artifact under `sessionsRoot` (any generation, see
+ * `isSessionLogFilename`) as absolute paths — the collection half of the
+ * seam, shared by the trace builder and by the raw-log capture the behavior
+ * runner does before cleanup.
  * @param {string} sessionsRoot - the run's `session-persistence-jsonl` root.
- * @returns {EvalTrace | undefined} the trace, or `undefined` when no log materialized.
+ * @returns {string[]} artifact paths, in directory order.
  */
-export function loadTraceDir(sessionsRoot) {
-  let files
-  try {
-    files = collectFiles(sessionsRoot, 'session.jsonl')
-  } catch {
-    return undefined
+export function listSessionLogFiles(sessionsRoot) {
+  return listFiles(sessionsRoot).filter(path => isSessionLogFilename(basename(path)))
+}
+
+/** Most candidate names one gap diagnostic lists before it truncates. */
+const GAP_NAME_LIMIT = 10
+
+/**
+ * Why a collection produced no artifact, phrased for a failure message: the
+ * candidate names actually seen (a renamed artifact is the likeliest host
+ * drift) plus the generation suspicion. Never returns an empty string — an
+ * empty root is itself the fact to report.
+ */
+function traceGapMessage(sessionsRoot, files) {
+  const names = [...new Set(files.map(file => basename(file)))]
+  const lookalikes = names.filter(name => name.toLowerCase().startsWith('session'))
+  const pool = lookalikes.length > 0 ? lookalikes : names
+  const shown = pool.slice(0, GAP_NAME_LIMIT)
+  const rest = pool.length - shown.length
+  const scan = shown.length === 0
+    ? 'the root holds no files (missing or empty)'
+    : `${lookalikes.length > 0 ? 'session-like file(s)' : 'file(s)'} under it: `
+      + `${shown.join(', ')}${rest > 0 ? ` (+${rest} more)` : ''}`
+  return 'no session trace materialized: no session artifact'
+    + ` (session.jsonl / session.vN.jsonl) under '${sessionsRoot}' — ${scan}`
+    + '; the host artifact naming may have changed generation'
+}
+
+/**
+ * Collect one run's session trace and, when there is none, the seam
+ * diagnosis for it.
+ *
+ * The `gap` string exists so that "the host's artifact/session layout moved"
+ * surfaces as that sentence in the behavior runner's failure text and in the
+ * review adapter's accounting, instead of as a bare `undefined` the reader
+ * has to trace back through the parser (see docs/host-wiring.md).
+ *
+ * @param {string} sessionsRoot - the run's `session-persistence-jsonl` root.
+ * @returns {{ trace: EvalTrace | undefined, gap: string | undefined }} the
+ *   trace, or `undefined` plus the reason no trace could be built.
+ */
+export function collectSessionTrace(sessionsRoot) {
+  const files = listFiles(sessionsRoot)
+  const artifacts = files.filter(file => isSessionLogFilename(basename(file)))
+  if (artifacts.length === 0) {
+    return { trace: undefined, gap: traceGapMessage(sessionsRoot, files) }
+  }
+  const logs = []
+  const broken = []
+  for (const artifact of artifacts) {
+    try {
+      logs.push(parseSessionLog(readFileSync(artifact, 'utf8')))
+    } catch (error) {
+      broken.push(`${basename(artifact)}: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  if (broken.length > 0) {
+    return {
+      trace: undefined,
+      gap: `session artifact(s) failed to parse — ${broken.join('; ')}`
+        + '; the host session format may have changed generation',
+    }
   }
-  if (files.length === 0) return undefined
-  const logs = files
-    .map(file => readFileSync(file, 'utf8'))
-    .map(parseSessionLog)
-  return buildTrace(logs)
+  return { trace: buildTrace(logs), gap: undefined }
 }
 
 /**
@@ -290,4 +552,39 @@ export function loadTraceDir(sessionsRoot) {
  *     last assistant text ('' when it produced none — dispatched but not
  *     answered).
  * @property {string} finalText - the last assembled assistant text ('' when none).
+ * @property {object | undefined} census - what the raw logs contained against
+ *   what the projections kept (numbers only, never a verdict). Two data
+ *   sources: `eventTypeCounts` counts the MAIN log's events by type (any type,
+ *   plug-in ones included), and `subagent` censuses the child logs that enter
+ *   `subagentChildren` (their `subagent/descriptor` event counts and how many
+ *   carry the supported `version === 3`). `projectionLengths` are the five
+ *   main-log projections' lengths after empty-text drops; `projectionSkipped`
+ *   records where count minus length is positive, per projection, plus the two
+ *   child-identity counters. Undefined only on a hand-built trace; a nested log
+ *   under `sessions` carries none because the parsers never add one.
+ * @property {Record<string, number>} census.projectionFieldGaps
+ *   - events the projection kept while a field it reads went missing, keyed by
+ *     what was missing (`toolCallWithoutName`, `toolCallWithoutCallId`,
+ *     `toolResultWithoutCallId`, `headerWithoutSystem`, `headerWithoutToolNames`).
+ *     This is the 1:1-projection signal: for `tool/call`, `tool/result` and
+ *     `request/header`, count − length is structurally zero, so a moved field
+ *     shows up only here. An absent `request/header.tools` array is NOT counted
+ *     (it projects to the same empty list as an empty one).
+ * @property {{ mainLogDescriptorEvents: number, supportedDescriptors: number, children: object[] }} census.subagent
+ *   - the child-log data source the main-log counts cannot reach.
+ *     `mainLogDescriptorEvents` counts `subagent/descriptor` events in the MAIN
+ *     log itself (the current host writes them into the child log, so this is
+ *     usually 0); `supportedDescriptors` sums the per-child counts below, i.e.
+ *     it counts DESCRIPTOR EVENTS, not child sessions — one child may fold its
+ *     identity from a single descriptor while logging several.
+ * @property {{ sessionId: string | undefined, parentSession: string | undefined, delegationDepth: number | undefined, descriptorEvents: number, supportedDescriptors: number, label: string | undefined, mode: string | undefined, provider: string | undefined }[]} census.subagent.children
+ *   - the accepted child logs, each with the identity `projectChild` folded
+ *     from them; `descriptorEvents === 0` means the log states no identity at
+ *     all, and a non-zero count with `supportedDescriptors === 0` means every
+ *     descriptor was outside the supported version.
+ * @property {Record<string, number>} census.projectionSkipped.children
+ *   - `withoutIdentity` counts children that folded no identity field at all;
+ *     `withoutLabel` counts children whose `label` is absent — the field the
+ *     `subagent*Count` matchers match on, so those are the records whose
+ *     zero-count assertions pass only because there was nothing to match.
  */