lanekeeper 0.1.0

package/dist/hooks/worktree-create.js

@@ -0,0 +1,150 @@
+/**
+ * The Claude Code WorktreeCreate hook. Claude Code already isolates agents
+ * in worktrees natively (`--worktree`, `isolation: "worktree"`) — this hook
+ * doesn't compete with that, it plugs into it. A WorktreeCreate hook
+ * "replaces default git behavior entirely" (Claude Code's own docs), so
+ * this script is responsible for actually creating the worktree; what it
+ * adds on top of the native flow is LaneKeeper's numbered-lane convention
+ * and a `node_modules` SYMLINK instead of a copy — Claude Code's own
+ * `.worktreeinclude` mechanism copies gitignored files in, which is fine
+ * for a `.env` file and genuinely expensive for `node_modules`.
+ *
+ * Per Claude Code's hook contract: print the new worktree's absolute path
+ * on stdout and exit 0, or print an error to stderr and exit non-zero to
+ * abort creation (WorktreeCreate is the one hook event that can block).
+ *
+ * There's no long-lived process behind this the way there was behind the
+ * old standalone launcher — the hook runs once and exits. So lane claiming
+ * can't be PID-liveness-based here; there's no PID to track. Instead the
+ * claim IS the worktree: a lane is free iff `<repo><worktreeSuffix><n>`
+ * doesn't exist on disk, and `git worktree add` failing on an
+ * already-claimed path is the same atomicity guarantee a `mkdir` race gave
+ * the old launcher, just delegated to git itself. When Claude Code (or you,
+ * or its cleanup sweep) removes a worktree, that lane number is free again
+ * automatically — nothing to release by hand.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, symlinkSync } from "node:fs";
+import { dirname, join, basename } from "node:path";
+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
+// away from spinning the CPU forever instead of failing loud — which is
+// precisely what happened here: an earlier, separate implementation of what
+// is now resolveMainCheckout used path.join instead of path.resolve, so
+// invoking this hook from INSIDE an already-created linked worktree (where
+// git reports an ABSOLUTE git-common-dir, not the relative ".git" a fresh
+// checkout reports) produced a nonsense path that never matched an existing
+// lane and never let `git worktree add` succeed either — an infinite loop,
+// confirmed burning 80%+ CPU indefinitely in production use. Fixing the path
+// bug alone doesn't rule out some other future bug in this class; capping
+// the loop means any of them fails loud instead of hanging.
+const MAX_LANE_ATTEMPTS = 1000;
+// Trying a lane number that turns out to already be claimed (the expected,
+// routine race with another concurrent hook invocation) is not an error
+// worth showing anyone — git's own "fatal: cannot lock ref" on that attempt
+// would otherwise leak to the terminal even though the hook recovers and
+// succeeds. Force stdout/stderr into pipes explicitly rather than trusting
+// the ambient default, so a probing attempt is always silent until we
+// decide it's actually fatal.
+function tryGit(args, cwd) {
+    try {
+        return {
+            ok: true,
+            out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(),
+        };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: `${err.stdout ?? ""}${err.stderr ?? ""}` };
+    }
+}
+/**
+ * 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 function createLane(mainTop, cfg) {
+    // Clean up administrative entries for worktrees whose directories are
+    // already gone (e.g. someone `rm -rf`'d one instead of `git worktree
+    // remove`) so reusing that lane number's branch name doesn't fail with
+    // "already checked out elsewhere."
+    tryGit(["worktree", "prune"], mainTop);
+    const repoName = basename(mainTop);
+    let lane = 0;
+    for (;;) {
+        lane += 1;
+        if (lane > MAX_LANE_ATTEMPTS) {
+            throw new Error(`could not claim a lane after ${MAX_LANE_ATTEMPTS} attempts — is mainTop ('${mainTop}') actually the repo root?`);
+        }
+        const wt = join(dirname(mainTop), `${repoName}${cfg.worktreeSuffix}${lane}`);
+        if (existsSync(wt))
+            continue; // still claimed — try the next lane
+        const branch = `${cfg.branchPrefix}${lane}`;
+        const branchExists = tryGit(["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], mainTop).ok;
+        // Base every new lane on the main checkout's own current HEAD — never on
+        // origin/integrationBranch. The main checkout is kept fast-forwarded by
+        // `sync` precisely so its local HEAD IS the trusted, up-to-date view;
+        // reading origin directly instead can be *behind* local HEAD (a commit
+        // made here but not yet pushed) and silently drop it from every new
+        // lane. That's not a hypothetical: it breaks the literal Quickstart —
+        // `init` writes lanekeeper.config.mjs/CLAUDE.md/.claude locally, and the
+        // very first lane created before that commit is pushed anywhere would
+        // otherwise come up with none of it.
+        let add;
+        if (branchExists) {
+            add = tryGit(["worktree", "add", wt, branch], mainTop);
+        }
+        else {
+            add = tryGit(["worktree", "add", wt, "-b", branch], mainTop);
+        }
+        if (!add.ok) {
+            // Someone else claimed this exact lane between our existsSync check
+            // and `git worktree add` — the same race a `mkdir` guards against.
+            // Try the next one.
+            continue;
+        }
+        for (const rel of cfg.symlinks) {
+            const src = join(mainTop, rel);
+            const dest = join(wt, rel);
+            if (!existsSync(src) || existsSync(dest))
+                continue;
+            try {
+                mkdirSync(dirname(dest), { recursive: true });
+                symlinkSync(src, dest);
+            }
+            catch {
+                /* best-effort — a missing symlink degrades to "run npm install," not a hard failure */
+            }
+        }
+        return { wt, branch, lane };
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runWorktreeCreateHook() {
+    let input = {};
+    try {
+        input = JSON.parse(await readStdin());
+    }
+    catch {
+        /* no/invalid stdin — fall back to process.cwd() below */
+    }
+    const fromCwd = input.cwd ?? process.cwd();
+    try {
+        const mainTop = resolveMainCheckout(fromCwd);
+        const cfg = hasConfig(mainTop) ? await loadConfig(mainTop) : { ...DEFAULTS };
+        const { wt } = createLane(mainTop, cfg);
+        process.stdout.write(wt + "\n");
+        process.exit(0);
+    }
+    catch (err) {
+        process.stderr.write(`lanekeeper worktree-create hook failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}

package/dist/land.d.ts

@@ -0,0 +1 @@
+export declare function land(): Promise<void>;

package/dist/land.js

@@ -0,0 +1,128 @@
+/**
+ * land.ts — the ONLY sanctioned way for a lane to land onto the integration
+ * branch.
+ *
+ * Left to behavioral convention alone ("only one lane rebases-and-pushes at
+ * a time"), several lanes going green around the same time all rebase and
+ * push at once: pushes race, the loser's checks run against an already-stale
+ * remote, and when something breaks everyone ends up mid-push fixing the
+ * same failure. This makes "land" a single cross-worktree FIFO queue
+ * (queue-lock.ts — the same crash-safe mechanics build-lock uses) so only
+ * one lane is ever fetching, rebasing, pushing, and checking at a time.
+ *
+ * A failed attempt releases the lock rather than holding it hostage — the
+ * next lane in line lands next while the failed lane fixes and re-runs
+ * `lanekeeper land` (re-entering the back of the queue). That keeps one
+ * broken lane from blocking every OTHER lane's unrelated, ready-to-land
+ * work, while still guaranteeing no two lanes are ever mid-push at once.
+ *
+ * This is only half the guarantee, though — a convention that says "always
+ * run `lanekeeper land`" is exactly the kind of rule a confused agent (or a
+ * human under time pressure) eventually skips by hand-rolling `git push`.
+ * The other half lives in hooks/pre-push: it hard-rejects a direct push to
+ * the integration branch that didn't set LANEKEEPER_LANDING=1, which this
+ * script sets right before its own push and nothing else legitimately would.
+ * Wire that hook up (see the README) and the queue isn't a convention
+ * anymore — it's the only door.
+ *
+ *   Usage:  lanekeeper land   (run from a lane worktree, on its own branch)
+ */
+import { execSync, spawnSync } from "node:child_process";
+import { createQueueLock } from "./lib/queue-lock.js";
+import { hasConfig, loadConfig } from "./lib/config.js";
+import { resolveMainCheckout } from "./lib/main-checkout.js";
+import { pruneLandedLanes } from "./lib/prune-lanes.js";
+import { sync } from "./sync.js";
+const DIM = "\x1b[2m", RESET = "\x1b[0m", RED = "\x1b[31m", GREEN = "\x1b[32m";
+export async function land() {
+    if (!hasConfig()) {
+        console.error("lanekeeper land: no lanekeeper.config found at the repo root. Run `lanekeeper init` first.");
+        process.exit(1);
+    }
+    const cfg = await loadConfig();
+    const branch = execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+    if (branch === cfg.integrationBranch || cfg.protectedBranches.includes(branch) || branch === "HEAD") {
+        console.error(`lanekeeper land: refusing to run from '${branch}' — land is for lane branches only.`);
+        process.exit(1);
+    }
+    // A rebase refuses to run at all with a dirty tree. Build-tool-regenerated
+    // noise shouldn't block landing — discard ONLY the configured
+    // regenerableFiles, exactly like sync does for the fast-forward on the
+    // other end. Any other dirty file is real work-in-progress: leave it alone
+    // and let the rebase fail loud.
+    const regenerable = new Set(cfg.regenerableFiles);
+    const status = execSync("git status --porcelain", { encoding: "utf8" });
+    const dirty = status
+        .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) {
+        execSync(`git checkout -- ${dirty.map((f) => `"${f}"`).join(" ")}`);
+    }
+    const lock = createQueueLock("land");
+    await lock.acquire({
+        label: branch,
+        onWait: ({ ahead, holder }) => {
+            if (ahead > 0) {
+                console.log(`${DIM}[land-queue] ${branch}: waiting — ${ahead} landing${ahead === 1 ? "" : "s"} ahead…${RESET}`);
+            }
+            else if (holder) {
+                console.log(`${DIM}[land-queue] ${branch}: next up — waiting for '${holder.label ?? holder.lane}' to finish landing…${RESET}`);
+            }
+        },
+    });
+    let exitCode = 0;
+    try {
+        console.log(`${DIM}[land-queue] ${branch}: lock acquired — landing…${RESET}`);
+        console.log(`${DIM}fetching origin/${cfg.integrationBranch}…${RESET}`);
+        execSync(`git fetch origin ${cfg.integrationBranch} --quiet`, { stdio: "inherit" });
+        console.log(`${DIM}rebasing onto origin/${cfg.integrationBranch}…${RESET}`);
+        const rebase = spawnSync("git", ["rebase", `origin/${cfg.integrationBranch}`], { stdio: "inherit" });
+        if (rebase.status !== 0) {
+            spawnSync("git", ["rebase", "--abort"], { stdio: "ignore" });
+            console.error(`\n${RED}land: rebase onto origin/${cfg.integrationBranch} conflicted — aborted, working tree left clean.${RESET}`);
+            console.error(`Resolve it yourself (git fetch origin ${cfg.integrationBranch} && git rebase origin/${cfg.integrationBranch}), then re-run 'lanekeeper land'.`);
+            exitCode = 1;
+        }
+        else {
+            console.log(`${DIM}pushing to ${cfg.integrationBranch} (this is where your CI/checks hook runs)…${RESET}`);
+            const push = spawnSync("git", ["push", "origin", `HEAD:${cfg.integrationBranch}`], {
+                stdio: "inherit",
+                env: { ...process.env, LANEKEEPER_LANDING: "1" },
+            });
+            if (push.status !== 0) {
+                console.error(`\n${RED}land: push to ${cfg.integrationBranch} failed — see output above.${RESET}`);
+                console.error(`Fix the failure, then re-run 'lanekeeper land'.`);
+                exitCode = 1;
+            }
+            else {
+                console.log(`${GREEN}✓ ${branch} landed on ${cfg.integrationBranch}.${RESET}`);
+                // Landing isn't "done" until the checkout that actually serves your
+                // dev server can see it — call sync in-process rather than shelling
+                // back out to the CLI, so this doesn't depend on `lanekeeper` being
+                // resolvable on PATH.
+                exitCode = await sync();
+                // Housekeeping, never a reason to fail this landing: sweep sibling
+                // lanes whose OWN branch already made it upstream (nothing created
+                // ever tears a worktree down on the way out) so they don't
+                // accumulate on disk forever waiting for someone to remember.
+                try {
+                    const mainTop = resolveMainCheckout(process.cwd());
+                    const pruned = pruneLandedLanes(mainTop, cfg, process.cwd());
+                    if (pruned.length > 0) {
+                        const names = pruned.map((p) => p.split("/").pop()).join(", ");
+                        console.log(`${DIM}pruned ${pruned.length} already-landed lane${pruned.length === 1 ? "" : "s"}: ${names}${RESET}`);
+                    }
+                }
+                catch {
+                    /* best-effort — never block a successful landing over cleanup */
+                }
+            }
+        }
+    }
+    finally {
+        lock.release();
+    }
+    process.exit(exitCode);
+}

package/dist/lib/check-command.d.ts

@@ -0,0 +1,29 @@
+import type { LaneKeeperConfig } from "./config.js";
+/**
+ * Which package manager actually installed this project — detected from its
+ * lockfile, since that's the one signal that's always there regardless of
+ * what's on PATH. Defaulting straight to npm regardless of the real answer
+ * isn't a hypothetical: a pnpm workspace's scripts can rely on pnpm-specific
+ * behavior (workspace: protocol deps, `--filter`), and `npm run` may not
+ * even be installed on a pnpm/yarn/bun-only machine.
+ */
+export declare function detectPackageManager(root: string): "npm" | "pnpm" | "yarn" | "bun";
+/** Look at package.json's own scripts for something to run — best-effort, never throws. */
+export declare function detectCheckCommand(root: string): string | null;
+/**
+ * Run the configured check command. Returns the exit code to propagate.
+ *
+ * A null checkCommand is only ever silent if checksRequired was explicitly
+ * turned off — the default is to FAIL the push, because a merge queue that
+ * lets unverified code through by default isn't one, it's a false sense of
+ * safety.
+ *
+ * Always runs from `root`, not whatever the caller's cwd happens to be. In
+ * the real git-push flow that's moot — git always resets cwd to the repo
+ * root before running a hook — but `check-push` is also a directly
+ * user-runnable command, and silently depending on git's hook behavior for
+ * correctness (instead of just being correct on its own) is exactly the
+ * kind of implicit assumption that bites the first time someone runs it by
+ * hand from a subdirectory.
+ */
+export declare function runCheckCommand(cfg: Pick<LaneKeeperConfig, "checkCommand" | "checksRequired">, root: string): number;

package/dist/lib/check-command.js

@@ -0,0 +1,83 @@
+/**
+ * The part of the merge queue that actually earns the name: running your
+ * lint/typecheck/test/build before a landing is allowed through. Without
+ * this, "merge queue" is just "push queue" — serialized, but blind.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+// Priority order: prefer a script that already bundles multiple checks
+// (a repo's own "check" or CI script) over a narrower "test" script, but
+// take whatever exists rather than assume one specific name.
+const CANDIDATE_SCRIPTS = ["check:push", "check", "ci", "test"];
+/**
+ * Which package manager actually installed this project — detected from its
+ * lockfile, since that's the one signal that's always there regardless of
+ * what's on PATH. Defaulting straight to npm regardless of the real answer
+ * isn't a hypothetical: a pnpm workspace's scripts can rely on pnpm-specific
+ * behavior (workspace: protocol deps, `--filter`), and `npm run` may not
+ * even be installed on a pnpm/yarn/bun-only machine.
+ */
+export function detectPackageManager(root) {
+    if (existsSync(join(root, "pnpm-lock.yaml")) || existsSync(join(root, "pnpm-workspace.yaml")))
+        return "pnpm";
+    if (existsSync(join(root, "yarn.lock")))
+        return "yarn";
+    if (existsSync(join(root, "bun.lockb")) || existsSync(join(root, "bun.lock")))
+        return "bun";
+    return "npm";
+}
+/** Look at package.json's own scripts for something to run — best-effort, never throws. */
+export function detectCheckCommand(root) {
+    const pkgPath = join(root, "package.json");
+    if (!existsSync(pkgPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const found = CANDIDATE_SCRIPTS.find((name) => pkg.scripts?.[name]);
+        return found ? `${detectPackageManager(root)} run ${found}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the configured check command. Returns the exit code to propagate.
+ *
+ * A null checkCommand is only ever silent if checksRequired was explicitly
+ * turned off — the default is to FAIL the push, because a merge queue that
+ * lets unverified code through by default isn't one, it's a false sense of
+ * safety.
+ *
+ * Always runs from `root`, not whatever the caller's cwd happens to be. In
+ * the real git-push flow that's moot — git always resets cwd to the repo
+ * root before running a hook — but `check-push` is also a directly
+ * user-runnable command, and silently depending on git's hook behavior for
+ * correctness (instead of just being correct on its own) is exactly the
+ * kind of implicit assumption that bites the first time someone runs it by
+ * hand from a subdirectory.
+ */
+export function runCheckCommand(cfg, root) {
+    if (!cfg.checkCommand) {
+        if (cfg.checksRequired) {
+            console.error([
+                "",
+                "✋ No checkCommand configured, and checksRequired is true (the default).",
+                "   This push would land with NOTHING verifying it — no lint, no test, no build.",
+                "   Set checkCommand in lanekeeper.config.mjs, e.g. \"npm run check\".",
+                "   Or, if you really have nothing to check yet, set checksRequired: false —",
+                "   deliberately, so it's a visible, committed choice, not a silent gap.",
+                "",
+            ].join("\n"));
+            return 1;
+        }
+        console.log("lanekeeper check-push: no checkCommand configured (checksRequired: false — running with no checks, on purpose).");
+        return 0;
+    }
+    console.log(`lanekeeper check-push: running "${cfg.checkCommand}"…`);
+    const result = spawnSync(cfg.checkCommand, { shell: true, stdio: "inherit", cwd: root });
+    if (result.status !== 0) {
+        console.error(`\n✋ checkCommand failed (exit ${result.status ?? 1}) — landing blocked.`);
+    }
+    return result.status ?? 1;
+}

package/dist/lib/check-push.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The enforcement half of the landing queue. `land.ts` (and `promote.ts`)
+ * are *conventions* — "always land through here" — and conventions are
+ * exactly the kind of rule a confused agent, or a human moving fast,
+ * eventually skips by hand-rolling `git push`. This is the mechanism that
+ * makes the convention unnecessary to trust: it reads the same ref-update
+ * lines git's pre-push hook always gets on stdin, and rejects a direct push
+ * to the integration branch or any protected/production branch by default.
+ *
+ * `land.ts` sets LANEKEEPER_LANDING=1 right before its own push — that's
+ * the only thing that legitimately unblocks the integration branch on the
+ * normal path. `promote.ts` pushes to productionBranch with `--no-verify`,
+ * which skips this hook entirely (same as git always does for --no-verify).
+ *
+ * Every branch here (including the integration branch, which used to have
+ * NO override at all) also has a genuine emergency hatch: it needs BOTH
+ * LANEKEEPER_EMERGENCY_PUSH=1 (declares the intent) AND
+ * LANEKEEPER_EMERGENCY_PUSH_CONFIRM=<exact branch name> (names the specific
+ * target) set and matching. Two independent, specific pieces of intent, not
+ * one flag — the CLI's check-push handler fills the second one in via an
+ * interactive /dev/tty prompt if you only set the first, so a human doing
+ * this on purpose types the branch name once; nothing about it happens by
+ * flipping a single boolean.
+ */
+import type { LaneKeeperConfig } from "./config.js";
+export interface RefUpdate {
+    localRef: string;
+    localSha: string;
+    remoteRef: string;
+    remoteSha: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    message?: string;
+}
+export declare function parseRefUpdates(stdin: string): RefUpdate[];
+export declare function checkPush(refUpdates: RefUpdate[], cfg: Pick<LaneKeeperConfig, "integrationBranch" | "productionBranch" | "protectedBranches">, env: NodeJS.ProcessEnv): CheckResult;

package/dist/lib/check-push.js

@@ -0,0 +1,48 @@
+export function parseRefUpdates(stdin) {
+    return stdin
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [localRef, localSha, remoteRef, remoteSha] = line.split(/\s+/);
+        return { localRef: localRef ?? "", localSha: localSha ?? "", remoteRef: remoteRef ?? "", remoteSha: remoteSha ?? "" };
+    });
+}
+function emergencyConfirmed(branch, env) {
+    return env.LANEKEEPER_EMERGENCY_PUSH === "1" && env.LANEKEEPER_EMERGENCY_PUSH_CONFIRM === branch;
+}
+export function checkPush(refUpdates, cfg, env) {
+    const integrationRef = `refs/heads/${cfg.integrationBranch}`;
+    const protectedBranches = cfg.productionBranch ? [...cfg.protectedBranches, cfg.productionBranch] : cfg.protectedBranches;
+    const protectedRefs = new Set(protectedBranches.map((b) => `refs/heads/${b}`));
+    for (const { remoteRef } of refUpdates) {
+        const branch = remoteRef.replace("refs/heads/", "");
+        if (protectedRefs.has(remoteRef) && !emergencyConfirmed(branch, env)) {
+            return {
+                ok: false,
+                message: [
+                    "",
+                    `✋ Direct pushes to '${branch}' are blocked.`,
+                    `   This is a protected branch — promote it deliberately, not with a stray push.`,
+                    `   Emergency override:  LANEKEEPER_EMERGENCY_PUSH=1 git push …  (you'll be asked to`,
+                    `   type "${branch}" to confirm — or set LANEKEEPER_EMERGENCY_PUSH_CONFIRM=${branch} yourself for a non-interactive push).`,
+                    "",
+                ].join("\n"),
+            };
+        }
+        if (remoteRef === integrationRef && env.LANEKEEPER_LANDING !== "1" && !emergencyConfirmed(branch, env)) {
+            return {
+                ok: false,
+                message: [
+                    "",
+                    `✋ Direct pushes to '${cfg.integrationBranch}' are blocked — landing goes through the queue.`,
+                    `   Land your work:  lanekeeper land`,
+                    `   Genuine emergency:  LANEKEEPER_EMERGENCY_PUSH=1 git push …  (you'll be asked to`,
+                    `   type "${cfg.integrationBranch}" to confirm).`,
+                    "",
+                ].join("\n"),
+            };
+        }
+    }
+    return { ok: true };
+}

package/dist/lib/claude-md-snippet.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The actual "baked into Claude" mechanism — not a hook, not magic. Claude
+ * Code reads CLAUDE.md automatically at the start of every session and
+ * follows it as standing instructions. So instead of expecting a human to
+ * remember to type `lanekeeper land` after every change, this snippet tells
+ * the agent itself to do it — the same way a real production setup that
+ * runs several parallel Claude Code agents keeps its own human out of the
+ * loop for anything except the final promotion to production.
+ *
+ * `lanekeeper init` writes this into CLAUDE.md (creating it if missing,
+ * appending — once, idempotently, via MARKER — if one already exists) so
+ * every session in the repo picks it up with zero extra setup per agent.
+ */
+import type { LaneKeeperConfig } from "./config.js";
+export declare const MARKER = "<!-- lanekeeper:workflow -->";
+export declare function claudeMdSnippet(cfg: LaneKeeperConfig): string;

package/dist/lib/claude-md-snippet.js

@@ -0,0 +1,18 @@
+export const MARKER = "<!-- lanekeeper:workflow -->";
+export function claudeMdSnippet(cfg) {
+    const promoteBlock = cfg.productionBranch
+        ? `- **\`${cfg.productionBranch}\` is production, and it is not your call.** Only a human runs \`lanekeeper promote\` (${cfg.integrationBranch} → ${cfg.productionBranch}), on their own schedule. Never run it yourself, never suggest running it as part of "finishing" a task — landing on \`${cfg.integrationBranch}\` is the finish line for you.`
+        : `- There's no separate production branch configured — \`${cfg.integrationBranch}\` already is it. Landing is the whole deal.`;
+    return `${MARKER}
+## LaneKeeper workflow
+
+This repo uses [LaneKeeper](https://github.com/funador/lanekeeper) to run parallel Claude Code agents without them racing each other. It's not a suggestion — follow it by default, every session, without being asked:
+
+- **You're probably already in a lane.** If you were started with \`claude --worktree <name>\`, LaneKeeper's \`WorktreeCreate\` hook already isolated you into your own git worktree and branch. Just work.
+- **Land the moment your change is green — don't ask first.** Run \`lanekeeper land\` yourself once tests/build/lint pass. This is pre-authorized, standard workflow, not a decision that needs sign-off. It rebases onto \`${cfg.integrationBranch}\`, pushes through the FIFO landing queue, and syncs the dev checkout — that whole sequence is "done," not "pushed to a branch and waiting."
+- **Never push \`${cfg.integrationBranch}\` directly.** \`git push origin HEAD:${cfg.integrationBranch}\` is rejected by the pre-push hook anyway — always go through \`lanekeeper land\`.
+- **A failed \`lanekeeper land\` is not a stopping point — landed is the only "done."** A rebase conflict aborts safely and leaves your working tree clean; that's expected, not an error to report and hand back. Resolve the conflicting diff yourself the same way you'd fix any other bug, \`git add\` the result, \`git rebase --continue\`, then re-run \`lanekeeper land\` — repeat until it actually lands. Don't say a change is finished, complete, or ready while it's still sitting unlanded in your lane; \`checkCommand\` still gates the real push regardless of how many attempts it took, so a wrong resolution gets caught there, not by a human reading it first.
+- **Use \`lanekeeper build-lock -- <cmd>\` for anything heavy** (a full build, a slow test suite) so parallel lanes take turns instead of thrashing the machine together.
+${promoteBlock}
+`;
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,92 @@
+export interface LaneKeeperConfig {
+    /** Lane branches are named "<branchPrefix><n>" — lane/1, lane/2, ... */
+    branchPrefix: string;
+    /** Sibling worktree dirs are named "<repo><worktreeSuffix><n>" — ../myapp-lane-1. */
+    worktreeSuffix: string;
+    /** First lane's dev-server port. Lane n gets portBase + n. */
+    portBase: number;
+    /** The shared branch `lanekeeper land` rebases onto and pushes to. */
+    integrationBranch: string;
+    /**
+     * The production branch, if you run a two-stage model (agents land on
+     * `integrationBranch`; a human promotes that to `productionBranch` on
+     * their own schedule via `lanekeeper promote`). `null` means
+     * `integrationBranch` IS production — no separate promotion step, and
+     * `lanekeeper promote` is a no-op. When set, this branch is automatically
+     * protected by the pre-push hook — you don't need to also list it in
+     * `protectedBranches`.
+     */
+    productionBranch: string | null;
+    /**
+     * Extra branches the pre-push hook refuses a *direct* push to, beyond
+     * integrationBranch (always protected) and productionBranch (protected
+     * automatically when set). Most repos running the standard two-stage
+     * model don't need this at all.
+     */
+    protectedBranches: string[];
+    /**
+     * Files a build tool regenerates on its own (next-env.d.ts, a rewritten
+     * tsconfig "include" array, ...) that should never block a rebase or a
+     * fast-forward. Empty by default — you'll meet your first one the hard
+     * way, and then you add it here once, for good.
+     */
+    regenerableFiles: string[];
+    /**
+     * Git-ignored paths copied by reference (symlinked) into every new lane
+     * so it never needs a fresh install or a copy of your secrets.
+     */
+    symlinks: string[];
+    /**
+     * Build-output directories `preview` never copies onto the main checkout,
+     * on top of the fixed, always-excluded set (.git, node_modules, .env,
+     * .env.local). `preview` itself doesn't know or care what framework
+     * you're running — it just rsyncs source files onto a checkout your dev
+     * server is watching. The default list covers the common cases; add your
+     * own (".output" for Nuxt, ".svelte-kit" for SvelteKit, ...) rather than
+     * assuming this tool knows your build tool.
+     */
+    buildOutputDirs: string[];
+    /**
+     * The command `lanekeeper check-push` runs (in addition to the branch
+     * protections) before a landing is allowed through — your lint/typecheck/
+     * test/build, whatever "green" means for this repo. `null` means nothing
+     * runs. That's a real, dangerous state for a tool whose whole pitch is
+     * "tested before merge," so it's only silent if `checksRequired` is
+     * explicitly set to `false` too — otherwise a null checkCommand FAILS the
+     * push rather than landing something nobody verified.
+     */
+    checkCommand: string | null;
+    /**
+     * When true (the default) and `checkCommand` is null, `check-push` fails
+     * the push instead of landing unverified code. Set to `false` yourself to
+     * deliberately run with no checks — a real repo state (nothing to test
+     * yet), but one that should be a visible, committed, code-reviewable
+     * choice, not a silent default.
+     */
+    checksRequired: boolean;
+}
+export declare const DEFAULTS: LaneKeeperConfig;
+/**
+ * Fail loud on a malformed config instead of silently misbehaving three
+ * commands later. Returns a list of human-readable problems — empty means
+ * valid.
+ */
+export declare function validateConfig(cfg: LaneKeeperConfig): string[];
+/**
+ * The repo's actual current branch, so `init` doesn't blindly assume "main"
+ * — plenty of real repos still default to "master" (or something else
+ * entirely), and a generated config pointing at a branch that doesn't exist
+ * is exactly the kind of out-of-the-box friction this tool exists to avoid.
+ * Returns null (letting the caller fall back to DEFAULTS) if there's no
+ * commit yet or HEAD is detached.
+ */
+export declare function detectCurrentBranch(cwd?: string): string | null;
+export declare function findRepoRoot(cwd?: string): string | null;
+export declare function configPath(cwd?: string): string | null;
+export declare function hasConfig(cwd?: string): boolean;
+/**
+ * Load lanekeeper.config.(m)js from the current repo, merged over DEFAULTS.
+ * Throws with every problem listed if the merged config is invalid — a
+ * config that's silently wrong is worse than a command that refuses to run.
+ */
+export declare function loadConfig(cwd?: string): Promise<LaneKeeperConfig>;