@botbuddy/cli 1.32.4 → 1.33.1

package/src/stack.mjs

@@ -34,13 +34,17 @@ import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
 import { resolveAgentSessionCredential } from "./agent-session.mjs";
 import { clearAgentState } from "./agent-state.mjs";
 import { runDockerCommand, runDockerWorkflow, ADMITTED_DOCKER_VALIDATIONS } from "./docker-hygiene.mjs";
-import { projectIdFromConfig } from "./stack-file-lock.mjs";
+import { acquireStackLock, lockPathForProject, projectIdFromConfig } from "./stack-file-lock.mjs";
+import { assertLeasedStackIsolated, leasedStackIdentity, materializeRunStackDir, portMapInConfig, refreshLeasedStackRetention, releaseLeasedStackClaim, reservePortBlocks } from "./stack-isolation.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
 export const DEFAULT_RECEIPT_MAX_BYTES = 10240;
 export const DEFAULT_TIMEOUT_SEC = 3600;
+/** How often a run renews its stack directory's retention while it still exists
+ * (BOT-1798): frequent enough to cover the pre-child queue/provision waits. */
+const RETENTION_REFRESH_MS = 5 * 60 * 1000;
 
 // Meaningful, documented exit codes (mirrors bb-wait's taxonomy).
 export const EXIT = Object.freeze({
@@ -98,6 +102,11 @@ ${bold("done OPTIONS")}
 ${bold("run OPTIONS")}
   --repo <repo>          Required approved repository name.
   --ticket <BOT-123>     Required ticket for the batch.
+  --stack-path <relative> Optional PREPARED isolated stack dir. Omit it (the norm): run
+                         materializes .botbuddy/stacks/<project_id>/ from this worktree's
+                         supabase/ tree with a distinct project_id + remapped ports and
+                         leases that. "." is REFUSED — the worktree root is the shared
+                         canonical project and the Helper would start/clobber it.
   --provision-timeout N  Seconds to wait for a physical Helper provision (default: --timeout).
   --reap-timeout N       Seconds to wait for signed physical reap proof (default: 300).
   --connection-file P    Optional empty file path for the mode-0600 connection JSON.
@@ -162,7 +171,7 @@ export function parseStackArgs(argv) {
   const childArgv = divider === -1 ? [] : rawRest.slice(divider + 1);
   const opts = {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
-    prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".",
+    prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
     connectionFile: null, noWait: false, localExec: false,
     dockerContext: null, dockerEndpoint: null,
@@ -187,7 +196,7 @@ export function parseStackArgs(argv) {
       case "--pr": if (need(a, rest[i + 1])) opts.prId = rest[++i]; break;
       case "--pr-url": if (need(a, rest[i + 1])) opts.prUrl = rest[++i]; break;
       case "--purpose": if (need(a, rest[i + 1])) opts.purpose = rest[++i]; break;
-      case "--stack-path": if (need(a, rest[i + 1])) opts.stackPath = rest[++i]; break;
+      case "--stack-path": if (need(a, rest[i + 1])) { opts.stackPath = rest[++i]; opts.stackPathExplicit = true; } break;
       case "--idle-ttl": {
         if (need(a, rest[i + 1])) {
           const n = Number(rest[++i]);
@@ -273,6 +282,16 @@ export function parseStackArgs(argv) {
     errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
   }
   if (command === "run") {
+    // BOT-1798: `run` is Helper-backed — the Helper runs `supabase start` in
+    // <worktree_root>/<stack_path>, so "." is the SHARED canonical project. The
+    // DEFAULT is not an error (run materializes its own isolated stack); asking
+    // for the worktree root explicitly is, and says so like the BOT-1711 refusal.
+    if (opts.stackPathExplicit && opts.stackPath === ".") {
+      errors.push("run requires --stack-path <isolated-stack-dir>, not \".\": the worktree root declares the shared canonical " +
+        "project, so a lease there makes the Helper start (and clobber) the shared dev stack. Omit --stack-path to let " +
+        "`stack run` materialize an isolated stack, or point it at a directory with its own supabase/config.toml " +
+        "(distinct project_id + remapped ports).");
+    }
     if (!opts.repo) errors.push("run needs --repo <approved-repo>");
     if (!opts.ticket || !/^[A-Z][A-Z0-9]*-\d+$/i.test(opts.ticket)) errors.push("run needs --ticket <BOT-n|ENT-n>");
     if (divider === -1 || childArgv.length === 0) errors.push("run needs an executable after --");
@@ -324,6 +343,137 @@ export function resolveStackPath(cwd = process.cwd(), stackPath = ".") {
   return { worktreeRoot: root, stackPath: inside || "." };
 }
 
+/**
+ * BOT-1798 — resolve the stack directory a Helper-backed `stack run` will lease.
+ *
+ * With no `--stack-path` (the default, and what every caller uses) the CLI
+ * MATERIALIZES an isolated stack inside the worktree and leases that, instead of
+ * handing the Helper the worktree root — where `supabase start` operates the
+ * SHARED canonical project, collides with the running shared stack, fails
+ * provisioning with an unusable `supabase status`, and leaves an unreapable
+ * lease. An explicitly prepared isolated directory is honoured verbatim.
+ *
+ * Fail closed: whatever produced the path, a `run` lease at `"."` is refused.
+ *
+ * Each invocation gets its OWN stack directory and project id (BOT-1798, Codex
+ * #928 R3/R5): a second `run` on the same worktree+slot must never delete and
+ * recopy the `supabase/functions` tree a live batch's edge runtime is
+ * bind-mounting — and that batch stays live even when its OWNER process is gone
+ * (the child is detached, and the containers and server lease survive to the idle
+ * TTL), so no liveness check on this side could make a shared directory safe. The
+ * per-project lock is still taken and held for the whole batch, so the directory
+ * is visibly claimed while it is in use; a run's lease is released with `destroy`,
+ * so nothing is lost by not reusing the previous invocation's volume.
+ */
+async function claimProjectLock(projectId, lock, subject) {
+  try {
+    return await lock(lockPathForProject(projectId), { timeoutMs: 0 });
+  } catch (error) {
+    const busy = new Error(
+      `refusing to lease ${subject}: its project lock is already held — ${error?.message ?? error}. ` +
+        "Wait for that batch to finish, or re-run to get a fresh stack identity.",
+    );
+    busy.code = "stack_slot_busy";
+    throw busy;
+  }
+}
+
+export async function resolveRunExecution(cwd, opts, { materialize = materializeRunStackDir, lock = acquireStackLock, identity = leasedStackIdentity, reserveBlocks = reservePortBlocks, releaseClaim = releaseLeasedStackClaim, portRegistryDir = null } = {}) {
+  const refuseRoot = (execution) => {
+    if (execution.stackPath === ".") {
+      throw new Error(
+        'refusing to request a stack lease with stack_path "." — the Helper would run `supabase start` at the worktree root, ' +
+          "which declares the shared canonical project. Pass --stack-path <isolated-stack-dir>, or let `stack run` materialize one.",
+      );
+    }
+    return execution;
+  };
+  // An explicitly prepared directory is the caller's to manage, but it is NOT
+  // exempt from the isolation contract (BOT-1798, Codex #928 R8 P1): a copied root
+  // config — same project_id, or merely the same ports — would make the Helper
+  // start the SHARED canonical project from that directory, exactly the accident
+  // this ticket exists to close. Prove it before anything is leased.
+  if (opts.stackPath && opts.stackPath !== ".") {
+    const execution = refuseRoot(resolveStackPath(cwd, opts.stackPath));
+    const configOf = (dir) => {
+      try {
+        return readFileSync(`${dir}/supabase/config.toml`, "utf8");
+      } catch (error) {
+        throw new Error(
+          `refusing to lease --stack-path ${opts.stackPath}: ${dir}/supabase/config.toml is missing or unreadable ` +
+            `(${error?.code ?? error?.message ?? error}), so its isolation from the shared canonical stack cannot be proven.`,
+        );
+      }
+    };
+    const stackConfig = configOf(stackDirFor(execution));
+    assertLeasedStackIsolated(configOf(execution.worktreeRoot), stackConfig);
+    // Claim the prepared stack for this batch too (Codex #928 R17 P2): two runs on
+    // DIFFERENT tickets pointed at one directory are not serialized by their server
+    // slots, so both Helpers would `supabase start` the same project and ports.
+    const prepared = projectIdFromConfig(stackConfig);
+    const held = await claimProjectLock(prepared, lock, `--stack-path ${opts.stackPath}`);
+    // …and reserve the HOST blocks its ports occupy (Codex #928 R18 P2): the
+    // project lock only serializes runs that share a project id, so a second
+    // prepared directory with a different id but overlapping ports — or one
+    // overlapping a materialized stack — would still collide on the machine.
+    let ports;
+    try {
+      ports = reserveBlocks([...portMapInConfig(stackConfig).values()], {
+        ...(portRegistryDir ? { registryDir: portRegistryDir } : {}),
+        owner: {
+          projectId: prepared, ticket: opts.ticket, slot: opts.slot,
+          stackDir: stackDirFor(execution), idleTtlSecs: opts.idleTtl, invocationToken: randomUUID(),
+        },
+      });
+    } catch (error) {
+      held.release();
+      throw error;
+    }
+    return {
+      ...execution,
+      // A prepared directory carries no retention marker, so its reservation is
+      // renewed here on the batch's own beat (Codex #928 R21 P2).
+      renew: (options) => ports.renew(options),
+      release: ({ reaped = false } = {}) => {
+        if (reaped) ports.release();
+        held.release();
+      },
+    };
+  }
+  const worktreeRoot = realpathSync(cwd);
+  // One nonce per invocation, shared by the identity and the materialization below.
+  const nonce = opts.stackNonce ?? randomUUID();
+  const { projectId } = identity({ worktreeRoot, slot: opts.slot, ticket: opts.ticket, nonce });
+  const held = await claimProjectLock(projectId, lock, `this batch's isolated stack (${projectId})`);
+  try {
+    const execution = refuseRoot(resolveStackPath(cwd, materialize(
+      cwd,
+      { slot: opts.slot, repo: opts.repo, ticket: opts.ticket, nonce, idleTtlSecs: opts.idleTtl ?? undefined },
+      portRegistryDir ? { portRegistryDir } : {},
+    )));
+    return {
+      ...execution,
+      // Release is called once the batch's signed reap is done, so hand the host
+      // its port block back immediately rather than holding it for the retention
+      // window this batch no longer needs (Codex #928 R19 P2).
+      // The host block goes back only on a PROVEN reap (Codex #928 R20 P2): if the
+      // signed cleanup failed or timed out, the Helper may still be provisioning
+      // or running containers, so the reservation must stand until its retention
+      // expires. The project lock is always released — it guards this directory,
+      // which no other invocation can target.
+      release: ({ reaped = false } = {}) => {
+        if (reaped) {
+          try { releaseClaim(stackDirFor(execution), portRegistryDir ? { registryDir: portRegistryDir } : undefined); } catch { /* advisory */ }
+        }
+        held.release();
+      },
+    };
+  } catch (error) {
+    held.release();
+    throw error;
+  }
+}
+
 /** Parse `supabase status -o json` (or the plain key/value fallback) into a connection block. */
 export function parseSupabaseStatus(text) {
   const t = String(text || "");
@@ -868,55 +1018,11 @@ function projectIdUnder(dir, read = readFileSync) {
   catch { return 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). */
-// 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).
-function tomlIntToDecimal(token) {
-  const cleaned = String(token).replace(/_/g, "");
-  const n = Number(cleaned);
-  return Number.isInteger(n) && n >= 0 ? String(n) : null;
-}
-
-// 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_]*)";
-
-function portMapInConfig(toml) {
-  const map = new Map();
-  let section = "";
-  const bare = new RegExp(`^((?:[A-Za-z0-9]+_)?port)\\s*=\\s*${TOML_INT_PORT}`);
-  // Dotted TOML key form (BOT-1711 R16): `api.port = N` / `db.shadow_port = N`, section-
-  // qualified inline instead of under a `[section]` header. Normalizes to the same key.
-  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;
-}
+// BOT-1798: `portMapInConfig` (the section-qualified port map these isolation
+// checks read) now lives in ./stack-isolation.mjs, shared with the `stack run`
+// materializer that WRITES an isolated config — one parser, so what the
+// materializer emits is exactly what these guards read back.
 
-/** Read a stack directory's identity — project_id + its COMPLETE, section-qualified port
- * allocation — from its `supabase/config.toml`, in one read. Empty/null when unreadable. */
 function readStackIdentity(dir, read = readFileSync) {
   try {
     const toml = read(`${dir}/supabase/config.toml`, "utf8");
@@ -1593,8 +1699,11 @@ function requireConnectionText(connection, key) {
 
 /** Materialise the established integration runner inputs from a Helper receipt.
  * The runner already understands BB_INTEGRATION_ENV_FILE / BB_STACK_CONFIG;
- * never let its shared-stack defaults silently validate the wrong stack. */
-export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connection, { writePrivate = writePrivateTextFile, removePrivate = (path) => unlink(path).catch(() => {}) } = {}) {
+ * never let its shared-stack defaults silently validate the wrong stack.
+ * `worktreeRoot` is where the committed env template is read from; `edgeMountRoot`
+ * (default: the same) is the directory whose supabase/functions the running stack
+ * bind-mounts — the provisioning dir for a materialized leased stack. */
+export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connection, { writePrivate = writePrivateTextFile, removePrivate = (path) => unlink(path).catch(() => {}), edgeMountRoot = worktreeRoot } = {}) {
   const apiUrl = requireConnectionText(connection, "api_url");
   const anonKey = requireConnectionText(connection, "anon_key");
   const serviceRoleKey = requireConnectionText(connection, "service_role_key");
@@ -1635,7 +1744,12 @@ export async function materializeLeasedTestConfig(worktreeRoot, leaseId, connect
     await removePrivate(envFile);
     throw error;
   }
-  return { envFile, stackConfig, edgeMountRoot: worktreeRoot };
+  // BOT-1798 (Codex #928 R2 P1): the edge-mount root is the directory whose
+  // supabase/functions the stack actually bind-mounts — the PROVISIONING dir for a
+  // materialized leased stack (like the hermetic lane's scratch root), not the
+  // worktree root the env template is read from. Passing the bare root would make
+  // the integration lane's drift guard abort before a single test ran.
+  return { envFile, stackConfig, edgeMountRoot };
 }
 
 /**
@@ -1675,6 +1789,10 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const writeConnection = adapters.writeConnection ?? writeConnectionFile;
   const removeConnection = adapters.removeConnection ?? ((path) => unlink(path).catch(() => {}));
   const materializeTestConfig = adapters.materializeTestConfig ?? materializeLeasedTestConfig;
+  // BOT-1798: injectable so the lifecycle contract is testable without writing a
+  // stack directory; the default is the real materializing resolver.
+  const resolveExecution = adapters.resolveExecution ?? ((runOpts) => resolveRunExecution(process.cwd(), runOpts));
+  const refreshRetention = adapters.refreshRetention ?? refreshLeasedStackRetention;
   const clock = adapters.clock ?? { setInterval, clearInterval, setTimeout, clearTimeout };
   const signals = adapters.signals ?? process;
   const provisionTimeout = opts.provisionTimeout ?? opts.timeout;
@@ -1683,10 +1801,13 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   let childResult = null;
   let connectionFile = null;
   let heartbeat = null;
+  let retention = null;
   let hardTimer = null;
   let cleanupResult = null;
   let cleanupPromise = null;
   let leasedTestConfig = null;
+  let execution = null;
+  let leaseProvisioned = false;
   let receivedSignal = null;
   let forcedStopCode = null;
   let fencing = false;
@@ -1753,7 +1874,27 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: EXIT.BACKEND, outcome: "error", error: "could not determine this machine's hardware id (needed to dispatch the stack lease to the right machine)" };
     }
     const slot = deriveSlot(opts);
-    const execution = resolveStackPath(process.cwd(), opts.stackPath);
+    // BOT-1798: never "." — materialize/validate an ISOLATED stack dir first.
+    try {
+      execution = await resolveExecution({ ...opts, slot });
+    } catch (error) {
+      // A slot whose stack another live batch owns is a coordination refusal (the
+      // same class as the server's duplicate-lease rejection), not bad arguments.
+      const exitCode = error?.code === "stack_slot_busy" ? EXIT.BACKEND : EXIT.INVALID;
+      return { exitCode, outcome: "error", error: String(error?.message ?? error) };
+    }
+    // BOT-1798 (Codex #928 R13 P2): the queue and provisioning waits can outlast the
+    // directory's initial retention, and a kill during them leaves a lease the
+    // Helper may still be provisioning. Keep the claim fresh from the moment the
+    // stack exists, not from the moment the child starts.
+    let leaseIdleTtlSecs = opts.idleTtl ?? 1800;
+    const keepAlive = () => {
+      refreshRetention(stackDirFor(execution), { idleTtlSecs: leaseIdleTtlSecs });
+      execution.renew?.({ idleTtlSecs: leaseIdleTtlSecs });
+    };
+    keepAlive();
+    retention = clock.setInterval(keepAlive, RETENTION_REFRESH_MS);
+    retention?.unref?.();
     const leaseArgs = {
       slot, host_key: opts.host || undefined, repo: opts.repo, ticket_id: opts.ticket,
       ticket_url: opts.ticketUrl || undefined, pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
@@ -1764,7 +1905,18 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     // The retrying caller (api → rpc.call) transparently clears+self-heals+retries the
     // FIRST auth rejection among any of request/get/touch/release.
     const request = await api.request(leaseArgs);
-    if (!request?.ok) return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
+    if (!request?.ok) {
+      // Codex #928 R23 (P2): `status: null` (callToolJson's fetch-threw branch) means
+      // NO response was ever received — the request may have reached the backend and
+      // created a lease we simply never heard back about, so a Helper could already be
+      // provisioning it. Any OTHER failure carries a real HTTP status: the backend was
+      // reached and definitely refused (or errored) before creating anything of ours.
+      // Only the definite case is safe to treat as unprovisioned and free the port
+      // claim immediately below; an ambiguous transport failure retains it instead — it
+      // still expires on its own TTL if nothing was actually provisioned.
+      if (request?.status == null) leaseProvisioned = true;
+      return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
+    }
     if (!request.data?.success) {
       const hint = worktreeRegistrationHint(request.data?.code, rpc.auth);
       if (hint) process.stderr.write(`${hint}\n`);
@@ -1775,6 +1927,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: EXIT.BACKEND, outcome: "error", leaseId, error: "a live lease already exists for this agent and stack slot; wait for that batch to finish instead of sharing its stack" };
     }
 
+    leaseProvisioned = true; // from here a Helper may act on this lease
     let state = request.data.state;
     if (receivedSignal) {
       const cleanup = await requestCleanup();
@@ -1812,7 +1965,9 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       const cleanup = await requestCleanup();
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
-    if (isDenoIntegrationLane(childArgv)) leasedTestConfig = await materializeTestConfig(execution.worktreeRoot, leaseId, current.data.connection);
+    if (isDenoIntegrationLane(childArgv)) {
+      leasedTestConfig = await materializeTestConfig(execution.worktreeRoot, leaseId, current.data.connection, { edgeMountRoot: stackDirFor(execution) });
+    }
     if (receivedSignal) {
       const cleanup = await requestCleanup();
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
@@ -1827,23 +1982,36 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
         BB_EDGE_MOUNT_ROOT: leasedTestConfig.edgeMountRoot,
       } : {}),
     };
-    // resolveStackPath already canonicalised this bounded relative path.
-    const childCwd = execution.stackPath === "." ? execution.worktreeRoot : `${execution.worktreeRoot}/${execution.stackPath}`;
+    // BOT-1798 (Codex #928 R1 P1): the lease's stack_path is the PROVISIONING
+    // directory — where the Helper runs `supabase start` — never the command's
+    // working directory. The child is a repo command (`pnpm test:integration`),
+    // and the materialized stack dir holds only a `supabase/` tree, so running it
+    // there would fail on a missing package.json AFTER the stack was provisioned.
+    // The child therefore always runs in the (canonicalised) worktree root.
+    const childCwd = execution.worktreeRoot;
     child = startChild(childArgv, childEnv, childCwd);
-    const cadenceMs = Math.max(1_000, Math.floor((current.data.idle_ttl_secs ?? opts.idleTtl ?? 1800) * 1000 / 3));
+    leaseIdleTtlSecs = current.data.idle_ttl_secs ?? opts.idleTtl ?? 1800;
+    const cadenceMs = Math.max(1_000, Math.floor(leaseIdleTtlSecs * 1000 / 3));
+    // BOT-1798 (Codex #928 R8 P2): the directory's retention tracks the LEASE's
+    // last activity, not its creation, so a batch that outlives the default window
+    // and then loses its owner process is never collected while it is still running.
+    keepAlive();
     heartbeat = clock.setInterval(async () => {
       if (fencing || childResult) return;
       const touched = await api.touch(leaseId);
       if (!touched?.ok || !touched?.data?.success) {
         fencing = true;
         stopChild("SIGTERM", EXIT.LEASE_FAILED);
+        return;
       }
+      keepAlive();
     }, cadenceMs);
     heartbeat.unref?.();
     if (opts.hardTtl) hardTimer = clock.setTimeout(() => stopChild("SIGTERM", EXIT.TIMEOUT), opts.hardTtl * 1000);
     hardTimer?.unref?.();
     childResult = await waitForChild(child);
     if (heartbeat) clock.clearInterval(heartbeat);
+    if (retention) { clock.clearInterval(retention); retention = null; }
     if (hardTimer) clock.clearTimeout(hardTimer);
     const cleanup = await requestCleanup();
     const exitCode = receivedSignal ? SIGNAL_EXIT[receivedSignal] : forcedStopCode ?? (childResult.code !== 0 ? childResult.code : !cleanup.ok ? EXIT.CLEANUP_FAILED : 0);
@@ -1858,9 +2026,20 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     return { exitCode, outcome: "error", leaseId, error: String(error?.message ?? error), cleanup };
   } finally {
     if (heartbeat) clock.clearInterval(heartbeat);
+    if (retention) clock.clearInterval(retention);
     if (hardTimer) clock.clearTimeout(hardTimer);
     if (connectionFile) await removeConnection(connectionFile);
     if (leasedTestConfig) await Promise.all([removeConnection(leasedTestConfig.envFile), removeConnection(leasedTestConfig.stackConfig)]);
+    // Release the materialization lock only once the batch (and its signed reap)
+    // is finished — it is what keeps a second run off this stack directory. The
+    // host port block is handed back only when the reap was actually PROVEN
+    // (a null state means no lease was ever created, so nothing can be running).
+    // A request the backend refused, or one that only re-attached to somebody
+    // else's live lease, provisioned nothing of ours — its block must go back at
+    // once, or repeated refusals would exhaust the host (Codex #928 R21 P2).
+    const provenReap = !leaseProvisioned
+      || (cleanupResult?.ok === true && (cleanupResult.state === "reaped" || cleanupResult.state == null));
+    execution?.release?.({ reaped: provenReap });
     for (const [signal, handler] of signalHandlers) signals.off?.(signal, handler);
   }
 }