@haiyangbg/buildbeat 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -2,8 +2,16 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
+## v4.2.0 — 2026-10-07（次版本：合并决定点能接修复；合并批准绑定候选）
+
+- 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/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.0. 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.0`; latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@4.1.0` (dist-tag `latest`; `next` stays on `4.0.0` until the owner moves it with npm 2FA), anchored by annotated tag `v4.1.0` at commit `9259ac9`, workflow run [37590027989](https://github.com/HaiYangBG1/BuildBeat/actions/runs/37590027989), and 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/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.0",
   "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({
@@ -1506,6 +1521,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 +1592,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)) {