@haiyangbg/buildbeat 3.0.1 → 3.2.0

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

@@ -1,16 +1,21 @@
 // Workspace manager per docs/v2/RFC-0002-domain-model.md: every Run works in
 // an isolated git worktree; the candidate is whatever git reads back, never
-// what a worker claims. Locks are mkdir-atomic. Run branches are never
-// deleted here — the pinned candidate must stay reachable for evidence.
+// what a worker claims. Locks are mkdir-atomic and record their owner, so a
+// lock whose owner process is provably gone can be reclaimed. Run branches
+// are never deleted here — the pinned candidate must stay reachable for
+// evidence.
 
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 
 export class WorkspaceError extends Error {
-  constructor(message) {
+  constructor(message, details = {}) {
     super(message);
     this.name = "WorkspaceError";
+    Object.assign(this, details);
   }
 }
 
@@ -29,37 +34,260 @@ function git(cwd, args) {
   }
 }
 
-export function acquireLock(repoRoot, runId) {
-  const lockDir = join(repoRoot, ".buildbeat", "runtime", "locks");
-  mkdirSync(lockDir, { recursive: true });
-  const lockPath = join(lockDir, `${runId}.lock`);
+// Lock ownership. A driver killed by SIGKILL, a host-tool timeout or a
+// reboot never reaches its finally block, so its locks outlive it. Real
+// incident: a killed driver left active-run.lock and <RUN>.lock behind;
+// resume answered "another run is active" and stop "already locked", and the
+// only way out was deleting runtime directories by hand.
+const OWNER_FILE = "owner.json";
+const CLAIM_SLOTS = 16;
+
+function lockPathFor(repoRoot, id) {
+  return join(repoRoot, ".buildbeat", "runtime", "locks", `${id}.lock`);
+}
+
+function pidAlive(pid) {
   try {
-    mkdirSync(lockPath);
+    process.kill(pid, 0);
+    return true;
   } catch (error) {
-    if (error.code === "EEXIST") {
-      throw new WorkspaceError(`run ${runId} is already locked (${lockPath})`);
+    // EPERM: the process exists but belongs to someone else.
+    return error.code === "EPERM";
+  }
+}
+
+function readOwner(lockPath) {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockPath, OWNER_FILE), "utf8"));
+    if (owner && Number.isInteger(owner.pid) && owner.pid > 0 && typeof owner.host === "string") {
+      return owner;
     }
+  } catch {
+    // missing or unreadable: no owner record
+  }
+  return null;
+}
+
+function sameOwner(a, b) {
+  return a.pid === b.pid && a.host === b.host && a.acquiredAt === b.acquiredAt;
+}
+
+export function describeLockOwner(owner) {
+  return `pid ${owner.pid} on ${owner.host}, acquired ${owner.acquiredAt}${owner.command ? `, command ${owner.command}` : ""}`;
+}
+
+// alive | dead | foreign-host | unknown. Only "dead" is ever reclaimed: a
+// foreign host cannot be probed, and a lock with no owner record may belong
+// to an older buildbeat that is still running.
+export function inspectLock(lockPath, { host = hostname(), isAlive = pidAlive } = {}) {
+  const owner = readOwner(lockPath);
+  if (!owner) {
+    return { state: "unknown", owner: null };
+  }
+  if (owner.host !== host) {
+    return { state: "foreign-host", owner };
+  }
+  return { state: isAlive(owner.pid) ? "alive" : "dead", owner };
+}
+
+function ownerRecord() {
+  return {
+    pid: process.pid,
+    host: hostname(),
+    acquiredAt: new Date().toISOString(),
+    command: process.argv[2] ?? null,
+  };
+}
+
+// Readers never see a half-written owner: write aside, then rename over.
+function writeOwner(lockPath) {
+  const temp = join(lockPath, `.${OWNER_FILE}.${process.pid}-${randomBytes(4).toString("hex")}`);
+  writeFileSync(temp, `${JSON.stringify(ownerRecord())}\n`);
+  renameSync(temp, join(lockPath, OWNER_FILE));
+}
+
+function takeLock(lockPath) {
+  mkdirSync(lockPath);
+  try {
+    writeOwner(lockPath);
+  } catch (error) {
+    rmSync(lockPath, { recursive: true, force: true });
     throw error;
   }
+}
+
+function ownerGeneration(owner) {
+  return createHash("sha256").update(`${owner.pid}|${owner.host}|${owner.acquiredAt}`).digest("hex").slice(0, 16);
+}
+
+// A claim is abandoned only when its claimer is provably gone (this host,
+// pid no longer exists). Never by age: a claimer paused by the scheduler or
+// SIGSTOP is still alive and may still finish (review of the second version).
+function claimAbandoned(claimPath, isAlive) {
+  try {
+    const claimer = JSON.parse(readFileSync(claimPath, "utf8"));
+    return claimer.host === hostname() && !isAlive(claimer.pid);
+  } catch {
+    return false;
+  }
+}
+
+// Creates the claim with its content already in place: the claimer is
+// written aside and hard-linked to the claim name, and link() fails if the
+// name exists. There is no instant in which a claim exists but is empty.
+function createClaim(lockPath, claimPath) {
+  const temp = join(lockPath, `.claim.${process.pid}-${randomBytes(4).toString("hex")}`);
+  writeFileSync(temp, JSON.stringify({ pid: process.pid, host: hostname() }));
+  try {
+    linkSync(temp, claimPath);
+  } finally {
+    unlinkSync(temp);
+  }
+}
+
+// Wins the right to take over a lock whose owner was judged dead, or
+// returns false. The lock directory never disappears during a takeover, so
+// a plain acquire always sees it held and cannot slip in between (the
+// review of the first version found exactly that window: renaming the lock
+// aside let a third process take a fresh one). Reclaimers race on a claim
+// file created by link() and named after the dead owner's generation:
+// exactly one wins per generation. A winner that died before finishing
+// leaves its claim behind; the next slot is tried once that claimer is
+// provably gone. After winning, the owner record is re-read: if it is no
+// longer the dead owner, nothing is taken over.
+export function reclaimStaleLock(lockPath, expectedOwner, { isAlive = pidAlive } = {}) {
+  const generation = ownerGeneration(expectedOwner);
+  for (let slot = 1; slot <= CLAIM_SLOTS; slot += 1) {
+    const claimPath = join(lockPath, `claim-${generation}-${slot}`);
+    try {
+      createClaim(lockPath, claimPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return false;
+      }
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      if (claimAbandoned(claimPath, isAlive)) {
+        continue;
+      }
+      return false;
+    }
+    const current = readOwner(lockPath);
+    return Boolean(current && sameOwner(current, expectedOwner));
+  }
+  return false;
+}
+
+function heldError(id, seen) {
+  const where = `.buildbeat/runtime/locks/${id}.lock`;
+  let detail;
+  if (seen.state === "alive") {
+    detail = `held by ${describeLockOwner(seen.owner)}; that process is still running: wait for it, or end it once you are sure it is stuck`;
+  } else if (seen.state === "dead") {
+    detail = `held by ${describeLockOwner(seen.owner)}, whose process is gone; another process is taking it over right now: retry in a moment`;
+  } else if (seen.state === "foreign-host") {
+    detail = `held by ${describeLockOwner(seen.owner)}, another host; release it there`;
+  } else {
+    detail = `no owner record in ${where} (a lock from an older buildbeat, or a crash while taking it); check that no buildbeat process is still running, then remove that directory`;
+  }
+  return new WorkspaceError(`run ${id} is already locked: ${detail}`, { lock: { id, ...seen, detail } });
+}
+
+export function acquireLock(repoRoot, runId) {
+  mkdirSync(join(repoRoot, ".buildbeat", "runtime", "locks"), { recursive: true });
+  const lockPath = lockPathFor(repoRoot, runId);
+  try {
+    takeLock(lockPath);
+    return lockPath;
+  } catch (error) {
+    if (error.code !== "EEXIST") {
+      throw error;
+    }
+  }
+  const seen = inspectLock(lockPath);
+  if (seen.state !== "dead" || !reclaimStaleLock(lockPath, seen.owner)) {
+    throw heldError(runId, seen.state === "dead" ? inspectLock(lockPath) : seen);
+  }
+  writeOwner(lockPath);
+  process.stderr.write(`reclaimed stale lock ${runId} (owner ${describeLockOwner(seen.owner)} is gone)\n`);
   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) {
-  const lockPath = join(repoRoot, ".buildbeat", "runtime", "locks", `${runId}.lock`);
-  rmSync(lockPath, { recursive: true, force: true });
+  rmSync(lockPathFor(repoRoot, runId), { recursive: true, force: true });
 }
 
 export function createWorkspace({ repoRoot, runId, base, branch, protectPush = 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

@@ -1,5 +1,5 @@
 # BuildBeat v2 run 配置样板。拷到 delivery/work/<WORK-ID>/run-config.yaml 后改 work / run / allowedPaths / workers。
-# 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射，无行内 [] / {}、无锚点、注释必须独占一行。
+# 路径相对本文件解析。严格 YAML 子集：只有块列表与块映射（列表项可与键同缩进），行内只允许空的 [] / {}，无锚点，注释必须独占一行。
 # 起跑前：buildbeat doctor --config <本文件>；起跑：buildbeat start --config <本文件> --attempt new
 repo: ../../..
 work: WORK-X
@@ -16,11 +16,15 @@ allowedPaths:
   - tests
 # P0/P1 finding 先过人分诊再派 fixer；不需要就删掉这行
 reviewTriage: required
+# 非只读步成功不扣次数；review 按轮计费。到顶的阻断 review 在 enter-fix 一次批准修复、重验、再审。
+# Run/Work 上限同时到顶只问一次；总 attempt 超过（配置值 + 人批扩额）的 3 倍前仍兜底停人。
 # 可省；run 配置 > 预设 > 默认。reviewRoundsPerWork 是跨本 Work 所有 Run 累计的 review 轮数上限（对应 intent 的止损线）
 budgets:
   maxAttempts:
     review: 2
   reviewRoundsPerWork: 6
+# 默认一个仓库同时只驱动一个 Run。确认本项目的测试不抢固定端口、不共用数据库后，
+# 可加 parallel: true，让本 Work 的 Run 与其他同样打开开关的 Work 并行（同一 Work 仍互斥）
 # 同树 + 同命令 + 同信封已通过就复用 verify 证据
 cache:
   verify: tree