@haiyangbg/buildbeat 3.1.0 → 3.2.0

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

@@ -142,20 +142,26 @@ function parseList(lines, start, indent) {
     }
     const first = childLines[0].content;
     const quotedScalar = first.startsWith('"') || first.startsWith("'");
-    const mapItem = !quotedScalar && MAP_ITEM.test(first);
-    if (childLines.length === 1 && !mapItem) {
-      // Real YAML reads "echo a: b" as a map; rather than guess, ask for quotes.
-      if (!quotedScalar && (first.includes(": ") || first.endsWith(":"))) {
-        throw new YamlSubsetError(
-          `list item ${JSON.stringify(first)} contains ": "; quote it (- ${JSON.stringify(first)}) or write it as key: value`,
-          line.lineNo,
-        );
+    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);
       }
-      result.push(parseScalar(first, childLines[0].lineNo));
-    } else if (mapItem) {
+      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;
   }

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).
 

package/src/v2/runtime/gc.js

@@ -19,7 +19,14 @@ import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 
 import { EventLedger } from "../storage/event-ledger.js";
-import { describeLockOwner, inspectLock, readback, reclaimStaleLock } 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) {
@@ -65,18 +72,25 @@ export function planGc(repoRoot) {
   const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
   const locksDir = join(repoRoot, ".buildbeat", "runtime", "locks");
   const rows = [];
-  // The repository-wide lock belongs to no run: reclaimable only when its
-  // owner process is provably gone (same host, pid no longer exists).
-  const activeLock = join(locksDir, "active-run.lock");
-  if (existsSync(activeLock)) {
-    const seen = inspectLock(activeLock);
-    const row = { run: "(repository)", status: "active-run lock", actions: [], keep: [] };
+  // 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: activeLock, owner: seen.owner });
+      row.actions.push({ kind: "remove-lock", path: lockPath, owner: seen.owner });
     } else if (seen.state === "unknown") {
-      row.keep.push("active-run lock has no owner record (older buildbeat?); remove it by hand once no buildbeat process is running");
+      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(`active-run lock held by ${describeLockOwner(seen.owner)}${seen.state === "foreign-host" ? " (another host)" : " (still running)"}`);
+      row.keep.push(`${name} lock held by ${describeLockOwner(seen.owner)}${seen.state === "foreign-host" ? " (another host)" : " (still running)"}`);
     }
     rows.push(row);
   }
@@ -178,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";

package/src/v2/runtime/orchestrator.js

@@ -21,9 +21,12 @@ import { EventLedger, canonicalJson } from "../storage/event-ledger.js";
 import {
   acquireLock,
   createWorkspace,
+  describeLockOwner,
   listChangedPaths,
+  liveParallelMarkers,
   readback,
   releaseLock,
+  withRepoGitLock,
 } from "../workspace/workspace-manager.js";
 import { writeRunRecord } from "./run-record.js";
 import { computeWorkCost } from "./work-cost.js";
@@ -52,8 +55,14 @@ function sha256(text) {
   return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
 }
 
-// MVP is single project, single active run: driving a run takes a
-// repository-wide lock in addition to the per-run lock.
+// By default one run drives a repository at a time: it holds the
+// repository-wide active-run lock for its whole drive. A run whose config
+// sets `parallel: true` instead holds a per-work lock and a marker, passing
+// the active-run lock only briefly as a gate, so runs of different works can
+// drive together while runs of the same work stay exclusive. Real incident:
+// a session waited 3h23m behind another work's run although worktrees were
+// already isolated; parallelism is opt-in because verifiers that bind fixed
+// ports or share a database would collide.
 const ACTIVE_LOCK = "active-run";
 
 function lockActive(repoRoot) {
@@ -70,17 +79,81 @@ function lockActive(repoRoot) {
   }
 }
 
-function withRunLocks(repoRoot, runId, fn) {
+function lockActiveWaiting(repoRoot, waitMs) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      acquireLock(repoRoot, ACTIVE_LOCK);
+      return;
+    } catch (error) {
+      if (!error.lock || Date.now() >= deadline) {
+        break;
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+  }
   lockActive(repoRoot);
+}
+
+function holdRunLock(repoRoot, runId, fn) {
+  acquireLock(repoRoot, runId);
   try {
-    acquireLock(repoRoot, runId);
+    return fn();
+  } finally {
+    releaseLock(repoRoot, runId);
+  }
+}
+
+function withRunLocks(repoRoot, runId, fn, { workId = null, parallel = false } = {}) {
+  if (!parallel) {
+    lockActive(repoRoot);
     try {
-      return fn();
+      const running = liveParallelMarkers(repoRoot);
+      if (running.length > 0) {
+        throw new OrchestratorError(
+          `another run is active in this repository (parallel run(s) ${running
+            .map((marker) => (marker.owner ? `${marker.run}, ${describeLockOwner(marker.owner)}` : marker.run))
+            .join("; ")}); this run is exclusive (set parallel: true in its run config to drive alongside other works)`,
+        );
+      }
+      return holdRunLock(repoRoot, runId, fn);
     } finally {
-      releaseLock(repoRoot, runId);
+      releaseLock(repoRoot, ACTIVE_LOCK);
+    }
+  }
+  if (!workId) {
+    throw new OrchestratorError("a parallel run needs its work id");
+  }
+  const workLock = `@work.${workId}`;
+  const marker = `@parallel.${runId}`;
+  try {
+    acquireLock(repoRoot, workLock);
+  } catch (error) {
+    const detail = error.lock?.detail;
+    throw new OrchestratorError(
+      `another run of ${workId} is active (runs of the same work never drive together)${detail ? `; ${detail}` : ""}`,
+    );
+  }
+  try {
+    // Gate: an exclusive run holds active-run for its whole drive, so a
+    // parallel run cannot slip in while it runs; the marker, created under
+    // the gate, is what an exclusive run checks before it starts. Another
+    // parallel run holds the gate for milliseconds, so a busy gate is waited
+    // for briefly before it is reported (two parallel starts at the same
+    // instant must both get through).
+    lockActiveWaiting(repoRoot, 2000);
+    try {
+      acquireLock(repoRoot, marker);
+    } finally {
+      releaseLock(repoRoot, ACTIVE_LOCK);
+    }
+    try {
+      return holdRunLock(repoRoot, runId, fn);
+    } finally {
+      releaseLock(repoRoot, marker);
     }
   } finally {
-    releaseLock(repoRoot, ACTIVE_LOCK);
+    releaseLock(repoRoot, workLock);
   }
 }
 
@@ -926,7 +999,7 @@ export function startRun(options) {
   }
 
   return withRunLocks(repoRoot, runId, () => {
-    const workspace = createWorkspace({ repoRoot, runId, base });
+    const workspace = withRepoGitLock(repoRoot, () => createWorkspace({ repoRoot, runId, base }));
     const context = makeContext(options, ledger, workspace);
     const now = context.now;
     const supersession =
@@ -974,7 +1047,7 @@ export function startRun(options) {
       superseded: supersession.superseded,
       supersedeSkipped: supersession.skipped,
     };
-  });
+  }, { workId, parallel: options.parallel === true });
 }
 
 function resumeStepFromTransition(transition) {
@@ -1038,7 +1111,9 @@ export function resumeRun(options) {
   // decided again on a ledger read under the locks: another session may
   // have approved, resumed or stopped the run in between, and writing
   // through the earlier read would fork the hash chain.
-  const outside = resumeTarget(options, openLedgerFor(repoRoot, runId));
+  const outer = openLedgerFor(repoRoot, runId);
+  const outerLedger = outer.ledger;
+  const outside = resumeTarget(options, outer);
   if (outside.early) {
     return outside.early;
   }
@@ -1216,5 +1291,5 @@ export function resumeRun(options) {
       drive(context, startStep);
     }
     return { runId, ledgerPath, state: ledger.state, resumed: true, reason: null };
-  });
+  }, { workId: outerLedger.state.run.work, parallel: options.parallel === true });
 }

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

@@ -214,19 +214,78 @@ 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.
+// Locks that belong to no single run: the repository-wide active-run lock,
+// and names starting with "@" (per-work, parallel-run marker, repo-git),
+// which no run id can contain.
+export function isRunLockName(name) {
+  return name !== "active-run" && !name.startsWith("@");
+}
+
+// Run ids currently holding a lock in this repository: 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")
+    .filter((entry) => entry.endsWith(".lock"))
     .map((entry) => entry.slice(0, -".lock".length))
+    .filter(isRunLockName)
     .sort();
 }
 
+// Parallel-run markers (@parallel.<RUN>) whose owner is alive or cannot be
+// judged; markers of dead owners are reclaimed on the way and not returned.
+export function liveParallelMarkers(repoRoot) {
+  const lockDir = join(repoRoot, ".buildbeat", "runtime", "locks");
+  if (!existsSync(lockDir)) {
+    return [];
+  }
+  const live = [];
+  for (const entry of readdirSync(lockDir).sort()) {
+    if (!entry.startsWith("@parallel.") || !entry.endsWith(".lock")) {
+      continue;
+    }
+    const lockPath = join(lockDir, entry);
+    const seen = inspectLock(lockPath);
+    if (seen.state === "dead" && reclaimStaleLock(lockPath, seen.owner)) {
+      rmSync(lockPath, { recursive: true, force: true });
+      continue;
+    }
+    live.push({ run: entry.slice("@parallel.".length, -".lock".length), ...seen });
+  }
+  return live;
+}
+
+function pause(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Writes to the repository's shared git state (worktree add/remove, branch
+// create/delete, .git/config) are serialised: with parallel runs two drivers
+// could otherwise race on .git/config.lock or index.lock. Held for
+// milliseconds, so a busy lock is waited for (bounded), not reported.
+export function withRepoGitLock(repoRoot, fn, { waitMs = 10_000 } = {}) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    try {
+      acquireLock(repoRoot, "@repo-git");
+      break;
+    } catch (error) {
+      if (!error.lock || Date.now() >= deadline) {
+        throw error;
+      }
+      pause(100);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    releaseLock(repoRoot, "@repo-git");
+  }
+}
+
 export function releaseLock(repoRoot, runId) {
   rmSync(lockPathFor(repoRoot, runId), { recursive: true, force: true });
 }

package/templates/v2/CLAUDE.md

@@ -3,5 +3,5 @@
 本工作区的会话路由、协作规则、红线,**单点在同目录的 [`AGENTS.md`](AGENTS.md)** —— 请立即读取那份。
 
 > 本文件只为兼容「只认 `CLAUDE.md` 这个文件名的工具」而存在,**永远保持这几行**。
-> 往这里复制任何规则 = 两份文档必然漂移(上游 `lessons.md` 第 1 条:SSOT 腐烂)。
+> 往这里复制任何规则 = 两份文档必然漂移(上游 `lessons.md`「SSOT 腐烂)。
 > 也不要改成符号链接:Windows 上 git 默认 `core.symlinks=false`,clone 出来会静默退化成一个内容是路径字符串的普通文件,装载即失效。

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

@@ -23,6 +23,8 @@ budgets:
   maxAttempts:
     review: 2
   reviewRoundsPerWork: 6
+# 默认一个仓库同时只驱动一个 Run。确认本项目的测试不抢固定端口、不共用数据库后，
+# 可加 parallel: true，让本 Work 的 Run 与其他同样打开开关的 Work 并行（同一 Work 仍互斥）
 # 同树 + 同命令 + 同信封已通过就复用 verify 证据
 cache:
   verify: tree