lanekeeper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Heaslip
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="LaneKeeper — the local, zero-cost merge queue for parallel Claude Code agents" width="100%" />
+</p>
+
+<p align="center">
+  <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.x-3178c6.svg">
+  <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18-339933.svg">
+  <img alt="Runtime deps" src="https://img.shields.io/badge/runtime%20deps-0-brightgreen.svg">
+</p>
+
+# LaneKeeper 🚦
+
+**The local, zero-cost merge queue for parallel Claude Code agents.**
+
+Claude Code already isolates your agents — `--worktree` (or `isolation:
+"worktree"` on a subagent) gives every session its own git worktree, natively,
+no setup. That part's solved. LaneKeeper is the part that comes after: what
+happens when four isolated agents all try to land, build, and test *at the
+same time*.
+
+- 🏁 Everyone pushes to the same branch, someone loses the race, and the
+  rejected push turns into a rebase, which sometimes turns into *another*
+  rejected push.
+- 🔥 A full build is heavy. Four of them running at once turn your laptop
+  into a space heater.
+- 🎲 If your tests hit a shared database, concurrent runs race each other's
+  resets. The failures look flaky. They are not flaky. They're just honest.
+
+None of that is a skill issue. It's what happens when several fast,
+confident processes share one mutable thing with no traffic control.
+
+Telling the agents to "please coordinate" doesn't fix it. An agent (or a
+teammate in a hurry) will violate a documented convention exactly once, at
+exactly the wrong moment, and mean nothing by it.
+
+**So don't ask nicely. Make the collision impossible.** 🚦
+
+## 🆚 vs. GitHub's Merge Queue
+
+GitHub already ships a merge queue. Two things it costs you that this doesn't:
+
+| | GitHub Merge Queue | LaneKeeper |
+|---|---|---|
+| Private repo | **Enterprise Cloud only** | Any plan, any repo |
+| Cost per landing | GitHub Actions minutes, every queue attempt | $0 — runs on your own machine |
+| Requires | A pull request | Nothing — direct rebase + push |
+
+Same idea — serialize landings, test before merge, keep history clean — run
+locally instead of in someone else's billed cloud. 💸
+
+## 🧰 What's in the box
+
+| Command | What it does |
+|---|---|
+| `lanekeeper hook worktree-create` | A Claude Code `WorktreeCreate` hook. Plugs LaneKeeper's numbered lanes into Claude's *native* worktree creation — doesn't reinvent it. |
+| `lanekeeper build-lock -- <cmd>` | Runs `<cmd>` — your build — serialized across every lane, machine-wide. |
+| `lanekeeper land` | Rebases and pushes your lane onto the integration branch through a FIFO queue, so two lanes are never mid-push at once. Agents run this themselves — see below. |
+| `lanekeeper sync` | Fast-forwards your main checkout so a dev server actually sees what just landed. |
+| `lanekeeper promote` | Ships the integration branch to production. **Human-only** — never in an agent's instructions, never automated. |
+| `lanekeeper preview` | Instantly mirrors a lane's live working tree — uncommitted changes included — onto the main checkout, so you can look at it without a build. |
+| `lanekeeper port` | Prints a lane's dev-server port, derived from its own directory name. |
+
+Plus 🔒 a pre-push hook that makes `land` non-optional: a direct `git push`
+straight to the integration branch gets bounced, full stop. Not a lint
+warning. Not a Slack reminder. Rejected — with the actual command to run
+instead. The same hook also runs your actual checks (`checkCommand` —
+lint/typecheck/test/build) before allowing a landing through at all; a
+config with no checkCommand set **fails every push by default** rather than
+landing unverified code silently.
+
+Every one of those blocks has a real, deliberate way out — see "The
+emergency hatch" below — but it takes two matching, specific pieces of
+intent, not one flag.
+
+And 🧪 a documented extension point (`src/lib/ephemeral.ts` +
+`examples/ephemeral-tmp-dir.example.ts`) for the thing every setup guide
+skips: if your tests hit a shared resource — a database, a queue, anything
+stateful — concurrent lanes need their own throwaway copy of it, and a
+crashed run's copy needs to clean itself up without anyone noticing it died.
+
+## ⚡ Quickstart
+
+```bash
+npm install --save-dev lanekeeper   # or: pnpm add -D / yarn add -D / bun add -d
+npx lanekeeper init
+```
+
+This does the whole setup, not just the config file:
+
+- **`lanekeeper.config.mjs`** — `integrationBranch` auto-detected from your
+  current branch, `checkCommand` auto-detected from package.json
+  (`check:push` / `check` / `ci` / `test`, first match wins).
+- **`CLAUDE.md`** (or appends to yours if you already have one) — the part
+  that makes the whole thing hands-off. Claude Code reads it automatically,
+  every session, and it tells the agent to land its own work once green,
+  without being asked. See "The hands-off part" below.
+- **`.claude/settings.json`** — the `WorktreeCreate` hook wired in (created,
+  or merged into your existing settings without touching anything else
+  already there).
+- **`.husky/pre-push`** — created or appended to, *if* you already have
+  Husky. If you don't, `init` tells you so instead of silently writing to
+  the untracked, not-shared-with-your-team `.git/hooks/pre-push`.
+
+**Commit everything it wrote.** Then add to `package.json`:
+```json
+"scripts": {
+  "land": "lanekeeper land",
+  "sync": "lanekeeper sync",
+  "promote": "lanekeeper promote",
+  "preview": "lanekeeper preview",
+  "preview:restore": "lanekeeper preview --restore"
+}
+```
+
+If `init` couldn't detect a `checkCommand` (no matching script in
+package.json), every push is **blocked** until you set one — see 🧰 What's
+in the box above. That's on purpose.
+
+From here on: `claude --worktree <name>` to spin up an isolated lane —
+LaneKeeper's hook takes it from there, and CLAUDE.md tells the agent the rest.
+You show up to run `lanekeeper promote` when you actually want to ship. 🚀
+
+## ⚙️ Configuration
+
+Everything lives in one file — see
+[`examples/lanekeeper.config.mjs`](examples/lanekeeper.config.mjs) for every
+field with comments. The short version:
+
+```js
+export default {
+  branchPrefix: "lane/",               // lane/1, lane/2, ...
+  worktreeSuffix: "-lane-",            // ../your-repo-lane-1
+  portBase: 3000,                      // lane n gets portBase + n
+  integrationBranch: "main",           // where agents land — see below
+  productionBranch: null,              // set this for a two-stage model — see below
+  protectedBranches: [],               // extra branches beyond the two above; most repos need none
+  regenerableFiles: [],                // files a build tool rewrites — never block a rebase on these
+  symlinks: [".env", ".env.local", "node_modules"],
+  buildOutputDirs: ["dist", "build", ".next"], // preview never copies these onto your checkout
+  checkCommand: "npm run check",       // what actually gates a landing — see below
+  checksRequired: true,                // false = deliberately run with none; see below
+};
+```
+
+Nothing here is hardcoded to any framework or branch model. 🧩 A malformed
+config (empty branch names, a negative port, `productionBranch` equal to
+`integrationBranch`, ...) fails loud with every problem listed, the moment
+any command loads it — not a mysterious failure three steps later.
+
+## 🚨 The emergency hatch
+
+Every blocked push — the integration branch, `productionBranch`, anything
+in `protectedBranches` — has a real way through it. It's meant to be used
+rarely and on purpose, so it asks for two separate, specific things instead
+of one flag an agent could set just as easily as a human:
+
+```bash
+LANEKEEPER_EMERGENCY_PUSH=1 git push origin HEAD:main
+```
+
+That alone isn't enough — you'll be prompted, right there in your terminal,
+to **type the exact branch name** to confirm. No terminal attached (CI, a
+script)? Provide the second factor yourself instead:
+
+```bash
+LANEKEEPER_EMERGENCY_PUSH=1 LANEKEEPER_EMERGENCY_PUSH_CONFIRM=main git push origin HEAD:main
+```
+
+No confirmation, no tty, no match — it fails **closed**, not open. This is
+the one place in LaneKeeper that's honestly a convention, not a hard
+guarantee: the env vars stop mistakes and stray pushes, not a truly
+adversarial agent that decides to set them itself. Worth knowing, not worth
+pretending isn't true.
+
+## 🙌 The hands-off part
+
+Tests are the reviewer. Not a human, at any point in this pipeline — and
+that's a deliberate, named tradeoff, not an oversight.
+
+- **`checkCommand` gates landing.** Nothing reaches `integrationBranch`
+  without passing it. This is the first, and for most changes the *only*,
+  correctness check anything gets.
+- **`lanekeeper promote` is a release decision, not a code review.**
+  Running it means "this batch of already-landed, already-tested work
+  should ship now" — not "I read the diff and it looks right." If your own
+  CI provider also runs checks against the production branch (most real
+  setups have this — a deploy gate, an E2E suite, whatever), that's a
+  *second automated* checkpoint, still not a human one.
+- **When something gets through anyway, the fix is a test, not a
+  reviewer.** If a bug lands, the answer isn't "a human should have caught
+  that" — it's "what check would have caught it, and why didn't it exist
+  yet." Every miss becomes a permanent guardrail instead of a one-off
+  catch, which is the only version of this that scales past however many
+  diffs one person can actually read.
+
+This isn't for every team. If what you actually want is a human looking at
+every change before it ships, this tool will feel like it's missing a
+step — because it is, on purpose. It's built for the case where you trust
+the agent's *output conditional on the checks being real*, and the checks
+being non-optional (see 🧰 above) is what makes that trust earned rather
+than assumed.
+
+## 🔁 The one idea underneath most of it
+
+The build queue, the landing queue, and the ephemeral-resource pattern are
+all crash-safe the **same way**, on purpose:
+
+1. Claim a resource.
+2. Tag the claim with your process ID.
+3. Let liveness — not a timeout — decide when a claim is stale.
+
+`queue-lock.ts` does it for the build and landing queues. `ephemeral.ts`
+does it for whatever test resource you wire in. `Kill -9` any of them
+mid-claim, and the next process to come along notices the PID is dead and
+reclaims it.
+
+The `WorktreeCreate` hook uses a cousin of the same idea, adapted to the fact
+that it's a one-shot script with no long-lived process to check liveness
+against: the claim IS the worktree, and `git worktree add` failing on an
+already-taken path is the atomicity guard, delegated straight to git instead
+of a PID file.
+
+Either way: no stale locks, no "just restart your laptop," no magic number
+for how long is too long to wait. ✅ Structurally impossible beats politely
+requested, every time.
+
+## 🔍 Know the limits
+
+Things a sharp reader should already know before they ask:
+
+- **One machine, not a fleet.** The FIFO queue lives in local temp storage —
+  it doesn't coordinate across laptops. Two machines landing at the same
+  moment just get git's own ordinary non-fast-forward rejection (safe, not
+  corrupting — the loser re-fetches and retries, same as any team without a
+  queue does today). This solves the one-machine problem completely; it was
+  never trying to solve the distributed one.
+- **Not a security boundary.** Every guardrail here stops mistakes and
+  convention drift — a fast, confident, forgetful agent — not a truly
+  adversarial one. An agent with shell access can always `git push
+  --no-verify`, delete the hook, or edit the config on purpose. If your
+  threat model includes an agent actively trying to get around this, none
+  of this helps, and nothing local-only ever could.
+- **Guarantees a check ran — not that the check is good.** LaneKeeper
+  enforces that `checkCommand` exists and passed. It has no way to know if
+  that's a real test suite or `echo ok`. "Tests are the reviewer" is only
+  as true as what's actually in them.
+- **The `WorktreeCreate` hook is the youngest piece of this stack** — Claude
+  Code shipped it Feb 2026. Losing it degrades gracefully: fall back to
+  `git worktree add` by hand and you still keep the build queue, landing
+  queue, preview, and ephemeral-resource pieces, none of which depend on it.
+- **A slow `checkCommand` is a real throughput ceiling, not a free lunch.**
+  The FIFO lock holds for its entire duration — one landing at a time,
+  machine-wide. A 3–4 minute suite caps you well under 20 landings/hour
+  flat-out, before any queue wait.
+- **Rebase conflicts abort, they never guess.** `git rebase --abort` on any
+  conflict, working tree left clean — it never auto-resolves or silently
+  picks a side. In the normal flow that "you" is the agent, not a human:
+  CLAUDE.md tells it to resolve the conflict itself and re-run `land`, the
+  same way it'd fix any other bug — `checkCommand` still gates the result
+  either way, so a bad resolution gets caught there.
+
+## 🧬 Where this came from
+
+This is the extracted, generalized shape of tooling built to run several
+parallel Claude Code agents on one real production codebase (and this repo)
+without them tripping over each other — a build queue, a landing queue
+enforced by a git hook, instant previews, and the ephemeral-resource pattern
+for tests, all sitting on top of Claude Code's own native worktree isolation.
+The names have been filed off; the mechanics haven't.
+
+## 📄 License
+
+MIT. Fork it, rename it, argue with the config shape — that's the point.

package/dist/bin/lanekeeper.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/lanekeeper.js

@@ -0,0 +1,269 @@
+#!/usr/bin/env node
+/**
+ * The lanekeeper CLI. Every subcommand reads lanekeeper.config from the
+ * current repo — see src/lib/config.ts — so none of this is hardcoded to
+ * any one project's branch names.
+ */
+import { readFileSync } from "node:fs";
+import { land } from "../land.js";
+import { sync } from "../sync.js";
+import { promote } from "../promote.js";
+import { runPreview } from "../preview.js";
+import { buildLock } from "../build-lock.js";
+import { findRepoRoot, hasConfig, loadConfig, detectCurrentBranch, DEFAULTS } from "../lib/config.js";
+import { checkPush, parseRefUpdates } from "../lib/check-push.js";
+import { runWorktreeCreateHook } from "../hooks/worktree-create.js";
+import { lanePort } from "../lib/lane-port.js";
+import { claudeMdSnippet, MARKER } from "../lib/claude-md-snippet.js";
+import { detectCheckCommand, runCheckCommand } from "../lib/check-command.js";
+import { wireClaudeSettings, wireHuskyPrePush, ensureHooksPath } from "../lib/wire-hooks.js";
+const [, , command, ...rest] = process.argv;
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function init() {
+    const root = findRepoRoot();
+    if (!root) {
+        console.error("lanekeeper init: not inside a git repo.");
+        process.exit(1);
+    }
+    const { writeFileSync, readFileSync: read, existsSync, appendFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    if (hasConfig(root)) {
+        console.log("lanekeeper init: lanekeeper.config.mjs already exists — leaving it alone.");
+    }
+    else {
+        const detectedBranch = detectCurrentBranch(root);
+        const detectedCheck = detectCheckCommand(root);
+        const generated = {
+            ...DEFAULTS,
+            ...(detectedBranch ? { integrationBranch: detectedBranch } : {}),
+            ...(detectedCheck ? { checkCommand: detectedCheck } : {}),
+        };
+        const template = `// lanekeeper.config.mjs — generated by \`lanekeeper init\`. Edit freely.
+// Its presence here is what turns LaneKeeper ON for this repo.
+
+/** @type {import("lanekeeper").LaneKeeperConfig} */
+export default ${JSON.stringify(generated, null, 2)};
+`;
+        writeFileSync(join(root, "lanekeeper.config.mjs"), template);
+        console.log(`lanekeeper init: wrote ${join(root, "lanekeeper.config.mjs")}`);
+        if (detectedBranch && detectedBranch !== DEFAULTS.integrationBranch) {
+            console.log(`  (detected current branch "${detectedBranch}" — set as integrationBranch instead of the "${DEFAULTS.integrationBranch}" default)`);
+        }
+        else if (!detectedBranch) {
+            console.log("");
+            console.log(`  ⚠️  Couldn't detect the current branch (detached HEAD?) — integrationBranch`);
+            console.log(`      defaulted to "${DEFAULTS.integrationBranch}". Verify that's actually right`);
+            console.log(`      in lanekeeper.config.mjs before committing it.`);
+        }
+        if (detectedCheck) {
+            console.log(`  (detected "${detectedCheck}" from package.json — set as checkCommand)`);
+        }
+        else {
+            console.log("");
+            console.log("  ⚠️  No checkCommand detected (no check:push/check/ci/test script found in");
+            console.log("      package.json). Every push is BLOCKED until you set one — or set");
+            console.log("      checksRequired: false to deliberately run with no checks.");
+        }
+    }
+    // This is the part that actually makes agents use the workflow without a
+    // human reminding them every session — see claude-md-snippet.ts.
+    const claudeMdPath = join(root, "CLAUDE.md");
+    const cfg = hasConfig(root) ? await loadConfig(root) : DEFAULTS;
+    const snippet = claudeMdSnippet(cfg);
+    if (!existsSync(claudeMdPath)) {
+        writeFileSync(claudeMdPath, `# Project instructions for Claude Code\n\n${snippet}`);
+        console.log(`lanekeeper init: wrote ${claudeMdPath}`);
+    }
+    else if (!read(claudeMdPath, "utf8").includes(MARKER)) {
+        appendFileSync(claudeMdPath, `\n${snippet}`);
+        console.log(`lanekeeper init: appended the LaneKeeper workflow section to ${claudeMdPath}`);
+    }
+    else {
+        console.log(`lanekeeper init: ${claudeMdPath} already has the LaneKeeper workflow section — leaving it alone.`);
+    }
+    const claudeSettingsResult = wireClaudeSettings(root);
+    switch (claudeSettingsResult) {
+        case "created":
+            console.log(`lanekeeper init: wrote ${join(root, ".claude", "settings.json")} with the WorktreeCreate hook.`);
+            break;
+        case "merged":
+            console.log(`lanekeeper init: added the WorktreeCreate hook to your existing ${join(root, ".claude", "settings.json")}.`);
+            break;
+        case "already-wired":
+            console.log("lanekeeper init: .claude/settings.json already has the WorktreeCreate hook — leaving it alone.");
+            break;
+        case "unparseable":
+            console.log("lanekeeper init: .claude/settings.json exists but isn't valid JSON — left untouched. Wire it manually,");
+            console.log("  see node_modules/lanekeeper/hooks/claude-settings.example.json.");
+            break;
+    }
+    const prePushResult = wireHuskyPrePush(root);
+    switch (prePushResult) {
+        case "created":
+            console.log("lanekeeper init: wrote .husky/pre-push.");
+            break;
+        case "merged":
+            console.log("lanekeeper init: appended LaneKeeper's checks to your existing .husky/pre-push.");
+            break;
+        case "already-wired":
+            console.log("lanekeeper init: .husky/pre-push already wired — leaving it alone.");
+            break;
+        case "no-husky":
+            console.log("lanekeeper init: no .husky/ directory found — pre-push hook NOT wired automatically.");
+            console.log("  Install Husky, or copy node_modules/lanekeeper/hooks/pre-push to .git/hooks/pre-push");
+            console.log("  yourself (note: .git/hooks isn't version-controlled — only Husky's is shared with your team).");
+            break;
+    }
+    if (prePushResult === "created" || prePushResult === "merged" || prePushResult === "already-wired") {
+        // A .husky/pre-push file enforces nothing until core.hooksPath actually
+        // points at .husky — normally a side effect of the package manager's
+        // install step, which may not have run yet (e.g. a fresh clone, right
+        // where Quickstart leaves you). Without this, a direct push sails
+        // through uncontested with no indication anything's wrong.
+        switch (ensureHooksPath(root)) {
+            case "set":
+                console.log("lanekeeper init: set core.hooksPath=.husky so the pre-push hook actually runs (normally set by your package manager's install step, which may not have run yet).");
+                break;
+            case "already-set":
+                break; // the common case once installed — nothing to say
+            case "custom-path":
+                console.log("lanekeeper init: core.hooksPath is set to something other than .husky — leaving it alone.");
+                console.log("  Wrote .husky/pre-push, but it won't run until your hooks path points there. Reconcile this yourself.");
+                break;
+        }
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Check lanekeeper.config.mjs — integrationBranch/checkCommand were auto-detected;");
+    console.log("     set productionBranch too if you run a two-stage model.");
+    console.log('  2. Add to package.json "scripts": land, sync, promote, preview -> "lanekeeper <name>".');
+    console.log("  3. Commit lanekeeper.config.mjs, CLAUDE.md, .claude/settings.json, and .husky/pre-push.");
+    console.log("  4. claude --worktree <name> — the agent takes it from there.");
+}
+async function main() {
+    switch (command) {
+        case "init":
+            return init();
+        case "hook": {
+            const sub = rest[0];
+            if (sub === "worktree-create")
+                return runWorktreeCreateHook();
+            console.error(`lanekeeper hook: unknown hook "${sub ?? ""}". Only "worktree-create" is supported.`);
+            process.exit(1);
+            return;
+        }
+        case "port": {
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                console.error("lanekeeper port: no lanekeeper.config found — not a lane.");
+                process.exit(1);
+            }
+            const cfg = await loadConfig(root);
+            const port = lanePort(process.cwd(), cfg);
+            if (port === null) {
+                console.error("lanekeeper port: current directory doesn't look like a lane worktree.");
+                process.exit(1);
+            }
+            console.log(port);
+            return;
+        }
+        case "land":
+            return land();
+        case "sync":
+            process.exit(await sync());
+            return;
+        case "promote":
+            process.exit(await promote());
+            return;
+        case "preview":
+            return runPreview(rest);
+        case "build-lock": {
+            const parts = rest[0] === "--" ? rest.slice(1) : rest;
+            return buildLock(parts);
+        }
+        case "check-push": {
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                // No config means LaneKeeper isn't enabled for this repo — nothing to enforce.
+                process.exit(0);
+            }
+            const cfg = await loadConfig(root);
+            const stdin = await readStdin();
+            const refUpdates = parseRefUpdates(stdin);
+            // git still invokes pre-push (with empty stdin) for a push that
+            // updates zero refs — e.g. re-pushing a branch that's already exactly
+            // up to date on the remote. There's nothing to block (nothing is
+            // actually changing on the remote either way) and nothing meaningful
+            // for checkCommand to verify — running it anyway just produces a
+            // confusing, unrelated failure (a missing devDependency, say) that
+            // looks exactly like a real block but isn't one. Recognize "nothing
+            // to push" explicitly instead of silently falling through both checks.
+            if (refUpdates.length === 0) {
+                console.log("lanekeeper check-push: nothing being pushed (already up to date) — skipping checks.");
+                process.exit(0);
+            }
+            // LANEKEEPER_EMERGENCY_PUSH=1 alone isn't enough — that's one flag an
+            // agent (or a fat-fingered alias) could set as easily as a human. The
+            // second factor is naming the exact branch, either non-interactively
+            // (LANEKEEPER_EMERGENCY_PUSH_CONFIRM=<branch>, for a scripted case
+            // that already knows what it's doing) or by typing it at a real
+            // terminal right now. No tty available means no confirmation — fails
+            // closed, not open.
+            if (process.env.LANEKEEPER_EMERGENCY_PUSH === "1" && !process.env.LANEKEEPER_EMERGENCY_PUSH_CONFIRM) {
+                const target = refUpdates[0]?.remoteRef.replace("refs/heads/", "");
+                if (target) {
+                    const { promptTtyConfirm } = await import("../lib/tty-confirm.js");
+                    const typed = promptTtyConfirm(`\n🚨 LANEKEEPER_EMERGENCY_PUSH is set — this bypasses the landing queue.\nType the branch name ("${target}") to confirm, anything else to abort: `);
+                    if (typed === target) {
+                        process.env.LANEKEEPER_EMERGENCY_PUSH_CONFIRM = target;
+                        console.log(`\nConfirmed — pushing directly to '${target}', bypassing the queue.\n`);
+                    }
+                    else {
+                        console.error(`\n✋ Confirmation didn't match "${target}" exactly — push aborted.\n`);
+                        process.exit(1);
+                    }
+                }
+            }
+            const result = checkPush(refUpdates, cfg, process.env);
+            if (!result.ok) {
+                console.error(result.message);
+                process.exit(1);
+            }
+            process.exit(runCheckCommand(cfg, root));
+            return;
+        }
+        case "--version":
+        case "-v": {
+            const { join, dirname } = await import("node:path");
+            const { fileURLToPath } = await import("node:url");
+            const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            console.log(pkg.version);
+            return;
+        }
+        default:
+            console.log(`lanekeeper — keep parallel coding agents in their lane.
+
+Usage:
+  lanekeeper init                  write a starter lanekeeper.config.mjs
+  lanekeeper land                  rebase + push this lane onto the integration branch (queued)
+  lanekeeper sync                  fast-forward the MAIN checkout to its upstream
+  lanekeeper promote               ship the integration branch to production (human-only — never script this)
+  lanekeeper preview [--restore]   swap the MAIN checkout to this lane's working tree, or restore it
+  lanekeeper build-lock -- <cmd>   run <cmd>, serialized across every lane
+  lanekeeper port                  print this lane's dev-server port
+  lanekeeper hook worktree-create  (Claude Code WorktreeCreate hook — not for direct use)
+  lanekeeper check-push            (used by the pre-push hook — not for direct use)
+`);
+            process.exit(command ? 1 : 0);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/build-lock.d.ts

@@ -0,0 +1 @@
+export declare function buildLock(commandParts: string[]): Promise<void>;

package/dist/build-lock.js

@@ -0,0 +1,70 @@
+/**
+ * build-lock.ts — wrap any command so only ONE runs at a time, machine-wide,
+ * across every lane of this repo.
+ *
+ * A full production build is CPU/RAM-heavy. Run one per lane and four
+ * parallel agents will thrash a laptop into a death spiral. This doesn't
+ * make builds faster — it makes them take turns, via the same cross-worktree
+ * FIFO lock everything else in this repo shares (queue-lock.ts).
+ *
+ *   Usage:  lanekeeper build-lock -- <shell command>
+ *
+ * Crash-safe with no timeouts: a lock whose holder PID has died is reclaimed
+ * deterministically, so a killed build can't wedge the queue for anyone
+ * else. That's also why the child is spawned detached — SIGKILLing this
+ * process still leaves an orphaned build running unless something can reach
+ * its whole process group, so a caller that wants to hard-kill a build (a CI
+ * runner enforcing a deadline, say) needs a group to signal, not just a PID.
+ */
+import { spawn } from "node:child_process";
+import { createQueueLock } from "./lib/queue-lock.js";
+export async function buildLock(commandParts) {
+    const command = commandParts.join(" ").trim();
+    if (!command) {
+        console.error("lanekeeper build-lock: no command given. Usage: lanekeeper build-lock -- <command>");
+        process.exit(2);
+    }
+    const lock = createQueueLock("build");
+    await lock.acquire({
+        label: command,
+        onWait: ({ ahead, holder }) => {
+            if (ahead > 0) {
+                console.log(`\x1b[2m[build-queue] ${lock.lane}: waiting — ${ahead} build${ahead === 1 ? "" : "s"} ahead…\x1b[0m`);
+            }
+            else if (holder) {
+                console.log(`\x1b[2m[build-queue] ${lock.lane}: next up — waiting for the running build to finish…\x1b[0m`);
+            }
+        },
+    });
+    console.log(`\x1b[2m[build-queue] ${lock.lane}: lock acquired — building…\x1b[0m`);
+    const child = spawn(command, { shell: true, stdio: "inherit", detached: true });
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.on(sig, () => {
+            try {
+                // detached:true made the child its own process-group leader, so a
+                // negative pid signals the whole tree, not just the shell wrapper.
+                if (child.pid)
+                    process.kill(-child.pid, sig);
+            }
+            catch {
+                /* noop */
+            }
+            lock.release();
+            process.exit(130);
+        });
+    }
+    child.on("exit", (code, signal) => {
+        lock.release();
+        if (signal) {
+            process.kill(process.pid, signal);
+        }
+        else {
+            process.exit(code ?? 1);
+        }
+    });
+    child.on("error", (err) => {
+        console.error(`lanekeeper build-lock: failed to start command: ${err.message}`);
+        lock.release();
+        process.exit(1);
+    });
+}

package/dist/hooks/worktree-create.d.ts

@@ -0,0 +1,13 @@
+import { type LaneKeeperConfig } from "../lib/config.js";
+/**
+ * Claim the lowest free lane, create its worktree, and symlink the
+ * configured git-ignored paths into it. Throws with a human-readable
+ * message on failure — the caller turns that into the hook's stderr +
+ * non-zero exit.
+ */
+export declare function createLane(mainTop: string, cfg: LaneKeeperConfig): {
+    wt: string;
+    branch: string;
+    lane: number;
+};
+export declare function runWorktreeCreateHook(): Promise<void>;