@botbuddy/cli 1.39.0 → 1.39.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.39.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 };
@@ -1649,10 +1672,12 @@ 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).
     // BOT-2013: a lease reaped while queued (orphaned_agent, …) is lost, not "left the queue".
@@ -1837,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 });
@@ -1846,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 } : {}),
@@ -2447,6 +2479,8 @@ 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();
       // 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 });