@bridge_gpt/mcp-server 0.2.38 → 0.2.41

package/build/executor/worktree-lock.js

@@ -0,0 +1,264 @@
+/**
+ * Worktree-level mutual exclusion for executor workers (BAPI-793).
+ *
+ * Two executor processes can legitimately hold two DIFFERENT `executor_jobs`
+ * rows for the same ticket at the same time — a watchdog re-fire racing a
+ * terminal retry, a repo-scoped executor picking up a sibling's work, a lease
+ * the server declared expired while its worker was still alive. Before this
+ * module nothing stopped both of them from spawning a `claude` worker into the
+ * SAME git worktree, so two independent agents edited, `git add`-ed, and
+ * committed in one working tree concurrently (observed 2026-08-14 on BAPI-785
+ * and BAPI-778: two live PIDs, two `session_id`s in one `.conductor/worker.log`).
+ *
+ * This is the LOCAL BACKSTOP for that. It is deliberately the least clever layer
+ * in the stack: a single file in the worktree, created with an exclusive
+ * `open(..., "wx")`, carrying the owning job's identity. Dispatch exclusion and
+ * claim serialization (the Python side) reduce how often two rows exist at all;
+ * this makes the overlap non-destructive even when they do — which is the only
+ * ordering that survives a reconciler bug.
+ *
+ * Four properties are load-bearing:
+ *
+ *  - ATOMIC ACQUISITION. `open(..., "wx")` either creates the file or fails with
+ *    `EEXIST`; there is no observable window between the two. An
+ *    exists-then-write sequence would reintroduce exactly the race this exists
+ *    to close.
+ *  - A DIFFERENT CLAIM TOKEN IS FOREIGN, EVEN AT THE SAME PID. Several executor
+ *    loops can run inside one host process, so PID equality proves nothing about
+ *    ownership. Only the claim token — minted server-side, opaque to the
+ *    executor (R14 rule 4) — identifies the holder.
+ *  - FAIL CLOSED. Malformed metadata, an unreadable lock, or an owner whose
+ *    liveness cannot be established all refuse the spawn. Refusing costs one
+ *    job attempt; guessing costs a corrupted working tree.
+ *  - RELEASE IS OWNERSHIP-CHECKED. `release()` re-reads the lock and removes it
+ *    only while its own claim token is still the one recorded, so a straggler's
+ *    `finally` can never delete the lock of the job that replaced it.
+ *
+ * No claim token, lock payload, or file content is ever logged or returned in a
+ * server-bound message; the token travels only inside the lock file and the
+ * in-process handle.
+ */
+import { open, readFile, rm, mkdir } from "node:fs/promises";
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The `.conductor` directory the lock lives in (shared with the worker log). */
+export const EXECUTOR_WORKTREE_LOCK_DIR = ".conductor";
+/** The fixed lock filename inside {@link EXECUTOR_WORKTREE_LOCK_DIR}. */
+export const EXECUTOR_WORKTREE_LOCK_FILE = "worker.lock";
+/** Lock metadata schema version; a foreign version fails closed. */
+export const EXECUTOR_WORKTREE_LOCK_VERSION = 1;
+/**
+ * Hard bound on the lock file we are willing to parse. A lock file is a few
+ * hundred bytes; anything larger is not our metadata, and parsing it would let
+ * an unrelated file at that path drive this module's behavior.
+ */
+const MAX_LOCK_FILE_CHARS = 4_096;
+/** How many times acquisition may recover a dead owner's lock and retry. */
+const MAX_ACQUIRE_ATTEMPTS = 3;
+/** Resolve `<worktree>/.conductor/worker.lock` with platform-correct separators. */
+export function buildExecutorWorktreeLockPath(worktreePath, platform = process.platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    return pathApi.join(worktreePath, EXECUTOR_WORKTREE_LOCK_DIR, EXECUTOR_WORKTREE_LOCK_FILE);
+}
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/** Real exclusive create with restrictive permissions where the OS honors them. */
+async function defaultWriteFileExclusive(filePath, data) {
+    const handle = await open(filePath, "wx", 0o600);
+    try {
+        await handle.writeFile(data, "utf-8");
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Real liveness probe. `process.kill(pid, 0)` signals nothing and only reports
+ * reachability. Only an explicit `ESRCH` proves the owner is gone: `EPERM` means
+ * the process exists but belongs to another user, and an unrecognized failure
+ * means we do not know — both are treated as ALIVE so an uncertain probe can
+ * never authorize entering an occupied worktree.
+ */
+function defaultIsProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return errorCode(err) !== "ESRCH";
+    }
+}
+/**
+ * Parse lock metadata, or `null` when it is not a lock record this version
+ * understands. Bounded before parsing, and every field is type-checked — a
+ * partially-written or foreign file must not be mistaken for a releasable lock.
+ */
+export function parseExecutorWorktreeLock(raw) {
+    if (typeof raw !== "string" || raw.length === 0 || raw.length > MAX_LOCK_FILE_CHARS) {
+        return null;
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    const { version, worktreePath, jobId, claimToken, executorId, ownerPid, acquiredAt, } = record;
+    if (version !== EXECUTOR_WORKTREE_LOCK_VERSION)
+        return null;
+    if (typeof worktreePath !== "string" || worktreePath.length === 0)
+        return null;
+    if (typeof jobId !== "number" || !Number.isInteger(jobId))
+        return null;
+    if (typeof claimToken !== "string" || claimToken.length === 0)
+        return null;
+    if (typeof executorId !== "string" || executorId.length === 0)
+        return null;
+    if (typeof ownerPid !== "number" || !Number.isInteger(ownerPid))
+        return null;
+    if (typeof acquiredAt !== "string" || acquiredAt.length === 0)
+        return null;
+    return { version, worktreePath, jobId, claimToken, executorId, ownerPid, acquiredAt };
+}
+/** Serialize ownership metadata. Only the approved fields are ever written. */
+function serializeLock(request) {
+    const owner = {
+        version: EXECUTOR_WORKTREE_LOCK_VERSION,
+        worktreePath: request.worktreePath,
+        jobId: request.jobId,
+        claimToken: request.claimToken,
+        executorId: request.executorId,
+        ownerPid: request.ownerPid,
+        acquiredAt: request.acquiredAt ?? new Date().toISOString(),
+    };
+    return JSON.stringify(owner);
+}
+/**
+ * Acquire exclusive ownership of `worktreePath` for one claimed job.
+ *
+ * Returns an acquired handle, or a `worktree_busy` refusal when the worktree is
+ * held by a live foreign claim. A lock whose owning PID is provably gone is
+ * recovered — but only through a re-read-then-remove sequence that verifies the
+ * bytes have not changed since we read them, so recovery cannot delete a lock a
+ * successor wrote in the meantime.
+ */
+export async function acquireExecutorWorktreeLock(request, seams = {}) {
+    const platform = seams.platform ?? process.platform;
+    const pathApi = pathApiForExecutorPlatform(platform);
+    const dir = pathApi.join(request.worktreePath, EXECUTOR_WORKTREE_LOCK_DIR);
+    const lockPath = pathApi.join(dir, EXECUTOR_WORKTREE_LOCK_FILE);
+    const writeExclusive = seams.writeFileExclusive ?? defaultWriteFileExclusive;
+    const read = seams.readFile ?? ((filePath) => readFile(filePath, "utf-8"));
+    const remove = seams.removeFile ?? ((filePath) => rm(filePath, { force: true }));
+    const makeDir = seams.mkdir ?? ((dirPath, options) => mkdir(dirPath, options));
+    const isAlive = seams.isProcessAlive ?? defaultIsProcessAlive;
+    const refused = (owner) => ({
+        acquired: false,
+        reason: "worktree_busy",
+        lockPath,
+        owner,
+    });
+    try {
+        await makeDir(dir, { recursive: true });
+    }
+    catch {
+        // A `.conductor` that already exists is the normal case and `recursive: true`
+        // makes it a no-op; any other failure surfaces below as a failed exclusive
+        // create, which refuses. Never proceed as though the lock were held by us.
+    }
+    const payload = serializeLock(request);
+    for (let attempt = 0; attempt < MAX_ACQUIRE_ATTEMPTS; attempt += 1) {
+        try {
+            await writeExclusive(lockPath, payload);
+            const owner = parseExecutorWorktreeLock(payload);
+            // Unreachable in practice — we just serialized it — but typing the handle
+            // on a parsed record rather than a cast keeps the file the single source
+            // of truth for what a lock IS.
+            if (owner === null)
+                return refused(null);
+            return {
+                acquired: true,
+                lockPath,
+                owner,
+                release: () => releaseLock(lockPath, request, read, remove),
+            };
+        }
+        catch (err) {
+            if (errorCode(err) !== "EEXIST") {
+                // Not a contention signal: a permission problem, a read-only worktree, a
+                // vanished directory. We do not own the worktree, so we do not enter it.
+                return refused(null);
+            }
+        }
+        let raw;
+        try {
+            raw = await read(lockPath);
+        }
+        catch (err) {
+            // The holder released between our failed create and this read: retry the
+            // exclusive create. Anything else is unreadable state — fail closed.
+            if (errorCode(err) === "ENOENT")
+                continue;
+            return refused(null);
+        }
+        const owner = parseExecutorWorktreeLock(raw);
+        if (owner === null)
+            return refused(null);
+        if (isAlive(owner.ownerPid))
+            return refused(owner);
+        // Dead owner. Recover only if the bytes we are about to delete are still the
+        // exact bytes we read and judged stale.
+        let confirmation;
+        try {
+            confirmation = await read(lockPath);
+        }
+        catch (err) {
+            if (errorCode(err) === "ENOENT")
+                continue;
+            return refused(null);
+        }
+        if (confirmation !== raw)
+            continue;
+        try {
+            await remove(lockPath);
+        }
+        catch {
+            return refused(owner);
+        }
+    }
+    return refused(null);
+}
+/**
+ * Remove the lock only while this job is still its recorded owner.
+ *
+ * Best-effort by design: a failed release leaves a lock whose owner PID is this
+ * (exiting) process, which the next acquisition recovers as stale. Throwing here
+ * would turn a cleanup hiccup into a job failure after the work was already done.
+ */
+async function releaseLock(lockPath, request, read, remove) {
+    let raw;
+    try {
+        raw = await read(lockPath);
+    }
+    catch {
+        return;
+    }
+    const owner = parseExecutorWorktreeLock(raw);
+    if (owner === null)
+        return;
+    if (owner.claimToken !== request.claimToken || owner.jobId !== request.jobId)
+        return;
+    try {
+        await remove(lockPath);
+    }
+    catch {
+        /* best-effort */
+    }
+}