lanekeeper 0.1.3 → 0.1.5

package/README.md

@@ -49,6 +49,30 @@ GitHub already ships a merge queue. Two things it costs you that this doesn't:
 Same idea — serialize landings, test before merge, keep history clean — run
 locally instead of in someone else's billed cloud. 💸
 
+## 🧭 Prior art (so you don't have to wonder)
+
+Nothing here was invented in isolation — worth naming what already existed
+before you find it yourself:
+
+- **[block/agent-task-queue](https://github.com/block/agent-task-queue)**
+  already solves "concurrent agents thrash your machine running simultaneous
+  builds," standalone, with no git or worktree awareness at all.
+  `build-lock` here does the same narrow job, just wired into `land` and
+  lanes instead of running on its own.
+- **[Overstory](https://github.com/jayminwest/overstory)** (now archived)
+  built a FIFO merge queue plus a liveness-based watchdog for a fleet of
+  coding agents — the closest prior match to the landing queue and `prune`
+  here. It's a bigger, multi-runtime orchestration framework with its own
+  agent/worktree layer, not something that plugs into Claude Code's *native*
+  `--worktree`/hook system the way this does; its stated successor moved to
+  a hosted, cloud control-plane model.
+
+What I couldn't find shipped anywhere else, as of this writing: this
+specific combination — sitting on top of Claude Code's own worktree hook
+instead of reimplementing it, a landing queue enforced at the git pre-push
+hook layer, and liveness-aware auto-pruning — as one small, zero-cost, local
+package. If you know of one, open an issue.
+
 ## 🧰 What's in the box
 
 | Command | What it does |
@@ -266,6 +290,19 @@ Things a sharp reader should already know before they ask:
   refuses to touch any worktree with a live process's cwd inside it right
   now. That check needs `lsof` on PATH; if it's missing, pruning fails
   closed (treats liveness as unknown, never removes) rather than guessing.
+- **The `WorktreeCreate` hook needs the host project's own real install.**
+  It runs via `npx lanekeeper hook worktree-create` (a raw hook command has
+  no `node_modules/.bin` on its PATH, unlike an `npm run` script) — but npx
+  silently falls back to fetching an ephemeral, unpinned copy when it can't
+  resolve the package locally, which is exactly what happens if the host
+  project's own `node_modules` install of lanekeeper is missing or
+  mid-upgrade. That's a real failure mode, not hypothetical: it happened in
+  production and the fallback ran silently long enough to mask a broken
+  install for two lane-landings. The hook now refuses to run at all if it
+  detects it's executing from npx's ephemeral cache rather than the
+  project's own installed copy, so a broken install fails loud immediately
+  (`npm install` and retry) instead of quietly limping along on a
+  mismatched stand-in version.
 
 ## 🧬 Where this came from
 

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

@@ -10,4 +10,5 @@ export declare function createLane(mainTop: string, cfg: LaneKeeperConfig): {
     branch: string;
     lane: number;
 };
+export declare function isEphemeralNpxCopy(selfPath: string): boolean;
 export declare function runWorktreeCreateHook(): Promise<void>;

package/dist/hooks/worktree-create.js

@@ -25,7 +25,8 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, symlinkSync } from "node:fs";
-import { dirname, join, basename } from "node:path";
+import { dirname, join, basename, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadConfig, hasConfig, DEFAULTS } from "../lib/config.js";
 import { resolveMainCheckout } from "../lib/main-checkout.js";
 // A lane-claim loop with no upper bound is exactly one path-resolution bug
@@ -121,6 +122,24 @@ export function createLane(mainTop, cfg) {
         return { wt, branch, lane };
     }
 }
+// `.claude/settings.json` invokes this hook via `npx lanekeeper hook
+// worktree-create` rather than a project script, precisely because a raw
+// hook command has no `node_modules/.bin` on its PATH the way `npm run`
+// does — npx's own directory-walking local resolution is what makes that
+// work at all. The problem: npx treats a package it can't resolve locally as
+// license to silently fetch an ephemeral, unpinned copy from the registry
+// and run *that* instead of failing — which is exactly what happens when the
+// host project's own install of lanekeeper is missing or mid-upgrade (npm
+// removes the old version's files before extracting the new one; anything
+// that interrupts that leaves precisely this state). That fallback ran
+// silently for long enough in production to block two lanes from landing
+// before anyone noticed node_modules was broken. Refuse to proceed if this
+// module is executing from npx's ephemeral cache instead of the project's
+// own installed copy, so a broken install fails loud immediately instead of
+// limping along on a stand-in version nobody asked for.
+export function isEphemeralNpxCopy(selfPath) {
+    return selfPath.includes(`${sep}_npx${sep}`);
+}
 async function readStdin() {
     const chunks = [];
     for await (const chunk of process.stdin)
@@ -137,6 +156,10 @@ export async function runWorktreeCreateHook() {
     }
     const fromCwd = input.cwd ?? process.cwd();
     try {
+        if (isEphemeralNpxCopy(fileURLToPath(import.meta.url))) {
+            throw new Error("running from npx's ephemeral cache, not this project's own installed dependency — " +
+                "node_modules is missing or broken. Run `npm install` in the main checkout and try again.");
+        }
         const mainTop = resolveMainCheckout(fromCwd);
         const cfg = hasConfig(mainTop) ? await loadConfig(mainTop) : { ...DEFAULTS };
         const { wt } = createLane(mainTop, cfg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lanekeeper",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "The local, zero-cost merge queue for parallel Claude Code agents. Plugs into Claude Code's native worktree isolation; one build at a time, one landing at a time, zero races.",
   "type": "module",
   "license": "MIT",