@botbuddy/cli 1.4.1 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -46,7 +46,7 @@ export async function callTool(toolName, args = {}) {
 //   * { ok:true, data }        — tool result JSON (data.success may still be false)
 //   * { ok:false, auth:true }  — not authenticated / token expired
 //   * { ok:false, status }     — HTTP/JSON-RPC/transport error (status may be null)
-export async function callToolJson(toolName, args = {}, { fetchImpl = fetch } = {}) {
+export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal } = {}) {
   const cfg = getConfig();
   let auth;
   if (cfg.access_token) {
@@ -64,6 +64,7 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch } =
       method: "POST",
       headers: { "Content-Type": "application/json", ...auth },
       body: JSON.stringify(body),
+      signal,
     });
   } catch (err) {
     return { ok: false, status: null, error: `transport: ${err?.message ?? err}` };

package/src/profile-bootstrap.test.mjs

@@ -13,7 +13,7 @@ test("BOT-1353: the published CLI identifies this profile-bootstrap release", as
     cwd: new URL("..", import.meta.url),
   });
 
-  assert.equal(stdout.trim(), "botbuddy v1.4.1");
+  assert.equal(stdout.trim(), "botbuddy v1.4.2");
 });
 
 test("BOT-1382: profile --help succeeds and documents the subcommands", async () => {

package/src/stack.mjs

@@ -21,9 +21,12 @@
 //     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 { bold, dim, yellow } from "./utils.mjs";
@@ -42,6 +45,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 +55,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
@@ -70,6 +76,15 @@ ${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}).
@@ -77,13 +92,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,11 +137,15 @@ 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,
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
   const positionals = [];
@@ -161,6 +178,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]);
@@ -187,7 +229,17 @@ 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 (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 +360,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 +379,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,17 +444,23 @@ 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";
@@ -540,13 +629,315 @@ async function cmdDone(leaseId, opts) {
   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 } = 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 +951,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);

package/src/stack.test.mjs

@@ -5,15 +5,17 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { mkdtempSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
+import { mkdtempSync, writeFileSync, mkdirSync, realpathSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 
 import {
   EXIT, STACK_HELP, STACK_SCHEMA_VERSION, DEFAULT_RECEIPT_MAX_BYTES,
   deriveSlot, parseStackArgs, buildReceipt, truncateReceipt,
   parseSupabaseStatus, eventStreamBase, resolveLocalSupabaseUrl, resolveStackPath,
+  runStackLifecycle, materializeLeasedTestConfig, waitForLease,
 } from "./stack.mjs";
 
 const BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "botbuddy.mjs");
@@ -99,6 +101,242 @@ test("parseStackArgs: --stop sets disposition stop (default destroy)", () => {
   assert.equal(parseStackArgs(["done", "id"]).opts.disposition, "destroy");
   assert.equal(parseStackArgs(["done", "id", "--stop"]).opts.disposition, "stop");
 });
+test("BOT-1346: run requires an argv boundary and rejects direct Docker fallback", () => {
+  assert.ok(parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346"]).errors.some((e) => e.includes("executable")));
+  assert.ok(parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346", "--local-exec", "--", "echo", "ok"]).errors.some((e) => e.includes("forbidden")));
+  const parsed = parseStackArgs(["run", "--repo", "botbuddy-web", "--ticket", "BOT-1346", "--", "node", "-e", "process.exit(0)"]);
+  assert.equal(parsed.errors.length, 0);
+  assert.deepEqual(parsed.childArgv, ["node", "-e", "process.exit(0)"]);
+});
+
+test("BOT-1346: a clean lease-stream EOF honours the original deadline", async () => {
+  const requests = [];
+  const expired = await waitForLease(
+    "lease-1346", () => false, () => false,
+    { timeoutSec: 5, deadlineMs: Date.now() - 1, auth: { Authorization: "Bearer test" } },
+    async (_url, options = {}) => {
+      requests.push(options.method ?? "GET");
+      if (options.method === "POST") return new Response(JSON.stringify({ cursor_start: null }), { status: 200 });
+      return new Response(new ReadableStream({ start(controller) { controller.close(); } }), { status: 200 });
+    },
+  );
+  assert.deepEqual(expired, { timeout: true });
+  assert.deepEqual(requests, ["POST", "GET"]);
+});
+
+test("BOT-1346: a stalled lease-wait registration is aborted at its deadline", async () => {
+  let registrationSignal = null;
+  const result = await waitForLease(
+    "lease-1346", () => false, () => false,
+    { timeoutSec: 0.02, auth: { Authorization: "Bearer test" } },
+    async (_url, options = {}) => {
+      registrationSignal = options.signal;
+      return await new Promise((_resolve, reject) => options.signal.addEventListener("abort", () => reject(new Error("aborted")), { once: true }));
+    },
+  );
+  assert.equal(registrationSignal.aborted, true);
+  assert.deepEqual(result, { timeout: true });
+});
+
+test("BOT-1346: stack run owns active → argv child → signed reap and never exposes connection", async () => {
+  const calls = [];
+  const signals = new EventEmitter();
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4242;
+  let written = null; const removed = []; let childCall = null;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5, connectionFile: "/tmp/bot-1346-connection.json" },
+    ["pnpm", "test:all"],
+    {
+      auth: { Authorization: "Bearer test" }, signals,
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-1346", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", idle_ttl_secs: 30, connection: { db_url: "postgres://secret" } } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async (id) => { calls.push(["release", id]); return { ok: true, data: { success: true, state: "reaping" } }; },
+      },
+      wait: async (_id, done) => done("reaped") ? { woke: true, state: "reaped" } : { woke: true, state: "active" },
+      writeConnection: async (path, connection) => { written = { path, connection }; return path; },
+      materializeTestConfig: async () => ({
+        envFile: "/tmp/bot-1346-integration.env",
+        stackConfig: "/tmp/bot-1346-stack.toml",
+      }),
+      removeConnection: async (path) => { removed.push(path); },
+      startChild: (argv, env, cwd) => { childCall = { argv, env, cwd }; queueMicrotask(() => fakeChild.emit("exit", 7, null)); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, 7, "successful cleanup must not mask the child failure");
+  assert.deepEqual(childCall.argv, ["pnpm", "test:all"], "argv is forwarded without shell parsing");
+  assert.equal(childCall.env.BOTBUDDY_STACK_LEASE_ID, "lease-1346");
+  assert.equal(childCall.env.BOTBUDDY_STACK_CONNECTION_FILE, written.path);
+  assert.equal(childCall.env.BB_INTEGRATION_ENV_FILE, "/tmp/bot-1346-integration.env");
+  assert.equal(childCall.env.BB_STACK_CONFIG, "/tmp/bot-1346-stack.toml");
+  assert.equal(written.connection.db_url, "postgres://secret");
+  assert.deepEqual(removed.sort(), [written.path, "/tmp/bot-1346-integration.env", "/tmp/bot-1346-stack.toml"].sort());
+  assert.deepEqual(calls, [["release", "lease-1346"]]);
+  assert.doesNotMatch(JSON.stringify(result), /postgres:\/\/secret/);
+});
+
+test("BOT-1346: materialized integration environment uses the leased database port", async () => {
+  const root = mkdtempSync(join(tmpdir(), "bb-stack-integration-"));
+  const integrationDir = join(root, "supabase", "functions", "_test", "integration");
+  mkdirSync(integrationDir, { recursive: true });
+  writeFileSync(join(integrationDir, ".env.integration"), "SUPABASE_URL=http://127.0.0.1:56321\nINTEGRATION_DB_PORT=56322\n");
+  const config = await materializeLeasedTestConfig(root, "lease-port", {
+    api_url: "http://127.0.0.1:64321", db_port: 64322, anon_key: "anon", service_role_key: "service", project_id: "leased-project",
+  });
+  assert.match(readFileSync(config.envFile, "utf8"), /^INTEGRATION_DB_PORT=64322$/m);
+  assert.match(readFileSync(config.stackConfig, "utf8"), /port = 64322/);
+});
+
+test("BOT-1346: materialized integration config removes dotenv if its TOML write fails", async () => {
+  const root = mkdtempSync(join(tmpdir(), "bb-stack-integration-"));
+  const integrationDir = join(root, "supabase", "functions", "_test", "integration");
+  mkdirSync(integrationDir, { recursive: true });
+  writeFileSync(join(integrationDir, ".env.integration"), "SUPABASE_URL=http://127.0.0.1:56321\n");
+  const writes = []; const removed = [];
+  await assert.rejects(
+    materializeLeasedTestConfig(root, "lease-cleanup", {
+      api_url: "http://127.0.0.1:64321", db_port: 64322, anon_key: "anon", service_role_key: "service", project_id: "leased-project",
+    }, {
+      writePrivate: async (path) => { writes.push(path); if (writes.length === 2) throw new Error("ENOSPC"); },
+      removePrivate: async (path) => { removed.push(path); },
+    }),
+    /ENOSPC/,
+  );
+  assert.equal(writes.length, 2);
+  assert.deepEqual(removed, [writes[0]]);
+});
+
+test("BOT-1346: queue wait errors retain a failed signed-cleanup receipt", async () => {
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 },
+    ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-queue-error", state: "queued" } }),
+        release: async (_leaseId, signal) => {
+          assert(signal instanceof AbortSignal, "cleanup release receives the reap deadline signal");
+          return { ok: false, error: "signed reap unavailable" };
+        },
+      },
+      wait: async () => ({ error: "lease stream broke" }),
+    },
+  );
+  assert.equal(result.exitCode, EXIT.LEASE_FAILED);
+  assert.equal(result.cleanup.ok, false);
+  assert.match(result.cleanup.error, /signed reap unavailable/);
+});
+
+test("BOT-1346: queue timeout receipt retains a failed cleanup result", async () => {
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-queued", state: "queued" } }),
+        release: async () => ({ ok: false, error: "release rejected" }),
+      },
+      wait: async () => ({ timeout: true }),
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.TIMEOUT);
+  assert.equal(result.cleanup.ok, false);
+  assert.match(result.cleanup.error, /release rejected/);
+});
+
+test("BOT-1346: interruption during lease creation releases the lease once its ID arrives", async () => {
+  const signals = new EventEmitter();
+  let resolveRequest; let releases = 0;
+  const pending = runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["pnpm", "test:integration"],
+    {
+      auth: { Authorization: "Bearer test" }, signals,
+      api: {
+        request: () => new Promise((resolve) => { resolveRequest = resolve; }),
+        release: async () => { releases++; return { ok: true, data: { success: true, state: "reaping" } }; },
+      },
+      wait: async () => ({ woke: true, state: "reaped" }),
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  signals.emit("SIGINT");
+  resolveRequest({ ok: true, data: { success: true, lease_id: "lease-interrupted-request", state: "queued" } });
+  const result = await pending;
+  assert.equal(result.exitCode, 130);
+  assert.equal(releases, 1);
+  assert.equal(result.cleanup.ok, true);
+});
+
+test("BOT-1346: forced hard TTL cannot turn an incomplete child run into success", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4244;
+  let hardTimeout;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5, hardTtl: 1 }, ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-ttl", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ woke: true, state: "reaped" }), writeConnection: async (path) => path, removeConnection: async () => {},
+      startChild: () => { queueMicrotask(() => { hardTimeout(); fakeChild.emit("exit", 0, null); }); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: (fn) => { hardTimeout = fn; return { unref() {} }; }, clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.TIMEOUT);
+});
+
+test("BOT-1346: a fenced lease cannot report a gracefully-stopped child as success", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4245;
+  let heartbeat;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 }, ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-fenced", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: false, error: "lease unavailable" }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ woke: true, state: "reaped" }), writeConnection: async (path) => path, removeConnection: async () => {},
+      startChild: () => { queueMicrotask(async () => { await heartbeat(); fakeChild.emit("exit", 0, null); }); return fakeChild; },
+      clock: { setInterval: (fn) => { heartbeat = fn; return { unref() {} }; }, clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.exitCode, EXIT.LEASE_FAILED);
+  assert.equal(result.fenced, true);
+});
+
+test("BOT-1346: stack run reports failed signed cleanup after a successful child", async () => {
+  const fakeChild = new EventEmitter(); fakeChild.pid = 4243;
+  const result = await runStackLifecycle(
+    { repo: "botbuddy-web", ticket: "BOT-1346", stackPath: ".", timeout: 5, reapTimeout: 5 },
+    ["node", "-e", "process.exit(0)"],
+    {
+      auth: { Authorization: "Bearer test" }, signals: new EventEmitter(),
+      api: {
+        request: async () => ({ ok: true, data: { success: true, lease_id: "lease-unreaped", state: "active" } }),
+        get: async () => ({ ok: true, data: { success: true, state: "active", connection: {} } }),
+        touch: async () => ({ ok: true, data: { success: true } }),
+        release: async () => ({ ok: true, data: { success: true, state: "reaping" } }),
+      },
+      wait: async () => ({ timeout: true }),
+      writeConnection: async (path) => path,
+      removeConnection: async () => {},
+      startChild: () => { queueMicrotask(() => fakeChild.emit("exit", 0, null)); return fakeChild; },
+      clock: { setInterval: () => ({ unref() {} }), clearInterval() {}, setTimeout: () => ({ unref() {} }), clearTimeout() {} },
+    },
+  );
+  assert.equal(result.childExitCode, 0);
+  assert.equal(result.exitCode, EXIT.CLEANUP_FAILED);
+  assert.equal(result.cleanup.ok, false);
+});
 
 // ── receipts ─────────────────────────────────────────────────────────────────
 test("buildReceipt: stamps schema_version", () => {