heyspex 0.1.0 → 0.2.1

package/dev-factory/lib/worktree-allocator.mjs

@@ -0,0 +1,744 @@
+#!/usr/bin/env node
+// dev-factory/lib/worktree-allocator.mjs
+// CLAIM-BOUND WORKTREE ALLOCATION — the session-scoped layer on top of the build-scoped
+// engine primitives in dev-factory/engine/worktree.mjs.
+// Task: HS-L4Q5 (epic HS-03DO "Claim-bound worktree isolation for parallel agent sessions").
+//
+// The engine owns ONE lifecycle: a short-lived, detached, per-candidate gate worktree that the
+// dev-factory loop creates and tears down inside a single build (marker `kind: "build"`). This
+// module owns a SECOND, longer-lived lifecycle: a worktree bound to an agent's CLAIM on a spec
+// (marker `kind: "session"`), on its own `claim/<FILE KEY>` branch, which outlives any single
+// build and is reclaimed only when the claim is released / the owner dies / the console says the
+// claim is no longer active — and never while it holds uncommitted work.
+//
+// Everything here is built ON the engine primitives (makeCtx / setupWorktree / teardownWorktree /
+// sweepStaleWorktrees / makeLink / git / isPidAlive / OWNER_FILE), never forked from them. The
+// hard-won Windows lessons therefore apply unchanged:
+//   - node_modules is JUNCTIONED (root + workspace), never copied.
+//   - git always runs with core.longpaths=true (engine `git()`).
+//   - teardown removes the junction LINKS first, THEN `git worktree remove` — never a recursive
+//     delete through a live junction (that deletes the REAL node_modules).
+//   - Windows paths compare case-insensitively.
+//
+// Every exported function takes the engine `ctx` (from makeCtx) plus an injectable
+// `deps = { git, fs, now, isPidAlive, claimIsActive, fetch, consoleUrl }` so the whole surface is
+// testable without touching the real repo or the real console. Left unset, `claimIsActive` is
+// backed by the console's /api/claims (createConsoleClaimChecker) — one round trip per reap.
+//
+// LIVENESS IS THREE-VALUED, and that is the safety property this module turns on. A session's
+// owner pid is normally UNKNOWN (`null`), because on Windows the launcher that created the
+// worktree exits seconds after the agent starts; and the console can answer "no claim", "claimed",
+// or nothing at all. Only POSITIVE evidence of death — a release marker, a pid that is provably
+// gone, or a successful console read that lists no claim — makes a worktree reclaimable, and only
+// then if it holds nothing uncommitted.
+//
+// CLI:
+//   node dev-factory/lib/worktree-allocator.mjs <list|alloc|release|reap|rebind> [flags]
+
+import {
+  existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, lstatSync, rmSync, realpathSync,
+} from "node:fs";
+import { join, resolve, basename } from "node:path";
+import {
+  makeCtx, setupWorktree, teardownWorktree, sweepStaleWorktrees,
+  OWNER_FILE, isPidAlive, makeLink, git, slug,
+} from "../engine/worktree.mjs";
+import { resolveConsoleUrl } from "../../scripts/lib/console-url-resolver.mjs";
+
+// Re-exported so callers of this module never need to reach past it into the engine.
+export { makeCtx, setupWorktree, teardownWorktree, sweepStaleWorktrees, OWNER_FILE };
+
+// Stable exit codes for the CLI mode below.
+// mirrors spex-console/src/lib/cli/control-shared.ts
+const EXIT_OK = 0;            // success
+const EXIT_USAGE = 1;         // unknown verb/flag, malformed command
+const EXIT_CHECK_FAILED = 2;  // a read-only check ran correctly and its answer is "no"
+const EXIT_INVALID_ARG = 11;  // a required argument is missing or unparseable
+const EXIT_WRITE_FAILED = 13; // the write itself failed (git / fs)
+
+/** How long an UNCLAIMED `launch-*` placeholder worktree may sit untouched before `reap` treats
+ *  it as abandoned. Long enough that a human who opened a window yesterday evening and came back
+ *  this morning still finds it; short enough that a week of false starts does not accumulate. */
+export const LAUNCH_PLACEHOLDER_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Hard deadline on the one console round trip a reap makes. Reaping is housekeeping — it must
+ *  never hang on an unreachable console; an unanswered probe is simply "unknown". */
+export const CLAIM_PROBE_TIMEOUT_MS = 4000;
+
+/** The real implementations every function falls back to. Kept as ONE object so a test can
+ *  spread-override a single member (`{ ...DEFAULT_DEPS, git: spy }`) without losing the rest. */
+export const DEFAULT_DEPS = {
+  git,
+  fs: { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, lstatSync, rmSync },
+  now: () => new Date(),
+  isPidAlive,
+  // `null`, not a function: `reapWorktrees` then builds a FRESH console-backed checker for that
+  // one call (createConsoleClaimChecker below), so the claim list is fetched exactly once per
+  // reap no matter how many worktrees it walks. A caller that supplies its own function — a test,
+  // or an offline caller wanting the old "always unknown" behaviour — overrides it here.
+  claimIsActive: null,
+  // Injection points for that checker; undefined → global fetch and the resolved console URL.
+  fetch: undefined,
+  consoleUrl: undefined,
+};
+
+const withDeps = (deps) => ({ ...DEFAULT_DEPS, ...(deps || {}) });
+
+// Windows compares paths case-insensitively, `git worktree list` reports forward slashes, and a
+// path under %TEMP% may reach us as an 8.3 SHORT NAME (C:\Users\PWHER~1\...) from one side and
+// long-form from the other — three ways for the SAME directory to look like two. Every path
+// identity check (and the list's dedup key) goes through this one canonicalisation.
+function canonicalPath(p) {
+  if (!p) return "";
+  let out = resolve(String(p));
+  try { out = realpathSync.native(out); } catch { /* not on disk (a pruned registration) — resolve() is the best we have */ }
+  return out.replace(/[\\/]+$/, "").toLowerCase();
+}
+const samePath = (a, b) => !!a && !!b && canonicalPath(a) === canonicalPath(b);
+
+// ── key / label / branch derivation ──────────────────────────────────────────────────────────
+
+/** FNV-1a (32-bit), returned as 8 lowercase hex chars. `fnv1a32("")` is the offset basis,
+ *  811c9dc5 — the standard's own test vector, so a drift in this function is visible. */
+export function fnv1a32(input) {
+  let h = 0x811c9dc5;
+  const s = String(input ?? "");
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    // 32-bit multiply by the FNV prime (16777619) without losing the high bits to float64.
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/** Deterministic dev-server port for a worktree key: 3001..3050 inclusive, never 3000 (the
+ *  primary checkout's port — a session worktree must never collide with it). */
+export function devServerPortFor(key) {
+  return 3000 + (parseInt(fnv1a32(key).slice(0, 4), 16) % 50) + 1;
+}
+
+/**
+ * Split a spec id into the pieces the allocator names things with.
+ *
+ * Naming V3: `HS-<file key>-<family key>-<TYPE>-<slug>` — the token right after `HS-` is the
+ * unique FILE ID. A bare `launch-<id>` key (an unfiled ad-hoc session) has no `HS-` prefix and
+ * is used as-is, slugged.
+ *
+ * → `{ key, label, branch, launch }`
+ */
+export function keyInfoFor(specId) {
+  const raw = String(specId ?? "").trim();
+  const m = /^HS-([A-Za-z0-9]+)/i.exec(raw);
+  if (m) {
+    const key = m[1];
+    return {
+      key,
+      label: `session-${key.toLowerCase()}`,
+      branch: `claim/${key.toUpperCase()}`,
+      launch: false,
+    };
+  }
+  const key = slug(raw.toLowerCase());
+  return { key, label: `session-${key}`, branch: `claim/${key}`, launch: true };
+}
+
+/** The deterministic on-disk path for a spec's session worktree. Same `slug(label)` convention
+ *  as the engine's setupWorktree, so both lifecycles live side by side in ctx.worktreeRoot. */
+export function worktreePathFor(ctx, specId) {
+  return join(ctx.worktreeRoot, slug(keyInfoFor(specId).label));
+}
+
+// ── owner marker I/O ─────────────────────────────────────────────────────────────────────────
+
+function readMarker(path, d) {
+  try { return JSON.parse(d.fs.readFileSync(join(path, OWNER_FILE), "utf8")); }
+  catch { return null; }
+}
+
+function writeMarker(path, marker, d) {
+  d.fs.writeFileSync(join(path, OWNER_FILE), JSON.stringify(marker, null, 2));
+}
+
+// ── allocate ─────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Allocate (or re-attach to) the session worktree bound to `specId`.
+ *
+ * Idempotent: if the worktree already exists and its marker is for the same spec AND either the
+ * owner process is still alive or the sessionId matches, the existing worktree is returned with
+ * `created: false` — re-running `alloc` from the same session is a no-op, never a re-clone.
+ *
+ * → `{ path, branch, created, marker }`
+ */
+export function allocateForClaim(ctx, { specId, sessionId, agent, pid, baseRef } = {}, deps) {
+  const d = withDeps(deps);
+  if (!specId) throw new Error("allocateForClaim: specId is required");
+  const info = keyInfoFor(specId);
+  const path = worktreePathFor(ctx, specId);
+
+  // ── re-attach path ────────────────────────────────────────────────────────────────────────
+  const existing = d.fs.existsSync(path) ? readMarker(path, d) : null;
+  const ownerUnknownButUnreleased = existing != null && existing.pid == null && !existing.releasedAt;
+  if (existing && existing.specId === specId
+      && (d.isPidAlive(existing.pid)
+        || (sessionId && existing.sessionId === sessionId)
+        // Same doctrine as reap: an unknown owner (pid null) on an UNRELEASED marker is presumed
+        // LIVE. Tearing it down to re-create it would silently discard another session's work.
+        || ownerUnknownButUnreleased)) {
+    return { path, branch: existing.branch || info.branch, created: false, marker: existing };
+  }
+  // A stale directory for the SAME key (dead owner, different session) is reclaimed links-first
+  // before we hand the path to `git worktree add`, which refuses a non-empty destination.
+  if (d.fs.existsSync(path)) {
+    teardownWorktree(ctx, path, true);
+    if (d.fs.existsSync(path)) { try { d.fs.rmSync(path, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  }
+
+  // ── create path ───────────────────────────────────────────────────────────────────────────
+  d.fs.mkdirSync(ctx.worktreeRoot, { recursive: true });
+  const base = baseRef || "HEAD";
+  // The base is the CHECKED-OUT branch's HEAD, never `main`: the session must start from the
+  // code the agent is actually working on.
+  const baseSha = (d.git(ctx, ctx.repo, "rev-parse", base).stdout || "").trim() || null;
+  const baseBranch = (d.git(ctx, ctx.repo, "rev-parse", "--abbrev-ref", "HEAD").stdout || "").trim() || null;
+
+  const branchExists = d.git(ctx, ctx.repo, "rev-parse", "--verify", "--quiet", `refs/heads/${info.branch}`).status === 0;
+  const add = branchExists
+    ? d.git(ctx, ctx.repo, "worktree", "add", path, info.branch)
+    : d.git(ctx, ctx.repo, "worktree", "add", "-b", info.branch, path, base);
+  if (add.status !== 0) {
+    throw new Error(`git worktree add failed for ${specId}: ${String(add.stderr || add.stdout || "").trim()}`);
+  }
+
+  // Junction node_modules exactly as setupWorktree does — root (hoisted toolchain; Node
+  // resolution walks up) and the workspace. Only what actually exists (HS-OM28: a sibling repo
+  // may have no spex-console workspace).
+  const rootNM = join(ctx.repo, "node_modules");
+  if (d.fs.existsSync(rootNM) && !d.fs.existsSync(join(path, "node_modules"))) makeLink(join(path, "node_modules"), rootNM);
+  const spexNM = join(ctx.repo, ctx.spex, "node_modules");
+  if (d.fs.existsSync(spexNM) && d.fs.existsSync(join(path, ctx.spex)) && !d.fs.existsSync(join(path, ctx.spex, "node_modules"))) {
+    makeLink(join(path, ctx.spex, "node_modules"), spexNM);
+  }
+
+  const marker = {
+    kind: "session",
+    specId,
+    sessionId: sessionId ?? null,
+    agent: agent ?? null,
+    // pid is OPTIONAL and defaults to null — NOT to this process's pid (HS-L4Q5 integration
+    // finding). On Windows the `hs spawn` process and the `wt.exe` launcher both exit seconds
+    // after handing off to the terminal, so a pid recorded here is dead almost immediately while
+    // the agent session inside the worktree is very much alive. A dead pid is positive evidence
+    // for reaping; recording the launcher's pid would therefore make `reap` delete live sessions.
+    // `null` means UNKNOWN, and liveness has to come from releasedAt / claimIsActive instead.
+    // Build-kind markers (engine setupWorktree) keep their real pid — that process IS the owner.
+    pid: Number.isInteger(pid) && pid > 0 ? pid : null,
+    startedAt: d.now().toISOString(),
+    branch: info.branch,
+    baseSha,
+    baseBranch,
+    releasedAt: null,
+  };
+  writeMarker(path, marker, d);
+  return { path, branch: info.branch, created: true, marker };
+}
+
+// ── release ──────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Mark the session worktree for `specId` released. NEVER deletes anything — release makes the
+ * worktree ELIGIBLE for reaping; `reapWorktrees` still refuses to remove it while it is dirty.
+ * → `{ found, alreadyReleased, marker }`
+ */
+export function markReleased(ctx, { specId } = {}, deps) {
+  const d = withDeps(deps);
+  if (!specId) throw new Error("markReleased: specId is required");
+  const path = worktreePathFor(ctx, specId);
+  const marker = d.fs.existsSync(path) ? readMarker(path, d) : null;
+  if (!marker) return { found: false, alreadyReleased: false, marker: null };
+  if (marker.releasedAt) return { found: true, alreadyReleased: true, marker };
+  const next = { ...marker, releasedAt: d.now().toISOString() };
+  writeMarker(path, next, d);
+  return { found: true, alreadyReleased: false, marker: next };
+}
+
+// ── rebind ───────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Re-point an existing session worktree at a DIFFERENT spec — the `/hs-defer` shape, where the
+ * same live checkout continues under a split child id. The marker's specId and the branch NAME
+ * change; the DIRECTORY does not move (moving a live worktree out from under an editor, a dev
+ * server and git's own administrative pointer is exactly the class of breakage this epic exists
+ * to avoid). → `{ found, branch }`
+ */
+export function rebind(ctx, { fromSpecId, toSpecId } = {}, deps) {
+  const d = withDeps(deps);
+  if (!fromSpecId || !toSpecId) throw new Error("rebind: fromSpecId and toSpecId are required");
+  const path = worktreePathFor(ctx, fromSpecId);
+  const marker = d.fs.existsSync(path) ? readMarker(path, d) : null;
+  if (!marker) return { found: false, branch: null };
+  const nextBranch = keyInfoFor(toSpecId).branch;
+  const oldBranch = marker.branch || keyInfoFor(fromSpecId).branch;
+  if (oldBranch !== nextBranch) {
+    const mv = d.git(ctx, ctx.repo, "branch", "-m", oldBranch, nextBranch);
+    if (mv.status !== 0) {
+      throw new Error(`git branch -m ${oldBranch} ${nextBranch} failed: ${String(mv.stderr || mv.stdout || "").trim()}`);
+    }
+  }
+  writeMarker(path, { ...marker, specId: toSpecId, branch: nextBranch }, d);
+  return { found: true, branch: nextBranch };
+}
+
+// ── list ─────────────────────────────────────────────────────────────────────────────────────
+
+/** Parse `git worktree list --porcelain` into `[{ path, head, branch, detached, bare }]`. */
+function parsePorcelainWorktrees(stdout) {
+  const out = [];
+  let cur = null;
+  for (const raw of String(stdout ?? "").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("worktree ")) {
+      if (cur) out.push(cur);
+      cur = { path: line.slice("worktree ".length), head: null, branch: null, detached: false, bare: false };
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith("HEAD ")) cur.head = line.slice("HEAD ".length);
+    else if (line.startsWith("branch ")) cur.branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+    else if (line === "detached") cur.detached = true;
+    else if (line === "bare") cur.bare = true;
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/** Dirty line count for a worktree — `git status --porcelain -uall`. `null` when the path is
+ *  gone (a registration git has not pruned yet) or git refuses to run there. */
+function dirtyCountFor(ctx, path, d) {
+  if (!d.fs.existsSync(path)) return null;
+  const r = d.git(ctx, path, "status", "--porcelain", "-uall");
+  if (r.status !== 0) return null;
+  return String(r.stdout ?? "").split(/\r?\n/)
+    .filter((l) => l.trim().length > 0)
+    // The OWNER MARKER never counts as the agent's work: the allocator writes
+    // .hsewt-owner.json into every worktree it creates, so counting it would make EVERY
+    // session worktree permanently "dirty" and therefore permanently unreapable — the
+    // bookkeeping file masquerading as somebody's unsaved changes.
+    .filter((l) => l.slice(3).trim().replace(/^"|"$/g, "").replace(/\\/g, "/") !== OWNER_FILE)
+    .length;
+}
+
+/**
+ * Every worktree this repo knows about, joined with its owner marker.
+ *
+ * Two sources, because they disagree in exactly the cases that matter:
+ *   - `git worktree list --porcelain` (from ctx.repo) — the REGISTRY. The main checkout is the
+ *     first entry and is reported as `kind: "primary"`.
+ *   - the directory entries under ctx.worktreeRoot — anything here that the registry does not
+ *     know about is an UNREGISTERED leftover (`registered: false`), which is precisely what an
+ *     interrupted run or a `git worktree prune` behind our back leaves behind.
+ *
+ * `kind` comes from the marker (`"session"` / `"build"`); a worktree with no usable marker is
+ * `"foreign"` — someone else's, and never reaped without an explicit opt-in.
+ */
+export function listWorktrees(ctx, deps) {
+  const d = withDeps(deps);
+  const nowMs = d.now().getTime();
+  const rows = [];
+  const seen = new Set();
+
+  const push = (path, base, registered) => {
+    const marker = readMarker(path, d);
+    const isPrimary = samePath(path, ctx.repo);
+    const kind = isPrimary ? "primary" : (marker?.kind === "session" || marker?.kind === "build" ? marker.kind : "foreign");
+    const startedAt = marker?.startedAt ?? null;
+    const startedMs = startedAt ? Date.parse(startedAt) : NaN;
+    const pid = Number.isInteger(marker?.pid) ? marker.pid : null;
+    rows.push({
+      // resolve(): `git worktree list` reports FORWARD slashes on Windows, so a raw registry
+      // path would never string-compare equal to one a caller built with path.join().
+      path: resolve(path),
+      branch: base?.branch ?? marker?.branch ?? null,
+      head: base?.head ?? null,
+      kind,
+      specId: marker?.specId ?? null,
+      sessionId: marker?.sessionId ?? null,
+      pid,
+      // THREE-valued: true (alive), false (positively gone), null (UNKNOWN — the marker records
+      // no pid, which is the normal case for a session worktree whose launcher has exited).
+      // `null` must never be read as "dead"; see reapWorktrees.
+      pidAlive: pid == null ? null : d.isPidAlive(pid),
+      startedAt,
+      ageMs: Number.isFinite(startedMs) ? nowMs - startedMs : null,
+      releasedAt: marker?.releasedAt ?? null,
+      dirtyCount: dirtyCountFor(ctx, path, d),
+      registered,
+    });
+    seen.add(canonicalPath(path));
+  };
+
+  const listed = d.git(ctx, ctx.repo, "worktree", "list", "--porcelain");
+  if (listed.status === 0) {
+    for (const wt of parsePorcelainWorktrees(listed.stdout)) push(wt.path, wt, true);
+  }
+
+  if (d.fs.existsSync(ctx.worktreeRoot)) {
+    for (const entry of d.fs.readdirSync(ctx.worktreeRoot)) {
+      const path = join(ctx.worktreeRoot, entry);
+      if (seen.has(canonicalPath(path))) continue;
+      let st; try { st = d.fs.lstatSync(path); } catch { continue; }
+      if (!st.isDirectory() || st.isSymbolicLink()) continue;
+      push(path, null, false);
+    }
+  }
+  return rows;
+}
+
+// ── claim liveness (the console probe) ───────────────────────────────────────────────────────
+
+/** Is this claim row still live? Same two-field test peer-presence.mjs applies when it builds the
+ *  PEER AGENTS block — a row past its `staleAt` or `expiresAt` is not somebody working. */
+function claimRowIsLive(row, nowMs) {
+  const staleAtMs = row?.staleAt ? Date.parse(row.staleAt) : null;
+  const expiresAtMs = row?.expiresAt ? Date.parse(row.expiresAt) : null;
+  if (staleAtMs != null && Number.isFinite(staleAtMs) && staleAtMs < nowMs) return false;
+  if (expiresAtMs != null && Number.isFinite(expiresAtMs) && expiresAtMs < nowMs) return false;
+  return true;
+}
+
+/**
+ * A `claimIsActive(specId)` implementation backed by the console's `/api/claims`.
+ *
+ * → `true` a live claim for that spec exists · `false` the read SUCCEEDED and there is none ·
+ * `null` the read failed (no console URL, network error, non-OK response, bad payload). The
+ * three-way answer is the whole point: "the console says nobody holds this" is grounds to reclaim
+ * a worktree, "I could not ask" never is.
+ *
+ * ONE round trip for the lifetime of the checker: the claim list is fetched on the first call and
+ * every later spec id is answered from that array. `reapWorktrees` builds a fresh checker per
+ * call, so a reap over fifty worktrees still makes exactly one request.
+ *
+ * Ids are compared by FILE KEY via `keyInfoFor`, so a marker holding the full basename
+ * (`HS-L4Q5-03DO-TASK-…`), the store id (`HS-L4Q5`) and a bare `L4Q5` all match the same claim.
+ *
+ * The vendor modules are imported LAZILY: the controller imports this file on every build, and a
+ * console/auth module it never calls has no business being on that import path.
+ */
+export function createConsoleClaimChecker(ctx, {
+  fetchFn = globalThis.fetch, timeoutMs = CLAIM_PROBE_TIMEOUT_MS, consoleUrl, now = () => new Date(),
+} = {}) {
+  let pending = null;
+  const loadClaims = () => {
+    if (!pending) {
+      pending = (async () => {
+        const url = consoleUrl ?? consoleUrlForWorktree(ctx);
+        if (!url || typeof fetchFn !== "function") return null;
+        const [{ readClaimsFromConsole }, { getAuthHeader }] = await Promise.all([
+          import("../../vendor/heyspex-mcp/peer-presence.mjs"),
+          import("../../vendor/heyspex-mcp/console-fetch.mjs"),
+        ]);
+        // Same bearer every other console read sends (scripts/validate-no-foreign-session-sweep.mjs
+        // builds it identically) — a cloud console 401s an unauthenticated /api/claims, which
+        // would otherwise look like "no claims" instead of "could not check".
+        return await readClaimsFromConsole(url, fetchFn, timeoutMs, getAuthHeader());
+      })().catch(() => null);
+    }
+    return pending;
+  };
+
+  return async function claimIsActive(specId) {
+    if (!specId) return null;
+    const claims = await loadClaims();
+    if (!Array.isArray(claims)) return null; // could not check — never "no claim"
+    const want = keyInfoFor(specId).key.toLowerCase();
+    const nowMs = now().getTime();
+    return claims.some((c) => keyInfoFor(String(c?.specId ?? "")).key.toLowerCase() === want
+      && claimRowIsLive(c, nowMs));
+  };
+}
+
+// ── reap ─────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Retire the `claim/<KEY>` branch a session worktree was sitting on, once that worktree is gone.
+ *
+ * ALWAYS lowercase `-d`, never `-D`. `-d` refuses a branch holding commits that are not merged
+ * anywhere else, and that refusal is the entire safety property: the worktree's files are already
+ * deleted by this point, so a force-delete would be the last step of destroying work nobody has
+ * reviewed. It equally refuses a branch checked out in another worktree — also surfaced verbatim
+ * rather than worked around.
+ *
+ * → `{ name, deleted: true }` · `{ name, deleted: false, reason }` where reason is "unmerged",
+ *   "missing", or git's own first stderr line.
+ */
+function deleteClaimBranch(ctx, name, d) {
+  const r = d.git(ctx, ctx.repo, "branch", "-d", name);
+  if (r.status === 0) return { name, deleted: true };
+  const firstLine = String(r.stderr || r.stdout || "").trim().split(/\r?\n/)[0] || "git branch -d failed";
+  let reason = firstLine;
+  if (/not fully merged/i.test(firstLine)) reason = "unmerged";
+  else if (/not found|didn't match|does not exist/i.test(firstLine)) reason = "missing";
+  return { name, deleted: false, reason };
+}
+
+/**
+ * Reclaim worktrees that are finished with. Removal needs BOTH halves:
+ *
+ *   ELIGIBLE, which depends on what kind of worktree it is —
+ *     · foreign  — only ever with `includeForeign && yes`; the operator's explicit say-so IS the
+ *                  evidence, because a worktree with no marker tells us nothing else.
+ *     · launch-* — an UNCLAIMED placeholder (a window opened before any spec was claimed). Its
+ *                  `pid` is meaningless and there is no claim to ask about, so it ages out:
+ *                  `releasedAt` set OR at least `ttlMs` old (LAUNCH_PLACEHOLDER_TTL_MS). A
+ *                  window opened ten minutes ago is never touched; one abandoned yesterday is,
+ *                  and `ttlMs: 0` (`--ttl-hours 0`) ages every placeholder out at once.
+ *     · otherwise — `releasedAt` set, OR the console says the claim is NOT active, OR the owner
+ *                  process is POSITIVELY gone (`pidAlive === false`).
+ *   and CLEAN — `dirtyCount === 0`.
+ *
+ * `pidAlive === null` (UNKNOWN — the normal state of a session marker, whose launcher process
+ * exits seconds after the agent starts) is NOT evidence of death and never makes a worktree
+ * eligible on its own; it is reported as `owner_unknown`. Liveness must then come from
+ * `releasedAt` or from `claimIsActive`. This is the difference between housekeeping and deleting
+ * a colleague's uncommitted afternoon.
+ *
+ * The dirty check is the load-bearing one: every other signal is a heuristic about a process,
+ * but uncommitted work is unrecoverable once the worktree is gone.
+ *
+ * `dryRun` performs ZERO writes — no teardown, and no branch deletion either.
+ * The primary checkout is never a candidate, under any flags.
+ *
+ * → `{ dryRun, removed: [{ path, branch }], skipped: [{ path, reason }] }`, where `branch` is
+ *   `null` (a dry run, or a non-session worktree with no branch of ours) or
+ *   `{ name, deleted: true }` / `{ name, deleted: false, reason }`.
+ * Reasons: "primary" · "foreign" · "claim_active" · "owner_alive" · "owner_unknown" ·
+ *          "placeholder_fresh" · "dirty".
+ */
+export async function reapWorktrees(ctx, {
+  dryRun = false, includeForeign = false, yes = false, ttlMs = LAUNCH_PLACEHOLDER_TTL_MS,
+} = {}, deps) {
+  const d = withDeps(deps);
+  const removed = [];
+  const skipped = [];
+  // ONE checker per reap call → one console round trip, whatever the worktree count.
+  const claimIsActive = typeof d.claimIsActive === "function"
+    ? d.claimIsActive
+    : createConsoleClaimChecker(ctx, { fetchFn: d.fetch, consoleUrl: d.consoleUrl, now: d.now });
+
+  for (const wt of listWorktrees(ctx, d)) {
+    if (wt.kind === "primary") { skipped.push({ path: wt.path, reason: "primary" }); continue; }
+    if (wt.kind === "foreign" && !(includeForeign && yes)) { skipped.push({ path: wt.path, reason: "foreign" }); continue; }
+
+    let claimActive = null;
+    if (wt.specId) {
+      try { claimActive = await claimIsActive(wt.specId); } catch { claimActive = null; }
+    }
+    if (claimActive === true) { skipped.push({ path: wt.path, reason: "claim_active" }); continue; }
+
+    const isPlaceholder = Boolean(wt.specId) && keyInfoFor(wt.specId).launch;
+    let eligible, reason;
+    if (wt.kind === "foreign") {
+      eligible = true; // gated above on includeForeign && yes
+    } else if (isPlaceholder) {
+      // `>=`, not `>`. `--ttl-hours 0` means "age it out immediately", and a placeholder
+      // allocated in the same millisecond as the reap has `ageMs === 0`. Under a strict `>`
+      // that worktree read as FRESH, so a zero TTL silently kept it AND the dirty gate below
+      // was never reached — a dirty aged-out placeholder came back "placeholder_fresh"
+      // instead of "dirty", which is a refusal for the wrong reason (right answer, wrong
+      // evidence: a dirty-detection regression would have been invisible). At the real 24h
+      // TTL the two comparisons differ by exactly one millisecond and nothing else.
+      eligible = Boolean(wt.releasedAt) || (wt.ageMs != null && wt.ageMs >= ttlMs);
+      reason = "placeholder_fresh";
+    } else {
+      eligible = Boolean(wt.releasedAt) || claimActive === false || wt.pidAlive === false;
+      reason = wt.pidAlive === null ? "owner_unknown" : "owner_alive";
+    }
+    if (!eligible) { skipped.push({ path: wt.path, reason }); continue; }
+
+    if ((wt.dirtyCount ?? 0) > 0) { skipped.push({ path: wt.path, reason: "dirty" }); continue; }
+
+    if (dryRun) { removed.push({ path: wt.path, branch: null }); continue; }
+
+    // Links-first teardown, always — never a recursive delete through a live junction.
+    const clean = teardownWorktree(ctx, wt.path, true);
+    if (d.fs.existsSync(wt.path)) {
+      if (clean || !d.fs.existsSync(join(wt.path, "node_modules"))) {
+        try { d.fs.rmSync(wt.path, { recursive: true, force: true }); } catch { /* best-effort */ }
+      }
+    }
+    if (d.fs.existsSync(wt.path)) { skipped.push({ path: wt.path, reason: "dirty" }); continue; }
+
+    // The worktree is gone; retire its branch too. Removing the checkout but leaving
+    // `claim/<KEY>` behind is how a repo silently accumulates dozens of dead refs. Only SESSION
+    // worktrees have one — build worktrees are cut `--detach`, and a foreign worktree's branch
+    // is not ours to touch.
+    const branch = wt.kind === "session" && wt.branch ? deleteClaimBranch(ctx, wt.branch, d) : null;
+    removed.push({ path: wt.path, branch });
+  }
+  return { dryRun: Boolean(dryRun), removed, skipped };
+}
+
+// ── console URL ──────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The console URL a session worktree should talk to — deliberately the PRIMARY checkout's, not
+ * a per-worktree one: a worktree is an isolated *file* tree, not an isolated control plane, and
+ * every claim/progress/release call must land on the same console the human is looking at.
+ */
+export function consoleUrlForWorktree(ctx) {
+  try {
+    const url = resolveConsoleUrl({ repoRoot: ctx.repo });
+    if (url) return url;
+  } catch { /* fall through to the repo discovery file */ }
+  try {
+    const discovery = readFileSync(join(ctx.repo, ".heyspex", "console-url"), "utf8").trim();
+    if (discovery) return discovery.replace(/\/+$/, "");
+  } catch { /* nothing to fall back to */ }
+  return null;
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────
+
+const USAGE = `usage: node dev-factory/lib/worktree-allocator.mjs <list|alloc|release|reap|rebind> [options]
+
+  list                       every worktree (registry + unregistered leftovers) with its marker
+  alloc   --spec ID          allocate/re-attach the claim-bound worktree for a spec
+  release --spec ID          mark that worktree released (never deletes)
+  reap                       reclaim released/dead/claim-inactive worktrees that are CLEAN
+  rebind  --spec ID --to ID  re-point a worktree (and rename its branch) at another spec
+
+options:
+  --spec ID          the spec id (required for alloc/release/rebind)
+  --to ID            the new spec id (rebind)
+  --session ID       session id recorded in the owner marker
+  --agent NAME       agent name recorded in the owner marker
+  --pid N            owner pid recorded in the owner marker (default: NONE — a session's
+                     launcher process exits immediately, so a recorded pid would read as dead)
+  --ttl-hours N      how long an unclaimed launch-* placeholder may idle before reap takes it
+                     (default 24)
+  --root DIR         worktree root (default: %USERPROFILE%/.hsewt)
+  --repo DIR         repo root (default: this checkout)
+  --json             print ONE JSON object instead of human lines
+  --dry-run          compute the answer, write nothing
+  --include-foreign  let reap consider worktrees with no owner marker (requires --yes)
+  --yes              confirm a destructive reap
+`;
+
+const FLAGS_WITH_VALUE = new Set(["--spec", "--to", "--session", "--agent", "--pid", "--root", "--repo", "--ttl-hours"]);
+const BOOL_FLAGS = new Set(["--json", "--dry-run", "--include-foreign", "--yes"]);
+const VERBS = new Set(["list", "alloc", "release", "reap", "rebind"]);
+
+export function parseCliArgs(argv) {
+  const out = { verb: null, json: false, dryRun: false, includeForeign: false, yes: false };
+  let i = 0;
+  if (argv[0] && !argv[0].startsWith("-")) { out.verb = argv[0]; i = 1; }
+  for (; i < argv.length; i++) {
+    const a = argv[i];
+    if (BOOL_FLAGS.has(a)) {
+      if (a === "--json") out.json = true;
+      else if (a === "--dry-run") out.dryRun = true;
+      else if (a === "--include-foreign") out.includeForeign = true;
+      else out.yes = true;
+      continue;
+    }
+    if (FLAGS_WITH_VALUE.has(a)) {
+      const v = argv[++i];
+      if (v === undefined) return { error: `missing value for ${a}`, code: EXIT_INVALID_ARG };
+      if (a === "--spec") out.spec = v;
+      else if (a === "--to") out.to = v;
+      else if (a === "--session") out.session = v;
+      else if (a === "--agent") out.agent = v;
+      else if (a === "--pid") {
+        const n = Number.parseInt(v, 10);
+        if (!Number.isInteger(n) || n <= 0) return { error: `bad --pid ${v}`, code: EXIT_INVALID_ARG };
+        out.pid = n;
+      } else if (a === "--ttl-hours") {
+        const n = Number.parseFloat(v);
+        if (!Number.isFinite(n) || n < 0) return { error: `bad --ttl-hours ${v}`, code: EXIT_INVALID_ARG };
+        out.ttlMs = Math.round(n * 60 * 60 * 1000);
+      } else if (a === "--root") out.root = v;
+      else out.repo = v;
+      continue;
+    }
+    return { error: `unknown flag ${a}`, code: EXIT_USAGE };
+  }
+  if (!out.verb || !VERBS.has(out.verb)) return { error: `unknown verb ${out.verb ?? "(none)"}`, code: EXIT_USAGE };
+  return out;
+}
+
+async function runCli(argv) {
+  const args = parseCliArgs(argv);
+  if (args.error) { process.stderr.write(`${args.error}\n\n${USAGE}`); return args.code; }
+
+  const ctx = makeCtx({ repo: args.repo || undefined, worktreeRoot: args.root || undefined });
+  const emit = (obj, lines) => {
+    if (args.json) process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+    else for (const l of lines) process.stdout.write(`${l}\n`);
+  };
+
+  if (args.verb === "list") {
+    const worktrees = listWorktrees(ctx);
+    emit({ worktrees }, worktrees.map((w) =>
+      `${w.kind.padEnd(8)} ${String(w.branch ?? "(detached)").padEnd(28)} dirty=${w.dirtyCount ?? "?"} `
+      + `${w.registered ? "" : "UNREGISTERED "}${w.specId ?? ""}${w.releasedAt ? " released" : ""} ${w.path}`));
+    return EXIT_OK;
+  }
+
+  if (args.verb === "alloc") {
+    if (!args.spec) { process.stderr.write(`alloc requires --spec\n`); return EXIT_INVALID_ARG; }
+    const info = keyInfoFor(args.spec);
+    if (args.dryRun) {
+      const baseSha = (git(ctx, ctx.repo, "rev-parse", "HEAD").stdout || "").trim() || null;
+      emit({ dryRun: true, path: worktreePathFor(ctx, args.spec), branch: info.branch, baseSha },
+        [`would allocate ${worktreePathFor(ctx, args.spec)} on ${info.branch} from ${baseSha}`]);
+      return EXIT_OK;
+    }
+    try {
+      const r = allocateForClaim(ctx, {
+        specId: args.spec, sessionId: args.session, agent: args.agent, pid: args.pid,
+      });
+      emit(r, [`${r.created ? "allocated" : "re-attached"} ${r.path} on ${r.branch} `
+        + `(port ${devServerPortFor(info.key)})`]);
+      return EXIT_OK;
+    } catch (e) { process.stderr.write(`${e.message}\n`); return EXIT_WRITE_FAILED; }
+  }
+
+  if (args.verb === "release") {
+    if (!args.spec) { process.stderr.write(`release requires --spec\n`); return EXIT_INVALID_ARG; }
+    const r = markReleased(ctx, { specId: args.spec });
+    emit(r, [r.found
+      ? `${r.alreadyReleased ? "already released" : "released"} ${worktreePathFor(ctx, args.spec)}`
+      : `no worktree for ${args.spec}`]);
+    return r.found ? EXIT_OK : EXIT_CHECK_FAILED;
+  }
+
+  if (args.verb === "rebind") {
+    if (!args.spec || !args.to) { process.stderr.write(`rebind requires --spec and --to\n`); return EXIT_INVALID_ARG; }
+    try {
+      const r = rebind(ctx, { fromSpecId: args.spec, toSpecId: args.to });
+      emit(r, [r.found ? `rebound ${args.spec} → ${args.to} on ${r.branch}` : `no worktree for ${args.spec}`]);
+      return r.found ? EXIT_OK : EXIT_CHECK_FAILED;
+    } catch (e) { process.stderr.write(`${e.message}\n`); return EXIT_WRITE_FAILED; }
+  }
+
+  // reap
+  const r = await reapWorktrees(ctx, {
+    dryRun: args.dryRun, includeForeign: args.includeForeign, yes: args.yes,
+    ...(args.ttlMs != null ? { ttlMs: args.ttlMs } : {}),
+  });
+  emit(r, [
+    `${r.dryRun ? "would remove" : "removed"} ${r.removed.length}:`,
+    ...r.removed.map((x) => `  ${x.path}${x.branch
+      ? ` — branch ${x.branch.name} ${x.branch.deleted ? "deleted" : `KEPT (${x.branch.reason})`}`
+      : ""}`),
+    ...(r.removed.length ? [] : ["  (none)"]),
+    ...r.skipped.map((s) => `  skipped ${s.path} — ${s.reason}`),
+  ]);
+  return EXIT_OK;
+}
+
+// Guard on MAIN-entry (not just on a flag) so importing this module from the controller never
+// fires the CLI — the same convention engine/worktree.mjs uses for its --self-test.
+if (import.meta.url.endsWith(`/${basename(process.argv[1] ?? "")}`)) {
+  runCli(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}