@botbuddy/cli 1.42.1 → 1.43.1

package/package.json

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

package/src/stack.mjs

@@ -60,6 +60,16 @@ const CALLBACK_PORT_REMOTE_REFUSAL =
   "(pre-forward GatewayPorts probe). Use --local-only for a run that needs a callback port.";
 export const DEFAULT_RECEIPT_MAX_BYTES = 10240;
 export const DEFAULT_TIMEOUT_SEC = 3600;
+/**
+ * BOT-2154: how long `stack up --local-exec` lets `supabase start` run before it gives up and
+ * releases the lease itself (`--provision-timeout` overrides). Deliberately below the server's
+ * 1200 s `local_exec_provision_ttl_secs` backstop, so the CLI's own clean `stack done` wins the
+ * race against the reaper.
+ */
+export const LOCAL_EXEC_PROVISION_TIMEOUT_SEC = 900;
+/** BOT-2230: the bounds the control plane enforces on an owner place hold (hold_stack_lease_place). */
+export const HOLD_ON_TIMEOUT_MIN_SEC = 60;
+export const HOLD_ON_TIMEOUT_MAX_SEC = 14400;
 /** How often a run renews its stack directory's retention while it still exists
  * (BOT-1798): frequent enough to cover the pre-child queue/provision waits. */
 const RETENTION_REFRESH_MS = 5 * 60 * 1000;
@@ -104,6 +114,13 @@ ${bold("up OPTIONS")}
   --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).
+  --hold-on-timeout <seconds>
+                         BOT-2230: when the --timeout park runs out with the lease still queued,
+                         keep its queue place for <seconds> (60–14400) instead of losing it: the
+                         lease stays queued but is not dispatched, and re-running the same
+                         \`stack up\` (same agent + slot) before then re-attaches to it. The exit-2
+                         receipt carries queue_hold {held, until, queue_position}; \`stack done
+                         <lease_id>\` gives the place up.
   --claim-only           LOCAL-EXEC only: wait for and hold a provisioning lease without starting
                          Supabase. Resume with the identical \`stack up --local-exec\` command.
   --wait-capacity <dur>  Opt-in (BOT-2024): on a TRANSIENT HOST_CAPACITY_SOURCE_STALE refusal, park
@@ -112,6 +129,10 @@ ${bold("up OPTIONS")}
                          deadline (exit 2) and a failed wait (its own exit code) never retry.
   --local-exec           FALLBACK (no Helper): run 'supabase start' in an ISOLATED --stack-path
                          stack and self-activate. Refused at the worktree root (shared stack).
+  --provision-timeout N  LOCAL-EXEC: seconds 'supabase start' may run (default ${LOCAL_EXEC_PROVISION_TIMEOUT_SEC}). On
+                         timeout up runs 'stack done --local-exec' itself and exits 6 with
+                         park_reason provision_timeout (BOT-2154). The server also fails a local-exec
+                         lease still provisioning after local_exec_provision_ttl_secs (default 1200).
                          Refused (exit 4, ENGINE_PUBLISHES_BEYOND_LOOPBACK) when the Docker
                          engine would publish the stack's ports beyond loopback (BOT-2146).
   --docker-context <name> Explicit Docker context for the mandatory local preflight
@@ -255,7 +276,7 @@ export function parseStackArgs(argv) {
     slot: null, host: null, repo: null, ticket: null, ticketUrl: null,
     prId: null, prUrl: null, purpose: null, idleTtl: null, stackPath: ".", stackPathExplicit: false,
     timeout: DEFAULT_TIMEOUT_SEC, provisionTimeout: null, reapTimeout: 300, hardTtl: null,
-    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null,
+    connectionFile: null, noWait: false, claimOnly: false, localExec: false, waitCapacity: null, holdOnTimeout: null,
     dockerContext: null, dockerEndpoint: null,
     // BOT-2142: execution placement (null = command default), remote-lease callback + bundle cap.
     execution: null, remote: false, localOnly: false, callbackPort: null, bundleMaxBytes: null,
@@ -356,6 +377,15 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--hold-on-timeout": {
+        if (need(a, rest[i + 1])) {
+          const n = Number(rest[++i]);
+          if (!Number.isInteger(n) || n < HOLD_ON_TIMEOUT_MIN_SEC || n > HOLD_ON_TIMEOUT_MAX_SEC) {
+            errors.push(`--hold-on-timeout must be a whole number of seconds from ${HOLD_ON_TIMEOUT_MIN_SEC} to ${HOLD_ON_TIMEOUT_MAX_SEC}`);
+          } else opts.holdOnTimeout = n;
+        }
+        break;
+      }
       case "--no-wait": opts.noWait = true; break;
       case "--claim-only": opts.claimOnly = true; break;
       case "--local-exec": opts.localExec = true; break;
@@ -410,6 +440,11 @@ export function parseStackArgs(argv) {
   if (opts.waitCapacity != null && !["up", "run"].includes(command)) {
     errors.push("--wait-capacity is valid only with `stack up` or `stack run`");
   }
+  if (opts.holdOnTimeout != null && command !== "up") {
+    errors.push("--hold-on-timeout is valid only with `stack up`");
+  } else if (opts.holdOnTimeout != null && opts.noWait) {
+    errors.push("--hold-on-timeout cannot be combined with --no-wait: without a park there is no timeout to keep a place across");
+  }
   if (opts.claimOnly && (command !== "up" || !opts.localExec)) {
     errors.push("--claim-only is valid only with `stack up --local-exec`");
   }
@@ -453,6 +488,22 @@ export function describeQueuePosition(d) {
   return d?.scored_ticket_id ? `${where}, scored under ${d.scored_ticket_id}` : where;
 }
 
+/**
+ * BOT-2230: hold a timed-out queued lease's place for its owner (`hold_stack_lease_place`).
+ * Never throws: a refusal or a control plane without the tool is reported as `held: false`
+ * with the server's code, so the caller decides (the hermetic lane then cancels as before).
+ */
+export async function holdQueuePlace(call, leaseId, holdSecs) {
+  let res;
+  try { res = await call("hold_stack_lease_place", { lease_id: leaseId, hold_secs: holdSecs }); }
+  catch (err) { return { held: false, code: null, error: String(err?.message ?? err) }; }
+  const d = res?.data;
+  if (res?.ok && d?.success) {
+    return { held: true, until: d.queue_hold_until ?? null, queue_position: d.queue_position ?? null, hold_secs: d.hold_secs ?? holdSecs };
+  }
+  return { held: false, code: d?.code ?? null, error: d?.message || d?.error || res?.error || "hold refused" };
+}
+
 /** BOT-2019: the queue fields a server returned for a queued lease, for a receipt. */
 /**
  * BOT-2099: the human lines for the server's unit ledger (`stack_lease_unit_ledger`) — who
@@ -1811,7 +1862,16 @@ export function localProvision(opts, dockerTarget, execution, spawn = spawnSync,
   const url = resolveIsolatedStackApiUrl(stackDir, env);
   const spawnEnv = { ...dockerEnvForTarget(dockerTarget, env), VITE_SUPABASE_URL: url };
   process.stderr.write(`${yellow("⚠ LOCAL-EXEC FALLBACK")} — no BotBuddy Helper; running ${bold("supabase start")} in ${stackDir} (VITE_SUPABASE_URL=${url}).\n`);
-  const start = spawn("supabase", ["start", "--workdir", stackDir], { encoding: "utf8", env: spawnEnv });
+  // BOT-2154: never an unbounded start — a hung `supabase start` held the host slot for hours.
+  const timeoutSec = opts?.provisionTimeout ?? LOCAL_EXEC_PROVISION_TIMEOUT_SEC;
+  const start = spawn("supabase", ["start", "--workdir", stackDir], {
+    encoding: "utf8", env: spawnEnv, timeout: timeoutSec * 1000, killSignal: "SIGTERM",
+  });
+  if (start.error?.code === "ETIMEDOUT") {
+    const timedOut = new Error(`supabase start did not finish within ${timeoutSec}s (--provision-timeout); stopping it and releasing the lease`);
+    timedOut.code = "PROVISION_TIMEOUT";
+    throw timedOut;
+  }
   if (start.status !== 0) {
     throw new Error(`supabase start failed (${start.status}): ${(start.stderr || start.stdout || "").slice(0, 400)}`);
   }
@@ -1902,11 +1962,21 @@ function emit(receipt, opts, code) {
 
 // ── command orchestration ────────────────────────────────────────────────────
 
+/** BOT-2154: run `stack done` in-process and capture its receipt instead of printing it, so
+ * `stack up` still emits exactly one receipt. */
+async function runLocalDone(leaseId, opts, deps = {}) {
+  let receipt = null;
+  const exitCode = await cmdDone(leaseId, opts, { ...deps, emitResult: (r, _o, code) => { receipt = r; return code; } });
+  return { exitCode, receipt };
+}
+
 export async function cmdUp(opts, {
   runPreflight = runLocalExecPreflight,
   callTool = callToolJson,
   authProvider = stackAuthHeader,
   localProvisionFn = localProvision,
+  // BOT-2154: the self-release after a timed-out local start (`stack done --local-exec`).
+  localDoneFn = null,
   waitFn = waitForLease,
   emitResult = emit,
   machineUuidFn = machineUuid,
@@ -2107,7 +2177,14 @@ export async function cmdUp(opts, {
       let ledger = d.ledger ?? null;
       try { const read = await call("get_stack_lease", { lease_id: leaseId }); if (read?.ok && read.data?.success && read.data.ledger) ledger = read.data.ledger; } catch { /* keep the request-time ledger */ }
       for (const line of describeUnitLedger(ledger)) process.stderr.write(`stack: ${line}\n`);
-      return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity`, ...(ledger ? { unit_ledger: ledger } : {}) }), opts, EXIT.TIMEOUT);
+      // BOT-2230: keep the queue place for the owner's next attempt instead of losing it.
+      const queueHold = opts.holdOnTimeout ? await holdQueuePlace(call, leaseId, opts.holdOnTimeout) : null;
+      if (queueHold?.held) {
+        process.stderr.write(`stack: lease ${leaseId} keeps queue place ${queueHold.queue_position ?? "?"} until ${queueHold.until} — re-run the same \`stack up\` before then to re-attach (\`stack done ${leaseId}\` gives it up)\n`);
+      } else if (queueHold) {
+        process.stderr.write(`${yellow("⚠")} stack: lease ${leaseId} could not keep its queue place (${queueHold.code ?? "error"}: ${queueHold.error})\n`);
+      }
+      return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state: "queued", slot, error: `parked ${opts.timeout}s without capacity`, ...(ledger ? { unit_ledger: ledger } : {}), ...(queueHold ? { queue_hold: queueHold } : {}) }), opts, EXIT.TIMEOUT);
     }
     if (parked.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
     if (parked.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: parked.error }), opts, EXIT.BACKEND);
@@ -2231,6 +2308,21 @@ export async function cmdUp(opts, {
         try {
           conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget, execution), localDockerTarget);
         } catch (e) {
+          if (e?.code === "PROVISION_TIMEOUT") {
+            // BOT-2154: a bounded start that ran out of time. Release the lease ourselves —
+            // `stack done --local-exec` stops whatever the start left behind and reaps the lease
+            // — instead of leaving it provisioning for the server's backstop to find.
+            const done = await (localDoneFn ?? ((id, doneOpts) => runLocalDone(id, doneOpts, { callTool, authProvider })))(
+              leaseId, { ...opts, localExec: true, disposition: "destroy", json: false });
+            const doneReceipt = done?.receipt ?? {};
+            const cleaned = done?.exitCode === 0;
+            return emitResult(buildReceipt({
+              command: "up", outcome: "timeout", code: "PROVISION_TIMEOUT", park_reason: "provision_timeout",
+              lease_id: leaseId, slot, error: e.message, cleanup: cleaned,
+              done: { outcome: doneReceipt.outcome ?? null, state: doneReceipt.state ?? null, exit_code: done?.exitCode ?? null },
+              ...(cleaned ? {} : { cleanup_error: doneReceipt.error ?? `stack done --local-exec exited ${done?.exitCode}` }),
+            }), opts, EXIT.LEASE_FAILED);
+          }
           // Once the local provisioner has run, `supabase start` may have created
           // (or fully started) containers even on a nonzero exit or a status-parse
           // failure. Cancelling here would reap the lease and free the slot while