@haiyangbg/buildbeat 3.0.1 → 3.2.0

package/src/v2/cli/run.js

@@ -11,7 +11,7 @@
 
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -52,6 +52,7 @@ import { resumeRun, startRun } from "../runtime/orchestrator.js";
 import { toRepoRef } from "../runtime/repo-ref.js";
 import { EventLedger } from "../storage/event-ledger.js";
 import { acquireLock, listHeldRunLocks, releaseLock } from "../workspace/workspace-manager.js";
+import { checkRunConfigAgainstWorkflow, checkRunConfigShape, RunConfigError } from "./run-config-check.js";
 
 const KERNEL = { kind: "kernel", id: "cli" };
 
@@ -60,7 +61,7 @@ const USAGE = `BuildBeat runtime
 Usage:
   buildbeat --version
   buildbeat start --config <run-config.yaml> [--attempt new]
-  buildbeat resume --config <run-config.yaml> [--adopt <sha> --by <name>]   # --adopt: hand fix committed in the worktree; skip fix, resume at verify
+  buildbeat resume --config <run-config.yaml> [--run <RUN-ID>] [--adopt <sha> --by <name>]   # --adopt: hand fix committed in the worktree; skip fix, resume at verify
   buildbeat status --repo <path> --run <RUN-ID> [--stall-after <minutes>]
   buildbeat inbox --repo <path>
   buildbeat overview --repo <path> [--work <WORK-ID>] [--json true]
@@ -256,11 +257,29 @@ function loadRunConfig(flags, command) {
   }
   const configPath = resolve(flags.config);
   const config = parseYamlSubset(readFileSync(configPath, "utf8"));
+  // Validate before anything runs and list every problem at once: the
+  // workflow does not depend on repo, so its checks run whenever it loads.
+  const problems = checkRunConfigShape(config);
   const configDir = dirname(configPath);
+  let workflow = null;
+  let workflowPath = null;
+  let workflowText = null;
+  if (typeof config?.workflow === "string" && config.workflow.trim() !== "") {
+    workflowPath = resolve(configDir, config.workflow);
+    try {
+      workflowText = readFileSync(workflowPath, "utf8");
+      workflow = loadWorkflow(workflowPath);
+    } catch (error) {
+      problems.push(`workflow: cannot load ${config.workflow}: ${error.message}`);
+    }
+  }
+  if (workflow) {
+    problems.push(...checkRunConfigAgainstWorkflow(config, workflow));
+  }
+  if (problems.length > 0) {
+    throw new RunConfigError(flags.config, problems);
+  }
   const repoRoot = resolve(configDir, config.repo);
-  const workflowPath = resolve(configDir, config.workflow);
-  const workflowText = readFileSync(workflowPath, "utf8");
-  const workflow = loadWorkflow(workflowPath);
   const workflowDigest = `sha256:${createHash("sha256").update(workflowText, "utf8").digest("hex")}`;
 
   const adapters = {};
@@ -387,6 +406,7 @@ function loadRunConfig(flags, command) {
     requires: config.requires ?? [],
     reviewTriage: config.reviewTriage === "required" ? "required" : null,
     supersede: config.supersede ?? "waiting",
+    parallel: config.parallel === true,
     stallAfterMs: config.stallAfterMs !== undefined ? Number(config.stallAfterMs) : DEFAULT_STALL_AFTER_MS,
     planDigest: digestOfWorkFile("plan.md"),
     intentDigest: digestOfWorkFile("intent.md"),
@@ -495,7 +515,9 @@ async function commandStart(flags) {
       const label = repoLabelFor(options.repoRoot);
       const holders = listHeldRunLocks(options.repoRoot);
       if (holders.length === 0) {
-        console.error("blocked by: a stale active-run lock with no run holding it (a killed process?); `gc` clears locks of terminal runs, or remove .buildbeat/runtime/locks/active-run.lock after checking no driver process is alive");
+        // A dead owner would already have been reclaimed; the error below
+        // names who holds the lock and what to do.
+        console.error("blocked by: the active-run lock alone (no run lock beside it); its owner is named below");
       }
       for (const holder of holders) {
         const ledgerPath = join(options.repoRoot, ".buildbeat", "runtime", "runs", holder, "events.jsonl");
@@ -510,7 +532,7 @@ async function commandStart(flags) {
         console.error(`blocked by ${holder}: ${summary}`);
         console.error(`  watch it: buildbeat status --repo ${label} --run ${holder}`);
       }
-      console.error("queue position: next after the holder(s) above stop or wait on a human (the repository allows one driving run at a time; worktrees are already isolated)");
+      console.error("queue position: next after the holder(s) above stop or wait on a human (by default one run drives a repository at a time; works whose run configs both set parallel: true can drive together)");
     }
     throw error;
   }
@@ -531,8 +553,42 @@ async function commandStart(flags) {
   await notifyForState(options.repoRoot, repoLabel, ledger.state);
 }
 
+// Resolve only from runtime ledgers. Reading candidates does not acquire
+// their locks; resumeRun still owns the lock and freshness checks.
+function resolveResumeRun(repoRoot, family, explicitRun) {
+  const pattern = new RegExp(`^${family.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-\\d{2,}$`);
+  if (explicitRun !== undefined) {
+    if (explicitRun !== family && !pattern.test(explicitRun)) {
+      throw new Error(`--run ${explicitRun} is not in run family ${family} of this config`);
+    }
+    if (!existsSync(ledgerPathFor(repoRoot, explicitRun))) {
+      throw new Error(`no ledger for run ${explicitRun}`);
+    }
+    return explicitRun;
+  }
+  if (existsSync(ledgerPathFor(repoRoot, family))) {
+    return family;
+  }
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const runs = (existsSync(runsDir) ? readdirSync(runsDir) : [])
+    .filter((id) => pattern.test(id) && existsSync(ledgerPathFor(repoRoot, id)))
+    .sort((a, b) => a.localeCompare(b, "en", { numeric: true }))
+    .map((id) => ({ id, state: EventLedger.open(ledgerPathFor(repoRoot, id)).state }));
+  const open = runs.filter(({ state }) => !state.terminal);
+  if (open.length === 1) {
+    console.log(`resuming ${open[0].id} (the open run of family ${family})`);
+    return open[0].id;
+  }
+  if (open.length === 0) {
+    const latest = runs.at(-1);
+    throw new Error(`no open run in family ${family}; ${latest ? `latest run ${latest.id}: ${latest.state.terminal.status}` : "no ledgers found"}; use --run <RUN-ID> to select an existing run explicitly`);
+  }
+  throw new Error(`multiple open runs in family ${family}: ${open.map(({ id }) => id).join(", ")}; use --run <RUN-ID> to select one`);
+}
+
 async function commandResume(flags) {
   const options = loadRunConfig(flags, "resume");
+  options.runId = resolveResumeRun(options.repoRoot, options.runId, flags.run);
   if (flags.adopt !== undefined) {
     const resumeAt = nextStep(options.workflow, "fix", "succeeded") ?? "verify";
     const adopted = adoptCandidate(options.repoRoot, options.runId, {
@@ -624,7 +680,7 @@ function commandApprove(flags) {
   if (result.terminal) {
     console.log("run is terminal: SUCCEEDED (merge itself stays a manual external action)");
   } else {
-    console.log("decision recorded; continue with: run.js resume --config <run-config.yaml>");
+    console.log(`decision recorded; continue with: buildbeat resume --config <run-config.yaml> --run ${flags.run}`);
   }
 }
 
@@ -774,6 +830,11 @@ function commandDoctor(flags) {
     console.log("environment contract: none declared (implicit PATH facts stay unchecked)");
   }
   console.log(`supersede: ${options.supersede} (new run for the same work ${options.supersede === "off" ? "leaves" : "supersedes"} older WAITING_HUMAN runs)`);
+  console.log(
+    options.parallel
+      ? "concurrency: parallel (runs of other works with parallel: true may drive at the same time; runs of this work stay exclusive; verifiers must not share fixed ports or databases)"
+      : "concurrency: exclusive (default: one driving run per repository; set parallel: true to drive alongside other works)",
+  );
   console.log(`stall threshold: ${formatMs(options.stallAfterMs)} without worker output`);
   const { config: notify, error: notifyError } = notifyConfigFor(options.repoRoot);
   if (notifyError) {
@@ -954,16 +1015,21 @@ function commandStop(flags) {
     throw new Error("stop requires --repo and --run");
   }
   const repoRoot = resolve(flags.repo);
-  const ledger = EventLedger.open(ledgerPathFor(repoRoot, flags.run));
-  if (!ledger.state.run) {
+  if (!existsSync(ledgerPathFor(repoRoot, flags.run))) {
     throw new Error(`no ledger for run ${flags.run}`);
   }
-  if (ledger.state.terminal) {
-    console.log(`run already terminal: ${ledger.state.terminal.status}`);
-    return;
-  }
+  // Read and decide under the run lock: a ledger read before it may be
+  // stale by the time RUN_TERMINAL is written.
   acquireLock(repoRoot, flags.run);
   try {
+    const ledger = EventLedger.open(ledgerPathFor(repoRoot, flags.run));
+    if (!ledger.state.run) {
+      throw new Error(`no ledger for run ${flags.run}`);
+    }
+    if (ledger.state.terminal) {
+      console.log(`run already terminal: ${ledger.state.terminal.status}`);
+      return;
+    }
     ledger.append({
       type: "RUN_TERMINAL",
       actor: KERNEL,
@@ -1008,7 +1074,7 @@ function commandGc(flags) {
       if (action.kind === "delete-branch") {
         return `delete branch ${action.branch} (${action.reason})`;
       }
-      return "remove stale lock";
+      return action.owner ? "remove active-run lock (owner process is gone)" : "remove stale lock";
     });
     actionable += row.actions.length;
     const keep = row.keep.map((reason) => `keep: ${reason}`);

package/src/v2/engine/reducer.js

@@ -114,6 +114,9 @@ export function applyEvent(state, event) {
         attempts: data.attempt,
         detail: null,
         infraAttempts: state.steps[data.step]?.infraAttempts ?? 0,
+        // Omit the new key for legacy events to preserve their exact state.
+        ...(state.steps[data.step]?.freeAttempts !== undefined
+          ? { freeAttempts: state.steps[data.step].freeAttempts } : {}),
       };
       next.currentStep = data.step;
       break;
@@ -132,6 +135,9 @@ export function applyEvent(state, event) {
         // output, exit 75) is not charged to the step's budget.
         next.steps[data.step].infraAttempts = (step.infraAttempts ?? 0) + 1;
       }
+      if (data.free === true) {
+        next.steps[data.step].freeAttempts = (step.freeAttempts ?? 0) + 1;
+      }
       next.currentStep = null;
       break;
     }

package/src/v2/engine/yaml-subset.js

@@ -1,8 +1,10 @@
 // Fail-closed strict YAML subset parser for BuildBeat v2 config files.
-// Supports exactly what the official presets need: nested maps, block lists,
-// and plain/quoted scalars with space indentation. Everything else — tabs,
-// anchors, aliases, tags, block/flow scalars, multi-document streams,
-// duplicate keys — is rejected with a line number, never guessed at.
+// Supports exactly what the official presets need: nested maps, block lists
+// (indented under their key or at the key's own indentation), the empty
+// inline [] and {}, and plain/quoted scalars with space indentation.
+// Everything else — tabs, anchors, aliases, tags, block/flow scalars,
+// non-empty inline collections, multi-document streams, duplicate keys — is
+// rejected with a line number and a way to rewrite it, never guessed at.
 
 export class YamlSubsetError extends Error {
   constructor(message, lineNo) {
@@ -13,6 +15,9 @@ export class YamlSubsetError extends Error {
 }
 
 const KEY_PATTERN = /^[A-Za-z0-9_.-]+$/;
+// A list item is a map only when it starts like one: a valid key, then ": "
+// or a colon at the end of the line.
+const MAP_ITEM = /^[A-Za-z0-9_.-]+:( |$)/;
 const FORBIDDEN_SCALAR_START = ["&", "*", "!", "|", ">", "{", "[", "%", "@", "`"];
 
 function parseScalar(raw, lineNo) {
@@ -37,6 +42,14 @@ function parseScalar(raw, lineNo) {
     }
     return inner;
   }
+  if (/^\[\s*\]$/.test(text)) return [];
+  if (/^\{\s*\}$/.test(text)) return {};
+  if (text[0] === "[" || text[0] === "{") {
+    throw new YamlSubsetError(
+      `inline lists/maps are not supported except [] and {}; write one "- item" per line (or "key: value" per line): ${text}`,
+      lineNo,
+    );
+  }
   if (FORBIDDEN_SCALAR_START.includes(text[0])) {
     throw new YamlSubsetError(`unsupported YAML syntax at: ${text}`, lineNo);
   }
@@ -46,6 +59,8 @@ function parseScalar(raw, lineNo) {
   if (text === "true") return true;
   if (text === "false") return false;
   if (text === "null" || text === "~") return null;
+  // Leading zeros are kept as written (007 would otherwise silently be 7).
+  if (/^-?0\d+$/.test(text)) return text;
   if (/^-?\d+$/.test(text)) return Number.parseInt(text, 10);
   if (/^-?\d+\.\d+$/.test(text)) return Number.parseFloat(text);
   return text;
@@ -127,12 +142,26 @@ function parseList(lines, start, indent) {
     }
     const first = childLines[0].content;
     const quotedScalar = first.startsWith('"') || first.startsWith("'");
-    if (childLines.length === 1 && (quotedScalar || !first.includes(":"))) {
-      result.push(parseScalar(first, childLines[0].lineNo));
-    } else if (!quotedScalar && first.includes(":")) {
+    if (childLines.length > 1) {
+      // Multi-line items keep the previous rule and messages unchanged.
+      if (!quotedScalar && first.includes(":")) {
+        result.push(parseMapFromLines(childLines, itemIndent));
+      } else {
+        throw new YamlSubsetError("unsupported list item shape", line.lineNo);
+      }
+      index = cursor;
+      continue;
+    }
+    if (!quotedScalar && MAP_ITEM.test(first)) {
       result.push(parseMapFromLines(childLines, itemIndent));
+    } else if (!quotedScalar && (first.includes(": ") || first.endsWith(":"))) {
+      // Real YAML reads "echo a: b" as a map; rather than guess, ask for quotes.
+      throw new YamlSubsetError(
+        `list item ${JSON.stringify(first)} contains ": "; quote it (- ${JSON.stringify(first)}) or write it as key: value`,
+        line.lineNo,
+      );
     } else {
-      throw new YamlSubsetError("unsupported list item shape", line.lineNo);
+      result.push(parseScalar(first, childLines[0].lineNo));
     }
     index = cursor;
   }
@@ -168,8 +197,19 @@ function parseMap(lines, start, indent) {
       continue;
     }
     const childStart = index + 1;
-    if (childStart >= lines.length || lines[childStart].indent <= indent) {
-      throw new YamlSubsetError(`key "${key}" has no value`, line.lineNo);
+    const child = lines[childStart];
+    // A list may sit at its key's own indentation ("key:" then "- a").
+    if (child && child.indent === indent && (child.content === "-" || child.content.startsWith("- "))) {
+      const parsed = parseList(lines, childStart, indent);
+      result[key] = parsed.value;
+      index = parsed.next;
+      continue;
+    }
+    if (!child || child.indent <= indent) {
+      throw new YamlSubsetError(
+        `key "${key}" has no value: give it a value, write ${key}: [] for an empty list, or indent its items under it`,
+        line.lineNo,
+      );
     }
     const parsed = parseNode(lines, childStart, lines[childStart].indent);
     result[key] = parsed.value;
@@ -179,7 +219,8 @@ function parseMap(lines, start, indent) {
 }
 
 export function parseYamlSubset(text) {
-  const lines = toLines(text);
+  // A byte-order mark (Windows editors) is not content.
+  const lines = toLines(text.replace(/^\uFEFF/, ""));
   if (lines.length === 0) {
     throw new YamlSubsetError("empty document");
   }

package/src/v2/presets/policies/ui-render-gate.yaml

@@ -1,4 +1,4 @@
-# Invariant 22 (v1 lessons #3, machine form): a UI delivery's spec approval
+# Invariant 22 (lessons.md「静态稿拍板 → 返工螺旋」, machine form): a UI delivery's spec approval
 # subject must include renderable proof — a screenshot with a digest —
 # before a human may stamp it. Static prose is not an approvable design.
 kind: policy

package/src/v2/runtime/decisions.js

@@ -2,7 +2,7 @@
 // An approval is recorded only after re-reading the workspace and confirming
 // the subject is still exactly what the request showed — if the candidate
 // moved or the tree is dirty, the request is refreshed instead of stamped
-// (lessons #18: no rubber-stamping a moved target). Every decision lands both
+// (lessons.md「读过期 race」: no rubber-stamping a moved target). Every decision lands both
 // as a DECISION_RECORDED event and as a line in the Git plane
 // (delivery/work/<work>/decisions.jsonl).
 
@@ -54,20 +54,22 @@ function recordDecisionFile(repoRoot, work, line) {
 }
 
 export function approveRun(repoRoot, runId, { by = "human", transition, ts, policies } = {}) {
-  const ledger = openWaiting(repoRoot, runId);
-  const pending = ledger.state.pendingHuman;
-  if (!transition) {
-    throw new DecisionError(
-      `an approval must name its transition explicitly (pending: ${pending.transition})`,
-    );
-  }
-  if (transition !== pending.transition) {
-    throw new DecisionError(
-      `transition mismatch: pending is ${pending.transition}, got ${transition}`,
-    );
-  }
+  // Read, check and write under the run lock: a ledger read before the
+  // lock may be stale by the time it is written to.
   acquireLock(repoRoot, runId);
   try {
+    const ledger = openWaiting(repoRoot, runId);
+    const pending = ledger.state.pendingHuman;
+    if (!transition) {
+      throw new DecisionError(
+        `an approval must name its transition explicitly (pending: ${pending.transition})`,
+      );
+    }
+    if (transition !== pending.transition) {
+      throw new DecisionError(
+        `transition mismatch: pending is ${pending.transition}, got ${transition}`,
+      );
+    }
     const bound = ledger.state.workspaces[runId];
     const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
     if (!bound || !existsSync(worktreePath)) {
@@ -194,19 +196,19 @@ export function approveRun(repoRoot, runId, { by = "human", transition, ts, poli
 // fixes). The commit must already be the worktree HEAD: git is read back,
 // the claim is not trusted.
 export function adoptCandidate(repoRoot, runId, { sha, by = "human", resumeAt, ts } = {}) {
-  if (!sha || typeof sha !== "string" || sha.length < 7) {
-    throw new DecisionError("adopt requires a commit sha (at least 7 characters)");
-  }
-  if (!resumeAt) {
-    throw new DecisionError("adopt requires the step to resume at (resumeAt)");
-  }
-  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");
-  }
   acquireLock(repoRoot, runId);
   try {
+    if (!sha || typeof sha !== "string" || sha.length < 7) {
+      throw new DecisionError("adopt requires a commit sha (at least 7 characters)");
+    }
+    if (!resumeAt) {
+      throw new DecisionError("adopt requires the step to resume at (resumeAt)");
+    }
+    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 bound = ledger.state.workspaces[runId];
     const worktreePath = bound ? resolveRepoRef(repoRoot, bound.worktreePath) : null;
     if (!bound || !existsSync(worktreePath)) {
@@ -293,15 +295,15 @@ export function acceptArtifact(repoRoot, workId, artifact, { by = "human", ts }
 }
 
 export function rejectRun(repoRoot, runId, { by = "human", transition, reason, ts } = {}) {
-  const ledger = openWaiting(repoRoot, runId);
-  const pending = ledger.state.pendingHuman;
-  if (transition && transition !== pending.transition) {
-    throw new DecisionError(
-      `transition mismatch: pending is ${pending.transition}, got ${transition}`,
-    );
-  }
   acquireLock(repoRoot, runId);
   try {
+    const ledger = openWaiting(repoRoot, runId);
+    const pending = ledger.state.pendingHuman;
+    if (transition && transition !== pending.transition) {
+      throw new DecisionError(
+        `transition mismatch: pending is ${pending.transition}, got ${transition}`,
+      );
+    }
     const when = ts ?? new Date().toISOString();
     const decisionRef = `D-${runId}-${ledger.state.decisions.length + 1}`;
     ledger.append({

package/src/v2/runtime/gc.js

@@ -1,5 +1,6 @@
 // Runtime garbage collection (iteration 08, C3): terminal runs leave a
-// worktree, a run/* branch and sometimes a lock behind. Sixteen of them had
+// worktree, a run/* branch and sometimes a lock behind (and a killed driver
+// an active-run lock whose owner is gone). Sixteen of them had
 // piled up in the deploy campaign before the owner asked for "打扫卫生".
 //
 // Rules (fail-closed toward keeping things):
@@ -18,7 +19,14 @@ import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 
 import { EventLedger } from "../storage/event-ledger.js";
-import { readback } from "../workspace/workspace-manager.js";
+import {
+  describeLockOwner,
+  inspectLock,
+  isRunLockName,
+  readback,
+  reclaimStaleLock,
+  withRepoGitLock,
+} from "../workspace/workspace-manager.js";
 import { resolveRepoRef } from "./repo-ref.js";
 
 function git(cwd, args) {
@@ -64,6 +72,28 @@ export function planGc(repoRoot) {
   const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
   const locksDir = join(repoRoot, ".buildbeat", "runtime", "locks");
   const rows = [];
+  // Locks that belong to no single run (active-run, and the @work /
+  // @parallel / @repo-git locks): reclaimable only when their owner process
+  // is provably gone (same host, pid no longer exists).
+  const sharedLocks = existsSync(locksDir)
+    ? readdirSync(locksDir)
+        .filter((entry) => entry.endsWith(".lock") && !isRunLockName(entry.slice(0, -".lock".length)))
+        .sort()
+    : [];
+  for (const entry of sharedLocks) {
+    const name = entry.slice(0, -".lock".length);
+    const lockPath = join(locksDir, entry);
+    const seen = inspectLock(lockPath);
+    const row = { run: "(repository)", status: `${name} lock`, actions: [], keep: [] };
+    if (seen.state === "dead") {
+      row.actions.push({ kind: "remove-lock", path: lockPath, owner: seen.owner });
+    } else if (seen.state === "unknown") {
+      row.keep.push(`${name} lock has no owner record (older buildbeat?); remove it by hand once no buildbeat process is running`);
+    } else {
+      row.keep.push(`${name} lock held by ${describeLockOwner(seen.owner)}${seen.state === "foreign-host" ? " (another host)" : " (still running)"}`);
+    }
+    rows.push(row);
+  }
   if (!existsSync(runsDir)) {
     return rows;
   }
@@ -145,7 +175,16 @@ export function applyGc(repoRoot, rows, { force = false } = {}) {
       const result = { run: row.run, ...action, done: false, error: null };
       results.push(result);
       try {
-        if (action.kind === "remove-lock") {
+        if (action.kind === "remove-lock" && action.owner) {
+          // Winning the takeover makes this process the only one entitled
+          // to the lock; only then is it removed.
+          if (reclaimStaleLock(action.path, action.owner)) {
+            rmSync(action.path, { recursive: true, force: true });
+            result.done = true;
+          } else {
+            result.error = "lock changed hands since the plan (or is being taken over); left in place";
+          }
+        } else if (action.kind === "remove-lock") {
           rmSync(action.path, { recursive: true, force: true });
           result.done = true;
         } else if (action.kind === "remove-worktree") {
@@ -153,24 +192,26 @@ export function applyGc(repoRoot, rows, { force = false } = {}) {
             result.error = "worktree dirty; rerun with --force true to discard";
             continue;
           }
-          if (action.registered) {
-            const args = ["worktree", "remove"];
-            if (force || action.dirty) {
-              args.push("--force");
+          withRepoGitLock(repoRoot, () => {
+            if (action.registered) {
+              const args = ["worktree", "remove"];
+              if (force || action.dirty) {
+                args.push("--force");
+              }
+              args.push(action.path);
+              git(repoRoot, args);
+            } else if (action.present) {
+              rmSync(action.path, { recursive: true, force: true });
             }
-            args.push(action.path);
-            git(repoRoot, args);
-          } else if (action.present) {
-            rmSync(action.path, { recursive: true, force: true });
-          }
-          try {
-            git(repoRoot, ["worktree", "prune"]);
-          } catch {
-            // prune is best-effort
-          }
+            try {
+              git(repoRoot, ["worktree", "prune"]);
+            } catch {
+              // prune is best-effort
+            }
+          });
           result.done = true;
         } else if (action.kind === "delete-branch") {
-          git(repoRoot, ["branch", "-D", action.branch]);
+          withRepoGitLock(repoRoot, () => git(repoRoot, ["branch", "-D", action.branch]));
           result.done = true;
         }
       } catch (error) {

package/src/v2/runtime/metrics.js

@@ -1,6 +1,7 @@
 // buildbeat metrics v0: local, read-only, derived entirely from run ledgers.
-// No collection, no upload (V2-PLAN §6 / lessons #8: without numbers you are
-// forever doing precise work on the wrong thing).
+// No collection, no upload (V2-PLAN §6; lessons.md「流程只管"怎么做对",不管
+// "做的是不是对的事"」: without numbers you are forever doing precise work on
+// the wrong thing).
 
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";