claude-code-merge-queue 0.1.14

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,260 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="Claude Code Local Merge — 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>
+
+# Claude Code Local Merge 🚦
+
+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. Claude Code Local Merge 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.** 🚦
+
+**The local, zero-cost merge queue for parallel Claude Code agents.**
+
+## ⚡ Quickstart
+
+```bash
+npm install --save-dev claude-code-local-merge   # or: pnpm add -D / yarn add -D / bun add -d
+npx claude-code-local-merge init
+```
+
+This does the whole setup, not just the config file:
+
+- **`claude-code-local-merge.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`.
+- **`package.json` scripts** — `land`, `sync`, `promote`, `preview`, and
+  `preview:restore` added, skipping any you've already defined yourself.
+- **`claude-code-local-merge-preflight.mjs`** + `preland`/`presync` scripts — a
+  self-contained safety net npm runs automatically before `land`/`sync`. If
+  this tool's own name/bin ever changes again (it has once — `lanekeeper` →
+  `claude-code-local-merge`) and a lane hasn't rebased past that point yet, its
+  `package.json` still calls the old name, which no longer exists — a bare,
+  confusing `sh: lanekeeper: command not found`. This script catches that
+  case with an actual diagnosis ("this branch is stale relative to
+  origin/&lt;branch&gt; — rebase first") instead. It's deliberately plain
+  JS with zero dependency on `claude-code-local-merge` itself, so it keeps working across
+  future renames too.
+
+**Commit everything it wrote**, then you're running. Two steps, not a setup
+guide.
+
+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 below. That's on purpose.
+
+From here on: `claude --worktree <name>` to spin up an isolated lane —
+Claude Code Local Merge's hook takes it from there, and CLAUDE.md tells the agent the rest.
+You show up to run `claude-code-local-merge promote` when you actually want to ship. 🚀
+
+## 🆚 vs. GitHub's Merge Queue
+
+GitHub already ships a merge queue. Two things it costs you that this doesn't:
+
+| | GitHub Merge Queue | Claude Code Local Merge |
+|---|---|---|
+| 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 |
+|---|---|
+| `claude-code-local-merge hook worktree-create` | A Claude Code `WorktreeCreate` hook. Plugs Claude Code Local Merge's numbered lanes into Claude's *native* worktree creation — doesn't reinvent it. |
+| `claude-code-local-merge build-lock -- <cmd>` | Runs `<cmd>` — your build — serialized across every lane, machine-wide. |
+| `claude-code-local-merge 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. |
+| `claude-code-local-merge sync` | Fast-forwards your main checkout so a dev server actually sees what just landed — and re-installs dependencies if the lockfile changed, so the `node_modules` every lane symlinks from never goes stale. |
+| `claude-code-local-merge promote` | Ships the integration branch to production. **Human-only** — never in an agent's instructions, never automated. |
+| `claude-code-local-merge 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. |
+| `claude-code-local-merge port` | Prints a lane's dev-server port, derived from its own directory name. |
+| `claude-code-local-merge prune` | Removes already-landed sibling lane worktrees on demand — `land` already does this automatically, this is for "clean these up right now" instead of waiting for the next lane to land something. |
+
+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 naming the specific branch you mean
+to push, not one generic 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.
+
+## ⚙️ Configuration
+
+Everything lives in one file — see
+[`examples/claude-code-local-merge.config.mjs`](examples/claude-code-local-merge.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. One env var, no
+prompts, no second factor to remember:
+
+```bash
+CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH=1 git push origin HEAD:main
+```
+
+This is the one place that's honestly a convention, not a hard guarantee:
+it stops mistakes and stray pushes, not an adversarial agent that sets the
+var itself.
+
+## 🙌 The hands-off part
+
+Tests are the reviewer, not a human, at any point in this pipeline.
+
+- **`checkCommand` gates landing.** Nothing reaches `integrationBranch`
+  without passing it — the only correctness check most changes get.
+- **`claude-code-local-merge promote` is a release decision, not a code
+  review.** It means "this already-tested work should ship now," not "I
+  read the diff." Your own CI on the production branch is a second
+  automated checkpoint — still not a human one.
+- **When something gets through anyway, the fix is a test, not a
+  reviewer.** Every miss becomes a permanent guardrail, not a one-off catch.
+
+Not for every team — if you want a human looking at every change before it
+ships, this is missing that step on purpose.
+
+## 🔁 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**:
+
+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 test resources. `kill -9` any of them mid-claim, and the next
+process notices the PID is dead and reclaims it.
+
+The `WorktreeCreate` hook is a cousin of the same idea for a one-shot
+script with no process to check liveness against: the claim IS the
+worktree, and `git worktree add` failing on an already-taken path is the
+atomicity guard.
+
+No stale locks, no "just restart your laptop," no magic timeout number. ✅
+
+## 🔍 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 once just
+  get git's ordinary non-fast-forward rejection (safe, not corrupting — the
+  loser re-fetches and retries, same as any team without a queue does today).
+- **Not a security boundary.** Every guardrail here stops mistakes and
+  convention drift, not a truly adversarial agent. Shell access always
+  means `git push --no-verify`, deleting the hook, or editing the config on
+  purpose — nothing local-only can stop that.
+- **Guarantees a check ran — not that it's good.** It enforces that
+  `checkCommand` exists and passed, with 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. Normally "you" here is the agent, not
+  a human — CLAUDE.md tells it to resolve the conflict and re-run `land`,
+  same as any other bug; `checkCommand` still catches a bad resolution.
+- **Auto-pruning checks for a live Claude Code session, via `lsof`.** A
+  merged branch alone isn't enough — a brand-new, zero-commit lane is
+  *trivially* "merged" too, so pruning also refuses to touch a worktree
+  with a live Claude Code process in it. Deliberately narrower than "any
+  process at all": an orphaned MCP server or stray build process can
+  outlive the session that spawned it and otherwise keep an abandoned lane
+  stuck forever (confirmed live). Missing `lsof` fails closed — treats
+  liveness as unknown, never removes.
+- **The `WorktreeCreate` hook needs the host project's own real install.**
+  It runs via `npx claude-code-local-merge hook worktree-create` (no
+  `node_modules/.bin` on PATH for a raw hook, unlike an `npm run` script),
+  and npx silently falls back to an ephemeral, unpinned copy if it can't
+  resolve the package locally — which happened in production and masked a
+  broken install for two lane-landings. The hook now refuses to run at all
+  from npx's ephemeral cache, so a broken install fails loud immediately
+  instead of limping along on a mismatched stand-in.
+
+## 🧬 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 without them
+tripping over each other. 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/claude-code-local-merge.d.ts

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

package/dist/bin/claude-code-local-merge.js

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/**
+ * The claude-code-local-merge CLI. Every subcommand reads claude-code-local-merge.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, wirePackageJsonScripts, wirePreflightScript, PREFLIGHT_FILENAME } from "../lib/wire-hooks.js";
+import { resolveMainCheckout } from "../lib/main-checkout.js";
+import { pruneLandedLanes } from "../lib/prune-lanes.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("claude-code-local-merge 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");
+    // What actually got newly written or modified this run — only these need
+    // committing. If everything below was already wired from a previous run,
+    // there's nothing new to tell you to commit.
+    const writtenFiles = [];
+    if (hasConfig(root)) {
+        console.log("claude-code-local-merge init: claude-code-local-merge.config.mjs already exists — leaving it alone.");
+    }
+    else {
+        writtenFiles.push("claude-code-local-merge.config.mjs");
+        const detectedBranch = detectCurrentBranch(root);
+        const detectedCheck = detectCheckCommand(root);
+        const generated = {
+            ...DEFAULTS,
+            ...(detectedBranch ? { integrationBranch: detectedBranch } : {}),
+            ...(detectedCheck ? { checkCommand: detectedCheck } : {}),
+        };
+        const template = `// claude-code-local-merge.config.mjs — generated by \`claude-code-local-merge init\`. Edit freely.
+// Its presence here is what turns Claude Code Local Merge ON for this repo.
+
+/** @type {import("claude-code-local-merge").ClaudeCodeLocalMergeConfig} */
+export default ${JSON.stringify(generated, null, 2)};
+`;
+        writeFileSync(join(root, "claude-code-local-merge.config.mjs"), template);
+        console.log(`claude-code-local-merge init: wrote ${join(root, "claude-code-local-merge.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 claude-code-local-merge.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(`claude-code-local-merge init: wrote ${claudeMdPath}`);
+        writtenFiles.push("CLAUDE.md");
+    }
+    else if (!read(claudeMdPath, "utf8").includes(MARKER)) {
+        appendFileSync(claudeMdPath, `\n${snippet}`);
+        console.log(`claude-code-local-merge init: appended the Claude Code Local Merge workflow section to ${claudeMdPath}`);
+        writtenFiles.push("CLAUDE.md");
+    }
+    else {
+        console.log(`claude-code-local-merge init: ${claudeMdPath} already has the Claude Code Local Merge workflow section — leaving it alone.`);
+    }
+    const claudeSettingsResult = wireClaudeSettings(root);
+    switch (claudeSettingsResult) {
+        case "created":
+            console.log(`claude-code-local-merge init: wrote ${join(root, ".claude", "settings.json")} with the WorktreeCreate hook.`);
+            writtenFiles.push(".claude/settings.json");
+            break;
+        case "merged":
+            console.log(`claude-code-local-merge init: added the WorktreeCreate hook to your existing ${join(root, ".claude", "settings.json")}.`);
+            writtenFiles.push(".claude/settings.json");
+            break;
+        case "already-wired":
+            console.log("claude-code-local-merge init: .claude/settings.json already has the WorktreeCreate hook — leaving it alone.");
+            break;
+        case "unparseable":
+            console.log("claude-code-local-merge init: .claude/settings.json exists but isn't valid JSON — left untouched. Wire it manually,");
+            console.log("  see node_modules/claude-code-local-merge/hooks/claude-settings.example.json.");
+            break;
+    }
+    const prePushResult = wireHuskyPrePush(root);
+    switch (prePushResult) {
+        case "created":
+            console.log("claude-code-local-merge init: wrote .husky/pre-push.");
+            writtenFiles.push(".husky/pre-push");
+            break;
+        case "merged":
+            console.log("claude-code-local-merge init: appended Claude Code Local Merge's checks to your existing .husky/pre-push.");
+            writtenFiles.push(".husky/pre-push");
+            break;
+        case "already-wired":
+            console.log("claude-code-local-merge init: .husky/pre-push already wired — leaving it alone.");
+            break;
+        case "no-husky":
+            console.log("claude-code-local-merge init: no .husky/ directory found — pre-push hook NOT wired automatically.");
+            console.log("  Install Husky, or copy node_modules/claude-code-local-merge/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("claude-code-local-merge 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("claude-code-local-merge 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;
+        }
+    }
+    switch (wirePreflightScript(root, cfg.integrationBranch)) {
+        case "created":
+            console.log(`claude-code-local-merge init: wrote ${PREFLIGHT_FILENAME} (a self-contained pre-check "land"/"sync" run before landing — see comments in the file).`);
+            writtenFiles.push(PREFLIGHT_FILENAME);
+            break;
+        case "already-exists":
+            break; // don't overwrite — re-run init after changing integrationBranch if it needs updating
+    }
+    const scriptsResult = wirePackageJsonScripts(root);
+    switch (scriptsResult.result) {
+        case "added":
+            console.log(`claude-code-local-merge init: added "${scriptsResult.added.join('", "')}" to package.json scripts.`);
+            writtenFiles.push("package.json");
+            break;
+        case "already-wired":
+            console.log("claude-code-local-merge init: package.json already has all five scripts — leaving them alone.");
+            break;
+        case "no-package-json":
+            console.log("claude-code-local-merge init: no package.json found — scripts NOT wired automatically.");
+            console.log('  Add "land"/"sync"/"promote"/"preview"/"preview:restore" -> "claude-code-local-merge <name>", plus');
+            console.log(`  "preland"/"presync" -> "node ${PREFLIGHT_FILENAME} land"/"sync" yourself.`);
+            break;
+        case "unparseable":
+            console.log("claude-code-local-merge init: package.json exists but isn't valid JSON — left untouched. Wire the scripts manually.");
+            break;
+    }
+    console.log("");
+    console.log("Next steps:");
+    if (writtenFiles.length > 0) {
+        console.log(`  1. Commit what it wrote — ${writtenFiles.join(", ")}.`);
+        console.log("  2. claude --worktree <name> — the agent takes it from there.");
+    }
+    else {
+        console.log("  1. claude --worktree <name> — the agent takes it from there.");
+        console.log("     (everything was already wired — nothing new to commit)");
+    }
+}
+async function main() {
+    switch (command) {
+        case "init":
+            return init();
+        case "hook": {
+            const sub = rest[0];
+            if (sub === "worktree-create")
+                return runWorktreeCreateHook();
+            console.error(`claude-code-local-merge hook: unknown hook "${sub ?? ""}". Only "worktree-create" is supported.`);
+            process.exit(1);
+            return;
+        }
+        case "port": {
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                console.error("claude-code-local-merge port: no claude-code-local-merge.config found — not a lane.");
+                process.exit(1);
+            }
+            const cfg = await loadConfig(root);
+            const port = lanePort(process.cwd(), cfg);
+            if (port === null) {
+                console.error("claude-code-local-merge 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 "prune": {
+            // `land` already does this automatically as a side effect of every
+            // successful landing — this is the on-demand escape hatch for
+            // "clean these up right now" instead of waiting for the next lane to
+            // land something. Same safety rules apply: only already-merged
+            // branches, never anything with a live process inside, never the
+            // worktree this command itself is running from.
+            const root = findRepoRoot();
+            if (!root || !hasConfig(root)) {
+                console.error("claude-code-local-merge prune: no claude-code-local-merge.config found — nothing to do.");
+                process.exit(0);
+            }
+            const cfg = await loadConfig(root);
+            const mainTop = resolveMainCheckout(process.cwd());
+            const pruned = pruneLandedLanes(mainTop, cfg, process.cwd());
+            if (pruned.length === 0) {
+                console.log("claude-code-local-merge prune: nothing to clean up — no already-landed sibling lanes found.");
+            }
+            else {
+                const names = pruned.map((p) => p.split("/").pop()).join(", ");
+                console.log(`claude-code-local-merge prune: removed ${pruned.length} already-landed lane${pruned.length === 1 ? "" : "s"}: ${names}`);
+            }
+            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 Claude Code Local Merge 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("claude-code-local-merge check-push: nothing being pushed (already up to date) — skipping checks.");
+                process.exit(0);
+            }
+            if (process.env.CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH === "1") {
+                console.log("\n🚨 CLAUDE_CODE_LOCAL_MERGE_EMERGENCY_PUSH is set — bypassing the landing queue.\n");
+            }
+            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(`claude-code-local-merge — keep parallel coding agents in their lane.
+
+Usage:
+  claude-code-local-merge init                  write a starter claude-code-local-merge.config.mjs
+  claude-code-local-merge land                  rebase + push this lane onto the integration branch (queued)
+  claude-code-local-merge sync                  fast-forward the MAIN checkout to its upstream
+  claude-code-local-merge promote               ship the integration branch to production (human-only — never script this)
+  claude-code-local-merge preview [--restore]   swap the MAIN checkout to this lane's working tree, or restore it
+  claude-code-local-merge build-lock -- <cmd>   run <cmd>, serialized across every lane
+  claude-code-local-merge port                  print this lane's dev-server port
+  claude-code-local-merge hook worktree-create  (Claude Code WorktreeCreate hook — not for direct use)
+  claude-code-local-merge 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/bin/lanekeeper.d.ts

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