claude-code-merge-queue 0.1.14

package/dist/lib/ephemeral.js

@@ -0,0 +1,100 @@
+/**
+ * The extension point for per-run ephemeral test resources — a throwaway
+ * database branch, a scratch bucket, a sandboxed queue, whatever your test
+ * suite needs that would otherwise race across concurrent lanes.
+ *
+ * This file is deliberately NOT wired to any specific provider. Everyone's
+ * test setup is different (Neon, a local Postgres with template databases, a
+ * Docker container per run, nothing at all) and shipping one company's
+ * choice as the default would make this less useful, not more. What's
+ * shipped instead is the *shape* — the same claim → use → release, and the
+ * same PID-liveness self-heal, that queue-lock.ts and launch.ts already use
+ * for the lock and the lane. One pattern, three places, so a crashed run
+ * never needs a human to notice and clean up after it.
+ *
+ * See examples/ephemeral-tmp-dir.example.ts for a complete, runnable
+ * implementation (a scratch directory per run, no external service) — copy
+ * its shape when you wire this to your own database or resource provider.
+ */
+import { mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/**
+ * A tiny on-disk registry of "what's claimed, by which PID." Not a database
+ * — just enough bookkeeping to answer "is this orphaned?" the same way
+ * queue-lock.ts answers it for locks: check whether the claiming PID is
+ * still alive, with no timeout to tune.
+ */
+export class ClaimRegistry {
+    dir;
+    constructor(registryDir) {
+        this.dir = registryDir;
+        mkdirSync(this.dir, { recursive: true });
+    }
+    record(claim) {
+        writeFileSync(join(this.dir, claim.id), JSON.stringify(claim));
+    }
+    release(id) {
+        try {
+            unlinkSync(join(this.dir, id));
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    /** Every claim whose owning PID is no longer alive — safe to destroy. */
+    orphans() {
+        let names;
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch {
+            return [];
+        }
+        const found = [];
+        for (const name of names) {
+            try {
+                const claim = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
+                if (!alive(claim.pid))
+                    found.push(claim);
+            }
+            catch {
+                /* unreadable claim file — leave it, don't guess */
+            }
+        }
+        return found;
+    }
+}
+/**
+ * Run `fn` against a freshly created resource, prune any orphans left by a
+ * previous crashed run first, and always release the claim — including on
+ * a thrown error. If THIS process is killed before the `finally` runs, the
+ * resource isn't leaked forever: the next call to `withEphemeralResource`
+ * (in the next test run, from any lane) prunes it via `orphans()` before
+ * creating its own.
+ */
+export async function withEphemeralResource(provider, registry, fn) {
+    for (const orphan of registry.orphans()) {
+        await provider.destroyOrphan(orphan);
+        registry.release(orphan.id);
+    }
+    const id = `${Date.now()}-${process.pid}`;
+    const claim = { id, pid: process.pid, createdAt: Date.now() };
+    registry.record(claim);
+    const resource = await provider.create();
+    try {
+        await fn(resource);
+    }
+    finally {
+        await provider.destroy(resource);
+        registry.release(id);
+    }
+}

package/dist/lib/lane-port.d.ts

@@ -0,0 +1,3 @@
+import type { ClaudeCodeLocalMergeConfig } from "./config.js";
+export declare function laneNumberFromPath(path: string, cfg: Pick<ClaudeCodeLocalMergeConfig, "worktreeSuffix">): number | null;
+export declare function lanePort(path: string, cfg: Pick<ClaudeCodeLocalMergeConfig, "worktreeSuffix" | "portBase">): number | null;

package/dist/lib/lane-port.js

@@ -0,0 +1,25 @@
+/**
+ * A lane's dev-server port, derived from where it's sitting on disk rather
+ * than an injected environment variable. Claude Code's WorktreeCreate hook
+ * has no mechanism to hand environment variables to the session that runs
+ * in the worktree it creates — only the directory path. So instead of
+ * betting on a second, less-certain hook (SessionStart + CLAUDE_ENV_FILE)
+ * to smuggle a port in, the worktree's own name already carries it: Lane
+ * Keeper names worktrees "<repo><worktreeSuffix><n>", so any script running
+ * inside one can read its own lane number straight off `process.cwd()`.
+ * Self-describing beats injected, when the information's already sitting
+ * right there in the path.
+ */
+import { basename } from "node:path";
+export function laneNumberFromPath(path, cfg) {
+    const name = basename(path);
+    const idx = name.lastIndexOf(cfg.worktreeSuffix);
+    if (idx === -1)
+        return null;
+    const n = Number(name.slice(idx + cfg.worktreeSuffix.length));
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+export function lanePort(path, cfg) {
+    const lane = laneNumberFromPath(path, cfg);
+    return lane === null ? null : cfg.portBase + lane;
+}

package/dist/lib/main-checkout.d.ts

@@ -0,0 +1 @@
+export declare function resolveMainCheckout(cwd?: string): string;

package/dist/lib/main-checkout.js

@@ -0,0 +1,19 @@
+/**
+ * Resolve the MAIN checkout — the one non-lane checkout your dev server (or
+ * CI, or whatever's watching the filesystem) actually runs from — starting
+ * from any lane worktree.
+ *
+ * git-common-dir is ".git" (relative) from the main checkout itself, or an
+ * absolute path to <main>/.git from a linked worktree — either way its
+ * parent is MAIN. Shared by sync and preview so they agree on the one true
+ * answer.
+ */
+import { execFileSync } from "node:child_process";
+import { dirname, resolve } from "node:path";
+export function resolveMainCheckout(cwd = process.cwd()) {
+    const common = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+        cwd,
+        encoding: "utf8",
+    }).trim();
+    return dirname(resolve(cwd, common));
+}

package/dist/lib/prune-lanes.d.ts

@@ -0,0 +1,36 @@
+import type { ClaudeCodeLocalMergeConfig } from "./config.js";
+/**
+ * Is a Claude Code session's current working directory inside `dir` right
+ * now? `lsof`'s own exit code is NOT reliable for this — it returns
+ * non-zero both when nothing matches AND when it merely fails to inspect
+ * some unrelated process it lacks permission for (common, e.g. root-owned
+ * system daemons), even while correctly printing real matches. `-a` ANDs
+ * the two filters together (lsof ORs by default) so this only matches
+ * things actually inside `dir`, not every process on the system.
+ *
+ * Deliberately narrower than "any process at all": a lane keeps
+ * accumulating incidental subprocesses whose lifetime doesn't track the
+ * Claude Code session that spawned them — an MCP server is the confirmed
+ * live case (a lingering `@brightdata/mcp` process kept a fully-landed,
+ * already-abandoned lane stuck on disk indefinitely; caffeinate and stray
+ * build/watch processes are the same shape of problem). Counting any of
+ * those as "still in use" means a lane can never actually get swept once
+ * its real agent session exits, which defeats the entire point of pruning.
+ * Only a row whose COMMAND column is actually the Claude Code binary
+ * counts as "someone's still working here" — matched by prefix since
+ * `lsof` truncates COMMAND (macOS: `claude.ex`, so an exact match would be
+ * platform-fragile in the other direction).
+ *
+ * If `lsof` isn't available at all, this fails CLOSED — treats liveness as
+ * unknown/possible rather than confirmed-safe, so an unverifiable state
+ * never gets treated the same as a verified-idle one.
+ */
+/** Exported so the matching rule itself is unit-testable without spawning real processes. */
+export declare function isClaudeProcessRow(lsofRow: string): boolean;
+/**
+ * Removes already-landed sibling lane worktrees. Returns the paths it
+ * actually removed. Best-effort throughout — any failure for a given
+ * worktree (dirty, diverged, busy) just skips that one; this never blocks
+ * or fails the `land` it's running as part of.
+ */
+export declare function pruneLandedLanes(mainTop: string, cfg: Pick<ClaudeCodeLocalMergeConfig, "worktreeSuffix" | "branchPrefix" | "integrationBranch" | "regenerableFiles">, currentWorktree: string): string[];

package/dist/lib/prune-lanes.js

@@ -0,0 +1,196 @@
+/**
+ * After a lane lands, sibling lanes that were ALSO already fully landed have
+ * no more reason to keep a worktree around — nothing created one on the way
+ * in tore it down on the way out (Claude Code's own worktree lifecycle
+ * doesn't either), so directories silently accumulate on disk forever
+ * unless something sweeps them. This runs that sweep as a side effect of
+ * every successful `land`, never touching the worktree currently running
+ * this process or the main checkout itself.
+ *
+ * Safety:
+ *   1. Only prune a worktree whose branch is a git ANCESTOR of
+ *      origin/<integrationBranch> — the authoritative, already-pushed
+ *      truth — not the local integration branch, which may not be
+ *      fast-forwarded yet at the exact moment this runs. That's the literal
+ *      definition of "nothing to lose": the work already made it upstream
+ *      under its own name.
+ *   2. Never touch a worktree with a LIVE process currently working in it
+ *      (checked via `lsof -a -d cwd`, see below) — this is NOT redundant
+ *      with the ancestor check. A brand-new lane that hasn't diverged yet
+ *      is *trivially* an ancestor of upstream (its tip IS a commit already
+ *      on the integration branch, just because nothing's been committed
+ *      there yet) — structurally identical, in the git graph alone, to a
+ *      lane whose own real work already landed. Only a liveness check can
+ *      tell "someone's about to start working here" apart from "this is
+ *      truly done." Confirmed live: a fresh, zero-commit lane got swept by
+ *      another lane's land before its own first commit.
+ *   3. `git worktree remove` (no `--force`) refuses on its own if the
+ *      worktree has uncommitted changes — dirty work is never discarded
+ *      just because its branch happens to be merged. The ONE exception,
+ *      matching `sync`/`land`: files listed in `regenerableFiles`
+ *      (next-env.d.ts and the like) are discarded first and the removal
+ *      retried, since a build tool rewriting its own output shouldn't be
+ *      the thing that leaves an otherwise fully-landed lane stuck forever.
+ *      Any OTHER dirty file blocks pruning exactly as before — real
+ *      uncommitted work is never discarded just to tidy up disk space.
+ * Deleting the now-redundant local branch (`git branch -d`, never `-D`) is a
+ * separate, best-effort tidiness step AFTER the worktree is already gone —
+ * it checks merge state against local HEAD rather than origin, so it can
+ * legitimately fail if the local integration branch hasn't caught up yet.
+ * That failure doesn't undo the (already-safe) worktree removal or keep it
+ * out of the returned list; it just leaves a harmless leftover branch ref.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { basename, dirname } from "node:path";
+/**
+ * Is a Claude Code session's current working directory inside `dir` right
+ * now? `lsof`'s own exit code is NOT reliable for this — it returns
+ * non-zero both when nothing matches AND when it merely fails to inspect
+ * some unrelated process it lacks permission for (common, e.g. root-owned
+ * system daemons), even while correctly printing real matches. `-a` ANDs
+ * the two filters together (lsof ORs by default) so this only matches
+ * things actually inside `dir`, not every process on the system.
+ *
+ * Deliberately narrower than "any process at all": a lane keeps
+ * accumulating incidental subprocesses whose lifetime doesn't track the
+ * Claude Code session that spawned them — an MCP server is the confirmed
+ * live case (a lingering `@brightdata/mcp` process kept a fully-landed,
+ * already-abandoned lane stuck on disk indefinitely; caffeinate and stray
+ * build/watch processes are the same shape of problem). Counting any of
+ * those as "still in use" means a lane can never actually get swept once
+ * its real agent session exits, which defeats the entire point of pruning.
+ * Only a row whose COMMAND column is actually the Claude Code binary
+ * counts as "someone's still working here" — matched by prefix since
+ * `lsof` truncates COMMAND (macOS: `claude.ex`, so an exact match would be
+ * platform-fragile in the other direction).
+ *
+ * If `lsof` isn't available at all, this fails CLOSED — treats liveness as
+ * unknown/possible rather than confirmed-safe, so an unverifiable state
+ * never gets treated the same as a verified-idle one.
+ */
+/** Exported so the matching rule itself is unit-testable without spawning real processes. */
+export function isClaudeProcessRow(lsofRow) {
+    return (lsofRow.trim().split(/\s+/)[0] ?? "").toLowerCase().startsWith("claude");
+}
+function hasLiveProcessInside(dir) {
+    const result = spawnSync("lsof", ["-a", "-d", "cwd", "+D", dir], { encoding: "utf8" });
+    if (result.error)
+        return true; // lsof missing/unspawnable — can't verify, assume in use
+    const rows = result.stdout.trim().split("\n").slice(1); // drop the header row
+    return rows.some(isClaudeProcessRow);
+}
+// Best-effort realpath — a "current worktree" that's already gone (or was
+// never real to begin with) shouldn't crash the sweep over one path.
+function existsRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function tryRemoveWorktree(mainTop, wt) {
+    try {
+        execFileSync("git", ["worktree", "remove", wt], { cwd: mainTop, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function listWorktrees(mainTop) {
+    const out = execFileSync("git", ["worktree", "list", "--porcelain"], { cwd: mainTop, encoding: "utf8" });
+    const entries = [];
+    let current = {};
+    const flush = () => {
+        if (current.path)
+            entries.push({ path: current.path, branch: current.branch ?? null });
+        current = {};
+    };
+    for (const line of out.split("\n")) {
+        if (line.startsWith("worktree ")) {
+            flush();
+            current.path = line.slice("worktree ".length);
+        }
+        else if (line.startsWith("branch ")) {
+            current.branch = line.slice("branch ".length).replace("refs/heads/", "");
+        }
+        else if (line === "") {
+            flush();
+        }
+    }
+    flush();
+    return entries;
+}
+/**
+ * Removes already-landed sibling lane worktrees. Returns the paths it
+ * actually removed. Best-effort throughout — any failure for a given
+ * worktree (dirty, diverged, busy) just skips that one; this never blocks
+ * or fails the `land` it's running as part of.
+ */
+export function pruneLandedLanes(mainTop, cfg, currentWorktree) {
+    const pruned = [];
+    // `git worktree list` reports fully realpath-resolved paths (symlinks like
+    // macOS's /var -> /private/var followed) — resolve our own reference
+    // points the same way, or every comparison below silently never matches.
+    const mainTopReal = realpathSync(mainTop);
+    const currentWorktreeReal = existsRealpath(currentWorktree);
+    const laneDirPrefix = `${basename(mainTopReal)}${cfg.worktreeSuffix}`;
+    const parent = dirname(mainTopReal);
+    const upstream = `origin/${cfg.integrationBranch}`;
+    const regenerable = new Set(cfg.regenerableFiles);
+    let worktrees;
+    try {
+        worktrees = listWorktrees(mainTop);
+    }
+    catch {
+        return pruned;
+    }
+    for (const { path: wt, branch } of worktrees) {
+        if (wt === mainTopReal || wt === currentWorktreeReal)
+            continue;
+        if (dirname(wt) !== parent || !basename(wt).startsWith(laneDirPrefix))
+            continue; // not one of ours
+        if (!branch || !branch.startsWith(cfg.branchPrefix))
+            continue;
+        try {
+            execFileSync("git", ["merge-base", "--is-ancestor", branch, upstream], {
+                cwd: mainTop,
+                stdio: "ignore",
+            }); // throws (non-zero exit) if NOT an ancestor — caught below, left alone
+        }
+        catch {
+            continue; // not safe to touch — leave this lane exactly as it is
+        }
+        if (hasLiveProcessInside(wt))
+            continue; // someone's actively in here — never touch it
+        let removed = tryRemoveWorktree(mainTop, wt);
+        if (!removed) {
+            // Blocked by dirty files? Only retry if EVERY one of them is a
+            // configured regenerable file — anything else is real uncommitted
+            // work, and this lane is left alone exactly as before.
+            const dirty = execFileSync("git", ["status", "--porcelain"], { cwd: wt, encoding: "utf8" })
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => line.slice(3).trim());
+            const blocking = dirty.filter((f) => !regenerable.has(f));
+            if (dirty.length > 0 && blocking.length === 0) {
+                execFileSync("git", ["checkout", "--", ...dirty], { cwd: wt, stdio: "ignore" });
+                removed = tryRemoveWorktree(mainTop, wt);
+            }
+        }
+        if (!removed)
+            continue; // still dirty (real work) or otherwise busy — leave it alone
+        // The worktree is gone — this is now unconditionally a pruned lane,
+        // regardless of what happens to the branch ref below.
+        pruned.push(wt);
+        try {
+            execFileSync("git", ["branch", "-d", branch], { cwd: mainTop, stdio: "ignore" });
+        }
+        catch {
+            /* local integration branch may not be fast-forwarded yet — harmless, leaves the ref behind */
+        }
+    }
+    return pruned;
+}

package/dist/lib/queue-lock.d.ts

@@ -0,0 +1,26 @@
+interface LockHolder {
+    pid: number;
+    lane: string;
+    label?: string;
+    ts: number;
+}
+export interface AcquireOptions {
+    label?: string;
+    onWait?: (info: {
+        ahead: number;
+        holder: LockHolder | null;
+    }) => void;
+}
+export interface QueueLock {
+    acquire(options?: AcquireOptions): Promise<void>;
+    release(): void;
+    readonly lane: string;
+    readonly held: boolean;
+}
+/**
+ * Create a named FIFO lock. Each distinct `queueName` is an independent
+ * mutex — "build" and "land" never contend with each other even though
+ * they share this exact same code.
+ */
+export declare function createQueueLock(queueName: string): QueueLock;
+export {};

package/dist/lib/queue-lock.js

@@ -0,0 +1,212 @@
+/**
+ * A generic, cross-worktree FIFO lock: the one primitive every other command
+ * in this repo is built on. `build-lock` and `land` are the same core idea —
+ * "serialize one action, machine-wide" — wearing two different hats.
+ *
+ * One queue name = one global mutex for this repo, shared by every worktree
+ * of it (keyed off git's common dir, so a different clone gets its own queue
+ * and two unrelated repos never contend with each other).
+ *
+ * Design:
+ *   - FIFO: each waiter enrolls a timestamped ticket and only competes for
+ *     the lock once it owns the oldest still-live ticket. No starvation, no
+ *     "whoever polls fastest wins."
+ *   - Crash-safe with NO timeouts, so there's no magic staleness threshold to
+ *     tune: a lock or ticket whose holder PID is no longer alive is reclaimed
+ *     the instant another waiter checks. Kill -9 the holder mid-lock and the
+ *     queue heals itself on the next poll.
+ */
+import { mkdirSync, writeFileSync, readFileSync, linkSync, unlinkSync, readdirSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import { execSync } from "node:child_process";
+// How often a waiter re-checks whether it's its turn. Not a behavioral cap —
+// just poll granularity.
+const POLL_MS = 200;
+function repoKey() {
+    try {
+        const commonDir = execSync("git rev-parse --git-common-dir", {
+            encoding: "utf8",
+        }).trim();
+        // Resolve to an absolute, worktree-independent path so every worktree of
+        // the same repo hashes to the same queue.
+        return execSync(`cd "${commonDir}" && pwd -P`, { encoding: "utf8" }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+/**
+ * Create a named FIFO lock. Each distinct `queueName` is an independent
+ * mutex — "build" and "land" never contend with each other even though
+ * they share this exact same code.
+ */
+export function createQueueLock(queueName) {
+    const QUEUE_DIR = join(tmpdir(), `claude-code-local-merge-${queueName}-queue-${createHash("sha1").update(repoKey()).digest("hex").slice(0, 12)}`);
+    const TICKETS_DIR = join(QUEUE_DIR, "tickets");
+    const LOCK_FILE = join(QUEUE_DIR, "lock");
+    mkdirSync(TICKETS_DIR, { recursive: true });
+    const lane = basename(process.cwd());
+    const ME = process.pid;
+    const TICKET_TS = Date.now();
+    const TICKET_NAME = `${TICKET_TS}-${ME}`;
+    const TICKET_FILE = join(TICKETS_DIR, TICKET_NAME);
+    function alive(pid) {
+        if (!pid || pid === ME)
+            return pid === ME;
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM"; // exists but owned by someone else
+        }
+    }
+    function pidOf(name) {
+        const dash = name.lastIndexOf("-");
+        return dash === -1 ? 0 : Number(name.slice(dash + 1));
+    }
+    function pruneDeadTickets() {
+        let names;
+        try {
+            names = readdirSync(TICKETS_DIR);
+        }
+        catch {
+            return [];
+        }
+        const live = [];
+        for (const name of names) {
+            if (alive(pidOf(name))) {
+                live.push(name);
+            }
+            else {
+                try {
+                    unlinkSync(join(TICKETS_DIR, name));
+                }
+                catch {
+                    /* someone else cleaned it */
+                }
+            }
+        }
+        live.sort((a, b) => {
+            const [ta, pa] = a.split("-").map(Number);
+            const [tb, pb] = b.split("-").map(Number);
+            return ta - tb || pa - pb;
+        });
+        return live;
+    }
+    function readLockHolder() {
+        try {
+            return JSON.parse(readFileSync(LOCK_FILE, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    // Atomically take the lock via link() (fails if it already exists). Reclaim
+    // a lock whose holder is dead. Returns true iff we now hold it.
+    function tryTakeLock(info) {
+        const tmp = `${LOCK_FILE}.${ME}.tmp`;
+        writeFileSync(tmp, JSON.stringify(info));
+        try {
+            linkSync(tmp, LOCK_FILE);
+            unlinkSync(tmp);
+            return true;
+        }
+        catch (e) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch {
+                /* noop */
+            }
+            if (e.code !== "EEXIST")
+                throw e;
+            const holder = readLockHolder();
+            if (!holder || !alive(holder.pid)) {
+                try {
+                    unlinkSync(LOCK_FILE);
+                }
+                catch {
+                    /* another waiter beat us to it */
+                }
+            }
+            return false;
+        }
+    }
+    let HOLD = false;
+    function release() {
+        if (HOLD) {
+            const holder = readLockHolder();
+            if (holder && holder.pid === ME) {
+                try {
+                    unlinkSync(LOCK_FILE);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            HOLD = false;
+        }
+        try {
+            unlinkSync(TICKET_FILE);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    /**
+     * Wait for and take the lock. `onWait({ahead, holder})` fires whenever the
+     * queue position changes, so callers can print progress.
+     */
+    async function acquire({ label, onWait } = {}) {
+        writeFileSync(TICKET_FILE, JSON.stringify({ pid: ME, lane, label, ts: TICKET_TS }));
+        let announced = -1;
+        for (;;) {
+            const queue = pruneDeadTickets();
+            const ahead = queue.indexOf(TICKET_NAME); // 0 = our turn
+            const holder = readLockHolder();
+            const lockFree = !holder || !alive(holder.pid);
+            if (ahead <= 0 && lockFree) {
+                if (tryTakeLock({ pid: ME, lane, label, ts: Date.now() })) {
+                    HOLD = true;
+                    try {
+                        unlinkSync(TICKET_FILE);
+                    }
+                    catch {
+                        /* noop */
+                    }
+                    return;
+                }
+            }
+            if (ahead > 0 && ahead !== announced) {
+                announced = ahead;
+                onWait?.({ ahead, holder: null });
+            }
+            else if (ahead <= 0 && holder && alive(holder.pid) && announced !== 0) {
+                announced = 0;
+                onWait?.({ ahead: 0, holder });
+            }
+            await sleep(POLL_MS);
+        }
+    }
+    // Best-effort release on graceful exit. Deliberately NOT registering
+    // SIGINT/SIGTERM/SIGHUP handlers here: adding any listener for those
+    // signals cancels Node's default "terminate the process" behavior, and
+    // this module doesn't own whether/how a caller's process should exit
+    // (build-lock.ts needs its OWN signal handler to kill a child's process
+    // group first). Correctness doesn't depend on this firing anyway — a
+    // lock/ticket left behind by a killed process is reclaimed deterministically
+    // by the next acquire() via the PID-liveness check above, same as a SIGKILL.
+    process.on("exit", release);
+    return {
+        acquire,
+        release,
+        lane,
+        get held() {
+            return HOLD;
+        },
+    };
+}

package/dist/lib/tty-confirm.d.ts

@@ -0,0 +1 @@
+export declare function promptTtyConfirm(promptText: string): string | null;

package/dist/lib/tty-confirm.js

@@ -0,0 +1,44 @@
+/**
+ * A synchronous, type-the-exact-word confirmation prompt read straight from
+ * /dev/tty — the same trick interactive git hooks use, since stdin during a
+ * `git push` is git's own protocol, not free for a hook to read from.
+ *
+ * Used exactly once: the emergency bypass for a blocked push (see
+ * check-push.ts). Returns null if there's no interactive terminal to prompt
+ * on at all (CI, a piped/non-interactive push) — the caller treats that as
+ * "can't confirm," not "confirmed."
+ */
+import { openSync, closeSync, readSync, writeSync } from "node:fs";
+export function promptTtyConfirm(promptText) {
+    let fd;
+    try {
+        fd = openSync("/dev/tty", "r+");
+    }
+    catch {
+        return null;
+    }
+    try {
+        writeSync(fd, promptText);
+        const buf = Buffer.alloc(1);
+        let input = "";
+        for (;;) {
+            let bytesRead;
+            try {
+                bytesRead = readSync(fd, buf, 0, 1, null);
+            }
+            catch {
+                break;
+            }
+            if (bytesRead <= 0)
+                break;
+            const ch = buf.toString("utf8");
+            if (ch === "\n" || ch === "\r")
+                break;
+            input += ch;
+        }
+        return input.trim();
+    }
+    finally {
+        closeSync(fd);
+    }
+}