@botbuddy/cli 1.32.3 → 1.33.0

package/src/stack-isolation.mjs

@@ -0,0 +1,1032 @@
+// BOT-1798 — the ISOLATED stack directory a Helper-backed `bb stack run` leases.
+//
+// A lease's `stack_path` is where the BotBuddy Helper runs `supabase start`
+// (`<worktree_root>/<stack_path>`). At the default `"."` that is the worktree
+// ROOT, whose committed `supabase/config.toml` declares the SHARED canonical
+// project (`xymjddoobrfnsmawmtbc` for botbuddy-web, `hhukfannuankqtswiqdq` for
+// supplyspark-ent). The Helper then collides with — and clobbers the edge
+// bind-mount of — the developer's already-running shared stack: `supabase status`
+// reports no local API URL, provisioning fails (`invalidStatus`), and the lease
+// cannot be reaped because its recorded teardown target IS the shared stack.
+// Observed in production 2026-09-21: zero `stack run` leases activated in 36h.
+//
+// BOT-1711 closed the same hole for `stack up --local-exec` by REFUSING `"."`.
+// `run` cannot just refuse: nothing (BotBuddy or Supply Guard) passes
+// `--stack-path` for it. So `run` materializes its own isolated stack instead —
+// a gitignored directory inside the worktree holding the worktree's own
+// `supabase/` tree with a DISTINCT, ticket-derived `project_id` and a fully
+// remapped port block. Same shape as the hermetic deno lane
+// (`scripts/run-deno-hermetic.mjs` + `scripts/lib/hermetic-config.mjs`) and
+// Supply Guard's `scripts/local-supabase-isolated.sh`, ported here because the
+// published CLI cannot import repo scripts and stays Node-stdlib only.
+import { createHash, randomUUID } from "node:crypto";
+import { cpSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { basename, join } from "node:path";
+import { lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
+
+/** Where materialized leased stacks live inside the worktree (gitignored). */
+export const LEASED_STACKS_DIR = ".botbuddy/stacks";
+
+// Port bands already spoken for on this host (docs/docker-capacity.md → "What
+// counts against the budget"): 41xxx/42xxx per-worktree preview + lighthouse,
+// 43xxx–53xxx hermetic deno lane, 54xxx supplyspark-ent shared, 55xxx another
+// tenant, 56320–56329 + 56683 the BB shared canonical stack, and 56321 + n×10
+// (n ≤ 399, i.e. up to ~60330) Supply Guard's per-ticket blocks. A leased stack
+// therefore gets a contiguous block above all of them, and every block stays a
+// valid TCP port (61000 + 200×20 − 1 = 64999).
+export const LEASED_PORT_BASE = 61000;
+/** Ports reserved per leased stack (the repo declares 10; the rest is headroom). */
+export const LEASED_PORT_STRIDE = 20;
+/** Distinct blocks available. Two worktree+slot pairs CAN hash to one block; as
+ * with the hermetic/e2e ports that is a loud `supabase start` port-bind failure,
+ * never a silently shared stack. */
+export const LEASED_PORT_SLOTS = 200;
+
+/** How long a leased stack directory must have been untouched before another run
+ * may collect it. Comfortably above the reaper's default 1800 s idle TTL, so a
+ * batch whose owner process died but whose child/containers are still finishing is
+ * never collected out from under itself (BOT-1798, Codex #928 R5). */
+export const LEASED_STACK_GC_MIN_AGE_MS = 2 * 60 * 60 * 1000;
+/** Ownership + retention metadata each materialized stack carries (BOT-1798). */
+export const LEASED_STACK_MARKER = ".bb-stack.json";
+/** HOST-scoped port-block reservations (BOT-1798, Codex #928 R13). Worktrees are
+ * private to each other, but the ports are the machine's — a reservation visible
+ * only inside one worktree lets two worktrees bind the same block. This lives
+ * beside `~/.botbuddy/machine-id`, the existing machine-scoped state. */
+export const LEASED_PORT_REGISTRY_DIRNAME = "leased-port-blocks";
+/** The host-scoped mutex that serializes "reclaim a stale claim, then take a
+ * block" (BOT-1798, Codex #928 R16). Without it two runs can both read the same
+ * expired claim, and the slower one's delete wipes the winner's NEW claim. */
+export const LEASED_ALLOCATION_LOCK = ".allocate.lock";
+/** A held allocation lock older than this is assumed abandoned (the critical
+ * section is a few file operations). */
+const LEASED_ALLOCATION_LOCK_STALE_MS = 60 * 1000;
+export function defaultPortRegistryDir() {
+  return join(homedir(), ".botbuddy", LEASED_PORT_REGISTRY_DIRNAME);
+}
+/** Grace added to a batch's own idle TTL before its directory may be collected:
+ * the reaper stops an idle stack at the TTL, and the teardown itself takes time. */
+const LEASED_STACK_RETENTION_GRACE_MS = 30 * 60 * 1000;
+/** The idle TTL a lease gets when the caller names none (`bb stack up --idle-ttl`). */
+const DEFAULT_IDLE_TTL_SECS = 1800;
+
+
+// TOML decimal integers may carry a leading sign (`+56321`); radix forms may not.
+// A negative value is rejected downstream by tomlIntToDecimal (BOT-1711 Codex R15).
+const TOML_INT_PORT = "(0[xX][0-9A-Fa-f_]+|0[oO][0-7_]+|0[bB][01_]+|[+-]?[0-9][0-9_]*)";
+
+/** Normalize any valid TOML integer literal to its decimal string: decimal (with `_`
+ * separators), or `0x`/`0o`/`0b` radix forms. Returns null for a non-integer. Without
+ * this a hex/octal port (`0xdc01` == 56321) or a separated one (`56_321`) would parse as
+ * a truncated value and bypass the port-collision checks while Supabase binds the full
+ * port (BOT-1711 Codex R11/R14). */
+export function tomlIntToDecimal(token) {
+  const cleaned = String(token).replace(/_/g, "");
+  const n = Number(cleaned);
+  return Number.isInteger(n) && n >= 0 ? String(n) : null;
+}
+
+/** Every port a `config.toml` allocates, as a SECTION-QUALIFIED map `"<section>.<key>" ->
+ * "<port>"` (e.g. `api.port`, `db.shadow_port`, `inbucket.pop3_port`). Section-qualified so
+ * the SAME `port` key under [api]/[db]/[studio]/[inbucket] stays distinct, which lets a
+ * target be checked for BOTH completeness (declares every port the root does) and
+ * disjointness (shares no port value). Comments are not configuration; both the
+ * `[section]` + bare-key form and the dotted `api.port = N` form are recognized
+ * (BOT-1711 R16). */
+export function portMapInConfig(toml) {
+  const map = new Map();
+  let section = "";
+  const bare = new RegExp(`^((?:[A-Za-z0-9]+_)?port)\\s*=\\s*${TOML_INT_PORT}`);
+  const dotted = new RegExp(`^([A-Za-z0-9_]+)\\.((?:[A-Za-z0-9]+_)?port)\\s*=\\s*${TOML_INT_PORT}`);
+  for (const raw of String(toml).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("#")) continue; // comments are not configuration
+    const sec = /^\[([^\]]+)\]/.exec(line);
+    if (sec) { section = sec[1].trim(); continue; }
+    const dot = dotted.exec(line);
+    if (dot) {
+      const dec = tomlIntToDecimal(dot[3]);
+      if (dec != null) map.set(`${dot[1]}.${dot[2]}`, dec);
+      continue;
+    }
+    const m = bare.exec(line);
+    if (m) {
+      const dec = tomlIntToDecimal(m[2]);
+      if (dec != null) map.set(`${section}.${m[1]}`, dec);
+    }
+  }
+  return map;
+}
+
+/** Lowercase-alphanumeric tail of a ticket/slot, e.g. `BOT-1798` → `bot1798`. */
+function identityTag(ticket, slot) {
+  const source = String(ticket ?? "").trim() || String(slot ?? "").trim();
+  const cleaned = source.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return cleaned.slice(-10) || "stack";
+}
+
+/**
+ * The identity of one batch's isolated stack:
+ *   * `projectId` — the Docker/Supabase project name. Ticket-derived so
+ *     `docker ps` ownership stays decidable (docs/docker-capacity.md rule 3),
+ *     hash-suffixed so two worktrees on one ticket never share containers, and
+ *     Supabase-safe (lowercase alphanumeric, leading letter, ≤20 chars).
+ *   * `portBase` — the first port of this stack's contiguous block.
+ *
+ * `nonce` scopes the identity to ONE invocation (BOT-1798, Codex #928 R5). A
+ * per-slot identity was reachable by a second run as soon as the first run's
+ * PROCESS died — its detached child, containers and server lease can outlive it,
+ * and the file lock then reads as reclaimable — so the refresh could swap the
+ * `supabase/functions` tree under a batch that was still running. A run's lease
+ * is released with `destroy`, so a stable identity bought no volume reuse anyway.
+ * Omit `nonce` for a deterministic per-slot identity (tests, diagnostics).
+ */
+export function leasedStackIdentity({ worktreeRoot, slot, ticket, nonce } = {}) {
+  // JSON-encode the parts so no path/slot/nonce combination can alias another
+  // (an unambiguous, escape-free separator).
+  const digest = createHash("sha256").update(JSON.stringify([worktreeRoot ?? "", slot ?? "", nonce ?? ""])).digest("hex");
+  const projectId = `bb${identityTag(ticket, slot)}${digest.slice(0, 6)}`.slice(0, 20);
+  const portBase = LEASED_PORT_BASE + (parseInt(digest.slice(8, 16), 16) % LEASED_PORT_SLOTS) * LEASED_PORT_STRIDE;
+  return { projectId, portBase, dirName: projectId };
+}
+
+const PROJECT_ID_RE = /^[a-z][a-z0-9]{0,19}$/;
+
+/**
+ * The worktree's own config with exactly THREE things changed: `project_id`,
+ * every declared host port, and the edge runtime's own public origin. Everything
+ * else — `[functions.*] verify_jwt`, `[auth.hook.*]`, every other
+ * `[edge_runtime.secrets]` env() interpolation, storage limits, comments —
+ * survives byte-for-byte, or the leased stack exercises a different contract
+ * than the shared one.
+ *
+ * Ports are assigned by first appearance into the stack's own block, so a port
+ * the config adds later is remapped automatically instead of silently falling
+ * back to Supabase's default (which would collide with every other stack).
+ *
+ * The origin pin (BOT-1798, Codex #928 R3 P1) is the leased equivalent of
+ * `resolveIsolatedStackApiUrl` on the `--local-exec` path. The committed config
+ * resolves the edge runtime's `VITE_SUPABASE_URL` through `env()` because a local
+ * `supabase start` exports the stack's Kong origin into the shell (BOT-903) — but
+ * the HELPER starts this stack with ITS environment, where that variable is
+ * absent, points at production, or points at another stack. The edge runtime
+ * would then emit foreign public URLs from inside the leased stack. The
+ * materialized config is disposable and is never used for `functions deploy`, so
+ * the safe answer is to pin the literal origin of its own remapped `[api] port`.
+ */
+export function rewriteLeasedStackConfig(configText, { projectId, portBase } = {}) {
+  if (!PROJECT_ID_RE.test(String(projectId ?? ""))) {
+    throw new Error(`rewriteLeasedStackConfig: projectId "${projectId}" must be lowercase alphanumeric, start with a letter, and be ≤20 characters`);
+  }
+  if (!Number.isInteger(portBase)) throw new Error("rewriteLeasedStackConfig: portBase must be an integer");
+
+  const bare = new RegExp(`^(\\s*)((?:[A-Za-z0-9]+_)?port)(\\s*=\\s*)${TOML_INT_PORT}(.*)$`);
+  const dotted = new RegExp(`^(\\s*)([A-Za-z0-9_]+\\.(?:[A-Za-z0-9]+_)?port)(\\s*=\\s*)${TOML_INT_PORT}(.*)$`);
+  const ports = new Map();
+  const assign = (key) => {
+    if (!ports.has(key)) {
+      if (ports.size >= LEASED_PORT_STRIDE) {
+        throw new Error(
+          `refusing to materialize an isolated leased stack: supabase/config.toml declares more than ${LEASED_PORT_STRIDE} host ports ` +
+            `(at "${key}") — the leased port block cannot hold them all, and reusing a port would collide inside the stack. ` +
+            "Widen LEASED_PORT_STRIDE (and the band in docs/docker-capacity.md) before adding more services.",
+        );
+      }
+      ports.set(key, portBase + ports.size);
+    }
+    return ports.get(key);
+  };
+
+  let section = "";
+  let sawProjectId = false;
+  const out = [];
+  for (const line of String(configText).split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("#")) { out.push(line); continue; }
+    const sec = /^\s*\[([^\]]+)\]/.exec(line);
+    if (sec) { section = sec[1].trim(); out.push(line); continue; }
+    // project_id is a root key: it precedes every section header.
+    if (!section && /^\s*project_id\s*=/.test(line)) {
+      out.push(`project_id = "${projectId}"`);
+      sawProjectId = true;
+      continue;
+    }
+    const dot = dotted.exec(line);
+    if (dot && tomlIntToDecimal(dot[4]) != null) {
+      out.push(`${dot[1]}${dot[2]}${dot[3]}${assign(dot[2])}${dot[5]}`);
+      continue;
+    }
+    const m = bare.exec(line);
+    if (m && tomlIntToDecimal(m[4]) != null) {
+      out.push(`${m[1]}${m[2]}${m[3]}${assign(`${section}.${m[2]}`)}${m[5]}`);
+      continue;
+    }
+    out.push(line);
+  }
+  // Pin the edge origin AFTER the port pass: [edge_runtime.secrets] may precede
+  // [api] in the file, so the leased api port is only known once every line is seen.
+  const apiPort = ports.get("api.port");
+  let pinned = 0;
+  let sawEdgeOrigin = false;
+  let pinSection = "";
+  for (let i = 0; i < out.length; i++) {
+    const line = out[i];
+    if (line.trim().startsWith("#")) continue;
+    const sec = /^\s*\[([^\]]+)\]/.exec(line);
+    if (sec) { pinSection = sec[1].trim(); continue; }
+    if (pinSection !== "edge_runtime.secrets") continue;
+    const m = /^(\s*)VITE_SUPABASE_URL(\s*=\s*).*$/.exec(line);
+    if (!m) continue;
+    sawEdgeOrigin = true;
+    if (apiPort === undefined) break;
+    out[i] = `${m[1]}VITE_SUPABASE_URL${m[2]}"http://127.0.0.1:${apiPort}"`;
+    pinned++;
+  }
+  if (sawEdgeOrigin && apiPort === undefined) {
+    throw new Error(
+      "refusing to materialize an isolated leased stack: its supabase/config.toml sets the edge runtime's " +
+        "VITE_SUPABASE_URL but declares no [api] port, so the stack's own origin cannot be pinned — the Helper " +
+        "would start an edge runtime that emits another stack's (or production's) public URLs.",
+    );
+  }
+  if (!sawProjectId) {
+    throw new Error(
+      "refusing to materialize an isolated leased stack: the worktree's supabase/config.toml declares no root project_id, " +
+        "so the leased stack cannot be given an identity distinct from the shared canonical project.",
+    );
+  }
+  return { text: out.join("\n"), ports, pinnedEdgeOrigin: pinned > 0 };
+}
+
+/** The literal `[edge_runtime.secrets] VITE_SUPABASE_URL` a config declares, or
+ * null when it declares none. Comments are not configuration. */
+export function edgeOriginInConfig(toml) {
+  let section = "";
+  for (const raw of String(toml).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("#")) continue;
+    const sec = /^\[([^\]]+)\]/.exec(line);
+    if (sec) { section = sec[1].trim(); continue; }
+    if (section !== "edge_runtime.secrets") continue;
+    const m = /^VITE_SUPABASE_URL\s*=\s*(.*)$/.exec(line);
+    if (m) return m[1].trim().replace(/^["']|["']$/g, "");
+  }
+  return null;
+}
+
+/**
+ * FAIL CLOSED before anything is leased: prove the written config is actually
+ * isolated from the worktree root's. Mirrors the BOT-1711 invariant
+ * (`assertIsolatedLocalExecTarget`) so a materializer bug can never hand the
+ * Helper the shared canonical stack.
+ */
+export function assertLeasedStackIsolated(rootConfigText, stackConfigText) {
+  const rootProject = projectIdFromConfig(rootConfigText);
+  const stackProject = projectIdFromConfig(stackConfigText);
+  // FAIL CLOSED (Codex #928 R17, mirroring BOT-1711 R6 P1): with no readable root
+  // identity, isolation from the shared canonical project cannot be proven — and
+  // its containers may well be running.
+  if (!rootProject) {
+    throw new Error(
+      "refusing to lease a stack: the worktree's supabase/config.toml declares no readable project_id, so isolation from the " +
+        "shared canonical project cannot be proven (its containers may still be running).",
+    );
+  }
+  if (!stackProject || stackProject === rootProject) {
+    throw new Error(
+      `refusing to lease a materialized stack whose project_id ("${stackProject ?? "<none>"}") is not distinct from the worktree's ` +
+        "shared canonical project — `supabase start` there would operate the shared dev stack.",
+    );
+  }
+  const rootPorts = portMapInConfig(rootConfigText);
+  const stackPorts = portMapInConfig(stackConfigText);
+  const missing = [...rootPorts.keys()].filter((k) => !stackPorts.has(k));
+  if (missing.length) {
+    throw new Error(`refusing to lease a materialized stack that omits port(s) the shared stack allocates (${missing.join(", ")}) — an omitted port falls back to Supabase's default and collides with other stacks.`);
+  }
+  const values = [...stackPorts.values()];
+  const dupes = [...new Set(values.filter((v, i) => values.indexOf(v) !== i))];
+  if (dupes.length) {
+    throw new Error(`refusing to lease a materialized stack that assigns the same port to multiple services (${dupes.join(", ")}).`);
+  }
+  const rootValues = new Set(rootPorts.values());
+  const shared = [...new Set(values)].filter((v) => rootValues.has(v));
+  if (shared.length) {
+    throw new Error(`refusing to lease a materialized stack that reuses the shared stack's port(s) ${shared.join(", ")}.`);
+  }
+  // The edge runtime must emit THIS stack's public URLs (BOT-1798, Codex #928 R9).
+  // A config that leaves `env(VITE_SUPABASE_URL)` in place — the repo default,
+  // because a local `supabase start` exports the origin into the shell — resolves
+  // against the HELPER's environment: missing, production, or another stack.
+  const edgeOrigin = edgeOriginInConfig(stackConfigText);
+  // Omitting it is not a way out either (Codex #928 R10): this repo's edge runtime
+  // is handed its public origin through that section and fails closed without it,
+  // so a leased stack must declare it whenever the worktree's own config does.
+  if (edgeOrigin === null && edgeOriginInConfig(rootConfigText) !== null) {
+    throw new Error(
+      "refusing to lease a stack that declares no [edge_runtime.secrets] VITE_SUPABASE_URL while the worktree's config does — " +
+        "the leased edge runtime would start without the public origin it fails closed on. Declare it, pinned to that stack's own api port.",
+    );
+  }
+  if (edgeOrigin !== null) {
+    const apiPort = stackPorts.get("api.port");
+    const expected = apiPort === undefined ? null : `http://127.0.0.1:${apiPort}`;
+    if (expected === null || edgeOrigin !== expected) {
+      throw new Error(
+        `refusing to lease a stack whose edge runtime origin is "${edgeOrigin}": it must be pinned to that stack's OWN api ` +
+          `port (${expected ?? "which its config does not declare"}), or the Helper's environment decides — and the leased ` +
+          "edge runtime emits another stack's (or production's) public URLs.",
+      );
+    }
+  }
+}
+
+// Supabase CLI scratch state is per-stack: never copied IN from the worktree, and
+// never pruned OUT of the leased stack (it belongs to that stack's own lifecycle).
+const SKIP_ENTRIES = new Set([".branches", ".temp"]);
+
+/**
+ * Is a stack directory still CLAIMED by its batch? `acquireStackLock` writes its
+ * lock file once and never refreshes it (the heartbeat goes to the server), so a
+ * batch that runs for hours has an ancient lock file — its age proves nothing
+ * (BOT-1798, Codex #928 R6). Only the recorded owner's liveness does. Anything
+ * unprovable — an unreadable payload, a claim recorded by another machine — counts
+ * as claimed, because wrongly deleting a live batch's tree is far worse than
+ * leaving a directory behind.
+ */
+function stackDirIsClaimed(projectId, { read, alive, host, marker = null }) {
+  // The marker's own owner is a second, independent claim: lock files live in the
+  // system temp directory, which the OS may sweep while a long batch is running.
+  if (marker && Number.isInteger(marker.owner_pid) && marker.owner_pid > 0
+      && (!marker.host || marker.host === host()) && alive(marker.owner_pid)) {
+    return true;
+  }
+  let raw;
+  try {
+    raw = read(lockPathForProject(projectId), "utf8");
+  } catch {
+    return false; // no lock file at all: nothing claims this directory
+  }
+  let holder;
+  try {
+    holder = JSON.parse(raw);
+  } catch {
+    return true; // a corrupt lock is not proof the batch is gone
+  }
+  if (!holder || !Number.isInteger(holder.pid) || holder.pid <= 0) return true;
+  if (holder.host && holder.host !== host()) return true; // another machine's claim
+  return alive(holder.pid);
+}
+
+/** Does this PID exist? EPERM means it exists and is simply not ours to signal. */
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}
+
+/**
+ * Does `dirName` belong to THIS ticket's family of materialized stacks?
+ *
+ * A prefix test is not enough (BOT-1798, Codex #928 R7): `BOT-179` prefixes
+ * `BOT-1798`, so `bbbot1798<hash>` would read as a `BOT-179` stack and a run for
+ * the shorter ticket could collect the longer one's live directory. The name must
+ * be the family prefix followed by exactly the generated hex suffix — and when the
+ * directory carries an ownership marker, that marker is authoritative.
+ */
+function isOwnStackFamily(dirName, { ticket, slot, marker }) {
+  // Compare NORMALIZED ticket keys (Codex #928 R11): `bot-1798` and `BOT-1798` are
+  // the same ticket, and the slot a previous batch happened to use is not part of
+  // ownership — requiring it left full supabase/ copies permanently uncollectable.
+  if (marker && (marker.ticket != null || marker.slot != null)) {
+    return identityTag(marker.ticket, marker.slot) === identityTag(ticket, slot);
+  }
+  return new RegExp(`^bb${identityTag(ticket, slot)}[0-9a-f]{1,6}$`).test(dirName);
+}
+
+/**
+ * Collect this ticket's long-finished stack directories (BOT-1798, Codex #928 R5/R6).
+ * Per-invocation directories would otherwise accumulate, but a batch that is still
+ * running must never be collected — so a directory is removed only when it is both
+ * older than `LEASED_STACK_GC_MIN_AGE_MS` (well past the reaper's idle TTL, so a
+ * child that outlived its dead owner cannot still be using it) AND unclaimed by a
+ * live lock owner. Best-effort throughout: collection never blocks provisioning.
+ */
+function collectFinishedStacks(stacksDir, { keep, ticket, slot, readdir, remove, stat, now, read, alive, host }) {
+  let entries;
+  try { entries = readdir(stacksDir); } catch { return []; }
+  const collected = [];
+  for (const entry of entries) {
+    if (entry === keep) continue;
+    try {
+      const marker = readStackMarker(join(stacksDir, entry), read);
+      // A marker states how long its batch must be kept, so an EXPIRED, unclaimed
+      // stack is provably finished whoever ran it — and one-off tickets would
+      // otherwise leave full supabase/ copies behind forever (Codex #928 R12).
+      // Without a marker nothing is provable, so stay inside this ticket's family
+      // and fall back to the conservative default age.
+      const retainUntil = Number.isFinite(marker?.retain_until) ? marker.retain_until : null;
+      if (retainUntil === null && !isOwnStackFamily(entry, { ticket, slot, marker })) continue;
+      if (now() < (retainUntil ?? stat(join(stacksDir, entry)).mtimeMs + LEASED_STACK_GC_MIN_AGE_MS)) continue;
+      if (stackDirIsClaimed(entry, { read, alive, host, marker })) continue;
+      remove(join(stacksDir, entry), { recursive: true, force: true });
+      collected.push(entry);
+    } catch { /* a racing collector or a permission fault is not fatal */ }
+  }
+  return collected;
+}
+
+/**
+ * Push this stack's retention deadline forward on a lease heartbeat (BOT-1798,
+ * Codex #928 R8). Anchoring retention to creation time was not enough: a batch
+ * that outlives its deadline and THEN loses its owner process still holds a live
+ * lease, child and containers for another idle-TTL window, and a later run would
+ * have collected the tree it is bind-mounting. The deadline therefore tracks the
+ * lease's last activity, exactly as the server's reaper does.
+ *
+ * Returns false (never throws) when there is no marker to refresh — an explicitly
+ * prepared `--stack-path` is the caller's to manage, not ours to annotate.
+ */
+export function refreshLeasedStackRetention(stackDir, { idleTtlSecs, now = Date.now, read = readFileSync, write = writeFileSync, rename = renameSync, portRegistryDir = null } = {}) {
+  const marker = readStackMarker(stackDir, read);
+  if (!marker) return false;
+  const ttlMs = Math.max(0, Number.isFinite(idleTtlSecs) ? idleTtlSecs : DEFAULT_IDLE_TTL_SECS) * 1000;
+  const at = now();
+  const renewed = JSON.stringify({
+    ...marker,
+    last_seen_at: at,
+    retain_until: at + Math.max(LEASED_STACK_GC_MIN_AGE_MS, ttlMs + LEASED_STACK_RETENTION_GRACE_MS),
+  });
+  try {
+    atomicWrite(join(stackDir, LEASED_STACK_MARKER), renewed, { write, rename });
+  } catch {
+    return false; // a best-effort extension must never fence a healthy batch
+  }
+  // Renew the host-scoped port reservation on the same beat, or another worktree
+  // would eventually read this live batch's block as free.
+  if (Number.isInteger(marker.port_base)) {
+    try {
+      // Codex #928 R23 (P2): a heartbeat can still be in flight when its own batch
+      // exits — cleanup releases (or an unrelated retry reclaims and re-reserves)
+      // this same block before the stale call reaches here. Verify the registry's
+      // CURRENT claim is still ours (by invocation, like releaseLeasedStackClaim)
+      // before overwriting it; otherwise this recreates a finished batch's claim,
+      // or worse, clobbers a different live invocation's claim with our stale
+      // metadata, making its fresh reservation look owned by our dead PID.
+      const claimPath = portClaimPath(portRegistryDir ?? defaultPortRegistryDir(), marker.port_base);
+      const owner = marker.invocation_token ?? marker.project_id;
+      let current = null;
+      try { current = JSON.parse(read(claimPath, "utf8")); } catch { current = null; }
+      if (current && (current.invocation_token ?? current.project_id) === owner) {
+        atomicWrite(claimPath, renewed, { write, rename });
+      }
+    } catch { /* the reservation is advisory; never fence a healthy batch */ }
+  }
+  return true;
+}
+
+/** This stack's ownership/retention marker, or null when it has none. */
+function readStackMarker(stackDir, read) {
+  try {
+    const parsed = JSON.parse(read(join(stackDir, LEASED_STACK_MARKER), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The port blocks this worktree's other leased stacks still hold (BOT-1798, Codex
+ * #928 R12). A per-invocation nonce spreads identities but says nothing about the
+ * 200 available blocks, so two concurrent runs could hash to the SAME ports: the
+ * server lease is keyed by the ticket slot, not the block, so nothing serializes
+ * them and the second Helper fails on a bind error after provisioning starts.
+ * A block counts as taken while its stack is retained or its lock owner is alive.
+ */
+function occupiedPortBlocks(registryDir, { keep, readdir, read, now, alive, host, stale = null }) {
+  const taken = new Map(); // portBase -> { projectId, createdAt }
+  let entries;
+  try { entries = readdir(registryDir); } catch { return taken; }
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    let claim;
+    try { claim = JSON.parse(read(join(registryDir, entry), "utf8")); } catch { continue; }
+    const portBase = Number(claim?.port_base);
+    if (!Number.isInteger(portBase)) continue;
+    const retained = Number.isFinite(claim.retain_until) && now() < claim.retain_until;
+    const ownerAlive = Number.isInteger(claim.owner_pid) && claim.owner_pid > 0
+      && (!claim.host || claim.host === host()) && alive(claim.owner_pid);
+    if (!retained && !ownerAlive) {
+      // A reservation whose batch is provably finished is not a claim — reclaim it
+      // even when it shares `keep`'s project id (Codex #928 R23): `keep` exempts a
+      // STILL-LIVE claim we already hold from looking like a peer's, not an expired
+      // one from a past, dead invocation of the same project. Checked before the
+      // `keep` exemption below, or an expired same-project claim is invisible to
+      // both `taken` and `stale` forever — never a collision, but never reclaimed
+      // either, wedging any caller that needs this EXACT block (reservePortBlocks'
+      // explicit --stack-path ports have nowhere else to go). It is NOT deleted
+      // here: removal happens under the allocation lock, so a peer's fresh claim can
+      // never be wiped by a decision made before it existed.
+      stale?.add(portBase);
+      continue;
+    }
+    if (claim.project_id === keep) continue; // a live claim we already hold: not a peer's
+    const previous = taken.get(portBase);
+    const createdAt = Number.isFinite(claim.created_at) ? claim.created_at : 0;
+    if (!previous || createdAt < previous.createdAt) taken.set(portBase, { projectId: claim.project_id ?? entry, createdAt });
+  }
+  return taken;
+}
+
+/** Overwrite a file atomically (BOT-1798, Codex #928 R15): a crash mid-write must
+ * never leave a truncated marker, because an unparseable marker downgrades a live
+ * stack to "no recorded retention" and invites the collector to delete it. */
+function atomicWrite(path, data, { write, rename }) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  write(tmp, data);
+  rename(tmp, path);
+}
+
+/** Block this thread for `ms` without async: the allocation critical section is
+ * a handful of file operations, and materialization is synchronous. */
+function sleepSync(ms) {
+  try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* fall through */ }
+}
+
+/**
+ * Run `fn` holding the host-scoped allocation lock (BOT-1798, Codex #928 R16).
+ * Taken by exclusive create; a lock whose owner is dead — or that is older than
+ * the critical section could possibly be — is stolen, so a crash never wedges the
+ * machine's port allocation.
+ */
+function withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep = sleepSync }, fn) {
+  const lockPath = join(registryDir, LEASED_ALLOCATION_LOCK);
+  const guardPath = `${lockPath}.reclaim`;
+  const token = randomUUID();
+  const deadline = now() + 30_000;
+  for (;;) {
+    try {
+      writeExclusive(lockPath, JSON.stringify({ pid: process.pid, host: host(), at: now(), owner_token: token }));
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      let raw = null;
+      try { raw = read(lockPath, "utf8"); } catch { raw = null; }
+      if (raw === null) continue; // it vanished: try to create again
+      let holder = null;
+      try { holder = JSON.parse(raw); } catch { /* corrupt: treat as abandoned */ }
+      const abandoned = !holder
+        || !Number.isInteger(holder.pid)
+        || (holder.host && holder.host !== host())
+        || !alive(holder.pid)
+        || now() - (Number(holder.at) || 0) > LEASED_ALLOCATION_LOCK_STALE_MS;
+      if (abandoned) {
+        // Serialize the STEAL itself and delete only the exact record we inspected
+        // (Codex #928 R18): two stealers could otherwise both read the abandoned
+        // lock and the slower one would delete the winner's replacement, putting
+        // both inside the critical section.
+        let guarded = false;
+        try {
+          writeExclusive(guardPath, JSON.stringify({ pid: process.pid, at: now(), owner_token: token }));
+          guarded = true;
+        } catch (guardError) {
+          if (guardError?.code !== "EEXIST") throw guardError;
+          // The guard itself can be abandoned (it is held for two file ops), but it
+          // is taken over with the same generation check as the lock (Codex #928
+          // R22): deleting it unconditionally would remove a peer's REPLACEMENT and
+          // admit two allocators at once.
+          let guardRaw = null;
+          try { guardRaw = read(guardPath, "utf8"); } catch { guardRaw = null; }
+          let guardHolder = null;
+          if (guardRaw !== null) {
+            try { guardHolder = JSON.parse(guardRaw); } catch { /* corrupt */ }
+            if (!guardHolder || now() - (Number(guardHolder.at) || 0) > LEASED_ALLOCATION_LOCK_STALE_MS) {
+              let current = null;
+              try { current = read(guardPath, "utf8"); } catch { current = null; }
+              if (current === guardRaw) {
+                try { remove(guardPath, { force: true }); } catch { /* a peer may have won */ }
+              }
+            }
+          }
+        }
+        if (guarded) {
+          try {
+            let current = null;
+            try { current = read(lockPath, "utf8"); } catch { current = null; }
+            if (current === raw) {
+              try { remove(lockPath, { force: true }); } catch { /* vanished already */ }
+            }
+          } finally {
+            // Only ever unlink OUR OWN guard.
+            try {
+              const mine = JSON.parse(read(guardPath, "utf8"));
+              if (mine?.owner_token === token) remove(guardPath, { force: true });
+            } catch { /* gone, corrupt, or superseded */ }
+          }
+          continue; // we just cleared the lock ourselves: worth an immediate retry
+        }
+        // Codex #928 R23 (P2): a peer's OWN reclaim guard is live (or merely looked
+        // fresh a moment ago) — we made no progress this iteration. Fall through to
+        // the SAME deadline check + backoff as the "lock is held" case below instead
+        // of looping straight back to the top: skipping both, as this branch used to,
+        // spins at full CPU re-reading the guard until it separately goes stale,
+        // which can take up to LEASED_ALLOCATION_LOCK_STALE_MS regardless of this
+        // call's own 30s deadline.
+      }
+      if (now() > deadline) {
+        throw new Error(
+          "refusing to materialize an isolated leased stack: another run has held the host's port-allocation lock for 30s. " +
+            "Retry once that batch has started.",
+        );
+      }
+      sleep(50);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    // Only ever unlink OUR OWN lock: a stealer may already have replaced it.
+    try {
+      const current = JSON.parse(read(lockPath, "utf8"));
+      if (current?.owner_token === token) remove(lockPath, { force: true });
+    } catch { /* gone, corrupt, or superseded: never unlink blindly */ }
+  }
+}
+
+/**
+ * The host blocks a set of declared ports occupies. Blocks are `LEASED_PORT_STRIDE`
+ * wide across the WHOLE port space (Codex #928 R19): the leased band is aligned to
+ * that stride, so materialized stacks key exactly as before, and a hand-prepared
+ * stack outside the band — two of which can just as easily reuse 57000 — is
+ * reserved on the same host registry instead of silently unserialized.
+ */
+export function blocksForPorts(ports) {
+  const blocks = new Set();
+  for (const value of ports) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0) continue;
+    blocks.add(Math.floor(port / LEASED_PORT_STRIDE) * LEASED_PORT_STRIDE);
+  }
+  return [...blocks].sort((a, b) => a - b);
+}
+
+/**
+ * Give back the host port block a materialized batch holds, the moment its stack
+ * is provably gone (BOT-1798, Codex #928 R19). Every invocation takes a NEW
+ * identity, so holding claims for their full retention after a proven reap would
+ * let a couple of hundred successful sequential runs exhaust the machine while
+ * nothing is running. Ownership-checked and best-effort: a claim that now belongs
+ * to another batch is never unlinked. Returns true when a claim was released.
+ */
+export function releaseLeasedStackClaim(stackDir, { registryDir = defaultPortRegistryDir(), io = {} } = {}) {
+  const read = io.readFile ?? readFileSync;
+  const remove = io.remove ?? rmSync;
+  const marker = readStackMarker(stackDir, read);
+  if (!marker || !Number.isInteger(marker.port_base)) return false;
+  const path = portClaimPath(registryDir, marker.port_base);
+  let claim = null;
+  try { claim = JSON.parse(read(path, "utf8")); } catch { return false; }
+  const owner = marker.invocation_token ?? marker.project_id;
+  if (!claim || (claim.invocation_token ?? claim.project_id) !== owner) return false;
+  try {
+    remove(path, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reserve the blocks an EXPLICIT `--stack-path` occupies (BOT-1798, Codex #928
+ * R18). Its project lock only serializes runs that share a project id; two
+ * prepared directories with different ids but overlapping ports — or one
+ * overlapping a materialized stack — would still collide on the host. Returns a
+ * `release()`; throws (code `stack_ports_busy`) when a live peer holds a block.
+ */
+export function reservePortBlocks(ports, { registryDir = defaultPortRegistryDir(), owner, io = {} } = {}) {
+  const read = io.readFile ?? readFileSync;
+  const write = io.writeFile ?? writeFileSync;
+  const mkdir = io.mkdir ?? mkdirSync;
+  const readdir = io.readdir ?? readdirSync;
+  const remove = io.remove ?? rmSync;
+  const now = io.now ?? Date.now;
+  const alive = io.alive ?? pidIsAlive;
+  const host = io.hostname ?? hostname;
+  const sleep = io.sleep ?? sleepSync;
+  const writeExclusive = io.writeExclusive ?? ((path, data) => writeFileSync(path, data, { flag: "wx" }));
+  const blocks = blocksForPorts(ports);
+  // Identity is not ownership (Codex #928 R21): a RETRY of a prepared path reuses
+  // its project id, and a claim retained because the previous attempt's reap was
+  // unproven must not be overwritten by it. Claims therefore carry a token unique
+  // to one invocation.
+  const invocationToken = owner?.invocationToken ?? randomUUID();
+  if (blocks.length === 0) return { blocks: [], invocationToken, release: () => {}, renew: () => false };
+
+  mkdir(registryDir, { recursive: true });
+  const claimed = [];
+  const record = (block, at = now(), ttlSecs = owner?.idleTtlSecs) => JSON.stringify({
+    schema: 1,
+    project_id: owner?.projectId ?? null,
+    invocation_token: invocationToken,
+    ticket: owner?.ticket == null ? null : String(owner.ticket),
+    slot: owner?.slot == null ? null : String(owner.slot),
+    stack_dir: owner?.stackDir ?? null,
+    port_base: block,
+    created_at: at,
+    retain_until: at + Math.max(LEASED_STACK_GC_MIN_AGE_MS, (Number(ttlSecs) || DEFAULT_IDLE_TTL_SECS) * 1000 + LEASED_STACK_RETENTION_GRACE_MS),
+    owner_pid: process.pid,
+    host: host(),
+  });
+  try {
+    withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
+      const stale = new Set();
+      const taken = occupiedPortBlocks(registryDir, { keep: owner?.projectId ?? null, readdir, read, now, alive, host, stale });
+      for (const block of stale) {
+        try { remove(portClaimPath(registryDir, block), { force: true }); } catch { /* best effort */ }
+      }
+      for (const block of blocks) {
+        if (taken.has(block)) {
+          const error = new Error(
+            `refusing to lease this stack: its port block ${block}-${block + LEASED_PORT_STRIDE - 1} is already reserved by ` +
+              `another live batch (${taken.get(block).projectId}). Wait for it to finish, or prepare the stack on a free block.`,
+          );
+          error.code = "stack_ports_busy";
+          throw error;
+        }
+        try {
+          writeExclusive(portClaimPath(registryDir, block), record(block));
+        } catch (error) {
+          if (error?.code !== "EEXIST") throw error;
+          // Only THIS invocation's own reservation is not a peer.
+          let existing = null;
+          try { existing = JSON.parse(read(portClaimPath(registryDir, block), "utf8")); } catch { /* unreadable */ }
+          if (existing && existing.invocation_token === invocationToken) write(portClaimPath(registryDir, block), record(block));
+          else {
+            const busy = new Error(`refusing to lease this stack: port block ${block} was claimed by another run.`);
+            busy.code = "stack_ports_busy";
+            throw busy;
+          }
+        }
+        claimed.push(block);
+      }
+    });
+  } catch (error) {
+    for (const block of claimed) {
+      try { remove(portClaimPath(registryDir, block), { force: true }); } catch { /* best effort */ }
+    }
+    throw error;
+  }
+  return {
+    blocks: claimed,
+    invocationToken,
+    /** Keep the reservation alive while the batch runs (Codex #928 R21): a
+     * prepared `--stack-path` has no directory marker, so nothing else renews it,
+     * and an aged-out claim could be reclaimed under a still-live stack. */
+    renew: ({ idleTtlSecs, now: at = now } = {}) => {
+      let renewed = false;
+      for (const block of claimed) {
+        try {
+          const current = JSON.parse(read(portClaimPath(registryDir, block), "utf8"));
+          if (current?.invocation_token !== invocationToken) continue;
+          write(portClaimPath(registryDir, block), record(block, at(), idleTtlSecs ?? owner?.idleTtlSecs));
+          renewed = true;
+        } catch { /* advisory: never fence a healthy batch */ }
+      }
+      return renewed;
+    },
+    release: () => {
+      for (const block of claimed) {
+        try {
+          const current = JSON.parse(read(portClaimPath(registryDir, block), "utf8"));
+          if (current?.invocation_token === invocationToken) remove(portClaimPath(registryDir, block), { force: true });
+        } catch { /* gone or superseded: never unlink blindly */ }
+      }
+    },
+  };
+}
+
+/** The host-scoped reservation file for a block. */
+function portClaimPath(registryDir, portBase) {
+  return join(registryDir, `${portBase}.json`);
+}
+
+/** The first free block at or after the identity's own hash-derived one. */
+function selectPortBase(preferred, taken) {
+  const start = Math.floor((preferred - LEASED_PORT_BASE) / LEASED_PORT_STRIDE);
+  for (let i = 0; i < LEASED_PORT_SLOTS; i++) {
+    const candidate = LEASED_PORT_BASE + ((start + i) % LEASED_PORT_SLOTS) * LEASED_PORT_STRIDE;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw new Error(
+    `refusing to materialize an isolated leased stack: all ${LEASED_PORT_SLOTS} leased port blocks ` +
+      `(${LEASED_PORT_BASE}-${LEASED_PORT_BASE + LEASED_PORT_SLOTS * LEASED_PORT_STRIDE - 1}) are held by live or retained stacks. ` +
+      "Finish or reap a batch before starting another.",
+  );
+}
+
+/**
+ * Refuse a materialization target that is not literally inside the worktree
+ * (BOT-1798, Codex #928 R4 P1). The refresh prunes and copies BEFORE
+ * `resolveStackPath` could notice an escape, so a stale or hostile symlink at
+ * `.botbuddy/`, `.botbuddy/stacks/`, `<project_id>/` or its `supabase/` would
+ * make `prune()` delete data OUTSIDE the worktree. Every existing component of
+ * the path must therefore resolve to itself; the first one that does not is
+ * fatal, and a component that does not exist yet ends the walk (nothing below it
+ * can exist either). `worktreeRoot` is already canonical (realpath of the cwd).
+ */
+function assertCanonicalTarget(worktreeRoot, relPath, realpath) {
+  let expected = worktreeRoot;
+  for (const part of relPath.split("/")) {
+    expected = join(expected, part);
+    let resolved;
+    try {
+      resolved = realpath(expected);
+    } catch (error) {
+      if (error?.code === "ENOENT") return; // not created yet
+      throw error;
+    }
+    if (resolved !== expected) {
+      throw new Error(
+        `refusing to materialize an isolated leased stack: ${expected} is a symlink (it resolves to ${resolved}), so refreshing ` +
+          "the stack would delete and rewrite files outside this worktree. Remove that link and re-run.",
+      );
+    }
+  }
+}
+
+/** Delete everything the refresh is about to replace, so a file removed from the
+ * worktree cannot linger in the leased stack (and be applied by `supabase start`).
+ * The stack's own CLI scratch state (SKIP_ENTRIES) is left alone. A not-yet-created
+ * directory is simply nothing to prune. */
+function prune(stackSupabaseDir, { readdir, remove }) {
+  let entries;
+  try { entries = readdir(stackSupabaseDir); } catch { return; }
+  for (const entry of entries) {
+    if (SKIP_ENTRIES.has(entry)) continue;
+    remove(join(stackSupabaseDir, entry), { recursive: true, force: true });
+  }
+}
+
+/**
+ * Materialize (or refresh) the isolated stack directory for this run and return
+ * its path RELATIVE to the worktree root — never `"."`. The directory belongs to
+ * ONE invocation (see `nonce` on `leasedStackIdentity`), so a concurrent or
+ * crashed batch's tree is never rewritten; this ticket's long-finished
+ * directories are collected on the way past.
+ *
+ * The worktree's whole `supabase/` tree is copied, not symlinked: the Helper's
+ * edge-runtime container bind-mounts `<stack_path>/supabase/functions`, and a
+ * symlink that resolves on the host does not resolve inside Docker (the same
+ * reason Supply Guard's isolated-stack script materializes function sources).
+ * Copying every run also keeps the leased stack in step with the worktree — and
+ * the copy is a REPLACE (rsync --delete semantics, like the hermetic lane), so a
+ * migration or function deleted in the worktree is not resurrected by the leased
+ * stack. Only the Supabase CLI's own scratch state survives the refresh.
+ */
+export function materializeRunStackDir(cwd, { slot, ticket, nonce, idleTtlSecs } = {}, io = {}) {
+  const read = io.readFile ?? readFileSync;
+  const write = io.writeFile ?? writeFileSync;
+  const mkdir = io.mkdir ?? mkdirSync;
+  const copy = io.copy ?? cpSync;
+  const readdir = io.readdir ?? readdirSync;
+  const remove = io.remove ?? rmSync;
+  const stat = io.stat ?? statSync;
+  const now = io.now ?? Date.now;
+  const rename = io.rename ?? renameSync;
+  const resolveRoot = io.realpath ?? realpathSync;
+
+  const worktreeRoot = resolveRoot(cwd);
+  const sourceDir = join(worktreeRoot, "supabase");
+  const configPath = join(sourceDir, "config.toml");
+  let rootConfig;
+  try {
+    rootConfig = read(configPath, "utf8");
+  } catch (error) {
+    throw new Error(
+      `cannot materialize an isolated leased stack: ${configPath} is missing or unreadable (${error?.code ?? error?.message ?? error}). ` +
+        "`bb stack run` derives its own stack from the worktree's supabase/config.toml; it never leases the worktree root, " +
+        "because the Helper would start the SHARED canonical project there.",
+    );
+  }
+
+  const alive = io.alive ?? pidIsAlive;
+  const host = io.hostname ?? hostname;
+  const sleep = io.sleep ?? sleepSync;
+  const identity = leasedStackIdentity({ worktreeRoot, slot, ticket, nonce });
+  const stackPath = `${LEASED_STACKS_DIR}/${identity.dirName}`;
+  const stackDir = join(worktreeRoot, stackPath);
+  const stacksDir = join(worktreeRoot, LEASED_STACKS_DIR);
+
+  collectFinishedStacks(stacksDir, {
+    keep: identity.dirName, ticket, slot, readdir, remove, stat, now, read, alive, host,
+  });
+  // Prove the target is really inside this worktree BEFORE pruning or copying.
+  assertCanonicalTarget(worktreeRoot, `${stackPath}/supabase`, resolveRoot);
+  let dirExisted = true;
+  try { stat(stackDir); } catch { dirExisted = false; }
+  mkdir(stackDir, { recursive: true });
+  assertCanonicalTarget(worktreeRoot, `${stackPath}/supabase`, resolveRoot);
+
+  // Claim a port block no live sibling holds, then re-scan: another run can pick
+  // the same free block at the same instant, and the tie-break moves exactly one
+  // of us. The claim is published as a marker before the copy, so a concurrent
+  // scanner can see it.
+  const createdAt = now();
+  const ttlMs = Math.max(0, Number.isFinite(idleTtlSecs) ? idleTtlSecs : DEFAULT_IDLE_TTL_SECS) * 1000;
+  // With a nonce the token IS the invocation; without one the identity is the
+  // stable per-slot one, so the project id is exactly as specific (and keeps a
+  // refresh idempotent).
+  const invocationToken = nonce ? String(nonce) : identity.projectId;
+  const marker = (portBase) => JSON.stringify({
+    schema: 1,
+    project_id: identity.projectId,
+    invocation_token: invocationToken,
+    ticket: ticket == null ? null : String(ticket),
+    slot: slot == null ? null : String(slot),
+    port_base: portBase,
+    stack_dir: stackDir,
+    created_at: createdAt,
+    retain_until: createdAt + Math.max(LEASED_STACK_GC_MIN_AGE_MS, ttlMs + LEASED_STACK_RETENTION_GRACE_MS),
+    owner_pid: process.pid,
+    host: host(),
+  });
+  const registryDir = io.portRegistryDir ?? defaultPortRegistryDir();
+  const writeExclusive = io.writeExclusive ?? ((path, data) => writeFileSync(path, data, { flag: "wx" }));
+  mkdir(registryDir, { recursive: true });
+  // Claim the block by EXCLUSIVE CREATE (Codex #928 R14) inside the host's
+  // allocation lock (Codex #928 R16): the scan only REPORTS stale reservations, and
+  // reclaiming one plus taking the block happen as one serialized step, so a
+  // slower peer can never delete the winner's fresh claim.
+  const portBase = withAllocationLock(registryDir, { writeExclusive, read, remove, now, alive, host, sleep }, () => {
+    let preferred = identity.portBase;
+    for (let attempt = 0; attempt < LEASED_PORT_SLOTS; attempt++) {
+      const stale = new Set();
+      const taken = occupiedPortBlocks(registryDir, { keep: identity.projectId, readdir, read, now, alive, host, stale });
+      // Every claim creation happens under this lock, so a reservation that read as
+      // finished a moment ago cannot have become live since: sweeping them here
+      // releases the machine's blocks without ever racing a peer's fresh claim.
+      for (const block of stale) {
+        try { remove(portClaimPath(registryDir, block), { force: true }); } catch { /* best effort */ }
+      }
+      const candidate = selectPortBase(preferred, taken);
+      try {
+        writeExclusive(portClaimPath(registryDir, candidate), marker(candidate));
+        return candidate;
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        // Our OWN previous claim (a re-materialization of this same batch) is not a
+        // peer: take it back rather than drifting onto a new block every refresh.
+        let existing = null;
+        try { existing = JSON.parse(read(portClaimPath(registryDir, candidate), "utf8")); } catch { /* unreadable: treat as a peer */ }
+        // Ownership is the INVOCATION, not the project id (Codex #928 R22): two
+        // nonces can in principle truncate to the same project suffix, and the
+        // earlier run's Helper may still be using that stack.
+        if (existing?.invocation_token === invocationToken) {
+          write(portClaimPath(registryDir, candidate), marker(candidate));
+          return candidate;
+        }
+        preferred = candidate + LEASED_PORT_STRIDE; // a peer won this one
+      }
+    }
+    return null;
+  });
+  if (portBase === null) {
+    throw new Error(
+      `refusing to materialize an isolated leased stack: every leased port block was claimed by another run while this one ` +
+        "was choosing. Retry once the host has fewer concurrent batches.",
+    );
+  }
+  // From here on the block is RESERVED: any failure must give it back, or a
+  // retrying start would take another one and eventually exhaust the host
+  // (Codex #928 R15). The half-built directory goes too, unless it predates us.
+  try {
+    atomicWrite(join(stackDir, LEASED_STACK_MARKER), marker(portBase), { write, rename });
+
+    const { text } = rewriteLeasedStackConfig(rootConfig, { projectId: identity.projectId, portBase });
+    assertLeasedStackIsolated(rootConfig, text);
+
+    prune(join(stackDir, "supabase"), { readdir, remove });
+    copy(sourceDir, join(stackDir, "supabase"), {
+      recursive: true,
+      force: true,
+      filter: (source) => !SKIP_ENTRIES.has(basename(source)),
+    });
+    write(join(stackDir, "supabase", "config.toml"), text);
+  // Re-state the claim after the copy: the marker records who owns this directory,
+  // which port block it holds, and how long a later run must keep it (Codex #928
+  // R7/R12). It lives beside `supabase/`, which the refresh replaces wholesale.
+    atomicWrite(join(stackDir, LEASED_STACK_MARKER), marker(portBase), { write, rename });
+    atomicWrite(portClaimPath(registryDir, portBase), marker(portBase), { write, rename });
+    return stackPath;
+  } catch (error) {
+    try { remove(portClaimPath(registryDir, portBase), { force: true }); } catch { /* best effort */ }
+    if (!dirExisted) {
+      try { remove(stackDir, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+    throw error;
+  }
+}