@botbuddy/cli 1.2.3 → 1.4.1

package/src/stack.mjs

@@ -0,0 +1,572 @@
+// 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 { spawnSync } from "child_process";
+import { readFileSync, realpathSync } from "fs";
+import { join, relative, isAbsolute } from "path";
+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
+});
+
+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
+
+${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("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
+
+${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"`;
+
+// ── 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, ...rest] = argv;
+  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,
+    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 "--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>`);
+  }
+  return { command, leaseId, opts, errors };
+}
+
+/** 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, 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" }),
+  });
+  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.
+ */
+async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth }, fetchImpl = fetch) {
+  let cursorStart = null;
+  try {
+    ({ cursorStart } = await registerLeaseWait(leaseId, timeoutSec, auth, fetchImpl));
+  } catch (err) {
+    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));
+  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 (res.status === 401 || res.status === 403) { clearTimeout(timer); return { auth: true }; }
+  if (!res.ok || !res.body) { clearTimeout(timer); return { error: `sse responded ${res.status}` }; }
+  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)) { clearTimeout(timer); ac.abort(); return { failed: true, state: st }; }
+        if (isDone(st)) { clearTimeout(timer); ac.abort(); return { woke: true, state: st }; }
+      }
+    }
+  } catch (err) {
+    clearTimeout(timer);
+    if (ac.signal.aborted) return { timeout: true };
+    return { error: `sse stream: ${err?.message ?? err}` };
+  }
+  clearTimeout(timer);
+  return { timeout: true };
+}
+
+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);
+}
+
+/** 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 } = 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;
+      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;
+}