@botbuddy/cli 1.4.1 → 1.5.0

package/src/stack.mjs

@@ -21,11 +21,15 @@
 //     labelled fallback for when no Helper is available: it runs `supabase start`/
 //     `stop` itself and self-activates/finalizes via the fallback MCP tools.
 
-import { spawnSync } from "child_process";
+import { spawn, spawnSync } from "child_process";
 import { readFileSync, realpathSync } from "fs";
-import { join, relative, isAbsolute } from "path";
+import { open, unlink, readFile } from "fs/promises";
+import { tmpdir } from "os";
+import { basename, dirname, join, relative, isAbsolute } from "path";
+import { randomUUID } from "crypto";
 import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
+import { runDockerWorkflow } from "./docker-hygiene.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
 export const STACK_SCHEMA_VERSION = 1;
@@ -42,6 +46,7 @@ export const EXIT = Object.freeze({
   BACKEND: 5,     // server/RPC/transport error, or the coordination request failed
   LEASE_FAILED: 6, // the lease was reaped / provision failed instead of going active
   INTERNAL: 7,    // unexpected local error
+  CLEANUP_FAILED: 8, // child completed but signed physical reap was not proven
 });
 
 export const STACK_HELP = `${bold("botbuddy stack")} — one command for a batch-scoped local stack lease (BOT-1218)
@@ -51,6 +56,8 @@ ${bold("USAGE")}
   botbuddy stack status <lease_id>   Show a lease's state + connection
   botbuddy stack touch  <lease_id>   Bump the idle clock so the reaper doesn't stop it
   botbuddy stack done   <lease_id>   Release (done): tear the stack down
+  botbuddy stack run [options] -- <executable> [args...]
+                                      Own one Helper-backed test/fix batch end-to-end
 
 ${bold("up OPTIONS")}
   --slot <slot>          Stable stack identity (BOT-1186): the shared CLI stack DB port
@@ -65,10 +72,24 @@ ${bold("up OPTIONS")}
   --timeout <seconds>    Max seconds to park for capacity before giving up (default ${DEFAULT_TIMEOUT_SEC}).
   --no-wait              If the host is full, print the queue position and exit (don't park).
   --local-exec           FALLBACK (no Helper): run 'supabase start' locally and self-activate.
+  --docker-context <name> Explicit OrbStack Docker context for the mandatory local preflight.
+  --docker-endpoint <uri> Explicit OrbStack endpoint instead of --docker-context.
 
 ${bold("done OPTIONS")}
   --stop                 Keep volumes (cheap re-provision next batch). Default: destroy.
   --local-exec           FALLBACK (no Helper): run 'supabase stop' locally and self-finalize.
+  --docker-context <name> Explicit OrbStack context used by the matching local-exec up.
+  --docker-endpoint <uri> Explicit OrbStack endpoint instead of --docker-context.
+                         Pre-1.5.0 leases also require exact worktree + live connection proof.
+
+${bold("run OPTIONS")}
+  --repo <repo>          Required approved repository name.
+  --ticket <BOT-123>     Required ticket for the batch.
+  --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.
+  --hard-ttl N           Bound the child runtime; timeout requests normal cleanup.
+  --local-exec           Rejected: stack run never starts Docker directly.
 
 ${bold("GLOBAL")}
   --json                 Pretty-print the receipt (default is one compact JSON line).
@@ -77,13 +98,11 @@ ${bold("GLOBAL")}
 ${bold("EXIT CODES")}
   0 ok/held (or queued+--no-wait)   2 park timed out            3 not authenticated
   4 invalid arguments               5 backend/coordination      6 lease failed/reaped
-  7 internal error
+  7 internal error                  8 cleanup/reap proof failed
 
 ${bold("EXAMPLE")}
   # request a per-worktree stack for this batch, run a lane against it, then reap it
-  id=$(botbuddy stack up --repo botbuddy-web --ticket BOT-1220 | jq -r .lease_id)
-  pnpm test:integration
-  botbuddy stack done "$id"`;
+  botbuddy stack run --repo botbuddy-web --ticket BOT-1346 -- pnpm test:integration`;
 
 // ── pure helpers (unit-tested) ───────────────────────────────────────────────
 
@@ -124,15 +143,26 @@ export function deriveSlot({ slot, repo, ticket } = {}, env = process.env) {
  */
 export function parseStackArgs(argv) {
   const errors = [];
-  const [command, ...rest] = argv;
+  const [command, ...rawRest] = argv;
+  const divider = rawRest.indexOf("--");
+  const rest = divider === -1 ? rawRest : rawRest.slice(0, divider);
+  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: ".",
-    timeout: DEFAULT_TIMEOUT_SEC, noWait: false, localExec: false,
+    timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
+    connectionFile: null, noWait: false, localExec: false,
+    dockerContext: null, dockerEndpoint: null,
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
   const positionals = [];
-  const need = (name, v) => { if (v === undefined) { errors.push(`${name} needs a value`); return false; } return true; };
+  const need = (name, v) => {
+    if (v === undefined || String(v).startsWith("--")) {
+      errors.push(`${name} needs a value`);
+      return false;
+    }
+    return true;
+  };
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     switch (a) {
@@ -161,6 +191,31 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--provision-timeout": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) errors.push("--provision-timeout must be a positive integer number of seconds");
+          else opts.provisionTimeout = n;
+        }
+        break;
+      }
+      case "--reap-timeout": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) errors.push("--reap-timeout must be a positive integer number of seconds");
+          else opts.reapTimeout = n;
+        }
+        break;
+      }
+      case "--hard-ttl": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) errors.push("--hard-ttl must be a positive integer number of seconds");
+          else opts.hardTtl = n;
+        }
+        break;
+      }
+      case "--connection-file": if (need(a, rest[i + 1])) opts.connectionFile = rest[++i]; break;
       case "--receipt-max-bytes": {
         if (need(a, rest[i + 1])) {
           const n = Number(rest[++i]);
@@ -171,6 +226,8 @@ export function parseStackArgs(argv) {
       }
       case "--no-wait": opts.noWait = true; break;
       case "--local-exec": opts.localExec = true; break;
+      case "--docker-context": if (need(a, rest[i + 1])) opts.dockerContext = rest[++i]; break;
+      case "--docker-endpoint": if (need(a, rest[i + 1])) opts.dockerEndpoint = rest[++i]; break;
       case "--stop": opts.disposition = "stop"; break;
       case "--destroy": opts.disposition = "destroy"; break;
       case "--json": opts.json = true; break;
@@ -187,7 +244,23 @@ export function parseStackArgs(argv) {
   if (command && ["status", "touch", "done"].includes(command) && !leaseId) {
     errors.push(`${command} needs a <lease_id>`);
   }
-  return { command, leaseId, opts, errors };
+  if (["up", "done"].includes(command) && opts.localExec && Boolean(opts.dockerContext) === Boolean(opts.dockerEndpoint)) {
+    errors.push(`--local-exec ${command} requires exactly one of --docker-context <name> or --docker-endpoint <uri>`);
+  }
+  if ((opts.dockerContext || opts.dockerEndpoint) && !(["up", "done"].includes(command) && opts.localExec)) {
+    errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
+  }
+  if (command === "run") {
+    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 --");
+    if (opts.noWait) errors.push("--no-wait is incompatible with run; the command owns its queue wait");
+    if (opts.localExec) errors.push("--local-exec is forbidden for run; Helper-backed physical lifecycle is required");
+    if (opts.connectionFile && !isAbsolute(opts.connectionFile)) errors.push("--connection-file must be an absolute path");
+  } else if (divider !== -1) {
+    errors.push("-- <executable> is only valid with stack run");
+  }
+  return { command, leaseId, opts, errors, childArgv };
 }
 
 /** Build the canonical receipt object (single JSON line to stdout). */
@@ -308,12 +381,13 @@ function parseSseFrames(buffer) {
 }
 
 /** Register a wait_session for this lease (so it shows on /waits) + return {cursorStart}. Best-effort. */
-async function registerLeaseWait(leaseId, timeoutSec, auth, fetchImpl = fetch) {
+async function registerLeaseWait(leaseId, timeoutSec, auth, signal, fetchImpl = fetch) {
   const deadline = new Date(Date.now() + timeoutSec * 1000).toISOString();
   const res = await fetchImpl(`${eventStreamBase()}`, {
     method: "POST",
     headers: { ...auth, "Content-Type": "application/json" },
     body: JSON.stringify({ action: "register", conditions: [{ type: "lease", params: { id: leaseId } }], deadline, mode: "any" }),
+    signal,
   });
   if (!res.ok) throw new Error(`register responded ${res.status}`);
   const body = await res.json();
@@ -326,29 +400,59 @@ async function registerLeaseWait(leaseId, timeoutSec, auth, fetchImpl = fetch) {
  * Resolves { woke, state } on a matching frame, { timeout:true } on --timeout,
  * { failed, state } if the lease was reaped, or { error } on a transport failure.
  */
-async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth }, fetchImpl = fetch) {
+export async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth, signal = null, deadlineMs = null }, fetchImpl = fetch) {
+  const absoluteDeadlineMs = deadlineMs ?? Date.now() + timeoutSec * 1000;
   let cursorStart = null;
+  let waitSessionId = null;
+  const ac = new AbortController();
+  const abortFromParent = () => ac.abort("interrupted");
+  if (signal?.aborted) ac.abort("interrupted");
+  else signal?.addEventListener?.("abort", abortFromParent, { once: true });
+  const timer = setTimeout(() => ac.abort("timeout"), Math.max(0, absoluteDeadlineMs - Date.now()));
+  const finish = async (result, status) => {
+    clearTimeout(timer);
+    signal?.removeEventListener?.("abort", abortFromParent);
+    if (waitSessionId) {
+      try {
+        const finalizer = new AbortController();
+        const finalizerTimer = setTimeout(() => finalizer.abort(), 5_000);
+        try {
+          const response = await fetchImpl(eventStreamBase(), {
+            method: "POST", headers: { ...auth, "Content-Type": "application/json" },
+            body: JSON.stringify({ action: "finalize", wait_session_id: waitSessionId, status, receipt: { outcome: status, lease_id: leaseId } }),
+            signal: finalizer.signal,
+          });
+          if (!response.ok) process.stderr.write(`${yellow("⚠")} stack: wait finalization returned ${response.status}\n`);
+        } finally {
+          clearTimeout(finalizerTimer);
+        }
+      } catch (err) {
+        process.stderr.write(`${yellow("⚠")} stack: wait finalization failed (${err?.message ?? err})\n`);
+      }
+    }
+    return result;
+  };
+  if (ac.signal.aborted) return finish(ac.signal.reason === "interrupted" ? { interrupted: true } : { timeout: true }, ac.signal.reason === "interrupted" ? "error" : "timeout");
   try {
-    ({ cursorStart } = await registerLeaseWait(leaseId, timeoutSec, auth, fetchImpl));
+    ({ cursorStart, waitSessionId } = await registerLeaseWait(leaseId, Math.max(0, Math.ceil((absoluteDeadlineMs - Date.now()) / 1000)), auth, ac.signal, fetchImpl));
   } catch (err) {
+    if (ac.signal.aborted) return finish(ac.signal.reason === "interrupted" ? { interrupted: true } : { timeout: true }, ac.signal.reason === "interrupted" ? "error" : "timeout");
     process.stderr.write(`${yellow("⚠")} stack: wait registration failed (${err?.message ?? err}); the lease will not appear on /waits — parking live-only.\n`);
   }
   const url = new URL(eventStreamBase());
   url.searchParams.set("tables", "agent_signal_events");
   if (cursorStart != null) url.searchParams.set("since", String(cursorStart));
+  if (waitSessionId) url.searchParams.set("wait_session", waitSessionId);
   url.searchParams.set("heartbeat", "1");
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort("timeout"), timeoutSec * 1000);
   let res;
   try {
     res = await fetchImpl(url, { headers: { ...auth, Accept: "text/event-stream", "Accept-Encoding": "identity" }, signal: ac.signal });
   } catch (err) {
-    clearTimeout(timer);
-    if (ac.signal.aborted) return { timeout: true };
-    return { error: `sse connect: ${err?.message ?? err}` };
+    if (ac.signal.aborted) return finish(ac.signal.reason === "interrupted" ? { interrupted: true } : { timeout: true }, ac.signal.reason === "interrupted" ? "error" : "timeout");
+    return finish({ error: `sse connect: ${err?.message ?? err}` }, "error");
   }
-  if (res.status === 401 || res.status === 403) { clearTimeout(timer); return { auth: true }; }
-  if (!res.ok || !res.body) { clearTimeout(timer); return { error: `sse responded ${res.status}` }; }
+  if (res.status === 401 || res.status === 403) return finish({ auth: true }, "error");
+  if (!res.ok || !res.body) return finish({ error: `sse responded ${res.status}` }, "error");
   const decoder = new TextDecoder();
   let buf = "";
   try {
@@ -361,25 +465,143 @@ async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth }, fet
         try { sig = JSON.parse(f.data); } catch { continue; }
         if (sig.signal_type !== "stack_lease" || sig.subject_key !== `lease:${leaseId}`) continue;
         const st = sig.payload?.state ?? null;
-        if (isFailed(st)) { clearTimeout(timer); ac.abort(); return { failed: true, state: st }; }
-        if (isDone(st)) { clearTimeout(timer); ac.abort(); return { woke: true, state: st }; }
+        if (isFailed(st)) { ac.abort(); return finish({ failed: true, state: st }, "error"); }
+        if (isDone(st)) { ac.abort(); return finish({ woke: true, state: st }, "matched"); }
       }
     }
   } catch (err) {
-    clearTimeout(timer);
-    if (ac.signal.aborted) return { timeout: true };
-    return { error: `sse stream: ${err?.message ?? err}` };
+    if (ac.signal.aborted) return finish(ac.signal.reason === "interrupted" ? { interrupted: true } : { timeout: true }, ac.signal.reason === "interrupted" ? "error" : "timeout");
+    return finish({ error: `sse stream: ${err?.message ?? err}` }, "error");
+  }
+  // A clean relay EOF is not a timeout: the server intentionally closes on
+  // scope changes and proxies can recycle idle streams. Re-arm from a fresh
+  // cursor until the original deadline, never silently fall back to polling.
+  const remainingSec = Math.ceil((absoluteDeadlineMs - Date.now()) / 1000);
+  if (remainingSec > 0 && !ac.signal.aborted) {
+    await finish({ reconnected: true }, "error");
+    return waitForLease(leaseId, isDone, isFailed, { timeoutSec: remainingSec, auth, signal, deadlineMs: absoluteDeadlineMs }, fetchImpl);
   }
-  clearTimeout(timer);
-  return { timeout: true };
+  return finish({ timeout: true }, "timeout");
 }
 
 const isActive = (s) => s === "active";
 const nonQueued = (s) => s != null && s !== "queued";
 const isReaped = (s) => s === "reaping" || s === "reaped";
 
+/** Read-only pressure gate used before local managed-stack provisioning. */
+export function runLocalExecPreflight(opts, runWorkflow = runDockerWorkflow) {
+  const selector = opts.dockerContext
+    ? ["--context", opts.dockerContext]
+    : ["--endpoint", opts.dockerEndpoint];
+  return runWorkflow(["preflight", ...selector, "--json"]);
+}
+
+export function dockerEnvForSelector(opts, env = process.env) {
+  const selected = { ...env };
+  delete selected.DOCKER_CONTEXT;
+  delete selected.DOCKER_HOST;
+  if (opts.dockerContext) selected.DOCKER_CONTEXT = opts.dockerContext;
+  else selected.DOCKER_HOST = opts.dockerEndpoint;
+  return selected;
+}
+
+export function dockerTargetFromPreflight(receipt) {
+  const context = receipt?.context;
+  const endpoint = context?.resolved_endpoint;
+  const serverId = context?.server?.id;
+  if (context?.validation !== "orbstack" || typeof endpoint !== "string" || !endpoint ||
+      typeof serverId !== "string" || !serverId) return null;
+  return { validation: "orbstack", resolved_endpoint: endpoint, server_id: serverId };
+}
+
+export function connectionWithDockerTarget(connection, target) {
+  if (!target?.resolved_endpoint || !target?.server_id) {
+    throw new Error("cannot persist an incomplete Docker target identity");
+  }
+  return { ...(connection || {}), botbuddy_docker_target: { ...target } };
+}
+
+function dockerTargetsMatch(expected, actual) {
+  return expected?.validation === "orbstack" && actual?.validation === "orbstack" &&
+    expected.resolved_endpoint === actual.resolved_endpoint && expected.server_id === actual.server_id;
+}
+
+function dockerEnvForTarget(target, env = process.env) {
+  const selected = { ...env };
+  delete selected.DOCKER_CONTEXT;
+  delete selected.DOCKER_HOST;
+  selected.DOCKER_HOST = target.resolved_endpoint;
+  return selected;
+}
+
+/**
+ * Compatibility fence for leases activated by CLI <1.5.0, before the daemon
+ * identity was persisted in `connection`. We cannot reconstruct the old daemon
+ * ID by guesswork. Instead, prove that the caller is in the exact registered
+ * worktree/stack path and that `supabase status`, pinned to the freshly validated
+ * OrbStack endpoint, reports the same non-secret API + DB endpoints stored on
+ * the lease. Only then may that observed daemon be used for teardown.
+ */
+export function proveLegacyLocalExecTarget(lease, observedTarget, opts, run = spawnSync, cwd = process.cwd()) {
+  if (!observedTarget?.resolved_endpoint || !observedTarget?.server_id) {
+    return { ok: false, error: "fresh OrbStack target identity is incomplete" };
+  }
+  let execution;
+  try {
+    execution = resolveStackPath(cwd, opts?.stackPath || ".");
+  } catch (error) {
+    return { ok: false, error: `could not resolve the invoking stack path: ${error.message}` };
+  }
+  if (!lease?.worktree_root || lease.worktree_root !== execution.worktreeRoot ||
+      (lease.stack_path || ".") !== execution.stackPath) {
+    return { ok: false, error: "legacy lease worktree/stack metadata does not exactly match the invoking worktree" };
+  }
+
+  const stackDir = execution.stackPath === "."
+    ? execution.worktreeRoot
+    : join(execution.worktreeRoot, execution.stackPath);
+  const status = run("supabase", ["status", "-o", "json", "--workdir", stackDir], {
+    encoding: "utf8",
+    env: dockerEnvForTarget(observedTarget),
+  });
+  if (status?.error || status?.status !== 0) {
+    return { ok: false, error: "legacy stack is not provably live on the freshly validated OrbStack endpoint" };
+  }
+  const live = parseSupabaseStatus(status.stdout || "");
+  const stored = lease.connection || {};
+  if (typeof stored.api_url !== "string" || typeof stored.db_url !== "string" ||
+      live.api_url !== stored.api_url || live.db_url !== stored.db_url) {
+    return { ok: false, error: "live Supabase connection on the observed OrbStack daemon does not match the legacy lease connection" };
+  }
+  let dbPort = null;
+  try { dbPort = new URL(live.db_url).port || null; } catch { /* exact URL already matched; omit display-only port */ }
+  return {
+    ok: true,
+    evidence: {
+      method: "legacy_worktree_connection_match",
+      worktree_root: execution.worktreeRoot,
+      stack_path: execution.stackPath,
+      api_url: live.api_url,
+      db_port: dbPort,
+      resolved_endpoint: observedTarget.resolved_endpoint,
+      server_id: observedTarget.server_id,
+    },
+  };
+}
+
+function compactPreflight(receipt) {
+  return {
+    outcome: receipt.outcome,
+    context: receipt.context,
+    pressure: receipt.pressure,
+    warnings: receipt.warnings,
+    errors: receipt.errors,
+    recommendation: receipt.recommendation,
+  };
+}
+
 /** LOUD local-exec fallback: bring a stack up in the cwd via the Supabase CLI. */
-function localProvision() {
+function localProvision(opts, dockerTarget) {
   // Pin a LOCAL origin so `supabase start` never bakes the repo's prod origin into the
   // edge runtime (BOT-903 / Codex P1). Refuse rather than risk crossing into production.
   const url = resolveLocalSupabaseUrl();
@@ -391,7 +613,7 @@ function localProvision() {
         "export VITE_SUPABASE_URL=http://127.0.0.1:<port> first.",
     );
   }
-  const spawnEnv = { ...process.env, VITE_SUPABASE_URL: url };
+  const spawnEnv = { ...dockerEnvForTarget(dockerTarget), VITE_SUPABASE_URL: url };
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — no BotBuddy Helper; running ${bold("supabase start")} in this worktree (VITE_SUPABASE_URL=${url}).\n`);
   const start = spawnSync("supabase", ["start", "--workdir", process.cwd()], { encoding: "utf8", env: spawnEnv });
   if (start.status !== 0) {
@@ -402,9 +624,12 @@ function localProvision() {
 }
 
 /** LOUD local-exec fallback: tear the stack down in the cwd. Returns true iff it succeeded. */
-function localTeardown() {
+export function localTeardown(_opts, dockerTarget, spawn = spawnSync, env = process.env) {
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — running ${bold("supabase stop")} in this worktree.\n`);
-  const res = spawnSync("supabase", ["stop", "--workdir", process.cwd()], { encoding: "utf8" });
+  const res = spawn("supabase", ["stop", "--workdir", process.cwd()], {
+    encoding: "utf8",
+    env: dockerEnvForTarget(dockerTarget, env),
+  });
   if (res.status !== 0) {
     process.stderr.write(`${yellow("⚠")} stack: supabase stop returned ${res.status}: ${(res.stderr || res.stdout || "").slice(0, 300)}\n`);
   }
@@ -419,19 +644,42 @@ function emit(receipt, opts, code) {
 
 // ── command orchestration ────────────────────────────────────────────────────
 
-async function cmdUp(opts) {
+export async function cmdUp(opts, {
+  runPreflight = runLocalExecPreflight,
+  callTool = callToolJson,
+  authProvider = stackAuthHeader,
+  localProvisionFn = localProvision,
+  emitResult = emit,
+} = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
-    return emit(buildReceipt({ command: "up", outcome: "error", error: e.message }), opts, EXIT.INVALID);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", error: e.message }), opts, EXIT.INVALID);
   }
-  const auth = stackAuthHeader();
-  if (!auth) return emit(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   let execution;
   try { execution = resolveStackPath(process.cwd(), opts.stackPath); } catch (e) {
-    return emit(buildReceipt({ command: "up", outcome: "error", error: (e).message }), opts, EXIT.INVALID);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", error: (e).message }), opts, EXIT.INVALID);
+  }
+  let localPreflight = null;
+  let localDockerTarget = null;
+  if (opts.localExec) {
+    const checked = runPreflight(opts);
+    localPreflight = compactPreflight(checked.receipt);
+    localDockerTarget = dockerTargetFromPreflight(checked.receipt);
+    if (checked.exitCode !== 0 || !localDockerTarget) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "refused", slot,
+        error: checked.receipt.errors?.[0] || "OrbStack preflight did not return a stable Docker server identity",
+        preflight: localPreflight,
+      }), opts, EXIT.LEASE_FAILED);
+    }
+    if (checked.receipt.outcome === "warn") {
+      process.stderr.write(`${yellow("⚠")} stack: OrbStack preflight warns of interface pressure; cleanup is recommended before another stack.\n`);
+    }
   }
+  const auth = authProvider();
+  if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
 
-  const req = await callToolJson("request_stack_lease", {
+  const req = await callTool("request_stack_lease", {
     slot, host_key: opts.host || undefined, repo: opts.repo || undefined,
     ticket_id: opts.ticket || undefined, ticket_url: opts.ticketUrl || undefined,
     pr_id: opts.prId || undefined, pr_url: opts.prUrl || undefined,
@@ -441,57 +689,78 @@ async function cmdUp(opts) {
   });
   if (!req.ok) {
     return req.auth
-      ? emit(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
-      : emit(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, EXIT.BACKEND);
+      ? emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
+      : emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, EXIT.BACKEND);
   }
   const d = req.data;
   if (!d.success) {
-    return emit(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: d.message || d.code || "request refused", slot }), opts, EXIT.BACKEND);
   }
   let leaseId = d.lease_id;
   let state = d.state;
 
   if (state === "queued") {
     if (opts.noWait) {
-      return emit(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, queue_position: d.queue_position, holders: d.holders }), opts, EXIT.QUEUED);
+      return emitResult(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, queue_position: d.queue_position, holders: d.holders }), opts, EXIT.QUEUED);
     }
     // Park zero-poll until the lease leaves the queue (granted in BOT-1187 order).
     const parked = await waitForLease(leaseId, nonQueued, () => false, { timeoutSec: opts.timeout, auth });
-    if (parked.timeout) return emit(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity` }), opts, EXIT.TIMEOUT);
-    if (parked.auth) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
-    if (parked.error) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
+    if (parked.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity` }), opts, EXIT.TIMEOUT);
+    if (parked.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
+    if (parked.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
     state = parked.state || "provisioning";
   }
 
   // Reach `active`: local-exec provisions itself; otherwise wait for the Helper.
   if (state !== "active") {
     if (opts.localExec) {
+      // Capacity may have changed while this command was queued. Re-run the
+      // non-mutating gate immediately before `supabase start`; on refusal,
+      // release the minted lease and never invoke the local provisioner.
+      const checked = runPreflight(opts);
+      localPreflight = compactPreflight(checked.receipt);
+      localDockerTarget = dockerTargetFromPreflight(checked.receipt);
+      if (checked.exitCode !== 0 || !localDockerTarget) {
+        const cancelled = await callTool("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+        const leaseCancellation = cancelled.ok && cancelled.data?.success
+          ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+          : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+        return emitResult(buildReceipt({
+          command: "up", outcome: "refused", lease_id: leaseId, state, slot,
+          error: checked.receipt.errors?.[0] || "OrbStack preflight did not return a stable Docker server identity",
+          preflight: localPreflight,
+          lease_cancellation: leaseCancellation,
+        }), opts, EXIT.LEASE_FAILED);
+      }
       let conn;
-      try { conn = localProvision(); } catch (e) {
-        return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
+      try {
+        conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
+      } catch (e) {
+        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
       }
-      const act = await callToolJson("activate_stack_lease", { lease_id: leaseId, connection: conn });
+      const act = await callTool("activate_stack_lease", { lease_id: leaseId, connection: conn });
       if (!act.ok || !act.data?.success) {
-        return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
+        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
       }
     } else {
       const active = await waitForLease(leaseId, isActive, isReaped, { timeoutSec: opts.timeout, auth });
-      if (active.timeout) return emit(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `provisioning did not reach active in ${opts.timeout}s (Helper may be down — retry with --local-exec)` }), opts, EXIT.TIMEOUT);
-      if (active.failed) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
-      if (active.error) return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
+      if (active.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `provisioning did not reach active in ${opts.timeout}s (Helper may be down — retry with --local-exec)` }), opts, EXIT.TIMEOUT);
+      if (active.failed) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
+      if (active.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
     }
   }
 
   // Authoritative final read (connection block, current state).
-  const got = await callToolJson("get_stack_lease", { lease_id: leaseId });
+  const got = await callTool("get_stack_lease", { lease_id: leaseId });
   const g = got.ok && got.data?.success ? got.data : null;
   if (!g || g.state !== "active") {
-    return emit(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: g?.state, error: g ? `lease is ${g.state}, not active` : (got.error || "could not read lease") }), opts, g?.state && isReaped(g.state) ? EXIT.LEASE_FAILED : EXIT.BACKEND);
+    return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: g?.state, error: g ? `lease is ${g.state}, not active` : (got.error || "could not read lease") }), opts, g?.state && isReaped(g.state) ? EXIT.LEASE_FAILED : EXIT.BACKEND);
   }
-  return emit(buildReceipt({
+  return emitResult(buildReceipt({
     command: "up", outcome: "active", lease_id: leaseId, state: "active",
     host_key: g.host_key, slot: g.slot, connection: g.connection,
     idle_ttl_secs: g.idle_ttl_secs, resource_name: g.resource_name,
+    ...(localPreflight ? { preflight: localPreflight } : {}),
   }), opts, EXIT.OK);
 }
 
@@ -516,10 +785,50 @@ async function cmdTouch(leaseId, opts) {
   return emit(buildReceipt({ command: "touch", outcome: "touched", lease_id: leaseId, last_used_at: r.data.last_used_at }), opts, EXIT.OK);
 }
 
-async function cmdDone(leaseId, opts) {
-  const r = await callToolJson("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition });
-  if (!r.ok) return emit(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
-  if (!r.data.success) return emit(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
+export async function cmdDone(leaseId, opts, {
+  callTool = callToolJson,
+  runPreflight = runLocalExecPreflight,
+  proveLegacyTarget = proveLegacyLocalExecTarget,
+  localTeardownFn = localTeardown,
+  emitResult = emit,
+} = {}) {
+  let dockerTarget = null;
+  let legacyTargetProof = null;
+  if (opts.localExec) {
+    const current = await callTool("get_stack_lease", { lease_id: leaseId });
+    if (!current.ok || !current.data?.success) {
+      return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId,
+        error: current.error || current.data?.code || "could not verify the lease Docker target" }), opts,
+      current.auth ? EXIT.AUTH : EXIT.BACKEND);
+    }
+    const expected = current.data.connection?.botbuddy_docker_target;
+    let checked;
+    try { checked = runPreflight(opts); } catch (error) {
+      return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+        error: `could not validate teardown Docker target: ${error.message}` }), opts, EXIT.LEASE_FAILED);
+    }
+    dockerTarget = dockerTargetFromPreflight(checked.receipt);
+    if (expected && !dockerTargetsMatch(expected, dockerTarget)) {
+      return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+        error: "teardown Docker target does not exactly match the OrbStack server persisted at provisioning; lease and slot remain fenced",
+        expected_docker_target: expected || null, observed_docker_target: dockerTarget,
+      }), opts, EXIT.LEASE_FAILED);
+    }
+    if (!expected) {
+      const proof = proveLegacyTarget(current.data, dockerTarget, opts);
+      if (!proof?.ok) {
+        return emitResult(buildReceipt({ command: "done", outcome: "refused", lease_id: leaseId,
+          error: `pre-1.5.0 lease has no persisted Docker target and compatibility proof failed: ${proof?.error || "unknown proof failure"}; lease and slot remain fenced`,
+          expected_docker_target: null, observed_docker_target: dockerTarget,
+        }), opts, EXIT.LEASE_FAILED);
+      }
+      legacyTargetProof = proof.evidence;
+    }
+  }
+
+  const r = await callTool("release_stack_lease", { lease_id: leaseId, disposition: opts.disposition });
+  if (!r.ok) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
+  if (!r.data.success) return emitResult(buildReceipt({ command: "done", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
   let state = r.data.state;
   if (opts.localExec && state === "reaping") {
     // Only finalize once the stack is PROVABLY down. A failed `supabase stop` (Docker
@@ -527,17 +836,320 @@ async function cmdDone(leaseId, opts) {
     // the next queued lease, which would collide with containers still running on this
     // slot (Codex P1). Leave the lease in `reaping` (slot stays fenced) for a retry /
     // the reaper. Fail with a non-zero exit so the caller knows teardown is incomplete.
-    if (!localTeardown()) {
-      return emit(buildReceipt({
+    if (!localTeardownFn(opts, dockerTarget)) {
+      return emitResult(buildReceipt({
         command: "done", outcome: "error", lease_id: leaseId, state,
         error: "local `supabase stop` failed — NOT finalizing; the slot stays fenced. Tear the stack down and re-run `stack done --local-exec`, or let the reaper reconcile.",
       }), opts, EXIT.LEASE_FAILED);
     }
-    const fin = await callToolJson("finalize_stack_lease", { lease_id: leaseId });
+    const fin = await callTool("finalize_stack_lease", { lease_id: leaseId });
     if (fin.ok && fin.data?.success) state = fin.data.state;
     else process.stderr.write(`${yellow("⚠")} stack: finalize failed (${fin.error || fin.data?.code}); the reaper will reconcile.\n`);
   }
-  return emit(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition: opts.disposition }), opts, EXIT.OK);
+  return emitResult(buildReceipt({ command: "done", outcome: "released", lease_id: leaseId, state, disposition: opts.disposition,
+    ...(legacyTargetProof ? { legacy_target_proof: legacyTargetProof } : {}) }), opts, EXIT.OK);
+}
+
+const SIGNAL_EXIT = Object.freeze({ SIGINT: 130, SIGTERM: 143, SIGHUP: 129 });
+
+function safeConnectionPath(requested, leaseId) {
+  if (requested) {
+    // `wx` below prevents clobbering; canonicalising the parent prevents a
+    // symlinked directory from redirecting the only credential-bearing file.
+    const filename = basename(requested);
+    if (!filename || filename === "." || filename === "..") throw new Error("--connection-file must name a file");
+    return `${realpathSync(dirname(requested))}/${filename}`;
+  }
+  return `${tmpdir()}/botbuddy-stack-${leaseId}-${randomUUID()}.json`;
+}
+
+/** Write credentials atomically without ever putting them into argv, output, or a receipt. */
+async function writeConnectionFile(path, connection) {
+  return writePrivateTextFile(path, JSON.stringify(connection));
+}
+
+/** Write a credential-bearing text artifact (dotenv/TOML/JSON) mode 0600. */
+async function writePrivateTextFile(path, text) {
+  const handle = await open(path, "wx", 0o600);
+  try {
+    await handle.writeFile(text);
+  } catch (error) {
+    await unlink(path).catch(() => {});
+    throw error;
+  } finally {
+    await handle.close();
+  }
+  return path;
+}
+
+function childGroupSignal(child, signal) {
+  if (!child?.pid) return;
+  try { process.kill(-child.pid, signal); }
+  catch { try { child.kill(signal); } catch { /* already gone */ } }
+}
+
+function waitForChild(child) {
+  return new Promise((resolveChild, rejectChild) => {
+    child.once("error", rejectChild);
+    child.once("exit", (code, signal) => resolveChild({ code: code ?? (signal ? SIGNAL_EXIT[signal] ?? 1 : 1), signal }));
+  });
+}
+
+function isDenoIntegrationLane(argv) {
+  // `test:all` is the supported package wrapper that transitively invokes
+  // `test:integration`; both must receive the leased runner configuration.
+  return argv.includes("test:integration") || argv.includes("test:integration:coverage") || argv.includes("test:all") || argv.includes("scripts/run-deno-integration.sh");
+}
+
+function requireConnectionText(connection, key) {
+  const value = connection?.[key];
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`active stack connection is missing ${key}`);
+  return value.trim();
+}
+
+/** 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(() => {}) } = {}) {
+  const apiUrl = requireConnectionText(connection, "api_url");
+  const anonKey = requireConnectionText(connection, "anon_key");
+  const serviceRoleKey = requireConnectionText(connection, "service_role_key");
+  const projectId = requireConnectionText(connection, "project_id");
+  const parsedApi = new URL(apiUrl);
+  if (!parsedApi.port || !["127.0.0.1", "localhost"].includes(parsedApi.hostname)) {
+    throw new Error("active stack connection api_url must be a local host URL with an explicit port");
+  }
+  const dbPort = Number(connection.db_port ?? new URL(requireConnectionText(connection, "db_url")).port);
+  if (!Number.isInteger(dbPort) || dbPort <= 0 || dbPort > 65535) throw new Error("active stack connection is missing a valid db_port");
+
+  const basePath = `${worktreeRoot}/supabase/functions/_test/integration/.env.integration`;
+  const base = await readFile(basePath, "utf8");
+  const values = {
+    SUPABASE_URL: apiUrl,
+    VITE_SUPABASE_URL: apiUrl,
+    SUPABASE_ANON_KEY: anonKey,
+    VITE_SUPABASE_PUBLISHABLE_KEY: anonKey,
+    SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
+    INTEGRATION_DB_PORT: String(dbPort),
+  };
+  const seen = new Set();
+  const env = base.split(/\r?\n/).map((line) => {
+    const key = /^([A-Z0-9_]+)=/.exec(line)?.[1];
+    if (!key || !(key in values)) return line;
+    seen.add(key);
+    return `${key}=${values[key]}`;
+  });
+  for (const [key, value] of Object.entries(values)) if (!seen.has(key)) env.push(`${key}=${value}`);
+
+  const stamp = `${tmpdir()}/botbuddy-stack-${leaseId}-${randomUUID()}`;
+  const envFile = `${stamp}.env`;
+  const stackConfig = `${stamp}.toml`;
+  await writePrivate(envFile, env.join("\n"));
+  try {
+    await writePrivate(stackConfig, `project_id = "${projectId}"\n\n[api]\nport = ${parsedApi.port}\n\n[db]\nport = ${dbPort}\n`);
+  } catch (error) {
+    await removePrivate(envFile);
+    throw error;
+  }
+  return { envFile, stackConfig, edgeMountRoot: worktreeRoot };
+}
+
+/**
+ * The command-owned lifecycle. The optional adapters are intentionally narrow so
+ * its queue, heartbeat, process-group, and cleanup contract is spawn-testable
+ * without Docker or a live BotBuddy service.
+ */
+export async function runStackLifecycle(opts, childArgv, adapters = {}) {
+  const api = adapters.api ?? {
+    request: (args) => callToolJson("request_stack_lease", args),
+    get: (leaseId) => callToolJson("get_stack_lease", { lease_id: leaseId }),
+    touch: (leaseId) => callToolJson("touch_stack_lease", { lease_id: leaseId }),
+    release: (leaseId, signal) => callToolJson("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
+  };
+  const auth = adapters.auth ?? stackAuthHeader();
+  const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
+  // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- validated executable + argv only; shell is never used.
+  const startChild = adapters.startChild ?? ((argv, env, cwd) => spawn(argv[0], argv.slice(1), { cwd, env, stdio: "inherit", detached: true }));
+  const writeConnection = adapters.writeConnection ?? writeConnectionFile;
+  const removeConnection = adapters.removeConnection ?? ((path) => unlink(path).catch(() => {}));
+  const materializeTestConfig = adapters.materializeTestConfig ?? materializeLeasedTestConfig;
+  const clock = adapters.clock ?? { setInterval, clearInterval, setTimeout, clearTimeout };
+  const signals = adapters.signals ?? process;
+  const provisionTimeout = opts.provisionTimeout ?? opts.timeout;
+  let leaseId = null;
+  let child = null;
+  let childResult = null;
+  let connectionFile = null;
+  let heartbeat = null;
+  let hardTimer = null;
+  let cleanupResult = null;
+  let cleanupPromise = null;
+  let leasedTestConfig = null;
+  let receivedSignal = null;
+  let forcedStopCode = null;
+  let fencing = false;
+  let activeWaitAbort = null;
+
+  const requestCleanup = () => {
+    // A signal can arrive while the lease-request RPC is in flight. There is
+    // nothing to release yet, so do not cache this no-op; once the RPC returns
+    // the interruption branch must perform the real signed cleanup.
+    if (!leaseId) return Promise.resolve({ ok: true, state: null });
+    if (cleanupPromise) return cleanupPromise;
+    cleanupPromise = (async () => {
+    if (!leaseId) return cleanupResult = { ok: true, state: null };
+    const cleanupAbort = new AbortController();
+    const cleanupTimer = clock.setTimeout(() => cleanupAbort.abort("reap-timeout"), opts.reapTimeout * 1000);
+    let release;
+    try {
+      release = await api.release(leaseId, cleanupAbort.signal);
+    } finally {
+      clock.clearTimeout(cleanupTimer);
+    }
+    if (!release?.ok || !release?.data?.success) {
+      return cleanupResult = { ok: false, error: release?.error || release?.data?.code || "release failed" };
+    }
+    if (release.data.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
+    const reaped = await wait(leaseId, (state) => state === "reaped", () => false, { timeoutSec: opts.reapTimeout, auth });
+    if (reaped?.woke || reaped?.state === "reaped") return cleanupResult = { ok: true, state: "reaped" };
+    return cleanupResult = { ok: false, error: reaped?.timeout ? `signed reap did not arrive within ${opts.reapTimeout}s` : (reaped?.error || "signed reap was not proven") };
+    })();
+    return cleanupPromise;
+  };
+
+  const stopChild = (signal = "SIGTERM", forcedCode = null) => {
+    if (!child || childResult) return;
+    forcedStopCode ??= forcedCode;
+    childGroupSignal(child, signal);
+    const kill = clock.setTimeout(() => childGroupSignal(child, "SIGKILL"), 10_000);
+    kill.unref?.();
+  };
+
+  const onSignal = (signal) => {
+    if (receivedSignal) return;
+    receivedSignal = signal;
+    activeWaitAbort?.abort("interrupted");
+    stopChild(signal);
+    // If capacity is still queued/provisioning there is no child to hold open;
+    // release immediately so an interrupted invocation cannot later provision.
+    if (!child) void requestCleanup();
+  };
+  const signalHandlers = new Map();
+  for (const signal of Object.keys(SIGNAL_EXIT)) {
+    const handler = () => onSignal(signal);
+    signalHandlers.set(signal, handler);
+    signals.on?.(signal, handler);
+  }
+
+  try {
+    if (!auth) return { exitCode: EXIT.AUTH, outcome: "error", error: "not authenticated — run botbuddy profile setup botbuddy-dev" };
+    const slot = deriveSlot(opts);
+    const execution = resolveStackPath(process.cwd(), opts.stackPath);
+    const request = await api.request({
+      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,
+      purpose: opts.purpose || "stack run", idle_ttl_secs: opts.idleTtl ?? undefined,
+      stack_path: execution.stackPath, worktree_root: execution.worktreeRoot,
+    });
+    if (!request?.ok) return { exitCode: request?.auth ? EXIT.AUTH : EXIT.BACKEND, outcome: "error", error: request?.error || "lease request failed" };
+    if (!request.data?.success) return { exitCode: EXIT.BACKEND, outcome: "error", error: request.data?.message || request.data?.code || "lease request refused" };
+    leaseId = request.data.lease_id;
+    if (request.data.reused) {
+      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" };
+    }
+
+    let state = request.data.state;
+    if (receivedSignal) {
+      const cleanup = await requestCleanup();
+      return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
+    }
+    if (state === "queued") {
+      activeWaitAbort = new AbortController();
+      const parked = await wait(leaseId, (s) => s !== "queued" && s != null, (s) => s === "reaped", { timeoutSec: opts.timeout, auth, signal: activeWaitAbort.signal });
+      activeWaitAbort = null;
+      if (parked?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup }; }
+      if (parked?.timeout) { const cleanup = await requestCleanup(); return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `parked ${opts.timeout}s without capacity`, cleanup }; }
+      if (parked?.failed || parked?.error || parked?.auth) { const cleanup = await requestCleanup(); return { exitCode: parked?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: parked?.error || "lease did not leave queue", cleanup }; }
+      state = parked.state;
+    }
+    if (state !== "active") {
+      activeWaitAbort = new AbortController();
+      const active = await wait(leaseId, (s) => s === "active", (s) => s === "reaped", { timeoutSec: provisionTimeout, auth, signal: activeWaitAbort.signal });
+      activeWaitAbort = null;
+      if (active?.interrupted || receivedSignal) { const cleanup = await requestCleanup(); return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup }; }
+      if (active?.timeout) { const cleanup = await requestCleanup(); return { exitCode: EXIT.TIMEOUT, outcome: "timeout", leaseId, error: `physical provision did not reach active in ${provisionTimeout}s`, cleanup }; }
+      if (active?.failed || active?.error || active?.auth) { const cleanup = await requestCleanup(); return { exitCode: active?.auth ? EXIT.AUTH : EXIT.LEASE_FAILED, outcome: "error", leaseId, error: active?.error || "lease was reaped before active", cleanup }; }
+    }
+    const current = await api.get(leaseId);
+    if (!current?.ok || !current.data?.success || current.data.state !== "active" || !current.data.connection || typeof current.data.connection !== "object") {
+      const cleanup = await requestCleanup();
+      return { exitCode: EXIT.LEASE_FAILED, outcome: "error", leaseId, error: current?.error || `lease is ${current?.data?.state ?? "unreadable"}, not active with a connection`, cleanup };
+    }
+    if (receivedSignal) {
+      const cleanup = await requestCleanup();
+      return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
+    }
+
+    connectionFile = await writeConnection(safeConnectionPath(opts.connectionFile, leaseId), current.data.connection);
+    if (receivedSignal) {
+      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 (receivedSignal) {
+      const cleanup = await requestCleanup();
+      return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
+    }
+    const childEnv = {
+      ...process.env,
+      BOTBUDDY_STACK_LEASE_ID: leaseId,
+      BOTBUDDY_STACK_CONNECTION_FILE: connectionFile,
+      ...(leasedTestConfig ? {
+        BB_INTEGRATION_ENV_FILE: leasedTestConfig.envFile,
+        BB_STACK_CONFIG: leasedTestConfig.stackConfig,
+        BB_EDGE_MOUNT_ROOT: leasedTestConfig.edgeMountRoot,
+      } : {}),
+    };
+    // resolveStackPath already canonicalised this bounded relative path.
+    const childCwd = execution.stackPath === "." ? execution.worktreeRoot : `${execution.worktreeRoot}/${execution.stackPath}`;
+    child = startChild(childArgv, childEnv, childCwd);
+    const cadenceMs = Math.max(1_000, Math.floor((current.data.idle_ttl_secs ?? opts.idleTtl ?? 1800) * 1000 / 3));
+    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);
+      }
+    }, 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 (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);
+    return { exitCode, outcome: exitCode === 0 ? "completed" : "failed", leaseId, childExitCode: childResult.code, cleanup, fenced: fencing };
+  } catch (error) {
+    const cleanup = await requestCleanup();
+    return { exitCode: cleanup?.ok === false ? EXIT.CLEANUP_FAILED : EXIT.INTERNAL, outcome: "error", leaseId, error: String(error?.message ?? error), cleanup };
+  } finally {
+    if (heartbeat) clock.clearInterval(heartbeat);
+    if (hardTimer) clock.clearTimeout(hardTimer);
+    if (connectionFile) await removeConnection(connectionFile);
+    if (leasedTestConfig) await Promise.all([removeConnection(leasedTestConfig.envFile), removeConnection(leasedTestConfig.stackConfig)]);
+    for (const [signal, handler] of signalHandlers) signals.off?.(signal, handler);
+  }
+}
+
+async function cmdRun(opts, childArgv) {
+  const result = await runStackLifecycle(opts, childArgv);
+  return emit(buildReceipt({
+    command: "run", outcome: result.outcome, lease_id: result.leaseId ?? null,
+    child_exit_code: result.childExitCode ?? null, cleanup: result.cleanup?.ok ?? null,
+    fenced: result.fenced ?? false, error: result.error ?? result.cleanup?.error ?? null,
+  }), opts, result.exitCode);
 }
 
 /** Entry point wired from commands.mjs (`botbuddy stack ...`). Returns/sets the exit code. */
@@ -546,7 +1158,7 @@ export async function cmdStack(argv) {
     process.stdout.write(STACK_HELP + "\n");
     return EXIT.OK;
   }
-  const { command, leaseId, opts, errors } = parseStackArgs(argv);
+  const { command, leaseId, opts, errors, childArgv } = parseStackArgs(argv);
   if (errors.length) {
     for (const e of errors) process.stderr.write(`${yellow("⚠")} stack: ${e}\n`);
     const code = emit(buildReceipt({ command: command || "?", outcome: "error", error: errors[0] }), opts, EXIT.INVALID);
@@ -560,6 +1172,7 @@ export async function cmdStack(argv) {
       case "status": code = await cmdStatus(leaseId, opts); break;
       case "touch": code = await cmdTouch(leaseId, opts); break;
       case "done": code = await cmdDone(leaseId, opts); break;
+      case "run": code = await cmdRun(opts, childArgv); break;
       default:
         process.stderr.write(`${yellow("⚠")} stack: unknown subcommand "${command}". Try ${bold("botbuddy stack help")}.\n`);
         code = emit(buildReceipt({ command: command || "?", outcome: "error", error: `unknown subcommand: ${command}` }), opts, EXIT.INVALID);