@botbuddy/cli 1.2.3 → 1.4.2

package/src/stack.mjs

@@ -0,0 +1,964 @@
+// BOT-1220 — `botbuddy stack`: one command to request, inspect, extend, and
+// release a short-lived batch-scoped local Supabase/Docker stack lease (BOT-1218),
+// mirroring the shape and discipline of `scripts/bb-wait.mjs`:
+//
+//   botbuddy stack up            → request a lease; park zero-poll if the host is
+//                                  saturated; return an ACTIVE lease receipt.
+//   botbuddy stack status <id>   → the lease's current state + connection.
+//   botbuddy stack touch  <id>   → bump the idle clock (before a long silent step).
+//   botbuddy stack done   <id>   → release (`done`): reap the stack.
+//
+// The canonical batch flow is:  stack up  →  test → break → fix → test  →  stack done.
+//
+// Design contract (matches bb-wait):
+//   * Dependency-free (Node stdlib only) so `npx @botbuddy/cli stack` cold-starts fast.
+//   * Exactly ONE single-line JSON receipt to stdout; all diagnostics go to stderr.
+//   * Receipt ≤ 10 KB (documented, --receipt-max-bytes overridable).
+//   * Documented, meaningful exit codes.
+//   * The CLI never executes docker itself on the primary path — the out-of-repo
+//     BotBuddy Helper provisions/tears down; `up` just coordinates and (zero-poll)
+//     waits for the lease to reach `active`. `--local-exec` is a LOUD, explicitly
+//     labelled fallback for when no Helper is available: it runs `supabase start`/
+//     `stop` itself and self-activates/finalizes via the fallback MCP tools.
+
+import { spawn, spawnSync } from "child_process";
+import { readFileSync, realpathSync } from "fs";
+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 { 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;
+
+// Meaningful, documented exit codes (mirrors bb-wait's taxonomy).
+export const EXIT = Object.freeze({
+  OK: 0,          // active lease held (or a successful status/touch/done)
+  QUEUED: 0,      // --no-wait: parked in the queue and exited (see receipt.queued)
+  TIMEOUT: 2,     // --timeout elapsed while parked for capacity
+  AUTH: 3,        // not authenticated / token expired / unauthorized
+  INVALID: 4,     // bad arguments / undeterminable slot
+  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)
+
+${bold("USAGE")}
+  botbuddy stack up [options]        Request a lease; park if the host is full; hold it active
+  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
+                         (e.g. 56322) or "<repo>-<ticket-slug>". Derived from --repo/--ticket
+                         when omitted. "default" is rejected.
+  --host <host_key>      Pin to a canonical host. Omit to auto-select a beacon-fresh host.
+  --repo <repo>          Repository the batch is for (e.g. botbuddy-web).
+  --ticket <BOT-123>     Ticket the batch is for (also used to derive the slot).
+  --stack-path <relative> Stack directory inside the registered worktree (default: .).
+  --purpose <text>       Free-text purpose recorded on the lease.
+  --idle-ttl <seconds>   Idle seconds before the reaper STOPS an unused stack (default 1800).
+  --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.
+
+${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.
+
+${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).
+  --receipt-max-bytes N  Receipt size cap (default ${DEFAULT_RECEIPT_MAX_BYTES}).
+
+${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                  8 cleanup/reap proof failed
+
+${bold("EXAMPLE")}
+  # request a per-worktree stack for this batch, run a lane against it, then reap it
+  botbuddy stack run --repo botbuddy-web --ticket BOT-1346 -- pnpm test:integration`;
+
+// ── pure helpers (unit-tested) ───────────────────────────────────────────────
+
+/** Derive the event-stream base URL from the MCP server URL. */
+export function eventStreamBase(serverUrl = SERVER_URL) {
+  return serverUrl.replace(/\/mcp-server\/?$/, "/event-stream");
+}
+
+/** Slugify a ticket key / repo fragment into a slot-safe token. */
+function slug(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Derive the BOT-1186 slot (stable stack identity). Precedence:
+ *   1. explicit --slot
+ *   2. "<repo>-<ticket>" when both are given
+ *   3. BB_STACK_SLOT env
+ * "default" is rejected (one slot per host can't represent shared + N worktree stacks).
+ * Throws a caller-facing Error when a slot can't be determined.
+ */
+export function deriveSlot({ slot, repo, ticket } = {}, env = process.env) {
+  let s = slot != null && String(slot).trim() !== "" ? String(slot).trim()
+    : (repo && ticket ? `${slug(repo)}-${slug(ticket)}` : null);
+  if (!s && env.BB_STACK_SLOT) s = String(env.BB_STACK_SLOT).trim();
+  if (!s) {
+    throw new Error("cannot determine a stack slot — pass --slot <port|repo-ticket>, or --repo and --ticket");
+  }
+  if (s.toLowerCase() === "default") {
+    throw new Error('slot "default" is rejected — use the shared CLI stack DB port (e.g. 56322) or "<repo>-<ticket-slug>"');
+  }
+  return s;
+}
+
+/**
+ * Parse `botbuddy stack` argv into { command, leaseId, opts, errors }. Pure — no I/O.
+ * `errors` non-empty ⇒ the caller emits an INVALID receipt and exits 4.
+ */
+export function parseStackArgs(argv) {
+  const errors = [];
+  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, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
+    connectionFile: null, noWait: false, localExec: false,
+    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; };
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    switch (a) {
+      case "--slot": if (need(a, rest[i + 1])) opts.slot = rest[++i]; break;
+      case "--host": if (need(a, rest[i + 1])) opts.host = rest[++i]; break;
+      case "--repo": if (need(a, rest[i + 1])) opts.repo = rest[++i]; break;
+      case "--ticket": if (need(a, rest[i + 1])) opts.ticket = rest[++i]; break;
+      case "--ticket-url": if (need(a, rest[i + 1])) opts.ticketUrl = rest[++i]; break;
+      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 "--idle-ttl": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) errors.push("--idle-ttl must be a positive integer number of seconds");
+          else opts.idleTtl = n;
+        }
+        break;
+      }
+      case "--timeout": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) errors.push("--timeout must be a positive integer number of seconds");
+          else opts.timeout = n;
+        }
+        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]);
+          if (!Number.isFinite(n) || !Number.isInteger(n) || n < 512) errors.push("--receipt-max-bytes must be an integer >= 512");
+          else opts.receiptMaxBytes = n;
+        }
+        break;
+      }
+      case "--no-wait": opts.noWait = true; break;
+      case "--local-exec": opts.localExec = true; break;
+      case "--stop": opts.disposition = "stop"; break;
+      case "--destroy": opts.disposition = "destroy"; break;
+      case "--json": opts.json = true; break;
+      default:
+        if (a.startsWith("-")) errors.push(`unknown option: ${a}`);
+        else positionals.push(a);
+    }
+  }
+  if (typeof opts.stackPath !== "string" || !opts.stackPath.trim() || opts.stackPath.startsWith("/") ||
+      opts.stackPath.split("/").some((part) => part === "..")) {
+    errors.push("--stack-path must be a non-empty relative path without '..'");
+  }
+  const leaseId = positionals[0] ?? null;
+  if (command && ["status", "touch", "done"].includes(command) && !leaseId) {
+    errors.push(`${command} needs a <lease_id>`);
+  }
+  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). */
+export function buildReceipt(fields) {
+  return { schema_version: STACK_SCHEMA_VERSION, ...fields };
+}
+
+/**
+ * Clamp a receipt under maxBytes: the connection block (the only unbounded field)
+ * collapses to a pointer first, then a hard fallback. lease_id/state/exit_code/outcome
+ * are always preserved so a truncated receipt is still actionable.
+ */
+export function truncateReceipt(receipt, maxBytes = DEFAULT_RECEIPT_MAX_BYTES) {
+  const enc = (o) => Buffer.byteLength(JSON.stringify(o), "utf8");
+  if (enc(receipt) <= maxBytes) return receipt;
+  const r = { ...receipt };
+  if (r.connection !== undefined) r.connection = { connection_truncated: true };
+  if (enc(r) <= maxBytes) return r;
+  return {
+    schema_version: r.schema_version, command: r.command, outcome: r.outcome,
+    lease_id: r.lease_id ?? null, state: r.state ?? null, exit_code: r.exit_code,
+    error: r.error ?? null, truncated: true,
+  };
+}
+
+/**
+ * Resolve a LOCAL Supabase API origin to pin into the `supabase start` environment
+ * (BOT-903 / Codex P1): without `VITE_SUPABASE_URL` pinned, config.toml's
+ * `env(VITE_SUPABASE_URL)` falls back to the repo's `.env` PRODUCTION origin, so the
+ * "disposable" local edge runtime would address `https://api.bot-buddy.ai`. Precedence:
+ *   1. an already-exported local (`127.0.0.1`/`localhost`) `VITE_SUPABASE_URL`;
+ *   2. `http://127.0.0.1:<[api] port>` read from `./supabase/config.toml`.
+ * Returns null when neither is available — the caller then REFUSES to run `supabase
+ * start` rather than risk crossing into production.
+ */
+export function resolveLocalSupabaseUrl(env = process.env, cwd = process.cwd()) {
+  const cur = env.VITE_SUPABASE_URL;
+  if (cur && /(127\.0\.0\.1|localhost)/.test(cur)) return cur;
+  try {
+    const toml = readFileSync(`${cwd}/supabase/config.toml`, "utf8");
+    // The [api] section's `port = NNNNN` (stop at the next section header).
+    const section = /\[api\]([\s\S]*?)(\n\[|$)/.exec(toml);
+    const m = section && /\bport\s*=\s*(\d+)/.exec(section[1]);
+    if (m) return `http://127.0.0.1:${m[1]}`;
+  } catch { /* no config.toml here */ }
+  return null;
+}
+
+/** Resolve the requested stack directory once, before it leaves the coding
+ * machine. This closes both `..` and symlink escapes; the server separately
+ * verifies the resulting root is a registered worktree on the selected host. */
+export function resolveStackPath(cwd = process.cwd(), stackPath = ".") {
+  if (typeof stackPath !== "string" || !stackPath || isAbsolute(stackPath) || stackPath.split("/").some((part) => part === "..")) {
+    throw new Error("--stack-path must be a non-empty relative path without '..'");
+  }
+  const root = realpathSync(cwd);
+  const target = realpathSync(`${root}/${stackPath}`);
+  const inside = relative(root, target);
+  if (inside === ".." || inside.startsWith(`..${process.platform === "win32" ? "\\\\" : "/"}`)) {
+    throw new Error("--stack-path resolves outside the current worktree");
+  }
+  return { worktreeRoot: root, stackPath: inside || "." };
+}
+
+/** Parse `supabase status -o json` (or the plain key/value fallback) into a connection block. */
+export function parseSupabaseStatus(text) {
+  const t = String(text || "");
+  try {
+    const j = JSON.parse(t);
+    return {
+      api_url: j.API_URL ?? j.api_url ?? null,
+      db_url: j.DB_URL ?? j.db_url ?? null,
+      anon_key: j.ANON_KEY ?? j.anon_key ?? j.PUBLISHABLE_KEY ?? null,
+      service_role_key: j.SERVICE_ROLE_KEY ?? j.service_role_key ?? null,
+    };
+  } catch {
+    const grab = (re) => { const m = re.exec(t); return m ? m[1].trim() : null; };
+    const conn = {
+      api_url: grab(/API URL:\s*(\S+)/i),
+      db_url: grab(/DB URL:\s*(\S+)/i),
+      anon_key: grab(/anon key:\s*(\S+)/i),
+      service_role_key: grab(/service_role key:\s*(\S+)/i),
+    };
+    return conn;
+  }
+}
+
+// ── runtime (network / process) ──────────────────────────────────────────────
+
+function stackAuthHeader() {
+  const cfg = getConfig();
+  if (cfg.access_token) {
+    if (cfg.token_expires_at && Date.now() >= cfg.token_expires_at) return null;
+    return { Authorization: `Bearer ${cfg.access_token}`, "x-agent-api-key": cfg.api_key || "" };
+  }
+  if (cfg.api_key) return { Authorization: `Bearer ${cfg.api_key}`, "x-agent-api-key": cfg.api_key };
+  return null;
+}
+
+function parseSseFrames(buffer) {
+  const frames = [];
+  let idx, remaining = buffer;
+  while ((idx = remaining.indexOf("\n\n")) !== -1) {
+    const block = remaining.slice(0, idx);
+    remaining = remaining.slice(idx + 2);
+    const dataLines = [];
+    for (const line of block.split("\n")) {
+      if (line === "" || line.startsWith(":")) continue;
+      const colon = line.indexOf(":");
+      const field = colon === -1 ? line : line.slice(0, colon);
+      let value = colon === -1 ? "" : line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+      if (field === "data") dataLines.push(value);
+    }
+    if (dataLines.length) frames.push({ data: dataLines.join("\n") });
+  }
+  return { frames, rest: remaining };
+}
+
+/** Register a wait_session for this lease (so it shows on /waits) + return {cursorStart}. Best-effort. */
+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();
+  return { waitSessionId: body.wait_session_id ?? null, cursorStart: body.cursor_start ?? null };
+}
+
+/**
+ * Zero-poll wait for `lease:<leaseId>` to reach a state satisfying `isDone(state)`.
+ * Registers a wait_session (visible on /waits), then blocks on the event-stream SSE.
+ * Resolves { woke, state } on a matching frame, { timeout:true } on --timeout,
+ * { failed, state } if the lease was reaped, or { error } on a transport failure.
+ */
+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, 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");
+  let res;
+  try {
+    res = await fetchImpl(url, { headers: { ...auth, Accept: "text/event-stream", "Accept-Encoding": "identity" }, signal: ac.signal });
+  } catch (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) 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 {
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      const { frames, rest } = parseSseFrames(buf);
+      buf = rest;
+      for (const f of frames) {
+        let sig;
+        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)) { ac.abort(); return finish({ failed: true, state: st }, "error"); }
+        if (isDone(st)) { ac.abort(); return finish({ woke: true, state: st }, "matched"); }
+      }
+    }
+  } catch (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);
+  }
+  return finish({ timeout: true }, "timeout");
+}
+
+const isActive = (s) => s === "active";
+const nonQueued = (s) => s != null && s !== "queued";
+const isReaped = (s) => s === "reaping" || s === "reaped";
+
+/** LOUD local-exec fallback: bring a stack up in the cwd via the Supabase CLI. */
+function localProvision() {
+  // 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();
+  if (!url) {
+    throw new Error(
+      "refusing --local-exec: cannot determine a LOCAL Supabase API origin (no supabase/config.toml [api] port " +
+        "in this directory, and VITE_SUPABASE_URL is not a 127.0.0.1/localhost origin). `supabase start` would bake " +
+        "the repository's PRODUCTION origin into the edge runtime — run from a repo with supabase/config.toml, or " +
+        "export VITE_SUPABASE_URL=http://127.0.0.1:<port> first.",
+    );
+  }
+  const spawnEnv = { ...process.env, 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) {
+    throw new Error(`supabase start failed (${start.status}): ${(start.stderr || start.stdout || "").slice(0, 400)}`);
+  }
+  const status = spawnSync("supabase", ["status", "-o", "json"], { encoding: "utf8", env: spawnEnv });
+  return parseSupabaseStatus(status.stdout || "");
+}
+
+/** LOUD local-exec fallback: tear the stack down in the cwd. Returns true iff it succeeded. */
+function localTeardown() {
+  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" });
+  if (res.status !== 0) {
+    process.stderr.write(`${yellow("⚠")} stack: supabase stop returned ${res.status}: ${(res.stderr || res.stdout || "").slice(0, 300)}\n`);
+  }
+  return res.status === 0;
+}
+
+function emit(receipt, opts, code) {
+  const out = truncateReceipt({ ...receipt, exit_code: code }, opts?.receiptMaxBytes ?? DEFAULT_RECEIPT_MAX_BYTES);
+  process.stdout.write((opts?.json ? JSON.stringify(out, null, 2) : JSON.stringify(out)) + "\n");
+  return code;
+}
+
+// ── command orchestration ────────────────────────────────────────────────────
+
+async function cmdUp(opts) {
+  let slot;
+  try { slot = deriveSlot(opts); } catch (e) {
+    return emit(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);
+  }
+
+  const req = await callToolJson("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,
+    purpose: opts.purpose || undefined, idle_ttl_secs: opts.idleTtl ?? undefined,
+    stack_path: execution.stackPath,
+    worktree_root: execution.worktreeRoot,
+  });
+  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);
+  }
+  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);
+  }
+  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);
+    }
+    // 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);
+    state = parked.state || "provisioning";
+  }
+
+  // Reach `active`: local-exec provisions itself; otherwise wait for the Helper.
+  if (state !== "active") {
+    if (opts.localExec) {
+      let conn;
+      try { conn = localProvision(); } catch (e) {
+        return emit(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 });
+      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);
+      }
+    } 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);
+    }
+  }
+
+  // Authoritative final read (connection block, current state).
+  const got = await callToolJson("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 emit(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,
+  }), opts, EXIT.OK);
+}
+
+async function cmdStatus(leaseId, opts) {
+  const got = await callToolJson("get_stack_lease", { lease_id: leaseId });
+  if (!got.ok) return got.auth
+    ? emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.AUTH)
+    : emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.BACKEND);
+  const g = got.data;
+  if (!g.success) return emit(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, code: g.code, error: g.code }), opts, EXIT.BACKEND);
+  return emit(buildReceipt({
+    command: "status", outcome: g.state, lease_id: leaseId, state: g.state,
+    host_key: g.host_key, slot: g.slot, connection: g.connection,
+    queue_position: g.queue_position, idle_ttl_secs: g.idle_ttl_secs, queued: g.queued,
+  }), opts, EXIT.OK);
+}
+
+async function cmdTouch(leaseId, opts) {
+  const r = await callToolJson("touch_stack_lease", { lease_id: leaseId });
+  if (!r.ok) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, error: r.error }), opts, r.auth ? EXIT.AUTH : EXIT.BACKEND);
+  if (!r.data.success) return emit(buildReceipt({ command: "touch", outcome: "error", lease_id: leaseId, code: r.data.code, error: r.data.code }), opts, EXIT.BACKEND);
+  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);
+  let state = r.data.state;
+  if (opts.localExec && state === "reaping") {
+    // Only finalize once the stack is PROVABLY down. A failed `supabase stop` (Docker
+    // unavailable, etc.) must NOT finalize — finalize frees the slot lock and promotes
+    // 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({
+        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 });
+    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);
+}
+
+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. */
+export async function cmdStack(argv) {
+  if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
+    process.stdout.write(STACK_HELP + "\n");
+    return EXIT.OK;
+  }
+  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);
+    process.exitCode = code;
+    return code;
+  }
+  let code;
+  try {
+    switch (command) {
+      case "up": code = await cmdUp(opts); break;
+      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);
+    }
+  } catch (err) {
+    code = emit(buildReceipt({ command: command || "?", outcome: "error", error: `internal: ${err?.message ?? err}` }), opts, EXIT.INTERNAL);
+  }
+  process.exitCode = code;
+  return code;
+}