@haiyangbg/buildbeat 2.0.0-beta.4 → 2.0.0

package/src/v2/runtime/overview.js

@@ -16,12 +16,13 @@ import { join } from "node:path";
 import { EventLedger } from "../storage/event-ledger.js";
 import { latestAdjudications, readFindingsAccount } from "./findings.js";
 import { nextReply } from "./notify.js";
+import { computeWorkCost, renderWorkCost } from "./work-cost.js";
 
 function sha256File(path) {
   return `sha256:${createHash("sha256").update(readFileSync(path, "utf8"), "utf8").digest("hex")}`;
 }
 
-function readJsonl(path) {
+export function readJsonl(path) {
   if (!existsSync(path)) {
     return [];
   }
@@ -38,7 +39,7 @@ function readJsonl(path) {
     .filter(Boolean);
 }
 
-function artifactStatus(workDir, decisions, artifact) {
+export function artifactStatus(workDir, decisions, artifact) {
   const path = join(workDir, `${artifact}.md`);
   if (!existsSync(path)) {
     return { exists: false, accepted: false, stale: false };
@@ -93,6 +94,8 @@ function runsFor(repoRoot, workId) {
         candidate: state.workspaces[state.run.id]?.candidate ?? null,
         createdAt: ledger.events[0]?.ts ?? null,
         lastAt: ledger.events[ledger.events.length - 1]?.ts ?? null,
+        workflow: state.run.workflowRef ?? null,
+        steps: Object.keys(state.steps),
         state,
         source: "runtime",
       });
@@ -118,6 +121,8 @@ function runsFor(repoRoot, workId) {
           candidate: record.workspaces?.[entry]?.candidate ?? null,
           createdAt: record.startedAt ?? null,
           lastAt: record.finishedAt ?? null,
+          workflow: record.workflow ?? null,
+          steps: Object.keys(record.attempts ?? {}),
           state: null,
           source: "run-record",
         });
@@ -156,14 +161,31 @@ export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {})
     const runs = runsFor(repoRoot, workId);
     const live = runs.filter((run) => run.status !== "SUPERSEDED");
     const latest = live[live.length - 1] ?? null;
-    let merged = false;
-    if (latest?.candidate) {
-      merged = isAncestor(repoRoot, latest.candidate, mainRef);
-    }
+    // "Merged" is a fact about any candidate of the work, not only the
+    // latest run's: a pilot's shipped candidate sat behind a CANCELLED run
+    // (its in-run review budget ran out and closure happened elsewhere) and
+    // overview reported the shipped work as STOPPED_CANCELLED.
+    const mergedRun =
+      [...runs].reverse().find((run) => run.candidate && isAncestor(repoRoot, run.candidate, mainRef)) ?? null;
+    const merged = Boolean(mergedRun);
+    const RELEASE_STEPS = ["preflight", "apply-readback", "observe"];
+    const isReleaseLane = (run) =>
+      Boolean(run) && (run.workflow === "release-readback" || run.steps.some((step) => RELEASE_STEPS.includes(step)));
+
+    // A Work is closed by an explicit row in decisions.jsonl:
+    //   {"transition":"close-work","decision":"closed"|"cancelled","subject":{"result":"..."}}
+    // A live run (RUNNING / WAITING_HUMAN) contradicts a closure and wins, so a
+    // stale close row can never hide something that still needs a human.
+    const closure = [...decisions].reverse().find((row) => row.transition === "close-work");
+    const liveRun = latest && (latest.status === "RUNNING" || latest.status === "WAITING_HUMAN");
 
     let stage;
     let next;
-    if (!intent.exists) {
+    if (closure && !liveRun) {
+      stage = closure.decision === "cancelled" ? "CANCELLED" : "CLOSED";
+      const result = typeof closure.subject?.result === "string" && closure.subject.result.length > 0 ? closure.subject.result : "see decisions.jsonl";
+      next = `${stage.toLowerCase()} @ ${closure.ts ?? "?"}: ${result.slice(0, 160)}`;
+    } else if (!intent.exists) {
       stage = "NO_INTENT";
       next = `write delivery/work/${workId}/intent.md (what and why), then plan.md`;
     } else if (!latest) {
@@ -181,7 +203,7 @@ export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {})
         next =
           configs.length > 0
             ? `buildbeat-v2 start --config delivery/work/${workId}/${configs[0]} --attempt new`
-            : `no run-config in delivery/work/${workId}: write one, or record the work as closed in decisions.jsonl if it was doc-only`;
+            : `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") {
       stage = "RUNNING";
@@ -190,16 +212,21 @@ export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {})
       stage = latest.pendingHuman?.kind === "final-decision" ? "MERGE_DECISION" : "WAITING_HUMAN";
       const replies = latest.state ? nextReply({ repoLabel, state: latest.state }) : [];
       next = replies[0] ?? `buildbeat-v2 inbox --repo ${repoLabel}`;
+    } 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".
+      stage = "RELEASED";
+      next = `release window closed by ${latest.id}; close the work with a decisions.jsonl row {"transition":"close-work","decision":"closed","subject":{"result":"released"}}`;
+    } else if (merged) {
+      stage = "MERGED";
+      next =
+        `candidate ${mergedRun.candidate.slice(0, 7)} (${mergedRun.id}) is on ${mainRef}; release/deploy stays a human action; then buildbeat-v2 gc --repo ${repoLabel}` +
+        (latest.status !== "SUCCEEDED" ? `   # latest run ${latest.id} ended ${latest.status} after the merge` : "");
     } else if (latest.status === "SUCCEEDED") {
-      if (merged) {
-        stage = "MERGED";
-        next = `release/deploy stays a human action; then buildbeat-v2 gc --repo ${repoLabel}`;
-      } else {
-        stage = "MERGE_READY";
-        next = latest.candidate
-          ? `merge ${latest.candidate.slice(0, 7)} (run/${latest.id}) into ${mainRef} — manual, then push`
-          : "run succeeded without a candidate; nothing to merge";
-      }
+      stage = "MERGE_READY";
+      next = latest.candidate
+        ? `merge ${latest.candidate.slice(0, 7)} (run/${latest.id}) into ${mainRef} — manual, then push`
+        : "run succeeded without a candidate; nothing to merge";
     } else {
       stage = `STOPPED_${latest.status}`;
       next = plan.accepted
@@ -214,10 +241,12 @@ export function computeOverview(repoRoot, { work = null, repoLabel = "." } = {})
       envFacts,
       openFindings,
       runs: runs.length,
+      cost: runs.length > 0 ? computeWorkCost(repoRoot, workId) : null,
       latest: latest
         ? { id: latest.id, status: latest.status, candidate: latest.candidate, at: latest.lastAt, source: latest.source, terminalReason: latest.terminal?.reason ?? null, waiting: latest.pendingHuman?.transition ?? null }
         : null,
       merged,
+      mergedCandidate: mergedRun?.candidate ?? null,
       next,
     });
   }
@@ -242,7 +271,8 @@ export function renderOverview(rows) {
   for (const row of rows) {
     lines.push(`${row.work}  ${row.stage}`);
     const parts = [`intent ${mark(row.intent)}`, `plan ${mark(row.plan)}`, `runs ${row.runs}`];
-    if (row.openFindings > 0) {
+    const settled = ["MERGED", "RELEASED", "CLOSED", "CANCELLED"].includes(row.stage);
+    if (row.openFindings > 0 && !settled) {
       // Unadjudicated, not necessarily unresolved: a fixer may have closed
       // them without anyone recording a verdict. The number says "nobody
       // ruled on these", which is exactly what a human should know.
@@ -252,8 +282,15 @@ export function renderOverview(rows) {
       parts.push("env-facts ✓");
     }
     lines.push(`  ${parts.join(" · ")}`);
+    if (row.cost) {
+      // What this work has already consumed across every run, superseded
+      // ones included: the number a "continue or cut" decision needs.
+      lines.push(`  cost: ${renderWorkCost(row.cost)}`);
+    }
     if (row.latest) {
-      const cand = row.latest.candidate ? ` candidate ${row.latest.candidate.slice(0, 7)}${row.merged ? " (merged)" : ""}` : "";
+      const cand = row.latest.candidate
+        ? ` candidate ${row.latest.candidate.slice(0, 7)}${row.latest.candidate === row.mergedCandidate ? " (merged)" : ""}`
+        : "";
       const wait = row.latest.waiting ? ` waiting ${row.latest.waiting}` : "";
       const why = row.latest.terminalReason ? ` — ${row.latest.terminalReason.slice(0, 100)}` : "";
       lines.push(`  latest ${row.latest.id} ${row.latest.status}${cand}${wait} @ ${row.latest.at ?? "?"}${why}`);

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

@@ -9,6 +9,7 @@ import { join, relative } from "node:path";
 
 import { canonicalJson } from "../storage/event-ledger.js";
 import { normalizeRepoRef } from "./repo-ref.js";
+import { ledgerCost } from "./work-cost.js";
 
 const KERNEL = { kind: "kernel", id: "orchestrator" };
 
@@ -40,12 +41,14 @@ export function writeRunRecord({ repoRoot, ledger, ts }) {
   const record = {
     run: first.run,
     work: first.work,
+    workflow: state.run?.workflowRef ?? null,
     terminal: state.terminal,
     events: { from: first.seq, to: last.seq, lastDigest: last.digest },
     startedAt: first.ts,
     finishedAt: last.ts,
     attempts,
     budgets: state.budgets,
+    cost: ledgerCost(ledger),
     workspaces,
     evidence,
     decisions: state.decisions,

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

@@ -0,0 +1,147 @@
+// Work-level cost (iteration 09): what a work has already consumed across
+// every run of it, superseded ones included. Per-run budgets were bypassed
+// by "one run per review round" (a pilot work ran 21 runs and 9 review
+// rounds while the preset's two-round cap never fired), and a work that ate
+// ten runs and a day was cut by the owner as "cost > benefit" with no
+// number in front of them. Derived only: runtime ledgers first, run-records
+// for runs whose runtime was wiped. Nothing is written.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { readFindingsAccount } from "./findings.js";
+
+function emptyCost() {
+  return {
+    runs: 0,
+    reviewRounds: 0,
+    findings: 0,
+    humanWaits: 0,
+    infraFailures: 0,
+    workerMs: 0,
+    firstAt: null,
+    lastAt: null,
+  };
+}
+
+// Cost facts of one ledger: review rounds, human waits, infra failures and
+// worker wall time (STEP_STARTED → STEP_FINISHED per attempt).
+export function ledgerCost(ledger) {
+  const cost = { reviewRounds: 0, humanWaits: 0, infraFailures: 0, workerMs: 0 };
+  const open = new Map();
+  for (const event of ledger.events) {
+    if (event.type === "STEP_STARTED") {
+      open.set(`${event.data.step}#${event.data.attempt}`, Date.parse(event.ts));
+    } else if (event.type === "STEP_FINISHED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      const startedAt = open.get(key);
+      if (startedAt !== undefined) {
+        const ms = Date.parse(event.ts) - startedAt;
+        if (Number.isFinite(ms) && ms > 0) {
+          cost.workerMs += ms;
+        }
+        open.delete(key);
+      }
+      if (event.data.step === "review") {
+        cost.reviewRounds += 1;
+      }
+      if (event.data.infra === true) {
+        cost.infraFailures += 1;
+      }
+    } else if (event.type === "HUMAN_REQUESTED") {
+      cost.humanWaits += 1;
+    }
+  }
+  return cost;
+}
+
+export function computeWorkCost(repoRoot, workId, { excludeRun = null } = {}) {
+  const cost = emptyCost();
+  const seen = new Set();
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  if (existsSync(runsDir)) {
+    for (const entry of readdirSync(runsDir)) {
+      const path = join(runsDir, entry, "events.jsonl");
+      if (!existsSync(path)) {
+        continue;
+      }
+      const ledger = EventLedger.open(path);
+      const state = ledger.state;
+      if (ledger.corruption || !state.run || state.run.work !== workId) {
+        continue;
+      }
+      seen.add(state.run.id);
+      if (state.run.id === excludeRun) {
+        continue;
+      }
+      const row = ledgerCost(ledger);
+      cost.runs += 1;
+      cost.reviewRounds += row.reviewRounds;
+      cost.humanWaits += row.humanWaits;
+      cost.infraFailures += row.infraFailures;
+      cost.workerMs += row.workerMs;
+      track(cost, ledger.events[0]?.ts, ledger.events[ledger.events.length - 1]?.ts);
+    }
+  }
+  const recordsDir = join(repoRoot, "delivery", "work", workId, "runs");
+  if (existsSync(recordsDir)) {
+    for (const entry of readdirSync(recordsDir)) {
+      if (seen.has(entry) || entry === excludeRun) {
+        continue;
+      }
+      const path = join(recordsDir, entry, "run-record.json");
+      if (!existsSync(path)) {
+        continue;
+      }
+      let record;
+      try {
+        record = JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        continue;
+      }
+      cost.runs += 1;
+      // Records written before iteration 09 carry attempts and decisions
+      // only; the cost block is preferred when present.
+      cost.reviewRounds += record.cost?.reviewRounds ?? record.attempts?.review ?? 0;
+      cost.humanWaits += record.cost?.humanWaits ?? record.decisions?.length ?? 0;
+      cost.infraFailures += record.cost?.infraFailures ?? 0;
+      cost.workerMs += record.cost?.workerMs ?? 0;
+      track(cost, record.startedAt, record.finishedAt);
+    }
+  }
+  cost.findings = readFindingsAccount(repoRoot, workId).filter((row) => row.kind === "finding").length;
+  return cost;
+}
+
+function track(cost, firstAt, lastAt) {
+  if (firstAt && (!cost.firstAt || firstAt < cost.firstAt)) {
+    cost.firstAt = firstAt;
+  }
+  if (lastAt && (!cost.lastAt || lastAt > cost.lastAt)) {
+    cost.lastAt = lastAt;
+  }
+}
+
+export function formatWorkerMs(ms) {
+  if (!ms || ms < 1000) {
+    return "0s";
+  }
+  if (ms < 60000) {
+    return `${Math.round(ms / 1000)}s`;
+  }
+  const totalMinutes = Math.round(ms / 60000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  return hours > 0 ? `${hours}h${String(minutes).padStart(2, "0")}m` : `${minutes}m`;
+}
+
+export function renderWorkCost(cost) {
+  return [
+    `review rounds ${cost.reviewRounds}`,
+    `findings ${cost.findings}`,
+    `human waits ${cost.humanWaits}`,
+    ...(cost.infraFailures > 0 ? [`infra failures ${cost.infraFailures}`] : []),
+    `worker ${formatWorkerMs(cost.workerMs)}`,
+  ].join(" · ");
+}

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

@@ -4,7 +4,7 @@
 // deleted here — the pinned candidate must stay reachable for evidence.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 export class WorkspaceError extends Error {
@@ -44,6 +44,19 @@ export function acquireLock(repoRoot, runId) {
   return lockPath;
 }
 
+// Run ids currently holding a lock in this repository (the repository-wide
+// active-run marker excluded): who a blocked `start` is queued behind.
+export function listHeldRunLocks(repoRoot) {
+  const lockDir = join(repoRoot, ".buildbeat", "runtime", "locks");
+  if (!existsSync(lockDir)) {
+    return [];
+  }
+  return readdirSync(lockDir)
+    .filter((entry) => entry.endsWith(".lock") && entry !== "active-run.lock")
+    .map((entry) => entry.slice(0, -".lock".length))
+    .sort();
+}
+
 export function releaseLock(repoRoot, runId) {
   const lockPath = join(repoRoot, ".buildbeat", "runtime", "locks", `${runId}.lock`);
   rmSync(lockPath, { recursive: true, force: true });

package/templates/contracts/PROTOCOL.md

@@ -13,6 +13,10 @@
 <!-- buildbeat-multirepo-map:v1
 repo=<代码子仓1>|contract=contracts/PROTOCOL.md|deployment=<bus-baseline.json app 名或 n/a>
 -->
+<!-- map 行格式:repo=<子仓路径>|contract=<contracts/*.md 或 n/a>|deployment=<bus-baseline.json app 名或 n/a>[|changelog=<该仓内模块 CHANGELOG 路径>]
+     · changelog= 给多模块仓用(根下没有 CHANGELOG,由某个模块 CHANGELOG 承载契约版本);缺省 <repo>/CHANGELOG.md。
+     · contract=n/a 表示该仓没有契约版本域(如只读存量前端、npm 包 semver 与契约版本不同域),只登记不核对;不得拿它掩盖真实的契约关系。
+     · 被核对的 CHANGELOG 首个已发布 H2 须以契约快照版本开头,如 `## [v1.3 · Deployed 2026-09-05 · <sha> · <流水线>]`。 -->
 
 ---
 

package/templates/gitignore.template

@@ -14,6 +14,11 @@
 # verify-status 的「上次全绿」标记(本地实查产物,不入 git)
 .last-green-*
 
+# BuildBeat v2 运行时面与隔离工作树(可随时整删重建;不入 git)
+# 同时让 rg / 尊重 .gitignore 的工具不再走进旧工作树;vitest / jest 等要另配 exclude,见 docs/v2/guide/02-workflow-guide.md
+.buildbeat/runtime/
+.buildbeat/worktrees/
+
 # 代码子仓(各自独立 git,meta 仓不跟踪;按实际仓名替换)
 /<代码仓1>/
 /<代码仓2>/

package/templates/scripts/bus-check.sh

@@ -438,14 +438,18 @@ check_multirepo_drift() {
     multirepo_line="${multirepo_line%$'\r'}"
     [ -n "$multirepo_line" ] || continue
     if ! printf '%s\n' "$multirepo_line" \
-        | grep -Eq '^repo=[^|]+\|contract=[^|]+\|deployment=[^|]+$'; then
+        | grep -Eq '^repo=[^|]+\|contract=[^|]+\|deployment=[^|]+(\|changelog=[^|]+)?$'; then
       multirepo_map_invalid=1
       continue
     fi
-    IFS='|' read -r multirepo_repo_field multirepo_contract_field multirepo_deployment_field <<< "$multirepo_line"
+    IFS='|' read -r multirepo_repo_field multirepo_contract_field multirepo_deployment_field multirepo_changelog_field <<< "$multirepo_line"
     multirepo_repo="${multirepo_repo_field#repo=}"
     multirepo_contract="${multirepo_contract_field#contract=}"
     multirepo_deployment="${multirepo_deployment_field#deployment=}"
+    # 可选第 4 字段 changelog=<repo 内的 CHANGELOG 路径>:多模块仓没有根 CHANGELOG 时,
+    # 由 map 显式指定承载契约版本的模块 CHANGELOG;缺省仍为 <repo>/CHANGELOG.md。
+    multirepo_changelog_override="${multirepo_changelog_field#changelog=}"
+    [ -n "$multirepo_changelog_field" ] || multirepo_changelog_override=""
     multirepo_repo_trimmed="$(printf '%s' "$multirepo_repo" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
     multirepo_contract_trimmed="$(printf '%s' "$multirepo_contract" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
     multirepo_deployment_trimmed="$(printf '%s' "$multirepo_deployment" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')"
@@ -454,12 +458,23 @@ check_multirepo_drift() {
         || [ "$multirepo_deployment" != "$multirepo_deployment_trimmed" ] \
         || ! multirepo_repo_path_safe "$multirepo_repo" \
         || ! multirepo_map_value_safe "$multirepo_contract" 240 \
-        || ! printf '%s\n' "$multirepo_contract" | grep -Eq '^contracts/[^/].*\.md$' \
+        || ! { [ "$multirepo_contract" = "n/a" ] \
+          || printf '%s\n' "$multirepo_contract" | grep -Eq '^contracts/[^/].*\.md$'; } \
         || ! multirepo_map_value_safe "$multirepo_deployment" 100; then
       multirepo_map_invalid=1
       continue
     fi
-    printf '%s\t%s\t%s\n' "$multirepo_repo" "$multirepo_contract" "$multirepo_deployment" >> "$multirepo_records"
+    # contract=n/a 表示该仓没有契约版本域(如只读存量前端、npm 包 semver 与契约版本不同域),
+    # 只登记入 inventory、不做版本核对;不得用它掩盖真实存在的契约版本关系。
+    if [ -n "$multirepo_changelog_override" ]; then
+      if ! multirepo_repo_path_safe "$multirepo_changelog_override" \
+          || [ "${#multirepo_changelog_override}" -gt 240 ] \
+          || ! printf '%s\n' "$multirepo_changelog_override" | grep -Eq "^$(printf '%s' "$multirepo_repo" | sed 's/[.[\*^$]/\\&/g')/.+/CHANGELOG\.md$"; then
+        multirepo_map_invalid=1
+        continue
+      fi
+    fi
+    printf '%s\t%s\t%s\t%s\n' "$multirepo_repo" "$multirepo_contract" "$multirepo_deployment" "$multirepo_changelog_override" >> "$multirepo_records"
     printf '%s\n' "$multirepo_repo" >> "$multirepo_expected"
   done < "$multirepo_map_raw"
 
@@ -485,9 +500,9 @@ check_multirepo_drift() {
     add_finding "sync.unverified" "unverified" "Discovered repo=$multirepo_repo is absent from buildbeat-multirepo-map:v1." "$multirepo_repo"
   done < "$multirepo_discovered"
 
-  while IFS=$'\t' read -r multirepo_repo multirepo_contract multirepo_deployment; do
+  while IFS=$'\t' read -r multirepo_repo multirepo_contract multirepo_deployment multirepo_changelog_override; do
     [ -n "$multirepo_repo" ] || continue
-    multirepo_changelog="$multirepo_repo/CHANGELOG.md"
+    multirepo_changelog="${multirepo_changelog_override:-$multirepo_repo/CHANGELOG.md}"
     multirepo_issue=0
     multirepo_drift=0
     multirepo_changelog_ok=0
@@ -544,6 +559,10 @@ check_multirepo_drift() {
         ;;
     esac
 
+    if [ "$multirepo_contract" = "n/a" ] && [ "$multirepo_deployment" = "n/a" ]; then
+      echo "  · $multirepo_repo 已登记,无契约/部署版本域(contract=n/a, deployment=n/a),不做版本核对"
+      continue
+    fi
     if [ -L "$multirepo_changelog" ] \
         || { [ -e "$multirepo_changelog" ] \
           && path_uses_symlink_component "$ROOT_PHYS/$multirepo_changelog"; }; then
@@ -557,8 +576,8 @@ check_multirepo_drift() {
         "the mapped CHANGELOG version source was not readable"
       multirepo_issue=1
     elif [ ! -f "$multirepo_changelog" ]; then
-      echo "  ⚠️  $multirepo_repo 缺少可读 regular CHANGELOG.md"
-      add_finding "sync.unverified" "unverified" "Repo=$multirepo_repo has no readable regular CHANGELOG.md version source." "$multirepo_changelog"
+      echo "  ⚠️  $multirepo_repo 缺少可读 regular $multirepo_changelog"
+      add_finding "sync.unverified" "unverified" "Repo=$multirepo_repo has no readable regular CHANGELOG version source: $multirepo_changelog." "$multirepo_changelog"
       multirepo_issue=1
     else
       multirepo_changelog_version="$(read_changelog_head_version "$multirepo_changelog" || true)"
@@ -572,8 +591,14 @@ check_multirepo_drift() {
     fi
 
     multirepo_contract_rc=0
-    validate_reference "$multirepo_contract" "$multirepo_map_path" || multirepo_contract_rc=$?
-    if [ "$multirepo_contract_rc" -ne 0 ]; then
+    if [ "$multirepo_contract" = "n/a" ]; then
+      multirepo_contract_rc=0
+    else
+      validate_reference "$multirepo_contract" "$multirepo_map_path" || multirepo_contract_rc=$?
+    fi
+    if [ "$multirepo_contract" = "n/a" ]; then
+      :
+    elif [ "$multirepo_contract_rc" -ne 0 ]; then
       echo "  ⚠️  $multirepo_repo 的契约版本来源不可读:$multirepo_contract"
       if [ "$multirepo_contract_rc" -eq 4 ]; then
         add_scan_boundary "symlink" "$multirepo_contract" \
@@ -672,9 +697,9 @@ check_multirepo_drift() {
       add_finding "sync.multirepo_drift" "conflict" "Version sources disagree for repo=$multirepo_repo: $multirepo_changelog=$multirepo_changelog_fact; $multirepo_contract=$multirepo_contract_fact; $multirepo_deployment_fact." "$multirepo_changelog"
     elif [ "$multirepo_issue" -eq 0 ]; then
       if [ "$multirepo_deployment" = "n/a" ]; then
-        echo "  ✅ $multirepo_repo 多仓版本一致: CHANGELOG.md ↔ $multirepo_contract (deployment=n/a)"
+        echo "  ✅ $multirepo_repo 多仓版本一致: $multirepo_changelog ↔ $multirepo_contract (deployment=n/a)"
       else
-        echo "  ✅ $multirepo_repo 多仓版本一致: CHANGELOG.md ↔ $multirepo_contract ↔ $multirepo_baseline#apps.$multirepo_deployment.imageTag"
+        echo "  ✅ $multirepo_repo 多仓版本一致: $multirepo_changelog ↔ $multirepo_contract ↔ $multirepo_baseline#apps.$multirepo_deployment.imageTag"
       fi
     fi
   done < "$multirepo_records"

package/templates/v2/AGENTS.md

@@ -7,14 +7,15 @@
 
 ## 0. v2 下工作怎么发生（一页流程）
 
-1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat-v2 accept`）前只是草稿、不产生义务。
+1. **工作项**：每件事一个 `delivery/work/<WORK-ID>/`（`intent.md` 为什么做 + **止损线**（最多几个 Run / 几轮 review / 几小时，越线先问所有者"继续还是砍"）+ `plan.md` 怎么做，可选 `env-facts.md` 记踩出来的环境事实）；被 digest 绑定接受（`buildbeat-v2 accept`）前只是草稿、不产生义务。`overview` 的 `cost:` 行就是止损线的读数。
 2. **代码工作跑 Run**：`buildbeat-v2 start --config <run-config.yaml> --attempt new` → 隔离 worktree 内 Build→Verify→Fix→Review 自动闭环 → **停在合并决定**。push、合并、部署永远是人批之后的人类动作。
 3. **人怎么知道该做什么**：`buildbeat-v2 overview --repo .` 回答「每件事走到哪、下一步该谁」；`inbox` 只列等人批的 Run，每条后面附可复制的下一句命令；`status --run <RUN>` 回答「还在动吗、动了多久、卡没卡」。
 4. **上线**：生产动作是人的；`release-readback` 预设 + `release` 风险预设把「做之前回读 → 人做 → 做之后回读 → 观察 → 人关窗」记成 L4 证据，任一步失败即停人批。
 5. **observe 盯生产**：`buildbeat-v2 observe run --config .buildbeat/observe.yaml` 一次=一轮只读体检；异常分层（落账→只读诊断→intent 草稿入队 `delivery/observe/intents/`），草稿**绝不自动执行**，人用 `observe triage` 分诊。
 6. **拍板台账**：平台级真实决策包一行进 `pm/decisions.md`；Run 级批准落各 Work 的 `decisions.jsonl`；finding 裁决落 `review-findings.jsonl`。契约在 `contracts/`。
 7. **通知**：`.buildbeat/notify.yaml` 配一条通道（URL 只能来自环境变量），Run 停在人批 / 终态 / 疑似卡住会来找人。
-8. **打扫**：终态 Run 留下的工作树用 `buildbeat-v2 gc --repo .` 清（默认只出计划）。
+8. **打扫**：终态 Run 留下的工作树用 `buildbeat-v2 gc --repo .` 清（默认只出计划）。工作树在仓内 `.buildbeat/worktrees/`：`.gitignore` 排除 `.buildbeat/runtime/` 与 `.buildbeat/worktrees/`，测试框架的收集范围也要排除 `**/.buildbeat/**`（vitest `exclude`、jest `testPathIgnorePatterns`、pytest `norecursedirs`），否则主干测试会把旧候选的用例一起跑。
+9. **worker 环境事实（写进 worker prompt / 信封）**：worker 的沙箱通常**不能监听端口**，需要起服务或绑定 loopback 的集成测试交给 verify 步，worker 只跑单测与静态检查，不要反复尝试；PATH 只认 POSIX 工具（`grep -E` 不用 `rg`，`find` 不用 `fd`）或在 `requires:` 里声明；verify / 包装脚本发现环境不满足（命令不在 PATH、端口被占、后端 404）就 `exit 75`，内核会当基础设施故障停人、不派 fixer、不扣预算。
 
 ## 1. 工作包路由 —— Builder 端到端负责，会话按 AI 视角隔离