@haiyangbg/buildbeat 4.0.0 → 4.2.0

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-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") {
@@ -280,9 +324,9 @@ 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 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: