@haiyangbg/buildbeat 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -2,10 +2,17 @@
 
 > 本项目吃自己的狗粮(红线④:必更 CHANGELOG)。格式循 Keep a Changelog,倒序。
 
-## Unreleased
+## v4.1.0 — 2026-10-07（次版本：跨仓总览；提示里的命令与路径都能照做）
+
+- 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.
+- `status --all-repos` prints English labels like the rest of the CLI (`pending decisions · <repo>`, `repo <repo>:`, `<repo>: settled N (closed a · cancelled b · merged, no release step c)`, `repo:` / `runs in:` under a work), and single-repository status again shows `NO_INTENT` for a work directory without a work description even when it has runs, as 4.0.0 did; a work known only from runtime ledgers still shows its run.
 
 ## v4.0.0 — 2026-10-04（主版本：聚焦可恢复交付，精简产品范围与操作入口）
 
+> **发布状态**：`@haiyangbg/buildbeat@4.0.0` 已于 2026-10-05 从 `main`（PR #70、#71 内容，release PR #72，merge commit `c15fbe0`，tag `v4.0.0`）经 OIDC Trusted Publishing 发布到 dist-tag **`latest`**（run 37262387333，publish 与 verify 双 job 一次 success；所有者授权「合并并发 4.0」）。独立回读（直连 npmjs.org）：`latest` = 4.0.0、`dist.integrity` 与本地用 Node 24 + npm 11.19.0 打的候选逐字一致、SLSA v1 provenance、隔离安装 `--version` = 4.0.0、裸调用零写入、用法含 `release` 与 `decide --action close`、`npm audit signatures` 通过；GitHub Release v4.0.0 标 Latest；本机两份全局安装均为 4.0.0；证据见 [`docs/releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md`](docs/releases/V4.0.0-RELEASE-EVIDENCE-2026-10-05.md)。同日所有者本人经 npm 两步验证把 dist-tag `next` 从 3.3.1 挪到 4.0.0；直连 npmjs.org 回读 `next` = `latest` = 4.0.0。
+
 - Owner decisions before 4.0 (WORK-4.0-INTENT-FOLLOWUPS): `requireScreenshot: true` makes verify write PNG screenshots of the real render to `BUILDBEAT_SCREENSHOT_DIR`, records them as candidate-bound evidence after checking each decodes, fails a verify that leaves none, requires them in the merge check and lists them for the reviewer, the decision card and notifications; `buildbeat release` runs the project's read-only readback after a merged release and records it in `delivery/work/<ID>/releases.jsonl`, and `decide --action close` closes the window only on a passing readback; a one-page guide states what people and tools without the runtime may read and write; the governance-template rationale is corrected.
 
 - Focus the product on portable work context, the recoverable delivery loop, and evidence-backed human decisions.

package/SKILL.md

@@ -20,7 +20,7 @@ description: BuildBeat 用项目文件接续上下文，在隔离工作树内自
 
 | 用户意图 | 操作 |
 |---|---|
-| 接手、查看进度、有什么待批 | `buildbeat status --repo .`；指定 `--work` 或 `--run` 查看细节 |
+| 接手、查看进度、有什么待批 | `buildbeat status --repo .`；主仓的 run 配置中 `repo:` 指向其他仓时，查看全部代码仓加 `--all-repos`（运行时 4.1 起；可加 `--work`、`--json`）；单仓指定 `--work` 或 `--run` 查看细节 |
 | 准备一项工作 | 写 `delivery/work/<ID>/work.md`，包含目标、范围、验收、实施计划；复制 run-config 样板并填真实命令 |
 | 接受工作说明 | `buildbeat accept --repo . --work <ID> --by <owner>`；用户已有明确授权时直接记录，不重复问同一个决定 |
 | 开工、继续 | `buildbeat run --config <config>`；首次编号，已有运行则恢复；明确新一轮时加 `--new` |
@@ -54,10 +54,10 @@ description: BuildBeat 用项目文件接续上下文，在隔离工作树内自
 ```yaml
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
 # 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
-# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
 work: WORK-X
-# 家族名；--attempt new 自动编成 RUN-X-01/02…
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
 run: RUN-X
 # builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths:

package/docs/CAPABILITY-MATRIX.md

@@ -1,6 +1,6 @@
 # BuildBeat capability matrix / 能力矩阵
 
-Current release: 4.0.0. One product path: Skill → local runtime →
+Current release: 4.1.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;
@@ -15,7 +15,7 @@ may be written by hand.
 | 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 |
 | Efficiency | Verify cache, review range hints, parallel Work isolation | External test state must be isolated and stable |
-| Feedback | Unified status/cost/decisions, liveness, webhook/DingTalk | Notifications do not approve |
+| 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 |
 | Release closeout | `release` records the project's readback in the Work; `decide --action close` on a passing readback | No deployment; observation stays with project monitoring |
 | Maintenance | Check, history/replay, safe gc | Not a production monitoring service |

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.0.0` (release candidate awaiting publication; the dated verified distribution below remains current until its readback); latest independently verified BuildBeat npm distribution `@haiyangbg/buildbeat@3.3.1` (dist-tags `latest` and `next`; the owner moved `next` from `3.3.0` to `3.3.1` with npm 2FA on 2026-10-02), anchored by annotated tag `v3.3.1` at commit `cc7a6db`, workflow run [36982501415](https://github.com/HaiYangBG1/BuildBeat/actions/runs/36982501415), and 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.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/`.
 
 ## Channels and branches
 

package/docs/v2/guide/00-how-to-talk.en.md

@@ -13,3 +13,5 @@
 | Switch sessions | Save missing facts and retain active runtime files; continue from project records |
 
 The loop ends at the merge decision. Merge, push, deployment and publication each require their corresponding authorization.
+
+For a main repository with code repositories, inspect them together with `buildbeat status --repo . --all-repos`. See [Session handoff](11-session-handoff.en.md) for discovery, filters and settled counts.

package/docs/v2/guide/00-how-to-talk.md

@@ -13,3 +13,5 @@
 | 换会话 | 保存未落盘事实，保留活动运行现场；新会话按项目记录接续 |
 
 工作流默认停在合并决定。合并、推送、部署和发布分别需要对应授权。
+
+主仓有多个代码仓时，用 `buildbeat status --repo . --all-repos` 一起查看；发现范围、筛选与已了结计数见[跨会话接续](11-session-handoff.md)。

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

@@ -3,7 +3,7 @@
 Install the runtime: `npm install --global @haiyangbg/buildbeat@latest` (Node ≥ 20). Before upgrading from 3.x, finish or cancel runs still in progress with their original 3.x runtime, see [Migration](../../MIGRATION.md); never replace a runtime underneath an active run.
 
 1. Check Node ≥20, Git, Bash and an authenticated AI tool. Keep project-owned instructions.
-2. Install templates/v2/AGENTS.md and CLAUDE.md according to the tool's loading rules; copy runtime exclusions from gitignore.template.
+2. The templates ship with the npm package under `$(npm root -g)/@haiyangbg/buildbeat/templates/`. Install `v2/AGENTS.md` and `v2/CLAUDE.md` according to the tool's loading rules; copy runtime exclusions from `gitignore.template` (in `templates/`, not in `v2/`).
 3. Create delivery/work/WORK-X/work.md using the goal, scope, acceptance and implementation sections in work.example.md.
 4. Copy templates/v2/envelope/ to delivery/envelope/ and configure real tool and verification commands. New work needs no workflow.yaml copy.
 5. After the user accepts the work, use the commands below. Detach long runs from short host timeouts and handle the decision shown by status.
@@ -18,10 +18,10 @@ buildbeat status --repo . --work WORK-X
 ```yaml
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
 # 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
-# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
 work: WORK-X
-# 家族名；--attempt new 自动编成 RUN-X-01/02…
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
 run: RUN-X
 # builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths:
@@ -92,3 +92,5 @@ workers:
 [Migration](../../MIGRATION.md) · [Worker contract](05-worker-contract.en.md) · [Recovery](10-recovery.en.md)
 
 Before starting, commit work.md and worker scripts into the selected base so the isolated checkout sees the accepted scope. Acceptance records may be committed afterward.
+
+For a main repository with code repositories, use `buildbeat status --repo . --all-repos` for pending decisions and open work across repositories; add `--work <ID>` or `--json` as needed. See [Session handoff](11-session-handoff.en.md).

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

@@ -3,7 +3,7 @@
 安装运行时：`npm install --global @haiyangbg/buildbeat@latest`（Node ≥ 20）。从 3.x 升级前，先用原来的 3.x 运行时完成或取消仍在进行的 Run，见[迁移说明](../../MIGRATION.md)；不要在 Run 进行中替换运行时。
 
 1. 检查 Node ≥20、Git、Bash 和已鉴权的 AI 工具；保留项目自己的规范。
-2. 将 templates/v2/AGENTS.md、CLAUDE.md 按工具装载方式放入项目；复制 gitignore.template 的运行时排除项。
+2. 模板随 npm 包安装在 `$(npm root -g)/@haiyangbg/buildbeat/templates/`。将其中 `v2/AGENTS.md`、`v2/CLAUDE.md` 按工具装载方式放入项目；从 `gitignore.template`（在 `templates/` 下，不在 `v2/` 里）复制运行时排除项。
 3. 建 delivery/work/WORK-X/work.md，使用 work.example.md 的目标、范围、验收、实施计划结构。
 4. 把 templates/v2/envelope/ 复制为 delivery/envelope/；配置真实工具和验证命令。新工作不用复制 workflow.yaml。
 5. 用户接受工作说明后运行下面命令。长运行使用宿主支持的脱离方式启动；根据 status 的待决定对象处理例外。
@@ -18,10 +18,10 @@ buildbeat status --repo . --work WORK-X
 ```yaml
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
 # 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
-# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
 work: WORK-X
-# 家族名；--attempt new 自动编成 RUN-X-01/02…
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
 run: RUN-X
 # builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths:
@@ -92,3 +92,5 @@ workers:
 [Migration](../../MIGRATION.md) · [Worker contract](05-worker-contract.md) · [Recovery](10-recovery.md)
 
 启动前将 work.md 和 worker 脚本提交到所选 base，确保隔离工作树能读到同一份已确认范围；接受记录可以随后提交。
+
+主仓管理多个代码仓时，用 `buildbeat status --repo . --all-repos` 查看跨仓待批与未了结工作；可加 `--work <ID>` 或 `--json`。详见[跨会话接续](11-session-handoff.md)。

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

@@ -10,6 +10,6 @@ Use decide --action accept|dismiss --work ... --fingerprint ... for findings. Ex
 
 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.
 
-Merging and releasing stay human actions. After a release, run `buildbeat release --config <config> [--note <text>]`: it checks that the Work's succeeded candidate is contained in `--ref` (default: the current HEAD), runs the read-only readback command from the run config's `release:` section in the main checkout (same shape, environment allowlist and redaction as a worker), and appends the outcome, exit code, commit, output digest and a redacted tail to `delivery/work/<ID>/releases.jsonl`. Once the latest readback has passed, close the window with `decide --repo . --work <ID> --action close --result <text>`, which records a close-work decision bound to that readback; a failed readback cannot close it.
+Merging and releasing stay human actions. After a release, run `buildbeat release --config <config> [--note <text>]`: it checks that the Work's succeeded candidate is contained in `--ref` (default: the current HEAD), runs the read-only readback command from the run config's `release:` section in the main checkout (same shape, environment allowlist and redaction as a worker), and appends the outcome, exit code, commit, output digest and a redacted tail to `delivery/work/<ID>/releases.jsonl`. Once the latest readback has passed, close the window with `decide --repo . --work <ID> --action close --result <text>`, which records a close-work decision bound to that readback; a failed readback cannot close it. A Work whose run configs have no `release:` section ends at the merge, and status says nothing is left to do.
 
 Notifications report waiting, termination and stalls; they do not accept approvals. Webhook/DingTalk URLs come only from environment variables, and delivery failure does not affect the run. The watcher is an internal feedback mechanism.

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

@@ -10,6 +10,6 @@ status 的决定卡包含 transition、候选、计划摘要、证据、原因
 
 正常修复自动继续；重复问题、阻断数增加、环境故障或预算耗尽才形成例外决定。预算批准一次放行对应修复、重验和再审；扩额记录可以重放，驾驶会话不能自行冒充用户批准。
 
-合并和上线仍由人完成。上线后运行 `buildbeat release --config <config> [--note <text>]`：它确认该 Work 已成功 Run 的候选包含在 `--ref`（默认当前 HEAD）中，在主检出执行 run-config `release:` 段配置的只读回读命令（形状、环境白名单与脱敏同 worker），把结果、退出码、提交、输出摘要和末尾若干行追加到 `delivery/work/<ID>/releases.jsonl`。最近一次回读通过后，用 `decide --repo . --work <ID> --action close --result <text>` 关窗，写入绑定该回读的 close-work 决定；回读失败时不能关窗。
+合并和上线仍由人完成。上线后运行 `buildbeat release --config <config> [--note <text>]`：它确认该 Work 已成功 Run 的候选包含在 `--ref`（默认当前 HEAD）中，在主检出执行 run-config `release:` 段配置的只读回读命令（形状、环境白名单与脱敏同 worker），把结果、退出码、提交、输出摘要和末尾若干行追加到 `delivery/work/<ID>/releases.jsonl`。最近一次回读通过后，用 `decide --repo . --work <ID> --action close --result <text>` 关窗，写入绑定该回读的 close-work 决定；回读失败时不能关窗。run 配置都没有 `release:` 段的 Work 到合并为止，status 提示没有剩余必做步骤。
 
 通知只报告待批、结束或疑似卡顿，不能接收审批；webhook/钉钉 URL 仅从环境变量读取，发送失败不影响 Run。看门进程是运行反馈的内部实现。

package/docs/v2/guide/11-session-handoff.en.md

@@ -6,6 +6,12 @@ Before closing a session, save the goal, decisions, unverified scope and next st
 
 A new session reads AGENTS.md, work.md (or legacy intent/plan), decisions and status. Verify available facts and reuse still-valid authorization. A new conversation is not permission to start a duplicate run.
 
+For a main repository managing several code repositories, start with `buildbeat status --repo . --all-repos`. This reads the main checkout, targets named by `repo:` in its `delivery/work/` run configurations, and immediate child Git checkouts containing `delivery/work/`. Discovery deduplicates real paths and never recurses. Missing or invalid targets and unreadable configurations produce warnings without hiding other repositories.
+
+Pending decisions come first, followed by open work grouped by repository. CLOSED, CANCELLED and merged work whose configuration has no `release:` are counted only. Merged work with `release:` remains visible until closed. `--json` returns `{repos: [{repo, works, settled}], pending, warnings}` including settled work. `--work <ID>` filters the merged results; `--run` cannot be combined with `--all-repos`.
+
+When a configured target has the matching work directory or a runtime ledger, its state, findings and decisions are authoritative and the work appears only under that repository. Suggested commands retain the main repository's configuration and use paths relative to the caller; fill in person/reason placeholders before executing. Work without target records remains under the main repository with its runtime target shown. Single-repository `status` also reads this one level of target state, preventing duplicate-start suggestions.
+
 Changing tools requires command, authentication and output-contract configuration. Records remain reusable; execution capability needs validation. Handoffs between people require candidate, records, access and a named next owner/action.
 
 Git transfers long-lived facts between machines. Active processes, runtime files, worktrees and host resources do not migrate with clone. Inspect the original environment before choosing how to continue.

package/docs/v2/guide/11-session-handoff.md

@@ -6,6 +6,12 @@
 
 新会话读取项目 AGENTS.md、Work 的 work.md（或旧 intent/plan）、决定与 status。能从记录查到的事实自行核对，沿用仍有效的授权；不把开新会话等同于重开 Run。
 
+主仓管理多个代码仓时，先运行 `buildbeat status --repo . --all-repos`。它只读查看主仓、主仓 `delivery/work/` 下 run 配置的 `repo:` 目标仓，以及主仓下一层含 `delivery/work/` 的 Git 仓，按真实路径去重，不递归。不存在或无效的目标、读不了的配置会给出警告，其余仓继续显示。
+
+待人决定先列出，随后按仓显示未了结工作；CLOSED、CANCELLED 和已合并且配置没有 `release:` 的工作只计数。已合并但配有 `release:`、尚未关窗的工作仍显示。`--json` 返回 `{repos: [{repo, works, settled}], pending, warnings}`，包含已了结工作；`--work <ID>` 筛选各仓合并后的这项工作，`--run` 不能与 `--all-repos` 同用。
+
+主仓配置指向的代码仓已有同名工作目录或运行台账时，状态、审查问题和决定取自代码仓，只在代码仓下显示；提示命令保留主仓配置，仓路径和配置路径相对当前目录，可填入人名、理由等占位内容后执行。目标仓还没有记录时，工作留在主仓并注明运行目标。不加 `--all-repos` 的主仓 `status` 也会读取这一层目标仓的真实状态，避免提示重复开跑。
+
 换工具时重新配置命令、鉴权和输出合同；接手事实可以复用，具体工具执行能力需要验证。换人时同步候选、记录和权限，说明当前推进人及下一步。
 
 换机器只能通过 Git 同步长期事实。活动进程、运行时文件、工作树和宿主资源不会随 clone 迁移，先核对原环境再选择接手方式。

package/example/delivery/work/WORK-EXPORT-DATE-FILTER/run-config.yaml

@@ -1,5 +1,5 @@
 # 简账 · WORK-EXPORT-DATE-FILTER 的 run 配置。路径相对本文件解析。
-# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
 work: WORK-EXPORT-DATE-FILTER
 run: RUN-EXPORT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyangbg/buildbeat",
-  "version": "4.0.0",
+  "version": "4.1.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

@@ -45,10 +45,12 @@ import { applyGc, planGc } from "../runtime/gc.js";
 import {
   artifactStatus,
   computeOverview,
+  computeRepositoryOverview,
   readJsonl,
   renderOverview,
   runsFor,
 } from "../runtime/overview.js";
+import { pathLabel, shellArg } from "../runtime/overview-repos.js";
 import { closeWork, runReadback } from "../runtime/release.js";
 import {
   DEFAULT_STALL_AFTER_MS,
@@ -94,7 +96,7 @@ Usage:
   buildbeat --version
   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>] [--json]
+  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> --work <WORK-ID> --action accept|dismiss --fingerprint <fp> [--by <name>] [--note <text>]
   buildbeat release --config <run-config.yaml> [--ref <ref>] [--note <text>]
@@ -110,7 +112,7 @@ check --step executes that worker in the main checkout, outside the evidence led
 
 // Switches may stand alone (`--json`) or take an explicit true/false
 // (`--json true`, the older spelling); every other flag needs a value.
-const SWITCHES = new Set(["json", "apply", "force", "once", "new", "verify"]);
+const SWITCHES = new Set(["json", "apply", "force", "once", "new", "verify", "all-repos"]);
 
 function parseFlags(argv) {
   const flags = {};
@@ -971,6 +973,7 @@ function commandInbox(flags, rows = null) {
   );
   let lastWork = null;
   for (const row of sorted) {
+    const rowRepo = row.repo ?? repoRoot;
     if (row.corrupted) {
       console.log(
         `${row.run}: LEDGER CORRUPTED after seq=${row.corrupted.afterSeq} (${row.corrupted.reason})`,
@@ -981,7 +984,7 @@ function commandInbox(flags, rows = null) {
       console.log(`work ${row.work}:`);
       lastWork = row.work;
     }
-    const ledger = EventLedger.open(ledgerPathFor(repoRoot, row.run));
+    const ledger = EventLedger.open(ledgerPathFor(rowRepo, row.run));
     const requested = [...ledger.events]
       .reverse()
       .find((event) => event.type === "HUMAN_REQUESTED");
@@ -1004,10 +1007,10 @@ function commandInbox(flags, rows = null) {
       console.log(`    reason: ${reason}`);
     }
     for (const line of nextReply({
-      repoLabel: repoLabelFor(repoRoot, flags.repo),
+      repoLabel: row.repo ? shellArg(pathLabel(process.cwd(), rowRepo)) : repoLabelFor(repoRoot, flags.repo),
       state: ledger.state,
     })) {
-      console.log(`    next: ${line}`);
+      console.log(`    next: ${row.config ? line.replaceAll("--config <run-config.yaml>", `--config ${shellArg(pathLabel(process.cwd(), row.config))}`) : line}`);
     }
   }
 }
@@ -1257,7 +1260,7 @@ function commandDoctor(flags) {
     console.log(`notify: PROBLEM ${notifyError}`);
   } else if (!notify) {
     console.log(
-      `notify: none (${NOTIFY_CONFIG} absent; a waiting run reaches nobody until someone runs inbox)`,
+      `notify: none (${NOTIFY_CONFIG} absent; a waiting run reaches nobody until someone runs status)`,
     );
   } else {
     console.log("notify channels:");
@@ -1455,30 +1458,57 @@ function commandMetrics(flags) {
 function commandStatus(flags) {
   if (!flags.repo) throw new Error("status requires --repo");
   const repoRoot = resolve(flags.repo);
+  if (flags["all-repos"] === "true" && flags.run)
+    throw new Error("status: --all-repos cannot be used with --run; use --work instead");
   if (flags.run && flags.work)
     throw new Error("status: choose --run or --work");
   if (!flags.run) {
-    const rows = computeOverview(repoRoot, {
-      work: flags.work ?? null,
-      repoLabel: repoLabelFor(repoRoot, flags.repo),
-    });
-    const pending = pendingFor(repoRoot, flags.work);
-    if (flags.json === "true")
-      console.log(
-        JSON.stringify(
-          {
-            works: rows,
-            pending,
-            metrics: flags.work ? null : computeMetrics(repoRoot),
-          },
-          null,
-          2,
-        ),
-      );
-    else {
-      console.log(renderOverview(rows));
-      if (pending.length) commandInbox(flags, pending);
-      if (!flags.work) console.log(renderMetrics(computeMetrics(repoRoot)));
+    const allRepos = flags["all-repos"] === "true";
+    const result = computeRepositoryOverview(repoRoot, { work: flags.work ?? null, allRepos, localRepoLabel: repoLabelFor(repoRoot, flags.repo) });
+    const rows = result.repos.flatMap((group) => group.works);
+    if (flags.json === "true") {
+      console.log(JSON.stringify(allRepos ? result : {
+        works: rows.map((row) => {
+          if (row.repo !== result.repos[0].repo || row.targetRepo) return row;
+          const { config, hasRelease, repo, repoLabel, settled, ...local } = row;
+          return local;
+        }),
+        pending: result.pending.map((row) => {
+          if (row.repo !== result.repos[0].repo) return row;
+          const { repo, config, ...local } = row;
+          return local;
+        }),
+        metrics: flags.work ? null : computeMetrics(repoRoot),
+        ...(result.warnings.length ? { warnings: result.warnings } : {}),
+      }, null, 2));
+    } else {
+      for (const warning of result.warnings) console.log(`warning: ${warning}`);
+      if (allRepos) {
+        for (const group of result.repos) {
+          const pending = result.pending.filter((row) => row.repo === group.repo);
+          if (pending.length) {
+            console.log(`pending decisions · ${pathLabel(process.cwd(), group.repo)}`);
+            commandInbox(flags, pending);
+          }
+        }
+        for (const group of result.repos) {
+          const open = group.works.filter((row) => !row.settled);
+          if (open.length) {
+            console.log(`repo ${pathLabel(process.cwd(), group.repo)}:`);
+            console.log(renderOverview(open));
+          }
+        }
+        for (const group of result.repos) {
+          const count = group.settled;
+          console.log(`${pathLabel(process.cwd(), group.repo)}: settled ${count.total} (closed ${count.closed} · cancelled ${count.cancelled} · merged, no release step ${count.merged})`);
+        }
+      } else {
+        // Keep the single-repo surface while forwarding work facts and waits.
+        console.log(renderOverview(rows.map((row) => row.repo === result.repos[0].repo
+          ? { ...row, repo: undefined } : row)));
+        if (result.pending.length) commandInbox(flags, result.pending);
+        if (!flags.work) console.log(renderMetrics(computeMetrics(repoRoot)));
+      }
     }
     return;
   }

package/src/v2/runtime/overview-repos.js

@@ -0,0 +1,79 @@
+// Read-only repository/config discovery shared by single- and multi-repo status.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parseYamlSubset } from "../engine/yaml-subset.js";
+
+export const pathLabel = (cwd, path) => relative(cwd, path) || ".";
+export const shellArg = (value) => /^[a-zA-Z0-9_./:-]+$/.test(value)
+  ? value : `'${value.replaceAll("'", "'\\''")}'`;
+export const directory = (path) => {
+  try { return statSync(path).isDirectory(); } catch { return false; }
+};
+
+// Require an actual checkout root, not a directory inside a parent checkout.
+export function repositoryRoot(path, cache = new Map()) {
+  const real = realpathSync(path);
+  if (cache.has(real)) {
+    const cached = cache.get(real);
+    if (cached instanceof Error) throw cached;
+    return cached;
+  }
+  try {
+    const top = execFileSync("git", ["-C", real, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (realpathSync(top) !== real) throw new Error("not a git repository root");
+    cache.set(real, real);
+    return real;
+  } catch (error) {
+    cache.set(real, error);
+    throw error;
+  }
+}
+
+export function workConfigs(repoRoot, workId, warnings = []) {
+  const dir = join(repoRoot, "delivery", "work", workId);
+  if (!directory(dir)) return [];
+  return readdirSync(dir).sort().filter((name) => /^run-config.*\.ya?ml$/.test(name)).map((name) => {
+    const path = join(dir, name);
+    try {
+      const doc = parseYamlSubset(readFileSync(path, "utf8"));
+      if (typeof doc.repo !== "string" || !doc.repo.trim()) throw new Error("repo must be a non-empty path");
+      const target = resolve(dirname(path), doc.repo);
+      return { path, target, release: Object.hasOwn(doc, "release") };
+    } catch (error) {
+      warnings.push(`${path}: ${error.message.replaceAll("\n", " ")}`);
+      return { path, error: true, release: null };
+    }
+  });
+}
+
+export function configTargets(configs, warnings, roots = new Map()) {
+  return configs.map((config) => {
+    if (!config.target) return config;
+    try { return { ...config, repo: repositoryRoot(config.target, roots) }; }
+    catch (error) {
+      warnings.push(`${config.path}: ${config.target}: ${error.message.replaceAll("\n", " ")}`);
+      return { ...config, error: true };
+    }
+  });
+}
+
+export function discoverRepos(repoRoot, warnings, roots = new Map()) {
+  const repos = new Set([repoRoot]);
+  const workRoot = join(repoRoot, "delivery", "work");
+  if (directory(workRoot)) {
+    for (const id of readdirSync(workRoot).sort()) {
+      for (const config of configTargets(workConfigs(repoRoot, id, warnings), warnings, roots)) {
+        if (config.repo) repos.add(config.repo);
+      }
+    }
+  }
+  for (const name of readdirSync(repoRoot).sort()) {
+    const child = join(repoRoot, name);
+    if (!directory(join(child, "delivery", "work"))) continue;
+    try { repos.add(repositoryRoot(child, roots)); } catch { /* only discover git roots */ }
+  }
+  return [...repos];
+}

package/src/v2/runtime/overview.js

@@ -10,13 +10,16 @@
 
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { join } from "node:path";
+import { listInbox } from "./decisions.js";
+import { configTargets, directory, discoverRepos, pathLabel, shellArg, workConfigs } from "./overview-repos.js";
 
 import { EventLedger } from "../storage/event-ledger.js";
 import { latestAdjudications, readFindingsAccount } from "./findings.js";
 import { nextReply } from "./notify.js";
 import { readReleases } from "./release.js";
+import { describeLiveness } from "./liveness.js";
 import { computeWorkCost, renderWorkCost } from "./work-cost.js";
 
 function sha256File(path) {
@@ -64,27 +67,35 @@ export function artifactStatus(workDir, decisions, artifact) {
   };
 }
 
-function isAncestor(repoRoot, sha, ref) {
+function isAncestor(repoRoot, sha, ref, context) {
+  const key = JSON.stringify([repoRoot, sha, ref]);
+  if (context.ancestry.has(key)) return context.ancestry.get(key);
   try {
     execFileSync(
       "git",
       ["-C", repoRoot, "merge-base", "--is-ancestor", sha, ref],
       { stdio: "ignore" },
     );
+    context.ancestry.set(key, true);
     return true;
   } catch {
+    context.ancestry.set(key, false);
     return false;
   }
 }
 
-function headRef(repoRoot) {
+function headRef(repoRoot, context) {
+  if (context.heads.has(repoRoot)) return context.heads.get(repoRoot);
   try {
-    return execFileSync(
+    const ref = execFileSync(
       "git",
       ["-C", repoRoot, "rev-parse", "--abbrev-ref", "HEAD"],
       { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
     ).trim();
+    context.heads.set(repoRoot, ref);
+    return ref;
   } catch {
+    context.heads.set(repoRoot, "HEAD");
     return "HEAD";
   }
 }
@@ -154,30 +165,64 @@ export function runsFor(repoRoot, workId) {
   );
 }
 
+// Per status invocation: known local roots need no validation subprocess,
+// and forwarded works share repository facts with the later target scan.
+function overviewContext(repoRoot) {
+  return { roots: new Map([[realpathSync(repoRoot), realpathSync(repoRoot)]]), heads: new Map(), ancestry: new Map() };
+}
+
 export function computeOverview(
   repoRoot,
-  { work = null, repoLabel = "." } = {},
+  { work = null, repoLabel: defaultRepoLabel = ".", cwd = null, followTargets = true, warnings = [], configsOverride = null, context = overviewContext(repoRoot), skipWorks = new Set(), localCompatibility = false } = {},
 ) {
   const workRoot = join(repoRoot, "delivery", "work");
   const rows = [];
-  if (!existsSync(workRoot)) {
-    return rows;
+  const workIds = new Set(directory(workRoot) ? readdirSync(workRoot).filter((id) => directory(join(workRoot, id))) : []);
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  if (directory(runsDir)) {
+    for (const id of readdirSync(runsDir)) {
+      const file = join(runsDir, id, "events.jsonl");
+      if (!existsSync(file)) continue;
+      const run = EventLedger.open(file).state.run;
+      if (run?.work) workIds.add(run.work);
+    }
   }
-  const mainRef = headRef(repoRoot);
-  for (const workId of readdirSync(workRoot).sort()) {
-    if (work && workId !== work) {
+  const mainRef = headRef(repoRoot, context);
+  // Resolve once; do not spawn another Git process for each local work.
+  const currentRoot = realpathSync(repoRoot);
+  for (const workId of [...workIds].sort()) {
+    if ((work && workId !== work) || skipWorks.has(workId)) {
       continue;
     }
     const workDir = join(workRoot, workId);
-    if (
-      !existsSync(join(workDir, "work.md")) &&
-      !existsSync(join(workDir, "intent.md")) &&
-      !existsSync(join(workDir, "plan.md")) &&
-      !existsSync(join(workDir, "decisions.jsonl")) &&
-      !existsSync(join(workDir, "runs"))
-    ) {
-      continue;
+    const configs = configsOverride ?? workConfigs(repoRoot, workId, warnings);
+    const resolved = followTargets ? configTargets(configs, warnings, context.roots) : configs;
+    const owner = followTargets ? resolved.find((item) => item.repo && item.repo !== currentRoot &&
+      (directory(join(item.repo, "delivery", "work", workId)) || runsFor(item.repo, workId).length)) : null;
+    const usable = resolved.filter((item) => !item.error);
+    const selected = owner ?? usable[0] ?? resolved[0] ?? null;
+    const applicable = selected?.repo ? resolved.filter((item) => item.repo === selected.repo) : usable;
+    const local = localCompatibility && (!selected?.target || selected.repo === currentRoot);
+    const config = (local ? null : applicable.find((item) => item.release)) ?? selected;
+    if (owner) {
+      const targetRows = computeOverview(config.repo, {
+        work: workId, repoLabel: shellArg(pathLabel(cwd ?? process.cwd(), config.repo)),
+        cwd: cwd ?? process.cwd(), followTargets: false, warnings, configsOverride: applicable, context,
+      });
+      if (targetRows.length) {
+        rows.push({ ...targetRows[0], repo: config.repo, repoLabel: pathLabel(cwd ?? process.cwd(), config.repo) });
+        continue;
+      }
     }
+    // Cross-repo work still belongs here until the target has records.
+    // Its commands need a copyable owner path, not the legacy local label.
+    const repoLabel = followTargets && config?.target && config.repo !== currentRoot
+      ? shellArg(pathLabel(cwd ?? process.cwd(), repoRoot)) : defaultRepoLabel;
+    const pathFor = (item) =>
+      shellArg(cwd && !local ? pathLabel(cwd, item.path) : `delivery/work/${workId}/${item.path.split("/").at(-1)}`);
+    const configPath = config ? pathFor(config) : "<run-config.yaml>";
+    const runs = runsFor(repoRoot, workId);
+    if (!configs.length && !runs.length && !["work.md", "intent.md", "plan.md", "decisions.jsonl", "runs"].some((name) => existsSync(join(workDir, name)))) continue;
     const decisions = readJsonl(join(workDir, "decisions.jsonl"));
     const unified = existsSync(join(workDir, "work.md"));
     const intent = artifactStatus(
@@ -195,7 +240,6 @@ export function computeOverview(
         (row.severity === "P0" || row.severity === "P1") &&
         !adjudicated.has(row.fingerprint),
     ).length;
-    const runs = runsFor(repoRoot, workId);
     const live = runs.filter((run) => run.status !== "SUPERSEDED");
     const latest = live[live.length - 1] ?? null;
     // "Merged" is a fact about any candidate of the work, not only the
@@ -207,7 +251,7 @@ export function computeOverview(
         .reverse()
         .find(
           (run) =>
-            run.candidate && isAncestor(repoRoot, run.candidate, mainRef),
+            run.candidate && isAncestor(repoRoot, run.candidate, mainRef, context),
         ) ?? null;
     const merged = Boolean(mergedRun);
     const RELEASE_STEPS = ["preflight", "apply-readback", "observe"];
@@ -238,7 +282,10 @@ export function computeOverview(
           ? closure.subject.result
           : "see decisions.jsonl";
       next = `${stage.toLowerCase()} @ ${closure.ts ?? "?"}: ${result.slice(0, 160)}`;
-    } else if (!intent.exists) {
+    } else if (!intent.exists && (!latest || directory(workDir))) {
+      // A work directory without a work description stays NO_INTENT even
+      // when it has runs, as in 4.0.0; only a work known solely from
+      // runtime ledgers (no directory here) shows its run state.
       stage = "NO_INTENT";
       next = `write delivery/work/${workId}/work.md (goal, scope, acceptance, implementation plan)`;
     } else if (!latest) {
@@ -263,12 +310,9 @@ export function computeOverview(
         next = `buildbeat accept --repo ${repoLabel} --work ${workId} --artifact ${artifacts} --by <you>${plan.stale ? `   # ${unified ? "work.md" : "plan"} changed since acceptance` : ""}`;
       } else {
         stage = "READY_TO_RUN";
-        const configs = readdirSync(workDir).filter((name) =>
-          /^run-config.*\.ya?ml$/.test(name),
-        );
         next =
           configs.length > 0
-            ? `buildbeat run --config delivery/work/${workId}/${configs[0]}`
+            ? `buildbeat run --config ${configPath}`
             : `no run-config in delivery/work/${workId}: write one, or close it with a decisions.jsonl row {"transition":"close-work","decision":"closed","subject":{"result":"..."}} if it was doc-only`;
       }
     } else if (latest.status === "RUNNING") {
@@ -282,7 +326,7 @@ export function computeOverview(
       const replies = latest.state
         ? nextReply({ repoLabel, state: latest.state })
         : [];
-      next = replies[0] ?? `buildbeat inbox --repo ${repoLabel}`;
+      next = replies[0] ?? `buildbeat status --repo ${repoLabel} --work ${workId}`;
     } else if (latest.status === "SUCCEEDED" && isReleaseLane(latest)) {
       // A release-readback lane that reached wait-close and was approved is
       // a closed release window, not "nothing to merge".
@@ -291,19 +335,23 @@ export function computeOverview(
     } else if (merged) {
       stage = "MERGED";
       // After the merge: the person releases, the project's readback proves
-      // it, and the window closes on a passing readback.
-      const configs = readdirSync(workDir).filter((name) =>
-        /^run-config.*\.ya?ml$/.test(name),
-      );
-      const config = configs.length
-        ? `delivery/work/${workId}/${configs[0]}`
-        : "<run-config.yaml>";
+      // it, and the window closes on a passing readback. The readback lives
+      // in whichever run config has a release: section; when every config
+      // was read and none has one, `buildbeat release` could only fail, so
+      // the merge is the end of the work. Unreadable or absent configs keep
+      // the generic hint.
+      const releaseConfig = configs.find((item) => item.release) ?? null;
+      const releasePath = releaseConfig ? pathFor(releaseConfig) : configPath;
+      const noReleaseStep =
+        configs.length > 0 && !releaseConfig && !configs.some((item) => item.error);
       const close = `buildbeat decide --repo ${repoLabel} --work ${workId} --action close --result <what was released> --by <you>`;
       next = !readback
-        ? `candidate ${mergedRun.candidate.slice(0, 7)} (${mergedRun.id}) is on ${mainRef}; release it (a human action), then buildbeat release --config ${config}; then ${close}`
+        ? noReleaseStep
+          ? "merged; no release readback configured, nothing left to do (add a release: section to the run config to record a readback and close the window)"
+          : `candidate ${mergedRun.candidate.slice(0, 7)} (${mergedRun.id}) is on ${mainRef}; release it (a human action), then buildbeat release --config ${releasePath}; then ${close}`
         : readback.status === "passed"
           ? `readback passed @ ${readback.ts} (${readback.commit.slice(0, 7)}); close the window: ${close}`
-          : `latest readback failed @ ${readback.ts} (exit ${readback.exitCode}); fix the release, then buildbeat release --config ${config} again`;
+          : `latest readback failed @ ${readback.ts} (exit ${readback.exitCode}); fix the release, then buildbeat release --config ${releasePath} again`;
       if (latest.status !== "SUCCEEDED") {
         next += `   # latest run ${latest.id} ended ${latest.status} after the merge`;
       }
@@ -315,11 +363,13 @@ export function computeOverview(
     } else {
       stage = `STOPPED_${latest.status}`;
       next = plan.accepted
-        ? `decide: retry (buildbeat run --config <run-config.yaml> --new) or close the work`
+        ? `decide: retry (buildbeat run --config ${configPath} --new) or close the work`
         : `${unified ? "work.md" : "plan"} not accepted (${plan.exists ? "draft" : "missing"}); fix that before another run`;
     }
     rows.push({
       work: workId,
+      ...(config ? { config: config.path, hasRelease: configs.some((item) => item.release) ? true : configs.some((item) => item.error) ? null : false } : { hasRelease: false }),
+      ...(config?.target && (!config.repo || config.repo !== currentRoot) && followTargets ? { targetRepo: config.repo ?? config.target, targetLabel: pathLabel(cwd ?? process.cwd(), config.repo ?? config.target) } : {}),
       stage,
       intent,
       plan,
@@ -358,7 +408,7 @@ export function computeOverview(
             },
           }
         : {}),
-      next,
+      next: local ? next : next.replaceAll("--config <run-config.yaml>", `--config ${configPath}`),
     });
   }
   return rows;
@@ -381,6 +431,8 @@ export function renderOverview(rows) {
   const lines = [];
   for (const row of rows) {
     lines.push(`${row.work}  ${row.stage}`);
+    if (row.repo) lines.push(`  repo: ${row.repoLabel ?? row.repo}`);
+    if (row.targetRepo) lines.push(`  runs in: ${row.targetLabel ?? row.targetRepo}`);
     const parts =
       row.workArtifact === "work"
         ? [`work.md ${mark(row.plan)}`, `runs ${row.runs}`]
@@ -429,3 +481,54 @@ export function renderOverview(rows) {
   }
   return lines.join("\n");
 }
+
+// The main repo's configuration remains the command source; all state and
+// decisions come from the checkout that owns the work. Only the main repo's
+// pointers are followed, so targets cannot recursively expand this view.
+export function computeRepositoryOverview(repoRoot, { work = null, allRepos = false, cwd = process.cwd(), localRepoLabel = shellArg(pathLabel(cwd, repoRoot)) } = {}) {
+  repoRoot = realpathSync(repoRoot);
+  const context = overviewContext(repoRoot);
+  const warnings = [];
+  const roots = allRepos ? discoverRepos(repoRoot, warnings, context.roots) : [repoRoot];
+  const primary = computeOverview(repoRoot, { work, cwd, repoLabel: allRepos ? shellArg(pathLabel(cwd, repoRoot)) : localRepoLabel, warnings, context, localCompatibility: !allRepos });
+  const groups = new Map(roots.map((repo) => [repo, new Map()]));
+  for (const row of primary) {
+    const owner = row.repo ?? repoRoot;
+    if (!groups.has(owner)) groups.set(owner, new Map());
+    groups.get(owner).set(row.work, row);
+  }
+  if (allRepos) {
+    for (const root of roots.filter((root) => root !== repoRoot)) {
+      for (const row of computeOverview(root, { work, cwd, followTargets: false, warnings, context, skipWorks: new Set(groups.get(root).keys()), repoLabel: shellArg(pathLabel(cwd, root)) })) {
+        if (!groups.get(root).has(row.work)) groups.get(root).set(row.work, row);
+      }
+    }
+  }
+  const pending = [];
+  const repos = [];
+  for (const [repo, byWork] of groups) {
+    const works = [...byWork.values()].sort((a, b) => a.work.localeCompare(b.work)).map((row) => ({
+      ...row, repo, repoLabel: pathLabel(cwd, repo),
+      ...(row.targetRepo ? { targetLabel: pathLabel(cwd, row.targetRepo) } : {}),
+    }));
+    const settled = { total: 0, closed: 0, cancelled: 0, merged: 0 };
+    for (const row of works) {
+      if (allRepos && row.stage === "RUNNING" && row.latest?.source === "runtime") {
+        const ledger = EventLedger.open(join(repo, ".buildbeat", "runtime", "runs", row.latest.id, "events.jsonl"));
+        const live = describeLiveness({ repoRoot: repo, runId: row.latest.id, ledger });
+        if (live.inFlight?.stalled) row.stage = "STALLED";
+      }
+      const kind = row.stage === "CLOSED" ? "closed" : row.stage === "CANCELLED" ? "cancelled" : row.stage === "MERGED" && row.hasRelease === false ? "merged" : null;
+      row.settled = Boolean(kind);
+      if (kind) { settled[kind]++; settled.total++; }
+    }
+    repos.push({ repo, works, settled });
+    for (const row of listInbox(repo)) {
+      if (work && row.work !== work && !row.corrupted) continue;
+      if (!allRepos && repo !== repoRoot && !byWork.has(row.work) && !row.corrupted) continue;
+      if (repo === repoRoot && primary.some((item) => item.work === row.work && item.repo && item.repo !== repoRoot)) continue;
+      pending.push({ ...row, repo, ...(byWork.get(row.work)?.config ? { config: byWork.get(row.work).config } : {}) });
+    }
+  }
+  return { repos, pending, warnings: [...new Set(warnings)] };
+}

package/templates/v2/AGENTS.md

@@ -6,7 +6,8 @@ One Work owns one user-visible result. Continue safe authorized work to its
 acceptance condition; intermediate commits are progress, not completion.
 
 Use accept once the user has accepted the scope, run to execute/continue, status
-to inspect, decide for a real human decision, and check for diagnostics. Keep
+to inspect (add --all-repos in a main repository to include its code repositories),
+decide for a real human decision, and check for diagnostics. Keep
 candidate/evidence/approval binding, allowedPaths, read-only review, and failure
 budgets. Do not impersonate a human approval or silently weaken requirements.
 

package/templates/v2/run-config.example.yaml

@@ -1,9 +1,9 @@
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
 # 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
-# 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
+# 起跑前：buildbeat check --config <本文件>；起跑：buildbeat run --config <本文件>
 repo: ../../..
 work: WORK-X
-# 家族名；--attempt new 自动编成 RUN-X-01/02…
+# 家族名；run 自动编成 RUN-X-01/02…，--new 开新一轮
 run: RUN-X
 # builder / fixer 只能改这些目录；越界改动不成为候选
 allowedPaths: