@botbuddy/cli 1.42.1 → 1.43.0

package/package.json

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

package/src/stack.mjs

@@ -60,6 +60,9 @@ 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-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 +107,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
@@ -255,7 +265,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 +366,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 +429,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 +477,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
@@ -2107,7 +2147,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);