@botbuddy/cli 1.36.3 → 1.37.0

package/package.json

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

package/src/stack.mjs

@@ -27,6 +27,7 @@ import { open, unlink, readFile } from "fs/promises";
 import { tmpdir } from "os";
 import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
+import { fileURLToPath } from "url";
 import { callToolJson, CALL_AUTH_ERROR_CODES } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
@@ -86,6 +87,10 @@ ${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).
+  --wait-capacity <dur>  Opt-in (BOT-2024): on a TRANSIENT HOST_CAPACITY_SOURCE_STALE refusal, park
+                         on the server's \`bb wait 'capacity:…'\` up to <dur> (90s, 10m, 1h) and
+                         re-attempt admission once when it matches. Sustained refusals, the
+                         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).
   --docker-context <name> Explicit Docker context for the mandatory local preflight
@@ -114,6 +119,7 @@ ${bold("run OPTIONS")}
   --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.
+  --wait-capacity <dur>  Same as up: park a TRANSIENT stale-capacity refusal, then re-admit once.
 
 ${bold("GLOBAL")}
   --json                 Pretty-print the receipt (default is one compact JSON line).
@@ -124,6 +130,13 @@ ${bold("EXIT CODES")}
   4 invalid arguments               5 backend/coordination      6 lease failed/reaped
   7 internal error                  8 cleanup/reap proof failed
 
+${bold("HOST_CAPACITY_SOURCE_STALE")} (BOT-2024)
+  HOST_CAPACITY_SOURCE_STALE is a capacity flag, not a Helper diagnosis. Read \`phase\` on the
+  receipt. transient → arm the printed \`bb wait 'capacity:…'\` and re-run once it fires
+  (or pass --wait-capacity); never report blocked, never ask for a Helper restart.
+  sustained (no beacon ever or >= 10 min) → report BLOCKED quoting \`stale_since\`; a Helper
+  check/restart is the right ask. A single refusal is never evidence of an outage.
+
 ${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`;
@@ -175,7 +188,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, localExec: false,
+    connectionFile: null, noWait: false, localExec: false, waitCapacity: null,
     dockerContext: null, dockerEndpoint: null,
     disposition: "destroy", json: false, receiptMaxBytes: DEFAULT_RECEIPT_MAX_BYTES,
   };
@@ -248,6 +261,14 @@ export function parseStackArgs(argv) {
         }
         break;
       }
+      case "--wait-capacity": {
+        if (need(a, rest[i + 1])) {
+          const secs = parseWaitCapacityDuration(rest[++i]);
+          if (secs == null) errors.push("--wait-capacity must be a positive duration: <N>, <N>s, <N>m or <N>h");
+          else opts.waitCapacity = secs;
+        }
+        break;
+      }
       case "--no-wait": opts.noWait = true; break;
       case "--local-exec": opts.localExec = true; break;
       case "--docker-context": if (need(a, rest[i + 1])) opts.dockerContext = rest[++i]; break;
@@ -280,6 +301,9 @@ export function parseStackArgs(argv) {
       "worktree root's default (shared canonical) project. Point --stack-path at a slot-derived stack directory with its " +
       "own supabase/config.toml (distinct project_id + remapped ports).");
   }
+  if (opts.waitCapacity != null && !["up", "run"].includes(command)) {
+    errors.push("--wait-capacity is valid only with `stack up` or `stack run`");
+  }
   if ((opts.dockerContext || opts.dockerEndpoint) && !(["up", "done"].includes(command) && opts.localExec)) {
     errors.push("--docker-context and --docker-endpoint are valid only with `stack up --local-exec` or `stack done --local-exec`");
   }
@@ -708,6 +732,124 @@ export function leaseRefusalError(data) {
   return data?.message || data?.code || "lease request refused";
 }
 
+// ── BOT-2024: phase-aware HOST_CAPACITY_SOURCE_STALE ─────────────────────────
+// The refusal is a capacity FLAG, not a Helper diagnosis. The server classifies it:
+// `sustained` iff the host never beaconed or its last beacon is >= 600 s old, else
+// `transient` (scheduler lag; the flag's own age is informational only). Agents escalated transient lag as an outage and asked the
+// user to restart a healthy Helper (2026-10-03), so the CLI renders the phase.
+export const HOST_CAPACITY_SOURCE_STALE_CODE = "HOST_CAPACITY_SOURCE_STALE";
+const CAPACITY_STALE_RULE =
+  "HOST_CAPACITY_SOURCE_STALE is a capacity flag, not a Helper diagnosis. Read `phase`: transient → arm the printed " +
+  "`bb wait 'capacity:…'` and re-run once it fires (never report blocked, never ask for a Helper restart); " +
+  "sustained (no beacon ever or >= 10 min) → report BLOCKED quoting `stale_since`. A single refusal is never evidence of an outage.";
+
+function humanSecs(secs) {
+  if (!Number.isFinite(secs)) return "an unknown time";
+  if (secs < 120) return `${secs}s`;
+  if (secs < 7200) return `${Math.floor(secs / 60)}m`;
+  return `${Math.floor(secs / 3600)}h${Math.floor((secs % 3600) / 60)}m`;
+}
+
+/** Operator/agent-facing guidance for a stale-capacity refusal (or null for any other code). */
+export function capacityStaleGuidance(data) {
+  if (data?.code !== HOST_CAPACITY_SOURCE_STALE_CODE) return null;
+  const host = data.host_key ? ` on ${data.host_key}` : "";
+  if (data.phase === "transient") {
+    const beacon = Number.isFinite(data.beacon_age_secs) ? `the Helper beaconed ${humanSecs(data.beacon_age_secs)} ago` : "no beacon recorded yet";
+    return `${yellow("⚠")} stack: capacity flag is stale${host} (${beacon}). Scheduler lag, not a Helper outage. ` +
+      "Do NOT report blocked or ask for a Helper restart.\n" +
+      (data.wait ? `  Wait for capacity, then re-run: bb wait '${data.wait}'   (or pass --wait-capacity <dur>)` : `  ${CAPACITY_STALE_RULE}`);
+  }
+  if (data.phase === "sustained") {
+    const age = Number.isFinite(data.beacon_age_secs) ? `for ${humanSecs(data.beacon_age_secs)}` : "ever recorded";
+    return `${yellow("⚠")} stack: no Helper beacon ${age}${host} (stale since ${data.stale_since ?? "unknown"}) — ` +
+      "report BLOCKED quoting stale_since; check `launchctl print user/$UID/com.botbuddy.helper.worker` and the worker log, " +
+      "or restart BotBuddy Helper.";
+  }
+  // A pre-BOT-2024 server sends no phase: give the rule, never a restart ask.
+  return `${yellow("⚠")} stack: ${CAPACITY_STALE_RULE}`;
+}
+
+/** The refusal's phase fields worth keeping on a receipt (empty for any other refusal). */
+export function capacityStaleReceiptFields(data) {
+  if (data?.code !== HOST_CAPACITY_SOURCE_STALE_CODE) return {};
+  const out = {};
+  for (const k of ["phase", "wait", "stale_since", "beacon_age_secs", "stale_for_secs"]) {
+    if (data[k] !== undefined) out[k] = data[k];
+  }
+  return out;
+}
+
+/** `--wait-capacity <dur>`: `90`, `90s`, `10m`, `1h` → seconds (null when invalid). */
+export function parseWaitCapacityDuration(raw) {
+  const m = /^([1-9]\d*)([smh]?)$/.exec(String(raw ?? "").trim());
+  if (!m) return null;
+  return Number(m[1]) * ({ "": 1, s: 1, m: 60, h: 3600 })[m[2]];
+}
+
+const BOTBUDDY_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "botbuddy.mjs");
+
+/** argv for the park: this CLI's own `bb wait` on the server's condition, bounded by --timeout. */
+export function capacityWaitArgv(condition, timeoutSec) {
+  return [process.execPath, BOTBUDDY_BIN, "wait", condition, "--timeout", String(timeoutSec)];
+}
+
+/**
+ * Park on the server's capacity wait via the real `bb wait` (registration, ranked
+ * grants, beacon-stale handling, checkpoint) — never a shell sleep/poll loop. Its
+ * receipt is captured; its stderr (arm notices) passes through.
+ */
+export function defaultWaitCapacity(condition, timeoutSec, { signal } = {}) {
+  const [cmd, ...args] = capacityWaitArgv(condition, timeoutSec);
+  return new Promise((resolve) => {
+    // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- fixed argv (this CLI's own bin), no shell.
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "inherit"], signal });
+    let stdout = "";
+    child.stdout.on("data", (d) => { stdout += d; });
+    const receiptOf = () => {
+      const last = stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
+      try { return last ? JSON.parse(last) : null; } catch { return null; }
+    };
+    child.on("error", (error) => resolve({ exitCode: EXIT.INTERNAL, receipt: null, error: error?.message ?? String(error) }));
+    child.on("close", (code) => resolve({ exitCode: code ?? EXIT.INTERNAL, receipt: receiptOf() }));
+  });
+}
+
+/**
+ * BOT-2024: request a lease; on a TRANSIENT stale-capacity refusal with
+ * `--wait-capacity`, park on the server's `wait` condition and re-attempt admission
+ * exactly once — ONLY when the wait MATCHED (exit 0). Sustained (or phase-less)
+ * refusals never park. The deadline returns `capacityTimeout`; any other nonzero wait
+ * exit (auth/backend failure, the host-pinned capacity_source_stale exit after its
+ * beacon-confirm window, …) is the wait's own terminal outcome and returns
+ * `waitFailed` for the caller to propagate typed — retrying there would mask it
+ * (Codex #1018 P2).
+ */
+export async function requestWithCapacityWait(request, opts, { waitCapacity = defaultWaitCapacity, log, signal = null } = {}) {
+  let req = await request();
+  const stale = (r) => r?.ok && r.data && !r.data.success && r.data.code === HOST_CAPACITY_SOURCE_STALE_CODE;
+  if (!stale(req)) return { req };
+  const guidance = capacityStaleGuidance(req.data);
+  if (guidance) log(guidance);
+  if (!opts.waitCapacity || req.data.phase !== "transient" || !req.data.wait) return { req };
+  log(`${dim("…")} stack: --wait-capacity: parking up to ${opts.waitCapacity}s on bb wait '${req.data.wait}'`);
+  const parked = await waitCapacity(req.data.wait, opts.waitCapacity, { signal });
+  if (signal?.aborted) return { req, interrupted: true };
+  if (parked?.exitCode === EXIT.TIMEOUT) return { req, capacityTimeout: true, waitReceipt: parked.receipt ?? null };
+  if (parked?.exitCode !== 0) {
+    const exitCode = Number.isInteger(parked?.exitCode) ? parked.exitCode : EXIT.INTERNAL;
+    const detail = parked?.receipt?.error ?? parked?.error ?? parked?.receipt?.outcome ?? "no receipt";
+    log(`${yellow("⚠")} stack: --wait-capacity: bb wait '${req.data.wait}' exited ${exitCode} (${detail}); not retrying admission.`);
+    return { req, waitFailed: { exitCode, receipt: parked?.receipt ?? null, detail } };
+  }
+  req = await request();
+  if (stale(req)) {
+    const again = capacityStaleGuidance(req.data);
+    if (again) log(again);
+  }
+  return { req };
+}
+
 // The MCP lease endpoint accepts a session token in x-agent-api-key, whereas
 // the event-stream relay requires that same token in its bearer form too. Keep
 // the lease RPC shape unchanged and derive the relay-compatible form only at
@@ -1355,6 +1497,7 @@ export async function cmdUp(opts, {
   machineUuidFn = machineUuid,
   assertIsolated = validateLocalExecTarget,
   refreshAuth = refreshRejectedCacheAuth,
+  waitCapacity = defaultWaitCapacity,
 } = {}) {
   let slot;
   try { slot = deriveSlot(opts); } catch (e) {
@@ -1437,11 +1580,58 @@ export async function cmdUp(opts, {
       ? emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "unauthorized" }), opts, EXIT.AUTH)
       : emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, EXIT.BACKEND);
   }
+  // BOT-2024: phase-aware stale-capacity guidance; --wait-capacity parks a TRANSIENT
+  // refusal on the server's capacity wait and re-admits once.
+  if (req.data && !req.data.success && req.data.code === HOST_CAPACITY_SOURCE_STALE_CODE) {
+    let first = req;
+    // Codex #1018 R4: the park can outlive the pre-wait credential (expired/revoked
+    // while parked; the spawned `bb wait` may itself have renewed the worktree
+    // session). So the post-wait retry RE-LOADS the credential from disk, then takes
+    // the standard refresh-once-on-auth-rejection path. A second rejection falls
+    // through to the typed AUTH exit below — never a loop.
+    const retryAfterWait = async () => {
+      const reloaded = await authProvider();
+      if (reloaded) auth = reloaded;
+      let retried = await call("request_stack_lease", leaseArgs);
+      if (!retried.ok && retried.auth) {
+        const fresh = await refreshAuth(auth, { cwd: process.cwd() });
+        if (fresh) {
+          auth = fresh;
+          retried = await call("request_stack_lease", leaseArgs);
+        }
+      }
+      return retried;
+    };
+    const admission = await requestWithCapacityWait(
+      async () => { if (first) { const r = first; first = null; return r; } return retryAfterWait(); },
+      opts, { waitCapacity, log: (line) => process.stderr.write(`${line}\n`) },
+    );
+    if (admission.capacityTimeout) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "timeout", code: admission.req.data.code, ...capacityStaleReceiptFields(admission.req.data),
+        wait_exit_code: EXIT.TIMEOUT, wait_receipt: admission.waitReceipt,
+        error: `capacity did not recover within --wait-capacity ${opts.waitCapacity}s (${admission.req.data.code})`, slot,
+      }), opts, EXIT.TIMEOUT);
+    }
+    if (admission.waitFailed) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "error", code: admission.req.data.code, ...capacityStaleReceiptFields(admission.req.data),
+        wait_exit_code: admission.waitFailed.exitCode, wait_receipt: admission.waitFailed.receipt,
+        error: `--wait-capacity: bb wait exited ${admission.waitFailed.exitCode} (${admission.waitFailed.detail})`, slot,
+      }), opts, admission.waitFailed.exitCode);
+    }
+    req = admission.req;
+    if (!req.ok) {
+      return emitResult(buildReceipt({ command: "up", outcome: "error", error: req.error || "request failed" }), opts, req.auth ? EXIT.AUTH : EXIT.BACKEND);
+    }
+  }
   const d = req.data;
   if (!d.success) {
     const hint = worktreeRegistrationHint(d.code, auth) ?? stackPathRootRefusalNotice(d.code, d.message);
     if (hint) process.stderr.write(`${hint}\n`);
-    return emitResult(buildReceipt({ command: "up", outcome: "error", code: d.code, error: leaseRefusalError(d), slot }), opts, leaseRefusalExit(d.code));
+    return emitResult(buildReceipt({
+      command: "up", outcome: "error", code: d.code, ...capacityStaleReceiptFields(d), error: leaseRefusalError(d), slot,
+    }), opts, leaseRefusalExit(d.code));
   }
   let leaseId = d.lease_id;
   let state = d.state;
@@ -2030,6 +2220,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
   const clock = adapters.clock ?? { setInterval, clearInterval, setTimeout, clearTimeout };
   const signals = adapters.signals ?? process;
   const provisionTimeout = opts.provisionTimeout ?? opts.timeout;
+  const stderrLine = adapters.stderr ?? ((line) => process.stderr.write(`${line}\n`));
   let leaseId = null;
   let child = null;
   let childResult = null;
@@ -2176,7 +2367,34 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     };
     // The retrying caller (api → rpc.call) transparently clears+self-heals+retries the
     // FIRST auth rejection among any of request/get/touch/release.
-    const request = await api.request(leaseArgs);
+    // BOT-2024: a stale-capacity refusal prints phase-aware guidance; with the opt-in
+    // --wait-capacity a TRANSIENT one parks on the server's capacity wait and re-admits once.
+    activeWaitAbort = new AbortController();
+    const admission = await requestWithCapacityWait(() => api.request(leaseArgs), opts, {
+      waitCapacity: adapters.waitCapacity ?? defaultWaitCapacity, log: stderrLine, signal: activeWaitAbort.signal,
+    });
+    activeWaitAbort = null;
+    const request = admission.req;
+    // Interrupted DURING the capacity park: the refused request created no lease, so
+    // there is nothing to release. (A signal during a request that DID admit falls
+    // through to the existing post-lease interruption branch, which cleans up.)
+    if (admission.interrupted) {
+      return { exitCode: SIGNAL_EXIT[receivedSignal] ?? EXIT.INTERNAL, outcome: "interrupted", code: request?.data?.code, ...capacityStaleReceiptFields(request?.data) };
+    }
+    if (admission.capacityTimeout) {
+      return {
+        exitCode: EXIT.TIMEOUT, outcome: "timeout", code: request.data.code, ...capacityStaleReceiptFields(request.data),
+        wait_exit_code: EXIT.TIMEOUT, wait_receipt: admission.waitReceipt,
+        error: `capacity did not recover within --wait-capacity ${opts.waitCapacity}s (${request.data.code})`,
+      };
+    }
+    if (admission.waitFailed) {
+      return {
+        exitCode: admission.waitFailed.exitCode, outcome: "error", code: request.data.code, ...capacityStaleReceiptFields(request.data),
+        wait_exit_code: admission.waitFailed.exitCode, wait_receipt: admission.waitFailed.receipt,
+        error: `--wait-capacity: bb wait exited ${admission.waitFailed.exitCode} (${admission.waitFailed.detail})`,
+      };
+    }
     if (!request?.ok) {
       // Codex #928 R23 (P2): `status: null` (callToolJson's fetch-threw branch) means
       // NO response was ever received — the request may have reached the backend and
@@ -2192,8 +2410,11 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     if (!request.data?.success) {
       const hint = worktreeRegistrationHint(request.data?.code, rpc.auth)
         ?? stackPathRootRefusalNotice(request.data?.code, request.data?.message);
-      if (hint) process.stderr.write(`${hint}\n`);
-      return { exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code, error: leaseRefusalError(request.data) };
+      if (hint) stderrLine(hint);
+      return {
+        exitCode: leaseRefusalExit(request.data?.code), outcome: "error", code: request.data?.code,
+        ...capacityStaleReceiptFields(request.data), error: leaseRefusalError(request.data),
+      };
     }
     leaseId = request.data.lease_id;
     if (request.data.reused) {
@@ -2341,6 +2562,9 @@ async function cmdRun(opts, childArgv) {
     // BOT-1797: carry the server's typed refusal code (e.g. stack_path_root_refused)
     // so automation can branch on it instead of matching the message text.
     command: "run", outcome: result.outcome, code: result.code ?? null, lease_id: result.leaseId ?? null,
+    // BOT-2024: a stale-capacity refusal carries its phase + armable wait on the receipt.
+    ...capacityStaleReceiptFields(result),
+    ...(result.wait_exit_code != null ? { wait_exit_code: result.wait_exit_code, wait_receipt: result.wait_receipt ?? 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);

package/src/wait-core.mjs

@@ -1179,13 +1179,13 @@ export async function runWaitLoop({
   // the primary hysteresis); 0 = exit immediately on the stale signal. Injectable so
   // a clock-controlled test can drive it. Not a grammar surface (no new condition name).
   //
-  // Default MUST exceed the beacon evaluator's worst-case cadence (Codex P2). The
-  // recovery transition is emitted by the `* * * * *` (60s) eval_container_beacon_staleness
-  // cron, and claim_container_job only refreshes last_beacon_at — it does not itself emit
-  // recovery — so a host that resumes polling right after a stale emission has its
-  // recovery frame arrive up to ~60s later. A confirm shorter than that would exit the
-  // wait capacity_source_stale even though the host recovered seconds after the stale
-  // frame. 90s = 60s cron + margin.
+  // Default MUST exceed the beacon evaluator's worst-case cadence (Codex P2). Before
+  // BOT-2024 the recovery transition was emitted only by the `* * * * *` (60s)
+  // eval_container_beacon_staleness cron, so a host that resumed polling right after a
+  // stale emission had its recovery frame arrive up to ~60s later. Since BOT-2024 the
+  // beacon itself (claim_container_job / attested registerHost) emits the recovery, so
+  // the frame now lands on the Helper's next beacon; 90s still covers one ~45-60s
+  // Helper beacon interval plus margin, and an older server's cron-only recovery.
   beaconConfirmMs = 90_000,
   // BOT-1837: the arm-time notice (if any) to carry into a TIMEOUT receipt's
   // `error`, so the receipt itself says what CI was already doing when this wait