@botbuddy/cli 1.38.0 → 1.39.1

package/package.json

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

package/src/stack.mjs

@@ -331,6 +331,29 @@ export function parseStackArgs(argv) {
   return { command, leaseId, opts, errors, childArgv };
 }
 
+/**
+ * BOT-2019: the human line for a queued lease's server position. `queue_position` is the
+ * server's dispatch rank (stack_lease_dispatch_queue — the order leases are considered in,
+ * not a guaranteed start order); a held / owner-offline lease has none and the server says
+ * why in `queue_position_reason`. `scored_ticket_id` is the ticket the lease is scored under
+ * (its own, or the requesting agent's when it has none). Older servers send neither field.
+ */
+export function describeQueuePosition(d) {
+  const reason = d?.queue_position_reason ? ` (${d.queue_position_reason})` : "";
+  const pos = d?.queue_position != null ? `queue position ${d.queue_position}` : `position: none${reason}`;
+  const where = [pos, d?.host_key ? `on ${d.host_key}` : null].filter(Boolean).join(" ");
+  return d?.scored_ticket_id ? `${where}, scored under ${d.scored_ticket_id}` : where;
+}
+
+/** BOT-2019: the queue fields a server returned for a queued lease, for a receipt. */
+function queueReceiptFields(d) {
+  return {
+    queue_position: d?.queue_position ?? null,
+    ...(d?.queue_position_reason !== undefined ? { queue_position_reason: d.queue_position_reason } : {}),
+    ...(d?.scored_ticket_id !== undefined ? { scored_ticket_id: d.scored_ticket_id } : {}),
+  };
+}
+
 /** Build the canonical receipt object (single JSON line to stdout). */
 export function buildReceipt(fields) {
   return { schema_version: STACK_SCHEMA_VERSION, ...fields };
@@ -998,7 +1021,12 @@ export async function waitForLease(leaseId, isDone, isFailed, { timeoutSec, auth
         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)) { decided = { reason: "failed", result: { failed: true, state: st }, status: "error" }; break frameLoop; }
+        if (isFailed(st)) {
+          // BOT-2013: carry the server's reap_reason so the receipt says WHY the lease is gone.
+          const reapReason = typeof sig.payload?.reap_reason === "string" ? sig.payload.reap_reason : null;
+          decided = { reason: "failed", result: { failed: true, state: st, ...(reapReason ? { reap_reason: reapReason } : {}) }, status: "error" };
+          break frameLoop;
+        }
         if (isDone(st)) { decided = { reason: "matched", result: { woke: true, state: st }, status: "matched" }; break frameLoop; }
       }
     }
@@ -1644,13 +1672,23 @@ export async function cmdUp(opts, {
 
   if (state === "queued") {
     // BOT-1319: a wrapped lefthook lane records this park as waiting for capacity.
-    const where = [d.queue_position != null ? `queue position ${d.queue_position}` : null, d.host_key ? `on ${d.host_key}` : null].filter(Boolean).join(" ");
+    // BOT-2019: the server's dispatch rank, or `position: none (<reason>)`, never a crash on null.
+    const where = describeQueuePosition(d);
     reportLaneStatus({ phase: "waiting", reason: "queued_for_capacity", detail: where || "host at capacity" });
+    process.stderr.write(`stack: lease ${leaseId} queued — ${where}\n`);
     if (opts.noWait) {
-      return emitResult(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);
+      return emitResult(buildReceipt({ command: "up", outcome: "queued", lease_id: leaseId, state, host_key: d.host_key, slot, queued: true, ...queueReceiptFields(d), holders: d.holders }), opts, EXIT.QUEUED);
     }
     // Park zero-poll until the lease leaves the queue (granted in BOT-1187 order).
-    const parked = await waitFn(leaseId, nonQueued, () => false, { timeoutSec: opts.timeout, auth });
+    // BOT-2013: a lease reaped while queued (orphaned_agent, …) is lost, not "left the queue".
+    const parked = await waitFn(leaseId, nonQueued, isReaped, { timeoutSec: opts.timeout, auth });
+    if (parked.failed) {
+      return emitResult(buildReceipt({
+        command: "up", outcome: "error", lease_id: leaseId, state: parked.state, slot,
+        reap_reason: parked.reap_reason ?? null,
+        error: `lease was ${parked.state} while queued (reap_reason=${parked.reap_reason ?? "unknown"}) — request a new lease`,
+      }), opts, EXIT.LEASE_FAILED);
+    }
     if (parked.timeout) return emitResult(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 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);
@@ -1824,7 +1862,9 @@ export async function cmdUp(opts, {
   }), opts, EXIT.OK);
 }
 
-export async function cmdStatus(leaseId, opts, { rpc = retryingStackCall(), emitResult = emit } = {}) {
+export async function cmdStatus(leaseId, opts, {
+  rpc = retryingStackCall(), emitResult = emit, stderr = (line) => process.stderr.write(`${line}\n`),
+} = {}) {
   const auth = await rpc.init();
   if (!auth) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
   const got = await rpc.call("get_stack_lease", { lease_id: leaseId });
@@ -1833,10 +1873,15 @@ export async function cmdStatus(leaseId, opts, { rpc = retryingStackCall(), emit
     : emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, error: got.error }), opts, EXIT.BACKEND);
   const g = got.data;
   if (!g.success) return emitResult(buildReceipt({ command: "status", outcome: "error", lease_id: leaseId, code: g.code, error: g.code }), opts, EXIT.BACKEND);
+  // BOT-2019: a queued lease names its server dispatch rank (or why it has none) and the
+  // ticket it is scored under; a null position is reported, never a crash.
+  const queued = g.state === "queued";
+  if (queued) stderr(`stack: lease ${leaseId} queued — ${describeQueuePosition(g)}`);
   return emitResult(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,
+    ...(queued ? queueReceiptFields(g) : { queue_position: g.queue_position }),
+    idle_ttl_secs: g.idle_ttl_secs, queued: g.queued,
     // BOT-1960: a lease fenced in `reaping` says since when, and — once the server gave up
     // retrying its failed reap — that it is reap_failed and why.
     ...(g.reap_requested_at ? { reap_requested_at: g.reap_requested_at } : {}),
@@ -2434,12 +2479,16 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
       return { exitCode: SIGNAL_EXIT[receivedSignal], outcome: "interrupted", leaseId, cleanup };
     }
     if (state === "queued") {
+      // BOT-2019: say where the lease sits (server dispatch rank, or why it has none) before parking.
+      stderrLine(`stack: lease ${leaseId} queued — ${describeQueuePosition(request.data)}`);
       activeWaitAbort = new AbortController();
-      const parked = await wait(leaseId, (s) => s !== "queued" && s != null, (s) => s === "reaped", { timeoutSec: opts.timeout, auth: rpc.auth, signal: activeWaitAbort.signal });
+      // BOT-2013: every reap state (reaping / reaped / reap_failed) means the queued lease is lost.
+      const parked = await wait(leaseId, (s) => s !== "queued" && s != null, isReaped, { timeoutSec: opts.timeout, auth: rpc.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 }; }
+      if (parked?.failed) { const cleanup = await requestCleanup(); return { exitCode: EXIT.LEASE_FAILED, outcome: "error", leaseId, error: `lease was ${parked.state} while queued (reap_reason=${parked.reap_reason ?? "unknown"})`, cleanup }; }
+      if (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") {

package/src/wait-core.mjs

@@ -24,8 +24,32 @@ export const EXIT = Object.freeze({
   // caller can tell "re-register under the new identity" apart from "your condition
   // fired" — the harness re-invokes bb-wait on exit, which re-registers canonically.
   SUPERSEDED: 8,
+  // BOT-2013: a `lease:id=` wait whose lease left the grantable path (reaping / reaped /
+  // reap_failed) before it was granted — re-request the lease. BOT-1754 reserves the name
+  // LEASE_LOST and forbids reusing 2-8; 9 is the first free code.
+  LEASE_LOST: 9,
 });
 
+// BOT-2013: the uuid spellings Postgres accepts for a lease id (uuid_in), mirrored by the SQL
+// liveness check and the /waits UI: 32 hex digits with an optional hyphen after any group of
+// four, optionally wrapped in ONE pair of braces.
+const LEASE_UUID_SPELLING = /^(?:\{(?=.*\}$)|(?!.*\}$))((?:[0-9a-f]{4}-?){7}[0-9a-f]{4})\}?$/;
+
+// BOT-2013: stack_lease frame states that mean the lease is gone, not granted.
+export const LEASE_LOST_STATES = Object.freeze(new Set(["reaping", "reaped", "reap_failed"]));
+
+/** The lease-lost detail for a matched lease frame, or null when the frame is a grant. */
+export function leaseLostDetail(signal, condition) {
+  if (condition?.type !== "lease" || signal?.signal_type !== "stack_lease") return null;
+  const leaseState = signal.payload?.state;
+  if (!LEASE_LOST_STATES.has(leaseState)) return null;
+  return {
+    lease_id: signal.payload?.lease_id ?? condition.params?.id ?? null,
+    lease_state: leaseState,
+    reap_reason: typeof signal.payload?.reap_reason === "string" ? signal.payload.reap_reason : null,
+  };
+}
+
 // BOT-1249: the internal CONTROL signal_type the reconciler emits when a wait's
 // resource identity is canonicalized away. runWaitLoop treats a wait_superseded frame
 // targeting its OWN wait_session as terminal (exit 8) before matchFrame sees it. It is
@@ -154,7 +178,17 @@ const VALIDATORS = {
   // lease's owning agent and keyed `lease:<lease_id>` (mirrors the run:<id> shape).
   lease(p) {
     if (!p.id) throw new Error("lease needs id=<lease_id>");
-    return { id: String(p.id) };
+    // BOT-2013: the server keys frames on the canonical hyphenated lowercase uuid
+    // (`lease:<id>`). Any other spelling Postgres accepts (upper case, braces, no or
+    // extra hyphens) would arm a wait that never matches, so canonicalize it here.
+    const raw = String(p.id).trim().toLowerCase();
+    if (!raw) throw new Error("lease needs id=<lease_id>");
+    // Only an accepted spelling is repaired (Codex #1017 R9); anything else passes through
+    // unchanged and simply matches nothing.
+    const m = LEASE_UUID_SPELLING.exec(raw);
+    const hex = m ? m[1].replace(/-/g, "") : null;
+    const id = hex ? `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}` : raw;
+    return { id };
   },
   // BOT-1064 — linear: wake on a logical state change of a named BOT-* issue.
   // The spine subject_key is the issue identifier as stored on the tickets
@@ -594,6 +628,14 @@ export function buildReceipt({
   return r;
 }
 
+/** BOT-2013: the three lease-lost fields, each bounded, or null when absent. */
+function compactLeaseLostState(state) {
+  if (!state || typeof state !== "object") return null;
+  const short = (v) => (typeof v === "string" ? v.slice(0, 64) : null);
+  if (state.lease_id == null && state.reap_reason == null) return null;
+  return { lease_id: short(state.lease_id), lease_state: short(state.lease_state), reap_reason: short(state.reap_reason) };
+}
+
 /**
  * Enforce the receipt byte cap. Oversized matched-payloads collapse to a
  * pointer (the `seq`, plus a `payload_truncated` marker); the caller re-fetches
@@ -608,9 +650,12 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
       m.payload_truncated = true;
     }
   }
-  // If still over cap, drop the (potentially large) state snapshot to a marker.
+  // If still over cap, drop the (potentially large) state snapshot to a marker. A lease_lost
+  // state is the whole point of that receipt (which lease, why) and is already three short
+  // fields, so it is kept compact instead (BOT-2013, Codex #1017 P2).
+  const leaseLostState = clone.outcome === "lease_lost" ? compactLeaseLostState(clone.state) : null;
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes) {
-    clone.state = { truncated: true };
+    clone.state = leaseLostState ?? { truncated: true };
   }
   // A matched signal's subject key can be caller-controlled through the raw
   // event escape hatch. Keep the durable sequence pointer, but not an
@@ -654,6 +699,24 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     delete clone.detail;
     clone.detail_truncated = true;
   }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "lease_lost") {
+    // BOT-2013: the bounded fallback keeps the lease-lost detail, then adds the resume
+    // pointers only while they still fit.
+    const base = {
+      schema_version: clone.schema_version,
+      outcome: "lease_lost",
+      error: "lease_lost",
+      state: leaseLostState ?? { truncated: true },
+      truncated: true,
+      ...(clone.client ? { client: clone.client } : {}),
+    };
+    for (const key of ["next_cursor", "wait_session_id"]) {
+      if (clone[key] == null) continue;
+      const candidate = { ...base, [key]: clone[key] };
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes) base[key] = clone[key];
+    }
+    return base;
+  }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "error") {
     const base = {
       schema_version: clone.schema_version,
@@ -1269,6 +1332,17 @@ export async function runWaitLoop({
     return { receipt: truncateReceipt(receipt, receiptMaxBytes), exitCode: extra.exitCode };
   };
 
+  // A matched spine frame is a MATCH, except a lease frame reporting that the lease was
+  // reaped: that wait ends lease_lost (BOT-2013) so the caller can re-request instead of
+  // provisioning against a dead lease.
+  const finalizeMatch = async (entry, signal) => {
+    const lost = leaseLostDetail(signal, conditions.find((c) => c.id === entry.condition_id));
+    if (lost) {
+      return finalize("lease_lost", { exitCode: EXIT.LEASE_LOST, matched: [entry], state: lost, error: "lease_lost" });
+    }
+    return finalize("matched", { exitCode: EXIT.MATCHED, matched: [entry] });
+  };
+
   const finalizeSuperseded = async (signal) => {
     // Re-arm from cursor_start rather than this high sequence. A matching row can
     // have been allocated earlier and arrive after the supersession on a replay.
@@ -1636,10 +1710,7 @@ export async function runWaitLoop({
             return fireAlarm(restoredAlarm);
           }
           if (replayCandidate.kind === "superseded") return finalizeSuperseded(replayCandidate.signal);
-          const terminal = await finalize("matched", {
-            exitCode: EXIT.MATCHED,
-            matched: [replayCandidate.entry],
-          });
+          const terminal = await finalizeMatch(replayCandidate.entry, replayCandidate.signal);
           if (onFrame) {
             await onFrame(replayCandidate.signal, {
               cursor: replayCandidate.seqKey,
@@ -1751,10 +1822,7 @@ export async function runWaitLoop({
           pendingReplayMatches.push({ entry, seqKey, signal });
           continue;
         }
-        const terminal = await finalize("matched", {
-          exitCode: EXIT.MATCHED,
-          matched: [entry],
-        });
+        const terminal = await finalizeMatch(entry, signal);
         if (onFrame) {
           await onFrame(signal, {
             cursor: seqKey,

package/src/wait.mjs

@@ -176,7 +176,10 @@ OUTPUT
   notice is on stderr and you will not see it until the wait exits.
   Exit codes: 0 matched · 2 timeout · 3 auth · 4 invalid conditions ·
               5 backend unavailable · 6 cursor expired · 7 internal ·
-              8 superseded (wait replaced server-side). If the receipt has
+              8 superseded (wait replaced server-side) · 9 lease lost (a
+                lease:id= wait whose lease was reaped before it was granted;
+                receipt outcome lease_lost + reap_reason — request a new
+                lease). If the receipt has
                 reacquire_lock (claim=true), acquire_lock again FIRST and re-run
                 only on a queued/busy result (granted = you hold it — just resume);
                 otherwise re-run from the receipt's next_cursor. docs/agent-wait.md.
@@ -503,6 +506,25 @@ async function registerWait(opts, conditions, deadlineIso) {
   };
 }
 
+// BOT-2013: wait_session_status has no lease_lost value. The session ends as a terminal
+// `error` and its stored receipt carries the precise outcome.
+export function cloudStatusForOutcome(outcome) {
+  return outcome === "lease_lost" ? "error" : outcome;
+}
+
+/** BOT-2013: the one stderr line for a lease_lost receipt (null for any other outcome). */
+export function leaseLostNotice(receipt) {
+  if (receipt?.outcome !== "lease_lost") return null;
+  const st = receipt.state ?? {};
+  return `bb-wait: lease ${st.lease_id ?? "?"} was ${st.lease_state ?? "reaped"} before it was granted ` +
+    `(reap_reason=${st.reap_reason ?? "unknown"}) — request a new lease (exit ${EXIT.LEASE_LOST})`;
+}
+
+function writeLeaseLostNotice(receipt) {
+  const notice = leaseLostNotice(receipt);
+  if (notice) process.stderr.write(`${notice}\n`);
+}
+
 // Record the terminal outcome. Best-effort AND bounded: the receipt has already
 // been written to stdout before this runs, so a slow/failing finalize must never
 // delay the agent's wake or change the exit path. A short abort timeout caps how
@@ -522,7 +544,7 @@ async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
       body: JSON.stringify({
         action: "finalize",
         wait_session_id: waitSessionId,
-        status: receipt.outcome,
+        status: cloudStatusForOutcome(receipt.outcome),
         receipt,
         reconnects: receipt.reconnects ?? 0,
         degraded: receipt.degraded ?? [],
@@ -1128,7 +1150,7 @@ async function deliverTerminalFinalization(checkpoint) {
   const result = await postRecovery(checkpoint.relay_url, {
     action: "recover_finalize",
     wait_session_id: checkpoint.cloud_wait_session_id,
-    status: receipt.outcome,
+    status: cloudStatusForOutcome(receipt.outcome),
     receipt,
     reconnects: receipt.reconnects ?? 0,
     degraded: receipt.degraded ?? [],
@@ -1197,6 +1219,7 @@ async function resumeSavedWait(id) {
     } finally {
       await fence?.release();
     }
+    writeLeaseLostNotice(checkpoint.terminal_receipt);
     process.stdout.write(`${JSON.stringify(checkpoint.terminal_receipt)}\n`);
     process.exit(Number.isInteger(checkpoint.exit_code) ? checkpoint.exit_code : EXIT.INTERNAL);
   }
@@ -1241,6 +1264,7 @@ function emitSavedWaitError(error) {
 
 function exitForRecoveredOutcome(receipt) {
   if (receipt?.outcome === "matched") return EXIT.MATCHED;
+  if (receipt?.outcome === "lease_lost") return EXIT.LEASE_LOST;
   if (receipt?.outcome === "cancelled") return EXIT.MATCHED;
   if (receipt?.outcome === "timeout") return EXIT.TIMEOUT;
   if (receipt?.outcome === "superseded") return EXIT.SUPERSEDED;
@@ -1415,10 +1439,12 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   if (argv[0] === "cancel") return argv.length === 2 ? cancelSavedWait(argv[1]) : emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "usage: bb wait cancel <local_wait_id>"));
   if (argv[0] === "acknowledge") return argv.length === 2 ? acknowledgeSavedWait(argv[1]) : emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "usage: bb wait acknowledge <local_wait_id>"));
   const opts = parseArgv(argv);
-  const emitReceipt = (receipt, options = {}) => emit(receipt, {
-    ...options,
-    maxBytes: opts.receiptMaxBytes,
-  });
+  // BOT-2013 (Codex #1017 P2): every receipt this command prints — live, recovered, or
+  // replayed — carries the lease-lost stderr line when it is a lease_lost terminal.
+  const emitReceipt = (receipt, options = {}) => {
+    writeLeaseLostNotice(receipt);
+    return emit(receipt, { ...options, maxBytes: opts.receiptMaxBytes });
+  };
   if (opts.help) {
     process.stdout.write(HELP);
     process.exit(0);