@haiyangbg/buildbeat 2.0.0-beta.2 → 2.0.0-beta.3

package/CHANGELOG.md

@@ -2,10 +2,24 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v2.0.0-beta.3 — 2026-09-01
+
+> 主题：三十轮部署战役（底座 WORK-C0-HEALTH-NONPROD-01，DEPLOY-01~30 + L4 之夜）的机制回灌。战役复盘：`底座/pm/2026-09-01-BuildBeat三十轮复盘.md`。
+> **发布状态**：同 beta.1/beta.2 流程（OIDC Trusted Publishing，dist-tag `next`；`latest` 保持 v1.21.0）。
+
+- **发现分诊门**（复盘改革条 4）：run 配置 `reviewTriage: required` 后，review 的 P0/P1 finding 不再自动派 fixer——停 `WAITING_HUMAN`（kind `finding-triage`）待人逐指纹裁决，approve `enter-fix` 才放行。finding 是处方不是事实；自动路由处方在战役振荡期连烧四轮
+- **锚定审查与裁决台账**（改革条 3）：finding 全部落 Git 面 `delivery/work/<id>/review-findings.jsonl`（指纹=严重度+正文规范化 hash）；`findings list` / `findings adjudicate --action accept|dismiss` 人裁决；`dismiss` 后同指纹不再阻断（重提记 `RE-RAISED` 可见）、严重度升级自动重开；Reviewer input 注入历史裁决锚（`anchor`）、fixer input 注入带裁决状态的工单（`findings`）。裁决记忆在 Git 面，删 runtime 不丢
+- **环境契约 `requires:`**：run 配置声明信封依赖的二进制与最低版本，Run 启动前 fail-closed 全量核验、一次报清（真实事故：vendored-only `rg`、bash 3.2、新 shell 解析 Node 14 各烧整轮才见真因）；`doctor` 同步报告
+- **review 轮数预算原生化**（改革条 1 的机制化）：官方预设 `budgets.maxAttempts.review: 2`——第三轮 review 启动前即停人批，无需 prompt 约束兜底
+- **`preflight` 预检通道**：`preflight --config <cfg> --step <id>` 在主 checkout 干跑某步 worker 命令，分钟级打到首个失败边界再进 Run；无 worktree、无台账、零证据（横幅明示 dry signal；`BUILDBEAT_PREFLIGHT=1`），Run 必须复现才算数
+- **fix(v2) 崩溃恢复不再误路由**：被中断的步现在重跑自身（丢失尝试仍计预算），不再按步骤失败走 failure 边——真实事故（deploy-18）：宿主超时杀掉 verify worker，crash 被路由去 fix，fixer 面对零 verifier 证据白烧一轮。交互式 shell 里 `start` 现在提示脱离启动（nohup/setsid）
+- 战役期间已并入的内核修复一并随本版发布：预算守卫（final attempt 失败不再派 fix，deploy-14）、porcelain 状态列保护、runtime 证据引用仓库相对化、Node <20 清晰报错（各见对应 commit）
+- 指南更新：验证金字塔警示与"真缺陷类清零即升层"（06）、分诊门与锚定审查（07）、环境契约与 review 预算（02）、崩溃重跑语义与启动纪律（10）
+
 ## v2.0.0-beta.2 — 2026-08-28
 
 > 主题：aiplatform-meta（底座）v2 迁移试点抓出的内核修复。
-> **发布状态**：同 beta.1 流程（OIDC Trusted Publishing，dist-tag `next`；`latest` 保持 v1.21.0）。
+> **发布状态**：`@haiyangbg/buildbeat@2.0.0-beta.2` 已于 2026-08-28 经 OIDC Trusted Publishing 发布到 dist-tag `next`（run 33175013599，双 job success）；`latest` 保持 v1.21.0。独立回读：dist-tag 路由、integrity、SLSA provenance、隔离安装全过，证据见 [`docs/V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](docs/V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md)。
 
 - **fix(v2) 范围门中文路径误拦**：git `core.quotepath` 默认把非 ASCII 路径转义为带引号的八进制串，`listChangedPaths` 直接喂给 allowedPaths 前缀检查导致范围内中文文件被判越界（真实事故：底座 `RUN-META-V2-01` 被 `pm/登录二期看板.md` 阻断）。读回改用 `core.quotepath=off`，中文路径永久回归进 `tests/v2-invariants.test.js`
 

package/bin/buildbeat-v2.js

@@ -2,5 +2,17 @@
 
 // v2 runtime CLI entry. The v1 `buildbeat` bin stays frozen on src/cli.js;
 // v2 ships as a separate entry until it takes over `latest`.
+//
+// Guard before loading any module: the kernel uses Node>=20 syntax, and on a
+// machine whose default node drifted older the raw SyntaxError stack hides
+// the actual problem (real incident: default node v14 during the meta pilot).
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 20) {
+  console.error(
+    `buildbeat-v2 needs Node >= 20; this shell resolved v${process.versions.node}.\n` +
+      "Check `which node` / nvm default, then rerun (e.g. `nvm use 23`).",
+  );
+  process.exit(1);
+}
 
-import "../src/v2/cli/run.js";
+import("../src/v2/cli/run.js");

package/docs/CLI.md

@@ -128,7 +128,7 @@ Schema 2 is the first write-capable shape targeted by Wave 1:
 {
   "schemaVersion": 2,
   "scaffoldVersion": "v1.21",
-  "cliVersion": "2.0.0-beta.2",
+  "cliVersion": "2.0.0-beta.3",
   "layout": "default",
   "installedAt": "2026-08-24T00:00:00.000Z",
   "files": {

package/docs/RELEASING.md

@@ -2,7 +2,7 @@
 
 This runbook governs BuildBeat's public npm distribution. The canonical package is `@haiyangbg/buildbeat` in `HaiYangBG1/BuildBeat`; the canonical executable is `buildbeat`, while `solobaton` remains an executable alias. The old `solobaton` npm package is a frozen legacy distribution ID and must not receive the scoped write/upgrade command surface.
 
-Release evidence at source package version `@haiyangbg/buildbeat@2.0.0-beta.2` (pending publication verification); latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.0-beta.1` (dist-tag `next`; `latest` remains `1.21.0`), anchored by annotated tag `v2.0.0-beta.1` at commit `946d43f`, workflow run [33171071539](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33171071539), and archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). The latest stable distribution stays `@haiyangbg/buildbeat@1.21.0`, anchored by annotated tag `v1.21.0` at commit `ce69a05`, workflow run [32864438692](https://github.com/HaiYangBG1/BuildBeat/actions/runs/32864438692), and the matching [GitHub Release](https://github.com/HaiYangBG1/BuildBeat/releases/tag/v1.21.0). Exact registry identity, provenance, signatures, isolated-install readback, Environment approval, and immutable-artifact boundary are archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md). First-scoped-release bootstrap behavior and legacy deprecation remain archived in [`WP4.3-RELEASE-EVIDENCE-2026-08-25.md`](WP4.3-RELEASE-EVIDENCE-2026-08-25.md). The legacy distribution remains `solobaton@1.16.3`; all three published legacy versions are retained and deprecated toward the scoped package.
+Release evidence at source package version `@haiyangbg/buildbeat@2.0.0-beta.3` (pending publication verification); latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@2.0.0-beta.2` (dist-tag `next`; `latest` remains `1.21.0`), anchored by annotated tag `v2.0.0-beta.2` at commit `d7a9ab9`, workflow run [33175013599](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33175013599), and archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md). The beta.1 chain stays archived in [`V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md`](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). The latest stable distribution stays `@haiyangbg/buildbeat@1.21.0`, anchored by annotated tag `v1.21.0` at commit `ce69a05`, workflow run [32864438692](https://github.com/HaiYangBG1/BuildBeat/actions/runs/32864438692), and the matching [GitHub Release](https://github.com/HaiYangBG1/BuildBeat/releases/tag/v1.21.0). Exact registry identity, provenance, signatures, isolated-install readback, Environment approval, and immutable-artifact boundary are archived in [`V1.21-RELEASE-EVIDENCE-2026-08-25.md`](V1.21-RELEASE-EVIDENCE-2026-08-25.md). First-scoped-release bootstrap behavior and legacy deprecation remain archived in [`WP4.3-RELEASE-EVIDENCE-2026-08-25.md`](WP4.3-RELEASE-EVIDENCE-2026-08-25.md). The legacy distribution remains `solobaton@1.16.3`; all three published legacy versions are retained and deprecated toward the scoped package.
 
 ## Release invariants
 

package/docs/V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md

@@ -0,0 +1,8 @@
+# v2.0.0-beta.2 发布证据（2026-08-28）
+
+> 授权：所有者会话内 "4. OK"（beta.2 发布 + 部署审批）；流程与 [beta.1](V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md) 完全一致。
+
+- 内容：单一内核修复——范围门中文路径误拦（git quotepath 转义；aiplatform-meta 迁移试点真实事故 `RUN-META-V2-01`），修复 + 中文路径永久回归（`3f39189`）。
+- 候选：`d7a9ab9`（`v2` tip），tag `v2.0.0-beta.2`；本地 prepublishOnly 全链 `GATE_EXIT=0`（node 143/143）；CI 两个 run（`3f39189` / `d7a9ab9`）conclusion=success。
+- 发布：workflow run [33175013599](https://github.com/HaiYangBG1/BuildBeat/actions/runs/33175013599) 双 job success（publish + verify：exact integrity、dist-tag 路由、provenance、隔离安装、签名审计）。
+- 本地独立回读：dist-tags `{bootstrap: 0.0.0, latest: 1.21.0, next: 2.0.0-beta.2}`（`latest` 未动）；`dist.integrity = sha512-Lt90fCFnNCvnMJK/cs/lUrau4uESf5iDCmy9GFYD6sFdGSHbwlcOM4afBlziHTuoz3rVKpgw8b/+bP+bjarh6w==`；provenance `https://slsa.dev/provenance/v1`；所有者机器全局安装已切换为该官方工件（quotepath 修复在包内核验）。

package/docs/v2/guide/01-quickstart.md

@@ -80,6 +80,8 @@ buildbeat-v2 approve --repo . --run RUN-DEMO-1 --transition enter-wait-merge --b
 
 批准即 merge-ready；合并/推送/发布永远是你的动作，Runner 不代劳。被 findings 阻断时会自动路由 fix→verify 重走，超预算或指纹重复则停下交还给你（[Approval 指南](07-approval-guide.md)、[Recovery](10-recovery.md)）。
 
+想让 finding 先过你的手再派 fixer：run 配置加 `reviewTriage: required`，配套 `findings list` / `findings adjudicate` 逐指纹裁决（dismiss 后同指纹不再阻断）；正式起 Run 前可用 `preflight --step <id>` 在主 checkout 分钟级干跑单步（不产证据）；信封的环境依赖用 `requires:` 声明，启动前 fail-closed 核验。详见 [Approval 指南](07-approval-guide.md)、[Evidence 指南](06-evidence-guide.md)、[Workflow 指南](02-workflow-guide.md)。
+
 ## 5. observe：让系统盯生产（v0）
 
 ```bash

package/docs/v2/guide/02-workflow-guide.md

@@ -37,6 +37,23 @@ terminal:
 
 run 配置里 `entry` 可覆盖 workflow 的 `entry`（例如从 `build` 起步、跳过 intent/plan 步——digest 仍会绑进批准对象）；`stopAt` 指定停点。workflow 文件整体做 sha256 → `RUN_CREATED.workflowDigest`，事后可证明当时跑的是哪份流程。
 
+run 配置还可声明（beta.3，皆来自三十轮部署战役的真实事故）：
+
+- **`requires:` 环境契约**——信封隐式依赖的二进制与最低版本，Run 启动前 fail-closed 全量核验，一次报清所有问题（真实事故：`rg` 只在某会话 vendored PATH、`/bin/bash` 3.2、新 shell 解析到 Node 14，各烧掉整轮 Run 才见真因）：
+
+  ```yaml
+  requires:
+    - command: bash
+      min: 4
+    - command: rg
+  ```
+
+- **`reviewTriage: required` 发现分诊门**——review 的阻断性 finding 先停人分诊、再派 fixer（见 [Approval 指南](07-approval-guide.md)）。
+
+## review 轮数预算
+
+官方预设自带 `budgets.maxAttempts.review: 2`（战役章程"每 Run 2 轮 review 封顶"的原生化）：第三轮 review 在启动前即停 `WAITING_HUMAN`，理由写明预算耗尽。项目可用自己的 workflow 文件覆盖；机制就是每步 `maxAttempts`，无需新概念。
+
 ## 修改纪律
 
 预设是产品的一部分：改 `software-delivery.yaml` 前先想清是不是项目差异——项目差异用自己的 workflow 文件（run 配置 `workflow:` 指过去），不改官方预设。schema additive-only，破坏性改法升 `version`。

package/docs/v2/guide/06-evidence-guide.md

@@ -20,6 +20,12 @@
 
 `L0` 自述 → `L1` 静态检查 → `L2` 本地真实执行（命令回读默认档）→ `L3` 部署后验证 → `L4` 生产实测。门用 `minGrade` 提要求（如 merge 底线 L2；生产切换收口要 L4）。
 
+**验证金字塔警示（三十轮战役最贵一课）**：低层验证追理论完备的边际价值远低于早一层真机。实战中 7400 行 L3 套件打磨到极限，而 4 个真正的上线阻断（systemd 解析行为、部署/服务身份分裂、探针预算按替身标定、TLS ref 格式）**全部是 L3 结构性测不到的**，一晚 L4 找齐。经验法则：**模拟层"真缺陷类清零"即升层，不追理论完备**。同理，verify 全量重跑在候选只动局部时是纯重复——按内容哈希缓存/裁剪属于信封层优化（战役实测 25→13 分钟），内核不代做：缓存正确性依赖环境稳定假设，由信封所有者自己承担。
+
+## 预检 ≠ 证据
+
+`buildbeat-v2 preflight --config <run-config> --step <id>`：在主 checkout 直接干跑某步的 worker 命令——无 worktree、无台账、不落任何证据（输出自带 `PREFLIGHT (dry signal, never evidence)` 横幅，环境变量 `BUILDBEAT_PREFLIGHT=1`）。用途是分钟级循环打到首个失败边界再进 Run（战役里 harness 缺陷每个要烧一整轮 Run，预检模式一晚拆完）；**预检发现的任何东西必须由 Run 复现才算数**。
+
 ## 候选作用域
 
 证据以 `subject` 绑定候选：merge 门只统计当前 candidate 的证据，旧候选/旧 review 轮次的记录不混入（真实事故回归，见 evals `fix-loop`）。

package/docs/v2/guide/07-approval-guide.md

@@ -32,3 +32,20 @@ merge 批准只表示 **merge-ready**：真正的合并、push、发布是你在
 ## 人批点由 Risk Preset 决定
 
 `fast` 仅 Merge；`standard` Plan+Merge；`controlled` Intent+Plan+Merge+Release；`legacy-four-gates` 为 v1 四 Gate 完整形态（迁移期用，见 [迁移指南](08-migration-v1.md)）。待批项强制携带 findings 摘要与理由——防"秒批"退化；人批等待时长进 `metrics`。
+
+## 发现分诊门与锚定审查（beta.3）
+
+来自三十轮部署战役最大的结构性教训：**finding 是处方不是事实**，无记忆 fresh reviewer 会开出互斥处方并翻案早已接受的设计，自动路由 fixer 让振荡直接烧钱。两个机制配套：
+
+1. **分诊门**：run 配置 `reviewTriage: required` 后，review 产出 P0/P1 finding 不再自动派 fixer，而是停 `WAITING_HUMAN`（kind `finding-triage`），待批理由逐条列出 finding 指纹。人先裁决、再 `approve --transition enter-fix` 放行（或 `reject` 终止 Run）。
+2. **裁决台账**：finding 全部落 Git 面 `delivery/work/<id>/review-findings.jsonl`（指纹 = 严重度+正文规范化 hash）：
+
+   ```bash
+   buildbeat-v2 findings list --repo . --work WORK-X
+   buildbeat-v2 findings adjudicate --repo . --work WORK-X --fingerprint <fp> --action dismiss --by <名字> --note "<为什么>"
+   ```
+
+   `dismiss` 后同指纹不再阻断（重提会以 `RE-RAISED` 记账可见，但不重启循环）；**严重度升级=新指纹，自动重新阻断**——压噪不压真信号，与 observe 的 dismiss 回调同一原则。
+3. **锚定注入**：Reviewer（readonly 步）的 `BUILDBEAT_INPUT` 带 `anchor`（历史 finding+裁决全表），信封 prompt 应告知 reviewer"已裁决的结论不得翻案"；fixer 等写入步的 input 带 `findings`（上一轮 review 的 finding 及其裁决状态）——fixer 只修 accepted/open，不猜。
+
+裁决记忆在 Git 面，删 runtime 不丢（不变量 23 同款测试覆盖）。

package/docs/v2/guide/10-recovery.md

@@ -18,7 +18,9 @@
 buildbeat-v2 resume --config <run-config.yaml>
 ```
 
-在途步会以 `crashed` 关闭（事实落账），从最近 checkpoint 继续；带批准恢复时会做 candidate/plan 新鲜度检查，变了即 `APPROVAL_STALE` 转人工。恢复不了就删 runtime 重跑——候选分支与 Git 面记录不丢。
+在途步会以 `crashed` 关闭（事实落账），然后**重跑该步本身**（beta.3 改）：进程死掉不说明候选有问题，丢失的那次尝试照常计入该步预算，预算耗尽即停人工。此前的语义是把 crash 当步骤失败走 failure 边——真实事故（deploy-18）：宿主工具超时杀掉 verify worker，crash 被路由去 fix，fixer 面对零 verifier 证据白烧一轮。工作树脏了仍然先停人工。带批准恢复时会做 candidate/plan 新鲜度检查，变了即 `APPROVAL_STALE` 转人工。恢复不了就删 runtime 重跑——候选分支与 Git 面记录不丢。
+
+**启动纪律**（同一事故的另一半）：长于分钟级的 Run 必须以脱离宿主工具超时的方式启动（`nohup`/`setsid`），交互式 shell 里 `start` 会打印这条提醒。
 
 ### 锁卡住（"another run is active"）
 

package/example/.buildbeat/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "scaffoldVersion": "v1.21",
-  "cliVersion": "2.0.0-beta.2",
+  "cliVersion": "2.0.0-beta.3",
   "layout": "default",
   "installedAt": "2026-08-25T00:00:00.000Z",
   "files": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.3",
   "description": "BuildBeat: a Git-based, human-gated engineering delivery protocol for humans and AI sessions.",
   "type": "module",
   "bin": {

package/src/v2/cli/run.js

@@ -3,10 +3,10 @@
 // Deliberately thin — all facts live in the event ledger; this file only
 // parses input, wires adapters, and renders derived state.
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 import { createShellAdapter } from "../adapters/shell.js";
 import { loadRiskPreset } from "../engine/risk-preset.js";
@@ -15,9 +15,17 @@ import { parseYamlSubset } from "../engine/yaml-subset.js";
 import { parsePolicyDoc } from "../policy/policy.js";
 import { observeStatus, runObserveCycle, triageIntent } from "../observe/observe.js";
 import { acceptArtifact, approveRun, listInbox, rejectRun } from "../runtime/decisions.js";
+import { checkRequires } from "../runtime/env-contract.js";
+import {
+  adjudicateFinding,
+  findingsAccountRef,
+  latestAdjudications,
+  readFindingsAccount,
+} from "../runtime/findings.js";
 import { computeMetrics, renderMetrics } from "../runtime/metrics.js";
 import { writeRunRecord } from "../runtime/run-record.js";
 import { resumeRun, startRun } from "../runtime/orchestrator.js";
+import { toRepoRef } from "../runtime/repo-ref.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { acquireLock, releaseLock } from "../workspace/workspace-manager.js";
 
@@ -41,6 +49,9 @@ Usage:
   run.js observe run --config <observe.yaml>
   run.js observe status --repo <path>
   run.js observe triage --repo <path> --intent <ref> --action <fix_now|schedule|dismiss> [--by <name>] [--note <text>]
+  run.js preflight --config <run-config.yaml> --step <id>
+  run.js findings list --repo <path> --work <WORK-ID>
+  run.js findings adjudicate --repo <path> --work <WORK-ID> --fingerprint <fp> --action <accept|dismiss> [--by <name>] [--note <text>]
 `;
 
 function parseFlags(argv) {
@@ -82,7 +93,8 @@ function printState(state, ledger) {
     console.log(`step ${step}: ${info.status} (attempts ${info.attempts})`);
   }
   for (const item of state.evidence) {
-    console.log(`evidence [${item.status}/${item.grade}] ${item.kind} ${item.ref}`);
+    const ref = isAbsolute(item.ref) ? "<legacy-absolute-evidence-ref>" : item.ref;
+    console.log(`evidence [${item.status}/${item.grade}] ${item.kind} ${ref}`);
   }
   if (state.pendingHuman) {
     console.log(`waiting on human: ${state.pendingHuman.transition}`);
@@ -141,6 +153,10 @@ function loadRunConfig(flags, command) {
     policies.push(parsePolicyDoc(parseYamlSubset(readFileSync(resolve(configDir, policyPath), "utf8"))));
   }
 
+  if (config.reviewTriage !== undefined && !["required", "off"].includes(config.reviewTriage)) {
+    throw new Error(`reviewTriage must be "required" or "off", got: ${config.reviewTriage}`);
+  }
+
   return {
     repoRoot,
     workflow,
@@ -157,6 +173,8 @@ function loadRunConfig(flags, command) {
     maxAttemptsPerStep: config.maxAttemptsPerStep ?? 4,
     stepTimeoutMs: config.stepTimeoutMs,
     allowedPaths: config.allowedPaths,
+    requires: config.requires ?? [],
+    reviewTriage: config.reviewTriage === "required" ? "required" : null,
     planDigest: digestOfWorkFile("plan.md"),
     intentDigest: digestOfWorkFile("intent.md"),
   };
@@ -164,8 +182,14 @@ function loadRunConfig(flags, command) {
 
 function commandStart(flags) {
   const options = loadRunConfig(flags, "start");
+  if (process.stdout.isTTY) {
+    // Run launch discipline (real incident: a host-tool timeout killed a
+    // verify worker mid-run): anything longer than minutes belongs in a
+    // detached process, not an interactive foreground shell.
+    console.log("tip: long runs should be started detached (nohup/setsid); interactive shells die with their host");
+  }
   const result = startRun(options);
-  console.log(`ledger: ${result.ledgerPath}`);
+  console.log(`ledger: ${toRepoRef(options.repoRoot, result.ledgerPath)}`);
   printState(result.state, { corruption: null });
 }
 
@@ -175,7 +199,7 @@ function commandResume(flags) {
   if (!result.resumed) {
     console.log(`nothing to resume: ${result.reason}`);
   }
-  console.log(`ledger: ${result.ledgerPath}`);
+  console.log(`ledger: ${toRepoRef(options.repoRoot, result.ledgerPath)}`);
   printState(result.state, { corruption: null });
 }
 
@@ -299,6 +323,116 @@ function commandDoctor(flags) {
     console.log("push protection: repository has no remotes (nothing to protect)");
   }
   console.log("kernel capabilities: merge/deploy/publish have no call path in the runner (invariant 20)");
+  if (options.requires.length > 0) {
+    console.log("environment contract (requires):");
+    const check = checkRequires(options.requires);
+    for (const row of check.checked) {
+      console.log(`  ${row.command}: OK${row.version ? ` (${row.version})` : ""}`);
+    }
+    for (const problem of check.problems) {
+      console.log(`  PROBLEM ${problem}`);
+    }
+  } else {
+    console.log("environment contract: none declared (implicit PATH facts stay unchecked)");
+  }
+}
+
+// Preflight: run one step's configured worker command directly in the main
+// checkout — no worktree, no ledger, no evidence. Minute-level dry loops
+// against the first failure boundary before a full run is what turned the
+// deploy campaign's idle phase around; the output is a dry signal only and a
+// Run must reproduce anything it finds.
+function commandPreflight(flags) {
+  const options = loadRunConfig(flags, "preflight");
+  if (!flags.step) {
+    throw new Error("preflight requires --step");
+  }
+  const stepDef = options.workflow.steps.find((candidate) => candidate.id === flags.step);
+  if (!stepDef) {
+    throw new Error(`step not in workflow: ${flags.step}`);
+  }
+  const spec = stepDef.worker ? options.adapterConfigs[stepDef.worker] : null;
+  if (!spec) {
+    throw new Error(`step ${flags.step} has no configured worker command to preflight`);
+  }
+  if (options.requires.length > 0) {
+    const check = checkRequires(options.requires);
+    for (const problem of check.problems) {
+      console.log(`requires PROBLEM: ${problem}`);
+    }
+  }
+  const fill = (text) =>
+    String(text)
+      .replaceAll("{workspace}", options.repoRoot)
+      .replaceAll("{step}", flags.step)
+      .replaceAll("{worker}", stepDef.worker);
+  const args = (spec.args ?? []).map(fill);
+  let env;
+  if (spec.inheritEnv === true) {
+    env = { ...process.env };
+  } else {
+    env = {};
+    for (const key of ["PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "TERM", "USER", "SHELL"]) {
+      if (process.env[key] !== undefined) {
+        env[key] = process.env[key];
+      }
+    }
+  }
+  Object.assign(env, spec.env ?? {});
+  env.BUILDBEAT_PREFLIGHT = "1";
+  console.log(`PREFLIGHT (dry signal, never evidence): step ${flags.step} -> ${spec.command} ${args.join(" ")}`);
+  console.log(`cwd: main checkout (no worktree, no ledger, no evidence written)`);
+  const result = spawnSync(spec.command, args, {
+    cwd: options.repoRoot,
+    stdio: "inherit",
+    env,
+    timeout: spec.timeoutMs,
+  });
+  if (result.error) {
+    throw new Error(`preflight could not run the command: ${result.error.message}`);
+  }
+  const exitCode = result.status ?? 1;
+  console.log(`preflight exit=${exitCode} — a Run must reproduce this before it counts`);
+  process.exitCode = exitCode;
+}
+
+function commandFindings(rest) {
+  const [sub, ...args] = rest;
+  const flags = parseFlags(args);
+  if (sub === "list") {
+    if (!flags.repo || !flags.work) {
+      throw new Error("findings list requires --repo and --work");
+    }
+    const rows = readFindingsAccount(resolve(flags.repo), flags.work);
+    const findings = rows.filter((row) => row.kind === "finding");
+    if (findings.length === 0) {
+      console.log(`no recorded findings (${findingsAccountRef(flags.work)})`);
+      return;
+    }
+    const adjudicated = latestAdjudications(rows);
+    for (const row of findings) {
+      const verdict = adjudicated.get(row.fingerprint);
+      const status = verdict ? `${verdict.action} by ${verdict.by}` : "open";
+      const reRaised = row.reRaised ? " RE-RAISED" : "";
+      console.log(`[${row.severity} ${row.fingerprint}] (${status})${reRaised} ${row.summary}`);
+    }
+  } else if (sub === "adjudicate") {
+    if (!flags.repo || !flags.work || !flags.fingerprint || !flags.action) {
+      throw new Error("findings adjudicate requires --repo, --work, --fingerprint and --action");
+    }
+    const row = adjudicateFinding(resolve(flags.repo), flags.work, {
+      fingerprint: flags.fingerprint,
+      action: flags.action,
+      by: flags.by,
+      note: flags.note,
+    });
+    console.log(`adjudicated ${row.fingerprint} -> ${row.action} ([${row.severity}] ${row.summary})`);
+    if (row.action === "dismiss") {
+      console.log("dismissed: this fingerprint no longer blocks; an escalated severity reopens on its own");
+    }
+  } else {
+    throw new Error(`findings subcommand must be list|adjudicate, got: ${sub ?? "(none)"}`);
+  }
 }
 
 function commandEvents(flags) {
@@ -393,7 +527,7 @@ function commandObserve(rest) {
       throw new Error("observe run requires --config <observe.yaml>");
     }
     const result = runObserveCycle({ configPath: flags.config });
-    console.log(`observe cycle ${result.cycle} finished (ledger: ${result.ledgerPath})`);
+    console.log(`observe cycle ${result.cycle} finished (ledger: ${result.ledgerRef})`);
     for (const row of result.results) {
       const bands = row.bands.length > 0 ? ` bands=${row.bands.join(",")}` : "";
       const intent = row.intent ? ` intent=${row.intent.outcome}:${row.intent.intentRef}` : "";
@@ -445,9 +579,9 @@ function commandObserve(rest) {
 
 function main() {
   const [command, ...rest] = process.argv.slice(2);
-  if (command === "observe") {
+  if (command === "observe" || command === "findings") {
     try {
-      commandObserve(rest);
+      (command === "observe" ? commandObserve : commandFindings)(rest);
     } catch (error) {
       console.error(`error: ${error.message}`);
       process.exitCode = 1;
@@ -480,6 +614,8 @@ function main() {
       commandStatus(flags);
     } else if (command === "stop") {
       commandStop(flags);
+    } else if (command === "preflight") {
+      commandPreflight(flags);
     } else {
       process.stdout.write(USAGE);
       process.exitCode = command ? 2 : 0;

package/src/v2/domain/event-registry.js

@@ -1,6 +1,8 @@
 // Initial event type registry v1 per docs/v2/SPEC-0001-events-v1.md §4.
 // Semantics are frozen; the registry and per-type data may only grow additively.
 
+import { isAbsolute } from "node:path";
+
 import {
   ACTOR_KINDS,
   BUDGET_KINDS,
@@ -58,6 +60,23 @@ const EVENT_ENUMS = {
   TRIAGE_RECORDED: { action: TRIAGE_ACTIONS },
 };
 
+const REPO_REF_FIELDS = {
+  WORKSPACE_BOUND: ["repo", "worktreePath"],
+  EVIDENCE_RECORDED: ["evidenceRef"],
+  RUN_COMPACTED: ["runRecordRef"],
+  INTENT_DRAFTED: ["intentRef"],
+  TRIAGE_RECORDED: ["intentRef"],
+};
+
+function unsafeRepoRef(value) {
+  return (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    isAbsolute(value) ||
+    /(^|[\\/])\.\.([\\/]|$)/.test(value)
+  );
+}
+
 export class EventInputError extends Error {
   constructor(message) {
     super(message);
@@ -87,6 +106,11 @@ export function validateEventInput(type, actor, data) {
       throw new EventInputError(`event ${type} missing required data field: ${field}`);
     }
   }
+  for (const field of REPO_REF_FIELDS[type] ?? []) {
+    if (unsafeRepoRef(data[field])) {
+      throw new EventInputError(`event ${type} field ${field} must be a repository-relative reference`);
+    }
+  }
   const enums = EVENT_ENUMS[type];
   if (enums) {
     for (const [field, allowed] of Object.entries(enums)) {

package/src/v2/engine/reducer.js

@@ -140,6 +140,9 @@ export function applyEvent(state, event) {
         status: data.status,
         grade: data.grade,
         ...(data.findings ? { findings: data.findings } : {}),
+        ...(data.suppressedFingerprints
+          ? { suppressedFingerprints: data.suppressedFingerprints }
+          : {}),
       });
       break;
     }

package/src/v2/observe/observe.js

@@ -22,6 +22,7 @@ import { collectCommandEvidence } from "../evidence/collector.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { loadObserveConfig, severityRank } from "./observe-config.js";
 import { OBSERVE_REDUCER } from "./observe-reducer.js";
+import { toRepoRef } from "../runtime/repo-ref.js";
 
 const OBSERVE_IDS = { run: "OBSERVE", work: "OBSERVE" };
 const KERNEL_ACTOR = { kind: "kernel", id: "observe" };
@@ -142,7 +143,7 @@ function recordEvidence({ ledger, config, cycle, provider, execResult, kind, ste
     type: "EVIDENCE_RECORDED",
     actor: { kind: "provider", id: provider.id },
     data: {
-      evidenceRef: record.location,
+      evidenceRef: toRepoRef(config.repoRoot, record.location),
       kind: record.kind,
       subject: record.subject,
       digest: record.digest,
@@ -350,7 +351,13 @@ export function runObserveCycle({ configPath, now = new Date().toISOString() })
     data: { cycle, providersRun: config.providers.length },
     ...OBSERVE_IDS,
   });
-  return { cycle, ledgerPath: ledger.path, results, state: ledger.state };
+  return {
+    cycle,
+    ledgerPath: ledger.path,
+    ledgerRef: toRepoRef(config.repoRoot, ledger.path),
+    results,
+    state: ledger.state,
+  };
 }
 
 export function triageIntent({ repoRoot, intentRef, action, by = "unknown", note, now = new Date().toISOString() }) {

package/src/v2/presets/software-delivery.yaml

@@ -37,3 +37,8 @@ transitions:
     to: fix
 terminal:
   - wait-merge
+# Review rounds are capped by default (deploy-campaign charter: two review
+# rounds per run, then a human). Override per project via budgets.maxAttempts.
+budgets:
+  maxAttempts:
+    review: 2

package/src/v2/runtime/decisions.js

@@ -13,6 +13,7 @@ import { evaluatePolicies, sha256Text } from "../policy/policy.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { acquireLock, readback, releaseLock } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
+import { resolveRepoRef } from "./repo-ref.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -68,10 +69,11 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
   acquireLock(repoRoot, runId);
   try {
     const bound = ledger.state.workspaces[runId];
-    if (!bound || !existsSync(bound.worktreePath)) {
+    const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
+    if (!bound || !existsSync(worktreePath)) {
       throw new DecisionError(`worktree missing for ${runId}; cannot verify the approval subject`);
     }
-    const tree = readback(bound.worktreePath);
+    const tree = readback(worktreePath);
     const when = ts ?? new Date().toISOString();
     if (tree.dirty || tree.head !== pending.subject.candidate) {
       const lastEvidence = ledger.state.evidence[ledger.state.evidence.length - 1];
@@ -102,8 +104,8 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
         state: ledger.state,
         candidate: pending.subject.candidate,
         workDir: join(repoRoot, "delivery", "work", ledger.state.run.work),
-        worktreePath: bound.worktreePath,
-        readWorktree: () => readback(bound.worktreePath),
+        worktreePath,
+        readWorktree: () => readback(worktreePath),
       },
     );
     for (const row of policyRows) {

package/src/v2/runtime/env-contract.js

@@ -0,0 +1,101 @@
+// Environment contract: a run config may declare the binaries (and minimum
+// versions) its frozen envelope silently depends on, and the kernel checks
+// them fail-closed before a run starts. Absorbed from real incidents: a
+// frozen verifier needed `rg` that only a vendored PATH provided, candidate
+// scripts assumed bash >= 4 on a /bin/bash 3.2 host, and a fresh shell
+// resolved Node 14 — each burned runs before anyone saw the real cause.
+
+import { spawnSync } from "node:child_process";
+
+export class EnvContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EnvContractError";
+  }
+}
+
+// Version detection in --version output needs at least major.minor (a bare
+// integer in arbitrary output is too easy to false-match); a declared min
+// may be major-only ("20").
+function parseVersion(text) {
+  const match = String(text).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+}
+
+function parseMin(value) {
+  const match = String(value).trim().match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if ((left[index] ?? 0) !== (right[index] ?? 0)) {
+      return (left[index] ?? 0) - (right[index] ?? 0);
+    }
+  }
+  return 0;
+}
+
+// Checks every entry and reports all problems at once (a run that dies on
+// the first missing binary hides the second). Non-zero --version exits are
+// tolerated; only a spawn failure means "not runnable".
+export function checkRequires(requires) {
+  const problems = [];
+  const checked = [];
+  for (const entry of requires ?? []) {
+    if (!entry || typeof entry !== "object" || typeof entry.command !== "string" || entry.command.length === 0) {
+      problems.push(`requires entries need a command name, got: ${JSON.stringify(entry)}`);
+      continue;
+    }
+    // A generous timeout: a missing binary fails instantly (ENOENT), while a
+    // loaded host must not turn a present binary into a false "not runnable".
+    const probe = spawnSync(entry.command, [entry.versionFlag ?? "--version"], {
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    if (probe.error) {
+      problems.push(
+        `${entry.command}: not runnable in this environment (${probe.error.code ?? probe.error.message})`,
+      );
+      continue;
+    }
+    const version = parseVersion(`${probe.stdout ?? ""}\n${probe.stderr ?? ""}`);
+    if (entry.min !== undefined) {
+      const min = parseMin(entry.min);
+      if (!min) {
+        problems.push(`${entry.command}: min ${JSON.stringify(entry.min)} is not a version`);
+        continue;
+      }
+      if (!version) {
+        problems.push(
+          `${entry.command}: version undetectable but min ${entry.min} is required (fail closed)`,
+        );
+        continue;
+      }
+      if (compareVersions(version, min) < 0) {
+        problems.push(
+          `${entry.command}: resolves to ${version.join(".")}, below required ${entry.min}`,
+        );
+        continue;
+      }
+    }
+    checked.push({ command: entry.command, version: version ? version.join(".") : null });
+  }
+  return { ok: problems.length === 0, problems, checked };
+}
+
+export function assertRequires(requires) {
+  const result = checkRequires(requires);
+  if (!result.ok) {
+    throw new EnvContractError(
+      `environment contract not satisfied:\n  - ${result.problems.join("\n  - ")}`,
+    );
+  }
+  return result;
+}

package/src/v2/runtime/findings.js

@@ -0,0 +1,158 @@
+// Review findings account per Work (Git plane, invariant 23: runtime stays
+// deletable). Every reviewer finding lands as a row keyed by a fingerprint;
+// human adjudications (accept/dismiss) append rows bound to that fingerprint.
+// A dismissed fingerprint no longer blocks and later reviewers receive the
+// adjudicated history as an anchor — re-litigating a settled verdict takes a
+// human decision, not a louder fresh reviewer. (Absorbed from the 30-run
+// deploy campaign: memoryless fresh reviewers oscillated between mutually
+// exclusive prescriptions and re-litigated accepted designs.)
+
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const ADJUDICATION_ACTIONS = ["accept", "dismiss"];
+
+export class FindingsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FindingsError";
+  }
+}
+
+export function findingsAccountRef(workId) {
+  return `delivery/work/${workId}/review-findings.jsonl`;
+}
+
+function accountPath(repoRoot, workId) {
+  return join(repoRoot, "delivery", "work", workId, "review-findings.jsonl");
+}
+
+// Same-text findings from different fresh reviewers must collide; severity is
+// part of the identity so an escalation (P2 -> P0) reopens on its own.
+export function fingerprintFinding(finding) {
+  const normalized = `${finding.severity}|${finding.summary}`
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+  return createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16);
+}
+
+export function readFindingsAccount(repoRoot, workId) {
+  const filePath = accountPath(repoRoot, workId);
+  if (!existsSync(filePath)) {
+    return [];
+  }
+  const rows = [];
+  for (const line of readFileSync(filePath, "utf8").split("\n")) {
+    if (line.length === 0) {
+      continue;
+    }
+    try {
+      rows.push(JSON.parse(line));
+    } catch {
+      throw new FindingsError(`findings account has an invalid line: ${filePath}`);
+    }
+  }
+  return rows;
+}
+
+function appendRow(repoRoot, workId, row) {
+  const dir = join(repoRoot, "delivery", "work", workId);
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(join(dir, "review-findings.jsonl"), `${JSON.stringify(row)}\n`, "utf8");
+}
+
+// Latest adjudication wins per fingerprint.
+export function latestAdjudications(rows) {
+  const map = new Map();
+  for (const row of rows) {
+    if (row.kind === "adjudication") {
+      map.set(row.fingerprint, row);
+    }
+  }
+  return map;
+}
+
+// Records one review attempt's findings into the account. Fingerprints that
+// already have a finding row are not duplicated; a finding whose fingerprint
+// a human dismissed is recorded as a re-raise attempt so the oscillation is
+// visible in the account, not just absent from the routing.
+export function recordReviewFindings(repoRoot, workId, { run, step, attempt, findings, ts }) {
+  const rows = readFindingsAccount(repoRoot, workId);
+  const adjudicated = latestAdjudications(rows);
+  const known = new Set(rows.filter((row) => row.kind === "finding").map((row) => row.fingerprint));
+  const recorded = [];
+  for (const [index, finding] of findings.entries()) {
+    const fingerprint = fingerprintFinding(finding);
+    const dismissed = adjudicated.get(fingerprint)?.action === "dismiss";
+    if (known.has(fingerprint) && !dismissed) {
+      continue;
+    }
+    const row = {
+      ts,
+      kind: "finding",
+      run,
+      step,
+      attempt,
+      id: `F-${run}-${step}-${attempt}-${index + 1}`,
+      severity: finding.severity,
+      summary: finding.summary,
+      fingerprint,
+      ...(dismissed ? { reRaised: true } : {}),
+    };
+    appendRow(repoRoot, workId, row);
+    known.add(fingerprint);
+    recorded.push(row);
+  }
+  return recorded;
+}
+
+export function adjudicateFinding(repoRoot, workId, { fingerprint, action, by, note, ts }) {
+  if (!ADJUDICATION_ACTIONS.includes(action)) {
+    throw new FindingsError(`action must be one of ${ADJUDICATION_ACTIONS.join("|")}, got: ${action}`);
+  }
+  const rows = readFindingsAccount(repoRoot, workId);
+  const finding = rows.find((row) => row.kind === "finding" && row.fingerprint === fingerprint);
+  if (!finding) {
+    throw new FindingsError(
+      `no recorded finding with fingerprint ${fingerprint}; adjudications bind to recorded findings only`,
+    );
+  }
+  const row = {
+    ts: ts ?? new Date().toISOString(),
+    kind: "adjudication",
+    fingerprint,
+    action,
+    by: by ?? "human",
+    ...(note ? { note } : {}),
+  };
+  appendRow(repoRoot, workId, row);
+  return { ...row, summary: finding.summary, severity: finding.severity };
+}
+
+// Compact anchor for worker input (BUILDBEAT_INPUT): the full adjudicated
+// history plus open findings, capped so the env payload stays small.
+const ANCHOR_CAP = 50;
+const SUMMARY_CAP = 300;
+
+export function buildAnchor(repoRoot, workId) {
+  const rows = readFindingsAccount(repoRoot, workId);
+  if (rows.length === 0) {
+    return null;
+  }
+  const adjudicated = latestAdjudications(rows);
+  const entries = rows
+    .filter((row) => row.kind === "finding")
+    .map((row) => ({
+      fingerprint: row.fingerprint,
+      severity: row.severity,
+      summary:
+        row.summary.length > SUMMARY_CAP ? `${row.summary.slice(0, SUMMARY_CAP)}…` : row.summary,
+      adjudication: adjudicated.get(row.fingerprint)?.action ?? "open",
+    }));
+  return {
+    account: findingsAccountRef(workId),
+    findings: entries.slice(-ANCHOR_CAP),
+  };
+}

package/src/v2/runtime/orchestrator.js

@@ -26,6 +26,15 @@ import {
   releaseLock,
 } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
+import { assertRequires } from "./env-contract.js";
+import {
+  buildAnchor,
+  fingerprintFinding,
+  latestAdjudications,
+  readFindingsAccount,
+  recordReviewFindings,
+} from "./findings.js";
+import { resolveRepoRef, toRepoRef } from "./repo-ref.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -135,6 +144,7 @@ function makeContext(options, ledger, workspace) {
     workflow.budgets?.maxAttempts?.[step] ?? maxAttemptsPerStep;
   context.policies = options.policies ?? [];
   context.allowedPaths = options.allowedPaths ?? null;
+  context.reviewTriage = options.reviewTriage ?? null;
   context.policyCtx = () => ({
     state: ledger.state,
     candidate: ledger.state.workspaces[workspace.workspaceId]?.candidate ?? null,
@@ -219,6 +229,14 @@ function settleOutcome(context, step, outcome, tree, exec) {
       ]);
       return null;
     }
+    // A step that failed its final attempt can never run again, so routing
+    // to fix would spend a worker on a candidate nothing can verify.
+    if ((ledger.state.steps[step]?.attempts ?? 0) >= context.maxAttemptsFor(step)) {
+      context.waitHuman(`resume-${step}`, [
+        `budget exhausted: ${step} failed its final attempt (maxAttempts=${context.maxAttemptsFor(step)}); not routing to fix`,
+      ]);
+      return null;
+    }
   }
   const to = nextStep(workflow, step, outcome);
   let result = "PASS";
@@ -337,11 +355,35 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     const outputsDir = join(context.runtimeDir, "runs", ledger.state.run.id, "outputs");
     mkdirSync(outputsDir, { recursive: true });
     const outputPath = join(outputsDir, `${step}-${attempt}.json`);
+    // Anchored review: readonly (reviewer) steps receive the adjudicated
+    // findings history so a fresh reviewer inherits settled verdicts instead
+    // of re-litigating them; writing steps get the latest review findings
+    // with their adjudication status (the fixer's worklist).
+    const input = { workId: ledger.state.run.work, runId: ledger.state.run.id, step, attempt };
+    const anchor = buildAnchor(context.repoRoot, ledger.state.run.work);
+    if (anchor && stepDef.readonly) {
+      input.anchor = anchor;
+    } else if (anchor) {
+      const lastReview = [...ledger.state.evidence]
+        .reverse()
+        .find((item) => item.kind === "review");
+      if (lastReview?.findings?.length) {
+        const adjudicated = latestAdjudications(
+          readFindingsAccount(context.repoRoot, ledger.state.run.work),
+        );
+        input.findings = lastReview.findings.map((finding) => ({
+          severity: finding.severity,
+          summary: finding.summary,
+          fingerprint: fingerprintFinding(finding),
+          adjudication: adjudicated.get(fingerprintFinding(finding))?.action ?? "open",
+        }));
+      }
+    }
     const exec = adapter.execute({
       step,
       worker: stepDef.worker,
       workspacePath: workspace.worktreePath,
-      input: { workId: ledger.state.run.work, runId: ledger.state.run.id, step, attempt },
+      input,
       timeoutMs: context.stepTimeoutMs,
       outputPath,
     });
@@ -359,7 +401,7 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
       actor: KERNEL,
       ts: now(),
       data: {
-        evidenceRef: evidence.location,
+        evidenceRef: toRepoRef(context.repoRoot, evidence.location),
         kind: evidence.kind,
         subject: evidence.subject,
         digest: evidence.digest,
@@ -432,21 +474,39 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
 
     let blockingFindings = [];
     if (envelope?.findings) {
-      blockingFindings = envelope.findings.filter(
-        (finding) => finding.severity === "P0" || finding.severity === "P1",
+      recordReviewFindings(context.repoRoot, ledger.state.run.work, {
+        run: ledger.state.run.id,
+        step,
+        attempt,
+        findings: envelope.findings,
+        ts: now(),
+      });
+      // A fingerprint a human dismissed stays visible in the evidence but no
+      // longer blocks: settled verdicts do not reopen without a human.
+      const adjudicated = latestAdjudications(
+        readFindingsAccount(context.repoRoot, ledger.state.run.work),
       );
+      const suppressed = [];
+      blockingFindings = envelope.findings.filter((finding) => {
+        if (adjudicated.get(fingerprintFinding(finding))?.action === "dismiss") {
+          suppressed.push(fingerprintFinding(finding));
+          return false;
+        }
+        return finding.severity === "P0" || finding.severity === "P1";
+      });
       ledger.append({
         type: "EVIDENCE_RECORDED",
         actor: KERNEL,
         ts: now(),
         data: {
-          evidenceRef: outputPath,
+          evidenceRef: toRepoRef(context.repoRoot, outputPath),
           kind: "review",
           subject: tree.head,
           digest: sha256(canonicalJson(envelope)),
           status: blockingFindings.length > 0 ? "failed" : "passed",
           grade: "L2",
           findings: envelope.findings,
+          ...(suppressed.length > 0 ? { suppressedFingerprints: suppressed } : {}),
         },
       });
     }
@@ -531,7 +591,29 @@ function drive(context, startStep, { skipBoundaryOnce = false } = {}) {
     } else {
       outcome = "succeeded";
     }
-    step = settleOutcome(context, step, outcome, tree, exec);
+    const routed = settleOutcome(context, step, outcome, tree, exec);
+    // Finding triage gate (reviewTriage: required): blocking findings stop
+    // for a human verdict before any fixer runs. Findings are prescriptions,
+    // not facts — auto-routing them to a fixer burned four oscillation
+    // rounds in the deploy campaign before a human stopped the loop.
+    if (routed && outcome === "findings-blocking" && context.reviewTriage === "required") {
+      context.waitHuman(
+        `enter-${routed}`,
+        [
+          `review found ${blockingFindings.length} blocking finding(s); triage before ${routed} runs`,
+          ...blockingFindings
+            .slice(0, 5)
+            .map(
+              (finding) =>
+                `[${finding.severity} ${fingerprintFinding(finding)}] ${finding.summary.slice(0, 200)}`,
+            ),
+          `adjudicate fingerprints (findings adjudicate), then approve enter-${routed} or reject the run`,
+        ],
+        "finding-triage",
+      );
+      return;
+    }
+    step = routed;
   }
 }
 
@@ -568,6 +650,11 @@ export function startRun(options) {
   if (!workflowDigest) {
     throw new OrchestratorError("workflowDigest is required (pin what you run)");
   }
+  // Environment contract first: a missing or too-old binary fails the start
+  // with a readable cause instead of burning a run on an implicit PATH fact.
+  if (options.requires?.length) {
+    assertRequires(options.requires);
+  }
   const { ledger, ledgerPath } = openLedgerFor(repoRoot, runId);
   if (ledger.events.length > 0) {
     throw new OrchestratorError(`run ${runId} already has a ledger; use resumeRun`);
@@ -600,9 +687,9 @@ export function startRun(options) {
       ts: now(),
       data: {
         workspaceId: workspace.workspaceId,
-        repo: repoRoot,
+        repo: toRepoRef(repoRoot, repoRoot),
         branch: workspace.branch,
-        worktreePath: workspace.worktreePath,
+        worktreePath: toRepoRef(repoRoot, workspace.worktreePath),
         base: workspace.base,
       },
     });
@@ -626,6 +713,9 @@ export function resumeRun(options) {
   if (!repoRoot || !runId) {
     throw new OrchestratorError("repoRoot and runId are required");
   }
+  if (options.requires?.length) {
+    assertRequires(options.requires);
+  }
   const { ledger, ledgerPath } = openLedgerFor(repoRoot, runId);
   const state = ledger.state;
   if (!state.run) {
@@ -647,15 +737,16 @@ export function resumeRun(options) {
   if (!bound) {
     throw new OrchestratorError(`run ${runId} has no bound workspace; cannot resume`);
   }
-  if (!existsSync(bound.worktreePath)) {
+  const worktreePath = resolveRepoRef(repoRoot, bound.worktreePath);
+  if (!existsSync(worktreePath)) {
     throw new OrchestratorError(
-      `worktree missing: ${bound.worktreePath}; recovery requires a human decision`,
+      "worktree missing; recovery requires a human decision",
     );
   }
   const workspace = {
     workspaceId: runId,
     repoRoot,
-    worktreePath: bound.worktreePath,
+    worktreePath,
     branch: bound.branch,
     base: bound.base,
   };
@@ -727,12 +818,12 @@ export function resumeRun(options) {
         ]);
         return { runId, ledgerPath, state: ledger.state, resumed: true, reason: null };
       }
-      startStep = settleOutcome(context, step, "failed", tree, {
-        command: "(interrupted)",
-        exitCode: null,
-        stdout: "",
-        stderr: "process lost before completion",
-      });
+      // An interrupted attempt says nothing about the candidate, so the step
+      // itself reruns (the lost attempt still counts against its budget)
+      // instead of settling as a step failure — routing a crash through the
+      // failure edge dispatched a fixer with no verifier evidence (real
+      // incident: deploy-18's verify worker was killed by a host timeout).
+      startStep = step;
     } else if (tree.dirty) {
       context.waitHuman("resume-run", [
         "worktree is dirty at resume with no step in flight; human triage required",

package/src/v2/runtime/repo-ref.js

@@ -0,0 +1,38 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+function outsideRepo(ref) {
+  return ref === ".." || ref.startsWith(`..${sep}`) || isAbsolute(ref);
+}
+
+// Runtime operations use absolute paths, but ledger/run-record references are
+// durable evidence and must not capture host-specific checkout locations.
+// Keep those references repository-relative and fail closed if a caller tries
+// to publish something outside the repository.
+export function toRepoRef(repoRoot, targetPath) {
+  const root = resolve(repoRoot);
+  const target = isAbsolute(targetPath) ? resolve(targetPath) : resolve(root, targetPath);
+  const ref = relative(root, target);
+  if (outsideRepo(ref)) {
+    throw new Error("runtime reference is outside the repository");
+  }
+  return ref === "" ? "." : ref.split(sep).join("/");
+}
+
+// Compatibility boundary: ledgers written before repo-relative references
+// contain absolute paths. They remain readable, while all newly written
+// events and compacted records use toRepoRef().
+export function resolveRepoRef(repoRoot, ref) {
+  if (typeof ref !== "string" || ref === "") {
+    throw new Error("runtime reference must be a non-empty string");
+  }
+  const root = resolve(repoRoot);
+  const target = isAbsolute(ref) ? resolve(ref) : resolve(root, ref);
+  if (outsideRepo(relative(root, target))) {
+    throw new Error("runtime reference is outside the repository");
+  }
+  return target;
+}
+
+export function normalizeRepoRef(repoRoot, ref) {
+  return toRepoRef(repoRoot, resolveRepoRef(repoRoot, ref));
+}

package/src/v2/runtime/run-record.js

@@ -8,6 +8,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 
 import { canonicalJson } from "../storage/event-ledger.js";
+import { normalizeRepoRef } from "./repo-ref.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -22,6 +23,20 @@ export function writeRunRecord({ repoRoot, ledger, ts }) {
   for (const [step, info] of Object.entries(state.steps)) {
     attempts[step] = info.attempts;
   }
+  const workspaces = Object.fromEntries(
+    Object.entries(state.workspaces).map(([id, workspace]) => [
+      id,
+      {
+        ...workspace,
+        repo: normalizeRepoRef(repoRoot, workspace.repo),
+        worktreePath: normalizeRepoRef(repoRoot, workspace.worktreePath),
+      },
+    ]),
+  );
+  const evidence = state.evidence.map((item) => ({
+    ...item,
+    ref: normalizeRepoRef(repoRoot, item.ref),
+  }));
   const record = {
     run: first.run,
     work: first.work,
@@ -31,11 +46,11 @@ export function writeRunRecord({ repoRoot, ledger, ts }) {
     finishedAt: last.ts,
     attempts,
     budgets: state.budgets,
-    workspaces: state.workspaces,
-    evidence: state.evidence,
+    workspaces,
+    evidence,
     decisions: state.decisions,
     approvals: state.approvals,
-    unverified: state.evidence
+    unverified: evidence
       .filter((item) => item.status === "unverified")
       .map((item) => item.ref),
   };

package/src/v2/workspace/workspace-manager.js

@@ -19,7 +19,10 @@ function git(cwd, args) {
     return execFileSync("git", ["-C", cwd, ...args], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
-    }).trim();
+    // Preserve porcelain's fixed-width leading status columns. Trimming the
+    // first leading space turns " M file" into "M file" and makes the
+    // downstream slice(3) drop the first path character.
+    }).trimEnd();
   } catch (error) {
     const stderr = error.stderr ? String(error.stderr).trim() : error.message;
     throw new WorkspaceError(`git ${args.join(" ")} failed: ${stderr}`);