@haiyangbg/buildbeat 4.1.0 → 4.2.1

package/CHANGELOG.md

@@ -2,8 +2,24 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v4.2.1 — 2026-10-07（补丁：审查没交报告当场停；成本按去向分开等待）
+
+- A review step that exits 0 without writing a report to `$BUILDBEAT_OUTPUT` now stops as `invalid-output` (an infrastructure failure: no fixer, no charge, `resume-review` waits for a person) instead of passing with no evidence until the merge approval refused it. The stop reason says where the report belongs and, when the reviewer printed something, how many bytes went to stdout. Found in a replay of real runs, where a reviewer's 3 P1, 6 P2 and 4 P3 findings reached stdout only.
+- The cost line splits human waits by how they ended: `human waits N (decided … · superseded … · stopped … · open …)`, listing only kinds that occurred; a request repeated before any decision continues the same wait, so overlapping time is not counted twice; JSON carries `cost.waits` with `{count, ms}` per kind and run-records keep it. In the same replay one work showed 32 minutes of decided waits while 11 hours passed on a request a new run superseded.
+- README (zh/en) describes the 4.x product: the three promises now name the mechanisms behind them (one `work.md` driven by `buildbeat run` and `status --all-repos`; evidence read back from Git and infrastructure stops instead of code fixes; merge approvals bound to the candidate and repairs at the merge decision), the cost line's waits, taking part without the runtime and the release readback.
+
+## v4.2.0 — 2026-10-07（次版本：合并决定点能接修复；合并批准绑定候选）
+
+> **发布状态**：`@haiyangbg/buildbeat@4.2.0` 已于 2026-10-07 从 `main`（release PR #76，merge commit `cc52ad3`，tag `v4.2.0`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37597691057，publish 与 verify 双 job 一次 success；所有者授权「推送并发 4.2.0」）。独立回读（直连 npmjs.org）：`latest` = 4.2.0、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、注册表 tarball 解压后与候选逐字节相同、SLSA v1 provenance、隔离安装 `--version` = 4.2.0、裸调用零写入、用法含 `--candidate <sha>` 与 `--action fix`、`npm audit signatures` 通过；GitHub Release v4.2.0 标 Latest；证据见 [`docs/releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md`](docs/releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md)。合并后 `main` CI 第 1 次尝试因跨仓测试快照混入 git 后台维护的锁文件失败、重跑转绿后才批准发布，测试修复随收尾合入。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 4.0.0 挪到 4.2.0；直连 npmjs.org 回读 `next` = `latest` = 4.2.0。
+
+- Bind merge approval replies to `--candidate <sha>` and forward the binding through the CLI; reject old or unbound replies after repair. Support both repair paths when the current candidate is still the base commit. Isolate repair regression fixtures from host Git configuration, signing and hooks. The owner confirmed the public name `--candidate <sha>` and runtime 4.2 as the next minor on 2026-10-07; merge-decision `run --adopt`, `decide --action fix` and candidate binding require runtime 4.2 or later.
+- Allow manual repair adoption at the merge decision: require clean actual HEAD, a new descendant of the candidate and changes within `allowedPaths`; resume at verify, review incrementally and return to the merge decision while preserving evidence and review accounting.
+- Add `decide --action fix --reason <text>` at the merge decision when a fixer is configured. Record an accepted P1 with the human's reason, feed it to the fixer and continue through verify/review without spending a review round for the decision or changing budgets. Status, inbox and notifications offer manual repair and the configured fixer path. SUCCEEDED and legacy 3.x Runs retain their existing boundaries.
+
 ## v4.1.0 — 2026-10-07（次版本：跨仓总览；提示里的命令与路径都能照做）
 
+> **发布状态**：`@haiyangbg/buildbeat@4.1.0` 已于 2026-10-07 从 `main`（release PR #74，merge commit `9259ac9`，tag `v4.1.0`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37590027989，publish 与 verify 双 job 一次 success；所有者授权「推送并发 4.1.0」）。独立回读（直连 npmjs.org）：`latest` = 4.1.0、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、注册表 tarball 解压后与候选逐字节相同、SLSA v1 provenance、隔离安装 `--version` = 4.1.0、裸调用零写入、用法含 `--all-repos`、`npm audit signatures` 通过；GitHub Release v4.1.0 标 Latest；本机两份全局安装均为 4.1.0；证据见 [`docs/releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md`](docs/releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md)。`next` 仍为 4.0.0。
+
 - Add read-only `status --all-repos`: discover the main repository, configured target checkouts and immediate child repositories, deduplicate real paths, show pending decisions first and count settled work. JSON retains all work; `--work` filters across repositories, while `--run` requires single-repository status.
 - Fix main-repository status/overview reporting target-repository work as ready to start: read state, findings and decisions from the target, retain the main run configuration for commands, and quote paths relative to the caller. Missing/invalid targets warn without hiding other work. Ship `src/v2/runtime/overview-repos.js` and update the package-file inventory for this runtime helper.
 - Hints give commands that work as written. A merged work whose run configs were all read and none has a `release:` section is told there is nothing left to do, instead of being sent to `buildbeat release`, which fails without that section and left the work unable to close; with a `release:` section the hint names the config that has it. A waiting run with no reply commands points to `status --work`, and `check` names `status` instead of the 3.x `inbox`. The run config template comment (and its copies in the Skill, both quickstarts and the example) names `check` / `run` / `--new`, and the quickstart says where the npm package installs the templates. Found by a first run of a fresh project on 4.0.0 with real codex workers.

package/README.en.md

@@ -2,11 +2,13 @@
 
 **Switch sessions. Keep building.**
 
-BuildBeat keeps work context in project files, drives a recoverable delivery loop, and brings evidence to human decisions. It is for humans and AI sessions.
+BuildBeat is for humans and AI sessions: the work description and every record stay in project files and Git; implementation, verification, review and repair move forward outside the session and can always resume; the candidate waits with its evidence for your merge decision.
 
 ## Three promises
 
-Switch sessions without losing progress; let the loop implement, verify, review and repair; inspect the candidate and evidence before deciding.
+- **Walk away.** Each work gets one `work.md`; once accepted, `buildbeat run` drives it. Close the session, switch AI tools or hand over to someone else, and continue from the project files and the run ledger. In a main repository with several code repositories, `buildbeat status --repo . --all-repos` shows what is pending everywhere.
+- **Come back to facts.** Verification runs the project's own commands, and the runtime reads results back from Git and the ledger instead of trusting what an AI says; review is independent and read-only. Missing tools, an unavailable backend or a review that hands in no report stop as infrastructure failures for a person, instead of being "fixed" as code.
+- **Decide with confidence.** A merge approval is bound to the candidate you reviewed (`--candidate`). When you spot a small problem at the merge decision, commit a fix and hand it over (`run --adopt`) or send it back to the fixer in one line (`decide --action fix`), without starting a new run. Merge, push, release and deployment stay with people.
 
 ## Start
 
@@ -26,13 +28,13 @@ buildbeat status --repo . --work WORK-X
 
 ## Records and handoffs
 
-End-to-end work packages contain work.md, configuration, decisions and terminal records under delivery/work/. Local in-flight events and logs live in .buildbeat/runtime/; candidates live in .buildbeat/worktrees/. Save missing facts before switching sessions. Active runs do not migrate through Git clone.
+End-to-end work packages contain work.md, configuration, decisions, review findings and terminal records under delivery/work/. Local in-flight events and logs live in .buildbeat/runtime/; candidates live in .buildbeat/worktrees/. The cost line in `status` shows review rounds, findings and where human waits went (decided, superseded, stopped, still open). Save missing facts before switching sessions; active runs do not migrate through Git clone. People and tools without the runtime can still read status and write work descriptions.
 
-[Handoff](docs/v2/guide/11-session-handoff.en.md) · [Recovery](docs/v2/guide/10-recovery.en.md)
+[Handoff](docs/v2/guide/11-session-handoff.en.md) · [Recovery](docs/v2/guide/10-recovery.en.md) · [Without the runtime](docs/v2/guide/12-without-runtime.en.md)
 
 ## Boundaries
 
-BuildBeat does not provide multi-user accounts, roles and permissions. It does not collect or upload project usage data and has no telemetry collection. Models and authentication belong to the configured AI tool. Merge, push, deployment and publication remain separately authorized external actions. Production monitoring, release lanes and arbitrary workflow/policy languages are outside the current product.
+BuildBeat does not provide multi-user accounts, roles and permissions. It does not collect or upload project usage data and has no telemetry collection. Models and authentication belong to the configured AI tool. Merge, push, deployment and publication remain separately authorized external actions; after a release, `buildbeat release` records the project's own readback and the window closes only when it passes. Production monitoring and arbitrary workflow/policy languages are outside the product.
 
 [Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.en.md) · [Migration](docs/MIGRATION.md)
 

package/README.md

@@ -2,11 +2,13 @@
 
 **会话随时换，项目接着干。**
 
-BuildBeat 面向人和 AI 会话，把工作上下文留在项目文件中，自动推进可恢复的交付循环，带证据交给人决定。
+BuildBeat 面向人和 AI 会话：工作说明和全部记录留在项目文件与 Git 里，实现、验证、审查和修复在会话之外自动推进、随时可恢复，候选带着证据停在你的合并决定前。
 
 ## 三个承诺
 
-换会话能接着干；实现、验证、审查和修复自动推进；候选和证据就绪后再做决定。
+- **走得开**：一项工作写一份 `work.md`，接受后由 `buildbeat run` 推进。关掉会话、换 AI 工具、换人，都能从项目文件和运行台账接着干；主仓带多个代码仓时，`buildbeat status --repo . --all-repos` 一条命令看全所有仓的待办。
+- **回来能信**：验证跑项目自己的命令，结果由运行时从 Git 和台账回读，不听 AI 自述；审查独立、只读。缺工具、后端不可用、审查没交报告，都按环境故障停下等人，不会把环境问题当成代码问题去修。
+- **敢拍板**：合并批准绑定你看过的那一版候选（`--candidate`）。在合并决定点发现小问题，可以自己修好交回（`run --adopt`），或一句话退回给修复者（`decide --action fix`），不必重开一轮。合并、推送、发布、部署始终由人决定。
 
 ## 开始使用
 
@@ -26,13 +28,13 @@ buildbeat status --repo . --work WORK-X
 
 ## 记录与接续
 
-端到端工作包在 delivery/work/ 保存 work.md、配置、决定与终态记录；本机在途事件和日志在 .buildbeat/runtime/，候选在 .buildbeat/worktrees/。换会话前补齐未落盘事实。Git clone 不迁移活动进程和现场。
+端到端工作包在 delivery/work/ 保存 work.md、配置、决定、审查问题与终态记录；本机在途事件和日志在 .buildbeat/runtime/，候选在 .buildbeat/worktrees/。`status` 的成本行列出审查轮数、问题数，以及人工等待各自的去向（已决定、被替代、被停掉、仍在等）。换会话前补齐未落盘事实；Git clone 不迁移活动进程和现场。没装运行时的人和工具也能读状态、写工作说明。
 
-[Handoff](docs/v2/guide/11-session-handoff.md) · [Recovery](docs/v2/guide/10-recovery.md)
+[Handoff](docs/v2/guide/11-session-handoff.md) · [Recovery](docs/v2/guide/10-recovery.md) · [没有运行时](docs/v2/guide/12-without-runtime.md)
 
 ## 能力边界
 
-BuildBeat 不提供多人账号、角色/权限系统，不采集或上传项目使用数据，没有遥测采集。模型和鉴权由配置的 AI 工具提供。合并、推送、部署、发布分别由获授权的外部操作完成。生产巡检、上线专用流程和任意工作流/规则语言已移出产品。
+BuildBeat 不提供多人账号、角色/权限系统，不采集或上传项目使用数据，没有遥测采集。模型和鉴权由配置的 AI 工具提供。合并、推送、部署、发布分别由获授权的外部操作完成；上线后可用 `buildbeat release` 记录项目自己的回读，回读通过才关窗。生产巡检和任意工作流/规则语言不在产品范围内。
 
 [Capabilities](docs/CAPABILITY-MATRIX.md) · [Security](docs/v2/guide/09-security-boundaries.md) · [Migration](docs/MIGRATION.md)
 

package/SKILL.md

@@ -11,11 +11,13 @@ description: BuildBeat 用项目文件接续上下文，在隔离工作树内自
 
 先跑 `buildbeat --version`，按结果选命令：
 
-- 4.x：按下文操作。
+- 4.x：按下文操作，但合并决定点的两种修复入口有下述版本限制。
 - 3.x：下文的 `run`、`status --work`、`decide`、`check`、`history` 和 `work.md` 在 3.x 不存在，沿用项目现有的 3.x 写法：`intent.md` + `plan.md`，分别 `accept --artifact intent` 与 `accept --artifact plan`；`start --config <config> --attempt new` 开工，`resume --config <config> [--run <RUN>] [--adopt <sha> --by <name>]` 续跑；`overview`、`inbox`、`status --run <RUN>` 看进度；`approve --transition <t>` / `reject --reason <why>` 决定；`findings adjudicate` 裁决问题；`doctor` 检查配置；run-config 保留 `workflow:` 与 `riskPreset:`。
 - 3.x 的活动 Run 只能用 3.x 运行时完成或取消。升级到 4.x 前先问用户，并按[迁移说明](docs/MIGRATION.md)处理。
 - 没有运行时：按[不装运行时也能参与](docs/v2/guide/12-without-runtime.md)只读状态、写 `work.md` 和规定格式的决定行；不得代批 Run，不得声称验证、审查或回读已通过。
 
+合并决定点的 `run --adopt`、`decide --action fix` 与批准命令的 `--candidate` 候选绑定要求运行时 4.2 或更高版本。
+
 ## 会话操作
 
 | 用户意图 | 操作 |
@@ -24,9 +26,10 @@ description: BuildBeat 用项目文件接续上下文，在隔离工作树内自
 | 准备一项工作 | 写 `delivery/work/<ID>/work.md`，包含目标、范围、验收、实施计划；复制 run-config 样板并填真实命令 |
 | 接受工作说明 | `buildbeat accept --repo . --work <ID> --by <owner>`；用户已有明确授权时直接记录，不重复问同一个决定 |
 | 开工、继续 | `buildbeat run --config <config>`；首次编号，已有运行则恢复；明确新一轮时加 `--new` |
-| 批准、拒绝 | 读取状态卡，再 `buildbeat decide --repo . --run <RUN> --action approve|reject --transition <t> --by <owner>`；非终态决定后续跑 |
+| 批准、拒绝 | 读取状态卡并复制批准或拒绝命令；合并批准为 `buildbeat decide --repo . --run <RUN> --action approve --transition enter-wait-merge --candidate <完整 SHA> --by <owner>`，使用卡片候选；修复后旧候选或未绑定候选的批准失效；非终态决定后续跑 |
+| 合并决定退回修复 | `buildbeat decide --repo . --run <RUN> --action fix --reason <要修什么> --by <owner>`；仅合并决定点且有 fixer 时可用，再 `buildbeat run --config <config> --run <RUN>` 续跑；原因记为已接受 P1，重验、再审，review 预算照常累计 |
 | 问题接受、驳回 | `buildbeat decide --repo . --work <ID> --action accept|dismiss --fingerprint <fp> --by <owner> --note <reason>` |
-| 已手修并提交 | `buildbeat run --config <config> --run <RUN> --adopt <sha> --by <name>`；检查干净工作树与实际 HEAD 后从 verify 继续 |
+| 已手修并提交 | `buildbeat run --config <config> --run <RUN> --adopt <sha> --by <name>`；检查干净工作树与实际 HEAD 后从 verify 继续；合并决定点也可用，此时须为当前候选的新后代且改动不越界 |
 | 配置或环境有问题 | `buildbeat check --config <config>`；显式 `--step <step>` 会在主检出执行 worker，只有用户任务需要才调用，结果不是正式证据 |
 | 上线后回读、关窗 | 人完成上线后 `buildbeat release --config <config> [--note <text>]`；最近一次回读通过再 `buildbeat decide --repo . --work <ID> --action close --result <text> --by <owner>`。回读失败不能关窗 |
 | 结束一轮 | `buildbeat stop --repo . --run <RUN> --reason <reason>`；活动驱动持锁时先处理进程，不能把 stop 当作进程杀手 |

package/docs/CAPABILITY-MATRIX.md

@@ -1,6 +1,6 @@
 # BuildBeat capability matrix / 能力矩阵
 
-Current release: 4.1.0. One product path: Skill → local runtime →
+Current release: 4.2.1. One product path: Skill → local runtime →
 project records. The Claude Code plugin distributes the Skill and references;
 install the runtime separately. Files remain readable without the runtime, but
 manual work has no automatic loop, isolation, budget or approval enforcement;
@@ -13,7 +13,7 @@ may be written by hand.
 | Delivery loop | Fixed build/verify/review/fix flow | External CLI tools do the actual work |
 | Recovery | Run/step ledger, resume, manual candidate adoption, stale locks | Active runtime is not transferred by Git clone |
 | Trusted result | Real command evidence, current candidate, read-only review | Script tests do not prove real AI business capability |
-| Decisions | Acceptance, exact approval, frozen checks, budget/convergence stops | No automatic merge, push or deployment |
+| Decisions | Acceptance, exact approval bound to the candidate, frozen checks, budget/convergence stops, repairs at the merge decision (adopt a hand fix or send it back to the fixer) | No automatic merge, push or deployment |
 | Efficiency | Verify cache, review range hints, parallel Work isolation | External test state must be isolated and stable |
 | Feedback | Unified status/cost/decisions, also across a main repository and its code repositories (`--all-repos`), liveness, webhook/DingTalk | Notifications do not approve |
 | UI evidence | `requireScreenshot`: screenshots from verify, bound to the candidate and required at merge | The project's verify renders and captures |

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 only executable is `buildbeat`. No other package name or executable alias receives publications.
 
-Release evidence at source package version `@haiyangbg/buildbeat@4.1.0`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.0.0` (dist-tags `latest` and `next`; the owner moved `next` from `3.3.1` to `4.0.0` with npm 2FA on 2026-10-05), anchored by annotated tag `v4.0.0` at commit `c15fbe0`, workflow run [37262387333](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37262387333), and archived in [`V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md). The 3.3.1 chain (`latest` from 2026-10-02 until 4.0.0 took over on 2026-10-05; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02) stays archived in [`V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md). The 3.3.0 chain (`latest` on 2026-10-02 until 3.3.1 took over the same day; the owner moved `next` from `3.2.1` to `3.3.0` with npm 2FA that day) stays archived in [`V3.3.0-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.0-RELEASE-EVIDENCE-2026-10-02.md). The 3.2.1 chain (`latest` from 2026-09-26 until 3.3.0 took over on 2026-10-02; the owner moved `next` from `3.0.1` to `3.2.1` with npm 2FA on 2026-09-26) stays archived in [`V3.2.1-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.1-RELEASE-EVIDENCE-2026-09-26.md). The 3.2.0 chain (`latest` on 2026-09-26 until 3.2.1 took over the same day) stays archived in [`V3.2.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.1.0 chain (`latest` on 2026-09-26 until 3.2.0 took over the same day) stays archived in [`V3.1.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.1.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.0.1 chain (`latest` from 2026-09-09 until 3.1.0 took over on 2026-09-26) stays archived in [`V3.0.1-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.1-RELEASE-EVIDENCE-2026-09-09.md). The 3.0.0 chain (`latest` from 2026-09-09 until 3.0.1 took over the same day; the first version without the removed generation) stays archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.0-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.2 chain (`latest` from 2026-09-09 until 3.0.0 took over the same day; the last version carrying the removed generation) stays archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](releases/V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](releases/V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](releases/V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](releases/V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](releases/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`](releases/V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/releases/`.
+Release evidence at source package version `@haiyangbg/buildbeat@4.2.1`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.2.0` (dist-tags `latest` and `next`; the owner moved `next` from `4.0.0` to `4.2.0` with npm 2FA on 2026-10-07), anchored by annotated tag `v4.2.0` at commit `cc52ad3`, workflow run [37597691057](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37597691057), and archived in [`V4.2.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.2.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.1.0 chain (`latest` on 2026-10-07 until 4.2.0 took over the same day) stays archived in [`V4.1.0-RELEASE-EVIDENCE-2026-10-07.md`](releases/V4.1.0-RELEASE-EVIDENCE-2026-10-07.md). The 4.0.0 chain (`latest` from 2026-10-05 until 4.1.0 took over on 2026-10-07; the owner moved `next` from `3.3.1` to `4.0.0` with npm 2FA on 2026-10-05) stays archived in [`V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md). The 3.3.1 chain (`latest` from 2026-10-02 until 4.0.0 took over on 2026-10-05; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02) stays archived in [`V3.3.1-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.1-RELEASE-EVIDENCE-2026-10-02.md). The 3.3.0 chain (`latest` on 2026-10-02 until 3.3.1 took over the same day; the owner moved `next` from `3.2.1` to `3.3.0` with npm 2FA that day) stays archived in [`V3.3.0-RELEASE-EVIDENCE-2026-10-02.md`](releases/V3.3.0-RELEASE-EVIDENCE-2026-10-02.md). The 3.2.1 chain (`latest` from 2026-09-26 until 3.3.0 took over on 2026-10-02; the owner moved `next` from `3.0.1` to `3.2.1` with npm 2FA on 2026-09-26) stays archived in [`V3.2.1-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.1-RELEASE-EVIDENCE-2026-09-26.md). The 3.2.0 chain (`latest` on 2026-09-26 until 3.2.1 took over the same day) stays archived in [`V3.2.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.2.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.1.0 chain (`latest` on 2026-09-26 until 3.2.0 took over the same day) stays archived in [`V3.1.0-RELEASE-EVIDENCE-2026-09-26.md`](releases/V3.1.0-RELEASE-EVIDENCE-2026-09-26.md). The 3.0.1 chain (`latest` from 2026-09-09 until 3.1.0 took over on 2026-09-26) stays archived in [`V3.0.1-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.1-RELEASE-EVIDENCE-2026-09-09.md). The 3.0.0 chain (`latest` from 2026-09-09 until 3.0.1 took over the same day; the first version without the removed generation) stays archived in [`V3.0.0-RELEASE-EVIDENCE-2026-09-09.md`](releases/V3.0.0-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.2 chain (`latest` from 2026-09-09 until 3.0.0 took over the same day; the last version carrying the removed generation) stays archived in [`V2.0.2-RELEASE-EVIDENCE-2026-09-09.md`](releases/V2.0.2-RELEASE-EVIDENCE-2026-09-09.md). The 2.0.1 chain (`latest` from 2026-09-06 until 2.0.2 took over on 2026-09-09) stays archived in [`V2.0.1-RELEASE-EVIDENCE-2026-09-06.md`](releases/V2.0.1-RELEASE-EVIDENCE-2026-09-06.md). The 2.0.0 chain (`latest` from 2026-09-05 until 2.0.1 took over on 2026-09-06) stays archived in [`V2.0.0-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-RELEASE-EVIDENCE-2026-09-05.md). The beta.5 chain stays archived in [`V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md`](releases/V2.0.0-BETA.5-RELEASE-EVIDENCE-2026-09-05.md). The beta.4 chain stays archived in [`V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md`](releases/V2.0.0-BETA.4-RELEASE-EVIDENCE-2026-09-03.md); the beta.3 chain in [`V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md`](releases/V2.0.0-BETA.3-RELEASE-EVIDENCE-2026-09-01.md). The beta.2 chain stays archived in [`V2.0.0-BETA.2-RELEASE-EVIDENCE-2026-08-28.md`](releases/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`](releases/V2.0.0-BETA.1-RELEASE-EVIDENCE-2026-08-28.md). Earlier distributions and the retired legacy package name are archived in the dated evidence files under `docs/releases/`.
 
 ## Channels and branches
 

package/docs/v2/guide/05-worker-contract.en.md

@@ -10,4 +10,6 @@ Review input includes adjudication anchors and an available lastReviewed increme
 
 Use exit 75 for missing tools, unavailable backends or an unusable execution environment. Do not change business code to hide an environment failure. Do not print credentials. The runner reads candidate, exit status and evidence itself.
 
+An invalid envelope is `invalid-output`, an environment failure, never a reason to change business code. A review step that exits 0 without writing its report to `$BUILDBEAT_OUTPUT` (printing it to stdout is not enough) is `invalid-output` too and stops for a person; a clean review hands in `{"findings": []}`.
+
 `BUILDBEAT_INPUT.workArtifact` carries the selected repository-relative `ref` and accepted `digest`. Read that artifact; use work.md first and legacy intent/plan only when work.md is absent.

package/docs/v2/guide/05-worker-contract.md

@@ -10,6 +10,6 @@ reviewer 输入包含历史裁决 anchor 和可用的 lastReviewed 增量范围
 
 环境缺工具、后端不可用、沙箱禁止必要操作等用 exit 75；不要通过修改业务代码掩盖环境问题。日志不得主动输出凭据。实际候选、退出码和证据都由内核回读，自述不能替代事实。
 
-无效信封记为 `invalid-output`，属于环境故障，不能据此要求修改业务代码。
+无效信封记为 `invalid-output`，属于环境故障，不能据此要求修改业务代码。审查步骤退出 0 却没有把报告写进 `$BUILDBEAT_OUTPUT`（只打印在 stdout 不算）同样记为 `invalid-output` 并停人；没有问题也要交 `{"findings": []}`。
 
 `BUILDBEAT_INPUT.workArtifact` carries the selected repository-relative `ref` and accepted `digest`. Read that artifact; use work.md first and legacy intent/plan only when work.md is absent.

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

@@ -6,6 +6,17 @@ New work has one work.md. accept binds its current digest but does not start exe
 
 Status presents the transition, candidate, plan digest, evidence, reasons and next action. decide --action approve|reject must name the run and transition. Approval re-reads the candidate and frozen safeguards; changed subjects, dirty trees, missing evidence or unacceptable reviews cannot be stamped. Continue nonterminal decisions with run. Final approval means merge-ready only.
 
+At the merge decision, `run --adopt`, `decide --action fix` and the approval command’s `--candidate` binding require runtime 4.2 or later.
+
+When a problem is found at the merge decision (`enter-wait-merge`), repair it within the same Run and verify and review again:
+
+- Manual repair: commit in the Run worktree, then execute `buildbeat run --config <config> --run <RUN> --adopt <sha> --by <name>`. The worktree must be clean, the SHA must be its actual HEAD and a new descendant of the current candidate, and changes must stay within `allowedPaths`. Resume at verify, review incrementally from the previous candidate, then wait for another merge decision.
+- Return to the fixer: execute `buildbeat decide --repo <repo> --run <RUN> --action fix --reason <what to repair> --by <name>`, then continue with `buildbeat run --config <config> --run <RUN>`. This is available only at the merge decision with a configured fixer; otherwise commit a manual repair and adopt it. The reason becomes an accepted P1 in the Work findings account and is passed in full to the fixer.
+
+After either repair path returns to the merge decision, read `buildbeat status --repo <repo> --run <RUN>` and copy its refreshed approval command: `buildbeat decide --repo <repo> --run <RUN> --action approve --transition enter-wait-merge --candidate <full SHA from the card> --by <name>`. The candidate is filled in by status, inbox and notifications. Approval with the old candidate, or without a candidate after repair, fails with `approval stale`; read the new card before deciding.
+
+The repair decision answers the old request and preserves historical evidence; the merge check uses only evidence for the current candidate. Returning to fix does not spend a review round, grant budget or refund it. Subsequent reviews count normally. SUCCEEDED Runs cannot be reopened; active 3.x Runs still require their original runtime.
+
 Use decide --action accept|dismiss --work ... --fingerprint ... for findings. Exact-fingerprint dismissals persist; similarity detects nonconverging reviews and never substitutes for adjudication.
 
 Normal repairs continue automatically. Repeated issues, increased blockers, infrastructure failures and exhausted budgets create exception decisions. One budget grant covers its repair/reverification/review plan and can be replayed. The driving session cannot approve on behalf of the user without authorization.

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

@@ -6,6 +6,17 @@
 
 status 的决定卡包含 transition、候选、计划摘要、证据、原因和下一步。decide --action approve|reject 必须指向该 Run 与转换。批准前重新回读候选与冻结校验；变化、脏树、缺证据或不合格审查不能盖章。非终态批准后用 run 续跑，最终批准只表示具备合并条件。
 
+合并决定点的 `run --adopt`、`decide --action fix` 与批准命令的 `--candidate` 候选绑定要求运行时 4.2 或更高版本。
+
+合并决定点（`enter-wait-merge`）发现问题时，可以在本 Run 中修复并重新验证、审查：
+
+- 手工修复：在 Run 工作树提交后执行 `buildbeat run --config <config> --run <RUN> --adopt <sha> --by <name>`。工作树必须干净，SHA 必须是实际 HEAD，并且是当前候选的新后代；改动仍受 `allowedPaths` 约束。从 verify 继续，review 使用上一候选的增量范围，最后再次等待合并决定。
+- 退回 fixer：执行 `buildbeat decide --repo <repo> --run <RUN> --action fix --reason <要修什么> --by <name>`，再用 `buildbeat run --config <config> --run <RUN>` 续跑。仅合并决定点可用，且配置必须有 fixer；否则先手修再接纳。原因记为本 Work 已接受的 P1 问题，fixer 收到完整原因。
+
+任一修复路径回到合并决定后，先读 `buildbeat status --repo <repo> --run <RUN>`，复制刷新后的批准命令：`buildbeat decide --repo <repo> --run <RUN> --action approve --transition enter-wait-merge --candidate <卡片中的完整 SHA> --by <name>`。状态卡、待批列表和通知会填好候选；旧候选命令或修复后未携带候选的命令会报 `approval stale`，需要重新读取卡片再决定。
+
+修复决定回答旧请求，保留历史证据；合并检查只使用当前候选的证据。退回本身不计 review、不扩额也不退款，后续 review 照常累计。已批准的 SUCCEEDED Run 不重新打开；3.x 活动 Run 仍由原运行时处理。
+
 审查问题通过 decide --action accept|dismiss --work ... --fingerprint ... 裁决。精确指纹的驳回持续生效；换说法的相似性只用于停止不收敛循环，不代替人的裁决。
 
 正常修复自动继续；重复问题、阻断数增加、环境故障或预算耗尽才形成例外决定。预算批准一次放行对应修复、重验和再审；扩额记录可以重放，驾驶会话不能自行冒充用户批准。

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

@@ -2,8 +2,12 @@
 
 [简体中文](10-recovery.md)
 
+At the merge decision, `run --adopt`, `decide --action fix` and the approval command’s `--candidate` binding require runtime 4.2 or later.
+
 - run resumes the unique nonterminal run in its family; choose --run when ambiguous. Archived work needs explicit --new to start another attempt.
 - An interrupted step reruns itself from the ledger. Handle a dirty worktree first. After committing a manual fix, --adopt checks the actual HEAD and continues at verify.
+- The merge decision also accepts a manual repair: the new HEAD must descend from the candidate and stay in scope. Alternatively use `decide --action fix --repo <repo> --run <RUN> --reason <what to repair> --by <name>` with a configured fixer, then `run --config <config> --run <RUN>`. Both paths verify and review again before another merge decision, preserving review budgets and historical evidence.
+- After repair, read the refreshed status card and copy its approval command with `--candidate <full SHA>`; old or unbound approvals fail with `approval stale`.
 - Reclaim a lock only when its owner is on this host and provably dead. Keep live, foreign-host and unidentified locks. stop is not a process-kill command.
 - Timeouts, crashes, malformed envelopes and exit 75 are infra: no fixer and no failure-budget charge. Decide and continue once the environment recovers.
 - A corrupt ledger exposes only its valid prefix and refuses appends. history --verify replays and validates without silently repairing it. Preserve the scene and candidate.

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

@@ -2,8 +2,12 @@
 
 [English](10-recovery.en.md)
 
+合并决定点的 `run --adopt`、`decide --action fix` 与批准命令的 `--candidate` 候选绑定要求运行时 4.2 或更高版本。
+
 - run 自动续接已有家族的唯一未终态 Run；多个候选时必须 --run 指定。历史工作需明确 --new 才会重新启动。
 - 中断步按台账重跑自身；脏工作树先处理。手修并提交后用 --adopt 指定实际 HEAD，从 verify 继续。
+- 合并决定点也可接纳手修：要求新 HEAD 是当前候选后代且改动不越界；也可 `decide --action fix --repo <repo> --run <RUN> --reason <要修什么> --by <name>` 退回已配置的 fixer，再 `run --config <config> --run <RUN>`。两者都会重验、再审并重新等待合并决定，review 预算与历史证据保留。
+- 修复后重新读取状态卡，复制带 `--candidate <完整 SHA>` 的批准命令；旧候选或未绑定候选的批准会报 `approval stale`。
 - 只有同机且持有者进程已不存在的锁自动回收。活动、异机、缺持有者信息的锁保留；stop 不是杀进程命令。
 - 超时、崩溃、无效信封、exit 75 属于 infra，不派 fixer、不扣失败预算。环境恢复后按待决策对象处理并续跑。
 - 台账损坏只读取合法前缀，拒绝追加；history --verify 校验回放，不会静默修复。保留现场与候选后决定恢复方式。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "BuildBeat: Git-based AI delivery across models, tools, sessions, and people, with context in project files, build-test-review-fix loops, and human decisions.",
   "type": "module",
   "bin": {

package/src/v2/cli/run.js

@@ -11,7 +11,7 @@
 
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -32,6 +32,7 @@ import {
   approveRun,
   listInbox,
   rejectRun,
+  requestFix,
 } from "../runtime/decisions.js";
 import { checkRequires } from "../runtime/env-contract.js";
 import {
@@ -50,7 +51,7 @@ import {
   renderOverview,
   runsFor,
 } from "../runtime/overview.js";
-import { pathLabel, shellArg } from "../runtime/overview-repos.js";
+import { configTargets, workConfigs, pathLabel, shellArg } from "../runtime/overview-repos.js";
 import { closeWork, runReadback } from "../runtime/release.js";
 import {
   DEFAULT_STALL_AFTER_MS,
@@ -97,7 +98,8 @@ Usage:
   buildbeat accept --repo <path> --work <WORK-ID> [--by <name>]
   buildbeat run --config <run-config.yaml> [--run <RUN-ID>] [--new] [--adopt <sha> --by <name>]
   buildbeat status --repo <path> [--work <WORK-ID> | --run <RUN-ID>] [--all-repos] [--json]
-  buildbeat decide --repo <path> --run <RUN-ID> --action approve|reject --transition <t> [--by <name>] [--reason <text>]
+  buildbeat decide --repo <path> --run <RUN-ID> --action approve|reject --transition <t> [--candidate <sha>] [--by <name>] [--reason <text>]
+  buildbeat decide --repo <path> --run <RUN-ID> --action fix --reason <text> [--by <name>]
   buildbeat decide --repo <path> --work <WORK-ID> --action accept|dismiss --fingerprint <fp> [--by <name>] [--note <text>]
   buildbeat release --config <run-config.yaml> [--ref <ref>] [--note <text>]
   buildbeat decide --repo <path> --work <WORK-ID> --action close --result <text> [--by <name>]
@@ -179,8 +181,8 @@ function repoLabelFor(repoRoot, typed) {
   return rel;
 }
 
-function printNextReply(repoLabel, state) {
-  const lines = nextReply({ repoLabel, state });
+function printNextReply(repoLabel, state, repoRoot) {
+  const lines = nextReply({ repoLabel, state, repoRoot });
   if (lines.length === 0) {
     return;
   }
@@ -289,7 +291,7 @@ function printState(state, ledger, view = {}) {
       console.log(`  reason: ${reason}`);
     }
     if (view.repoLabel) {
-      printNextReply(view.repoLabel, state);
+      printNextReply(view.repoLabel, state, view.repoRoot);
     }
   }
   if (state.terminal) {
@@ -590,7 +592,7 @@ async function notifyForState(repoRoot, repoLabel, state) {
     }
     const results = await dispatchNotification(
       config,
-      buildNotification(kind, { repoLabel, state }),
+      buildNotification(kind, { repoLabel, state, repoRoot }),
       { repoRoot },
     );
     for (const row of results) {
@@ -915,6 +917,7 @@ async function commandResume(
       sha: flags.adopt,
       by: flags.by ?? "human",
       resumeAt,
+      allowedPaths: options.allowedPaths,
     });
     console.log(
       `adopted ${adopted.adopted} as candidate (${adopted.decisionRef}, answers ${adopted.transition}); resuming at ${adopted.resumeAt}`,
@@ -1009,6 +1012,7 @@ function commandInbox(flags, rows = null) {
     for (const line of nextReply({
       repoLabel: row.repo ? shellArg(pathLabel(process.cwd(), rowRepo)) : repoLabelFor(repoRoot, flags.repo),
       state: ledger.state,
+      repoRoot: rowRepo,
     })) {
       console.log(`    next: ${row.config ? line.replaceAll("--config <run-config.yaml>", `--config ${shellArg(pathLabel(process.cwd(), row.config))}`) : line}`);
     }
@@ -1033,6 +1037,7 @@ function commandApprove(flags) {
   const result = approveRun(resolve(flags.repo), flags.run, {
     by: flags.by ?? "human",
     transition: flags.transition,
+    candidate: flags.candidate,
     policies,
   });
   if (!result.approved) {
@@ -1628,6 +1633,28 @@ function commandDecide(flags) {
   }
   if (flags.action === "approve") return commandApprove(flags);
   if (flags.action === "reject") return commandReject(flags);
+  if (flags.action === "fix") {
+    if (!flags.repo || !flags.run) throw new Error("fix requires --repo and --run");
+    const repoRoot = resolve(flags.repo);
+    const prior = EventLedger.open(ledgerPathFor(repoRoot, flags.run));
+    let hasFixer;
+    // Older 4.x ledgers did not freeze repair capabilities. Discover a
+    // single matching configuration; never guess between several configs.
+    if (prior.state.run?.deliveryChecks && !prior.state.run.repair) {
+      const configs = configTargets(workConfigs(repoRoot, prior.state.run.work), []);
+      const candidates = configs.filter((item) => item.repo === realpathSync(repoRoot)).map((item) =>
+        loadRunConfig({ config: item.path }, "resume")).filter((options) =>
+        inRunFamily(options.runId, flags.run));
+      if (candidates.length !== 1) throw new Error("cannot identify the run configuration; use manual repair and run --adopt");
+      assertRunConfiguration(prior.state, candidates[0]);
+      hasFixer = Boolean(candidates[0].adapters.fixer);
+    }
+    const result = requestFix(repoRoot, flags.run, {
+      by: flags.by ?? "human", reason: flags.reason, hasFixer,
+    });
+    console.log(`repair requested as ${result.decisionRef}; continue with: buildbeat run --config <run-config.yaml> --run ${flags.run}`);
+    return;
+  }
   if (["accept", "dismiss"].includes(flags.action) && flags.fingerprint) {
     if (!flags.repo || !flags.work)
       throw new Error("finding decisions require --repo and --work");
@@ -1641,7 +1668,7 @@ function commandDecide(flags) {
     return;
   }
   throw new Error(
-    "decide requires --action approve|reject, accept|dismiss with --work and --fingerprint, or close with --work and --result",
+    "decide requires --action approve|reject|fix, accept|dismiss with --work and --fingerprint, or close with --work and --result",
   );
 }
 

package/src/v2/domain/model.js

@@ -48,7 +48,7 @@ export const EVIDENCE_STATUSES = ["passed", "failed", "unverified"];
 
 export const EVIDENCE_GRADES = ["L0", "L1", "L2", "L3", "L4"];
 
-export const DECISION_VALUES = ["approved", "rejected"];
+export const DECISION_VALUES = ["approved", "rejected", "fix"];
 
 // observe v0 per docs/v2/RFC-0003-workflow-policy.md §8 (frozen shape):
 // bands are exactly three fixed levels; triage actions are a closed set.

package/src/v2/engine/reducer.js

@@ -71,6 +71,7 @@ export function applyEvent(state, event) {
         planDigest: data.planDigest ?? "UNVERIFIED",
         intentDigest: data.intentDigest ?? "UNVERIFIED",
         ...(data.deliveryChecks ? { deliveryChecks: data.deliveryChecks } : {}),
+        ...(data.repair ? { repair: data.repair } : {}),
       };
       break;
     }
@@ -221,7 +222,7 @@ export function applyEvent(state, event) {
         subject: data.subject,
         decisionRef: data.decisionRef,
       });
-      if (data.decision === "approved") {
+      if (data.decision === "approved" || data.decision === "fix") {
         next.approvals.push({
           decisionRef: data.decisionRef,
           transition: data.transition,

package/src/v2/runtime/decisions.js

@@ -14,6 +14,8 @@ import {
   readdirSync,
 } from "node:fs";
 import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { adjudicateFinding, fingerprintFinding, recordReviewFindings } from "./findings.js";
 
 import {
   deliveryChecks,
@@ -23,6 +25,7 @@ import {
 import { EventLedger } from "../storage/event-ledger.js";
 import {
   acquireLock,
+  listChangedPaths,
   readback,
   releaseLock,
 } from "../workspace/workspace-manager.js";
@@ -105,7 +108,7 @@ function recordDecisionFile(repoRoot, work, line) {
 export function approveRun(
   repoRoot,
   runId,
-  { by = "human", transition, ts, policies } = {},
+  { by = "human", transition, ts, policies, candidate } = {},
 ) {
   // Read, check and write under the run lock: a ledger read before the
   // lock may be stale by the time it is written to.
@@ -113,6 +116,12 @@ export function approveRun(
   try {
     const ledger = openWaiting(repoRoot, runId);
     const pending = ledger.state.pendingHuman;
+    const repaired = ledger.events.some((event) => event.type === "DECISION_RECORDED" &&
+      event.data.transition === "enter-wait-merge" && (event.data.adopted || event.data.decision === "fix"));
+    if ((candidate && candidate !== pending.subject.candidate) ||
+        (pending.kind === "final-decision" && repaired && !candidate)) {
+      throw new DecisionError("approval stale: read the current decision card and bind approval to its candidate");
+    }
     if (!transition) {
       throw new DecisionError(
         `an approval must name its transition explicitly (pending: ${pending.transition})`,
@@ -291,7 +300,7 @@ export function approveRun(
 export function adoptCandidate(
   repoRoot,
   runId,
-  { sha, by = "human", resumeAt, ts } = {},
+  { sha, by = "human", resumeAt, ts, allowedPaths } = {},
 ) {
   acquireLock(repoRoot, runId);
   try {
@@ -307,10 +316,12 @@ export function adoptCandidate(
     }
     const ledger = openWaiting(repoRoot, runId);
     const pending = ledger.state.pendingHuman;
-    if (pending.kind === "final-decision") {
-      throw new DecisionError(
-        "adopt is for a run waiting before fix/verify, not at the merge decision",
-      );
+    const final = pending.kind === "final-decision" && pending.transition === "enter-wait-merge";
+    if (pending.kind === "final-decision" && (!final || !ledger.state.run.deliveryChecks)) {
+      throw new DecisionError("legacy active run: use its original 3.3.1 runtime (docs/MIGRATION.md)");
+    }
+    if (final && resumeAt !== "verify") {
+      throw new DecisionError("a final-decision repair must resume at verify");
     }
     const bound = ledger.state.workspaces[runId];
     const worktreePath = bound
@@ -332,6 +343,19 @@ export function adoptCandidate(
         `worktree HEAD is ${tree.head}, not ${sha}; adopt what git reads back`,
       );
     }
+    if (final) {
+      const candidate = bound.candidate ?? bound.base;
+      const ancestor = spawnSync("git", ["-C", worktreePath, "merge-base", "--is-ancestor", candidate, tree.head]);
+      if (tree.head === candidate || ancestor.status !== 0) {
+        throw new DecisionError("adopt requires a new descendant of the current candidate; history rewrites are refused");
+      }
+    }
+    const scope = ledger.state.run.repair?.allowedPaths ?? allowedPaths;
+    if (scope) {
+      const violations = listChangedPaths(worktreePath, bound.base).filter((path) =>
+        !scope.some((prefix) => path === prefix || path.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`)));
+      if (violations.length) throw new DecisionError(`out-of-scope changes: ${violations.join(", ")}`);
+    }
     const when = ts ?? new Date().toISOString();
     const lastEvidence =
       ledger.state.evidence[ledger.state.evidence.length - 1];
@@ -390,6 +414,51 @@ export function adoptCandidate(
   }
 }
 
+// Queue a human-requested repair without fabricating a review or a budget
+// grant. The ordinary resume loop consumes this decision at the fix step.
+export function requestFix(repoRoot, runId, { by = "human", reason, ts, hasFixer } = {}) {
+  acquireLock(repoRoot, runId);
+  try {
+    const ledger = openWaiting(repoRoot, runId);
+    const pending = ledger.state.pendingHuman;
+    if (!ledger.state.run.deliveryChecks)
+      throw new DecisionError("legacy active run: use its original 3.3.1 runtime (docs/MIGRATION.md)");
+    if (pending.kind !== "final-decision" || pending.transition !== "enter-wait-merge")
+      throw new DecisionError("fix is only available at the merge decision");
+    if (!(ledger.state.run.repair?.hasFixer ?? hasFixer))
+      throw new DecisionError("no fixer configured; commit a manual repair and use run --adopt <sha> --by <name>");
+    if (typeof reason !== "string" || !reason.trim())
+      throw new DecisionError("fix requires a non-empty reason describing what to repair");
+    const bound = ledger.state.workspaces[runId];
+    const worktreePath = bound && resolveRepoRef(repoRoot, bound.worktreePath);
+    if (!worktreePath || !existsSync(worktreePath))
+      throw new DecisionError(`worktree missing for ${runId}`);
+    const tree = readback(worktreePath);
+    if (tree.dirty || tree.head !== (bound.candidate ?? bound.base) || tree.head !== pending.subject.candidate)
+      throw new DecisionError("worktree changed since the request; commit the manual repair and use run --adopt");
+    const when = ts ?? new Date().toISOString();
+    const decisionRef = `D-${runId}-${ledger.state.decisions.length + 1}`;
+    const finding = { severity: "P1", summary: reason.trim() };
+    recordReviewFindings(repoRoot, ledger.state.run.work, {
+      run: runId, step: "enter-wait-merge", attempt: ledger.state.decisions.length + 1,
+      findings: [finding], ts: when,
+    });
+    adjudicateFinding(repoRoot, ledger.state.run.work, {
+      fingerprint: fingerprintFinding(finding), action: "accept", by,
+      note: decisionRef, ts: when,
+    });
+    const data = {
+      decision: "fix", transition: pending.transition, subject: pending.subject,
+      decisionRef, reason: finding.summary, resumeAt: "fix",
+    };
+    ledger.append({ type: "DECISION_RECORDED", actor: { kind: "human", id: by }, ts: when, data });
+    recordDecisionFile(repoRoot, ledger.state.run.work, { ts: when, run: runId, ...data, by });
+    return { decisionRef, state: ledger.state };
+  } finally {
+    releaseLock(repoRoot, runId);
+  }
+}
+
 // Accepts a work artifact (plan, intent, spec) by binding a decision to the
 // file's current digest in the Git plane. If the file changes afterwards,
 // artifact.accepted evaluates false again — acceptance cannot go stale

package/src/v2/runtime/notify.js

@@ -10,9 +10,10 @@
 
 import { payloadFor } from "../adapters/notification-payload.js";
 import { currentScreenshots } from "../policy/policy.js";
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 
+import { configTargets, workConfigs } from "./overview-repos.js";
 import { parseYamlSubset } from "../engine/yaml-subset.js";
 
 export const NOTIFY_CONFIG = join(".buildbeat", "notify.yaml");
@@ -89,7 +90,22 @@ export function candidateScreenshots(state, candidate) {
 
 // The exact commands a human can copy to answer a pending request. Shared by
 // status, inbox and notifications so "what do I say now" has one answer.
-export function nextReply({ repoLabel, state }) {
+function configuredFixer(repoRoot, state) {
+  if (state.run.repair) return state.run.repair.hasFixer;
+  if (!repoRoot) return false;
+  // Existing 4.x runs have no repair snapshot. Hints are conservative when
+  // their configuration is missing, ambiguous or unreadable.
+  try {
+    const configs = configTargets(workConfigs(repoRoot, state.run.work), [])
+      .filter((item) => item.repo === realpathSync(repoRoot))
+      .map((item) => parseYamlSubset(readFileSync(item.path, "utf8")))
+      .filter((doc) => doc.run === state.run.id || (typeof doc.run === "string" &&
+        state.run.id.startsWith(`${doc.run}-`) && /^\d+$/.test(state.run.id.slice(doc.run.length + 1))));
+    return configs.length === 1 && Boolean(configs[0].workers?.fixer?.command);
+  } catch { return false; }
+}
+
+export function nextReply({ repoLabel, state, repoRoot }) {
   const pending = state.pendingHuman;
   if (!pending || !state.run) {
     return [];
@@ -120,14 +136,21 @@ export function nextReply({ repoLabel, state }) {
     );
   }
   lines.push(
-    `buildbeat decide --action approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition} --by <you>` +
+    `buildbeat decide --action approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition}` +
+      (pending.kind === "final-decision" ? ` --candidate ${pending.subject.candidate}` : "") + " --by <you>" +
       (pending.kind === "final-decision" ? "   # merge-ready; merge/push stay yours" : "   # then: run --config <run-config.yaml>"),
   );
   lines.push(`buildbeat decide --action reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
+  if (pending.kind === "final-decision") {
+    lines.push(`buildbeat run --config <run-config.yaml> --run ${runId} --adopt <sha> --by <you>   # commit a manual repair in the run worktree; verify and review again`);
+    if (configuredFixer(repoRoot, state)) {
+      lines.push(`buildbeat decide --repo ${repoLabel} --run ${runId} --action fix --reason <what to repair> --by <you>   # then: run --config <run-config.yaml> --run ${runId}`);
+    }
+  }
   return lines;
 }
 
-export function buildNotification(kind, { repoLabel, state, detail = {} }) {
+export function buildNotification(kind, { repoLabel, state, repoRoot, detail = {} }) {
   const run = state.run;
   const base = {
     kind,
@@ -149,7 +172,7 @@ export function buildNotification(kind, { repoLabel, state, detail = {} }) {
       reasons: pending?.reasons ?? [],
       candidate: pending?.subject?.candidate ?? null,
       ...(screenshots.length > 0 ? { screenshots } : {}),
-      nextReply: nextReply({ repoLabel, state }),
+      nextReply: nextReply({ repoLabel, state, repoRoot }),
     };
   }
   if (kind === "RUN_TERMINAL") {

package/src/v2/runtime/orchestrator.js

@@ -744,6 +744,21 @@ function beginStep(context, step, stepDef, attempt) {
       }));
     }
   }
+  // A human's final-decision repair is separate from reviewer evidence: it
+  // must not spend a review round or pretend that a reviewer reported it.
+  if (step === "fix") {
+    const decision = [...ledger.events].reverse().find((event) =>
+      event.type === "DECISION_RECORDED" && event.data.decision === "fix");
+    const priorFix = [...ledger.events].reverse().find((event) =>
+      event.type === "STEP_FINISHED" && event.data.step === "fix" && event.data.status === "succeeded");
+    if (decision && (!priorFix || decision.seq > priorFix.seq)) {
+      const finding = { severity: "P1", summary: decision.data.reason };
+      input.findings = [...(input.findings ?? []).filter((item) =>
+        item.fingerprint !== fingerprintFinding(finding)), {
+        ...finding, fingerprint: fingerprintFinding(finding), adjudication: "accept",
+      }];
+    }
+  }
   // Envelope (C6): the worker's prompt, materialised into the run
   // directory and handed over as BUILDBEAT_PROMPT / input.envelope.
   const prompt = materialisePrompt({
@@ -1058,6 +1073,13 @@ function recordStepResult(
     envelopeRaw = readFileSync(outputPath, "utf8");
   }
   const { envelope, error: envelopeError } = parseEnvelope(envelopeRaw);
+  // A review that exits cleanly without a report reviewed nothing the
+  // kernel can check: no evidence, no findings. Real incident: a reviewer
+  // printed 3 P1, 6 P2 and 4 P3 findings to stdout only; the step counted
+  // as passed and the gap surfaced only at the merge approval.
+  const reportMissing =
+    isReviewStep(step, stepDef) &&
+    (envelopeRaw === undefined || envelopeRaw === null);
 
   let stepStatus;
   if (exec.spawnError) {
@@ -1072,11 +1094,20 @@ function recordStepResult(
     // The command passed but a requirement the runner checks did not
     // (no screenshots): a candidate failure, routed like any other.
     stepStatus = "failed";
-  } else if (envelopeError) {
+  } else if (envelopeError || reportMissing) {
     stepStatus = "invalid-output";
   } else {
     stepStatus = "succeeded";
   }
+  let outputProblem = null;
+  if (stepStatus === "invalid-output" && !envelopeError) {
+    const stdoutBytes = Buffer.byteLength(String(exec.stdout ?? "").trim());
+    outputProblem =
+      "the reviewer exited 0 without writing a report to $BUILDBEAT_OUTPUT (stdout is not read)" +
+      (stdoutBytes > 0
+        ? `; stdout has ${stdoutBytes} bytes; write the JSON report to $BUILDBEAT_OUTPUT`
+        : "");
+  }
   // Infrastructure failure vs candidate failure. A timeout, a crash,
   // garbage output or the worker's own "environment unavailable" signal
   // (exit 75, EX_TEMPFAIL) says nothing about the candidate: no failure
@@ -1101,6 +1132,7 @@ function recordStepResult(
       status: stepStatus,
       exitCode: exec.exitCode,
       ...(exec.requirementFailure ? { reason: exec.requirementFailure } : {}),
+      ...(outputProblem ? { reason: outputProblem } : {}),
       ...(exec.screenshotsRejected
         ? { screenshotsRejected: exec.screenshotsRejected }
         : {}),
@@ -1123,7 +1155,7 @@ function recordStepResult(
       stepStatus === "failed"
         ? "exit 75 (worker reports its environment unavailable)"
         : stepStatus === "invalid-output"
-          ? "output is not a worker envelope"
+          ? (outputProblem ?? "output is not a worker envelope")
           : stepStatus;
     context.waitHuman(
       `resume-${step}`,
@@ -1506,6 +1538,9 @@ export function startRun(options) {
         run: runId,
         work: workId,
         data: {
+          ...(options.deliveryChecks ? {
+            repair: { hasFixer: Boolean(options.adapters?.fixer), allowedPaths: options.allowedPaths ?? null },
+          } : {}),
           workflowRef: workflow.name,
           workflowDigest,
           base: workspace.base,
@@ -1574,6 +1609,10 @@ export function assertRunConfiguration(state, options) {
   if (!state.run) throw new OrchestratorError("run has no creation record");
   if (options.workId && options.workId !== state.run.work)
     throw new OrchestratorError("run belongs to a different work");
+  if (state.run.repair && (
+    canonicalJson(state.run.repair.allowedPaths) !== canonicalJson(options.allowedPaths ?? null) ||
+    state.run.repair.hasFixer !== Boolean(options.adapters?.fixer)
+  )) throw new OrchestratorError("repair configuration changed since the run was created; refusing to resume");
   const { workflowDigest } = options;
   if (
     state.run.deliveryChecks &&

package/src/v2/runtime/overview.js

@@ -324,7 +324,7 @@ export function computeOverview(
           ? "MERGE_DECISION"
           : "WAITING_HUMAN";
       const replies = latest.state
-        ? nextReply({ repoLabel, state: latest.state })
+        ? nextReply({ repoLabel, state: latest.state, repoRoot })
         : [];
       next = replies[0] ?? `buildbeat status --repo ${repoLabel} --work ${workId}`;
     } else if (latest.status === "SUCCEEDED" && isReleaseLane(latest)) {

package/src/v2/runtime/work-cost.js

@@ -12,12 +12,29 @@ import { join } from "node:path";
 import { EventLedger } from "../storage/event-ledger.js";
 import { readFindingsAccount } from "./findings.js";
 
+// How each human wait ended. Counting waits alone hid where the time went:
+// one work showed 32 minutes of decided waits while 11 hours had passed on
+// a request nobody answered before a new run superseded it.
+export const WAIT_KINDS = ["decided", "superseded", "stopped", "open"];
+
+function emptyWaits() {
+  return Object.fromEntries(WAIT_KINDS.map((kind) => [kind, { count: 0, ms: 0 }]));
+}
+
+function addWait(bucket, ms) {
+  bucket.count += 1;
+  if (Number.isFinite(ms) && ms > 0) {
+    bucket.ms += ms;
+  }
+}
+
 function emptyCost() {
   return {
     runs: 0,
     reviewRounds: 0,
     findings: 0,
     humanWaits: 0,
+    waits: emptyWaits(),
     infraFailures: 0,
     workerMs: 0,
     firstAt: null,
@@ -25,11 +42,25 @@ function emptyCost() {
   };
 }
 
-// Cost facts of one ledger: review rounds, human waits, infra failures and
-// worker wall time (STEP_STARTED → STEP_FINISHED per attempt).
-export function ledgerCost(ledger) {
-  const cost = { reviewRounds: 0, humanWaits: 0, infraFailures: 0, workerMs: 0 };
+// Cost facts of one ledger: review rounds, human waits and how each ended,
+// infra failures and worker wall time (STEP_STARTED → STEP_FINISHED per
+// attempt). A wait runs from HUMAN_REQUESTED to the next DECISION_RECORDED
+// (decided) or to a RUN_TERMINAL without a decision (superseded or
+// stopped); a run still waiting counts up to `now` (open). A request
+// repeated before any decision (a resumed run asks again for the same
+// decision) continues the same wait from the first request: counting it
+// again would count the overlapping time twice.
+export function ledgerCost(ledger, { now = Date.now() } = {}) {
+  const cost = {
+    reviewRounds: 0,
+    humanWaits: 0,
+    waits: emptyWaits(),
+    infraFailures: 0,
+    workerMs: 0,
+  };
   const open = new Map();
+  let waitingSince = null;
+  let terminal = false;
   for (const event of ledger.events) {
     if (event.type === "STEP_STARTED") {
       open.set(`${event.data.step}#${event.data.attempt}`, Date.parse(event.ts));
@@ -51,12 +82,38 @@ export function ledgerCost(ledger) {
       }
     } else if (event.type === "HUMAN_REQUESTED") {
       cost.humanWaits += 1;
+      waitingSince ??= Date.parse(event.ts);
+    } else if (event.type === "DECISION_RECORDED") {
+      if (waitingSince !== null) {
+        addWait(cost.waits.decided, Date.parse(event.ts) - waitingSince);
+        waitingSince = null;
+      }
+    } else if (event.type === "RUN_TERMINAL") {
+      terminal = true;
+      if (waitingSince !== null) {
+        const kind = event.data?.status === "SUPERSEDED" ? "superseded" : "stopped";
+        addWait(cost.waits[kind], Date.parse(event.ts) - waitingSince);
+        waitingSince = null;
+      }
     }
   }
+  if (waitingSince !== null && !terminal) {
+    addWait(cost.waits.open, now - waitingSince);
+  }
   return cost;
 }
 
-export function computeWorkCost(repoRoot, workId, { excludeRun = null } = {}) {
+function addWaits(total, waits) {
+  for (const kind of WAIT_KINDS) {
+    const row = waits?.[kind];
+    if (row && Number.isFinite(row.count) && Number.isFinite(row.ms)) {
+      total[kind].count += row.count;
+      total[kind].ms += row.ms;
+    }
+  }
+}
+
+export function computeWorkCost(repoRoot, workId, { excludeRun = null, now = Date.now() } = {}) {
   const cost = emptyCost();
   const seen = new Set();
   const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
@@ -75,10 +132,11 @@ export function computeWorkCost(repoRoot, workId, { excludeRun = null } = {}) {
       if (state.run.id === excludeRun) {
         continue;
       }
-      const row = ledgerCost(ledger);
+      const row = ledgerCost(ledger, { now });
       cost.runs += 1;
       cost.reviewRounds += row.reviewRounds;
       cost.humanWaits += row.humanWaits;
+      addWaits(cost.waits, row.waits);
       cost.infraFailures += row.infraFailures;
       cost.workerMs += row.workerMs;
       track(cost, ledger.events[0]?.ts, ledger.events[ledger.events.length - 1]?.ts);
@@ -105,6 +163,8 @@ export function computeWorkCost(repoRoot, workId, { excludeRun = null } = {}) {
       // only; the cost block is preferred when present.
       cost.reviewRounds += record.cost?.reviewRounds ?? record.attempts?.review ?? 0;
       cost.humanWaits += record.cost?.humanWaits ?? record.decisions?.length ?? 0;
+      // Records written before wait kinds existed add no durations.
+      addWaits(cost.waits, record.cost?.waits);
       cost.infraFailures += record.cost?.infraFailures ?? 0;
       cost.workerMs += record.cost?.workerMs ?? 0;
       track(cost, record.startedAt, record.finishedAt);
@@ -137,10 +197,13 @@ export function formatWorkerMs(ms) {
 }
 
 export function renderWorkCost(cost) {
+  const waits = WAIT_KINDS.filter((kind) => cost.waits?.[kind]?.count > 0).map(
+    (kind) => `${kind} ${formatWorkerMs(cost.waits[kind].ms)}`,
+  );
   return [
     `review rounds ${cost.reviewRounds}`,
     `findings ${cost.findings}`,
-    `human waits ${cost.humanWaits}`,
+    `human waits ${cost.humanWaits}${waits.length > 0 ? ` (${waits.join(" · ")})` : ""}`,
     ...(cost.infraFailures > 0 ? [`infra failures ${cost.infraFailures}`] : []),
     `worker ${formatWorkerMs(cost.workerMs)}`,
   ].join(" · ");