@botbuddy/cli 1.19.2 → 1.20.0

package/package.json

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

package/src/wait-core.mjs

@@ -765,6 +765,28 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       // cannot actually be served. The wait loop handles it separately (fold the
       // capacity_source_stale marker / fast exit); it must not read as capacity here.
       if (signal.payload?.source_stale === true) return false;
+      // BOT-1577: a RANKED grant restricts the host broadcast to named winners.
+      // When the payload carries granted_wait_session_ids, match ONLY if THIS
+      // wait's session id is in it — otherwise keep parking (the server already
+      // vetted the slot count and this wait's minSlots when it built the list).
+      // A payload WITHOUT the list is a legacy broadcast (older server, or the
+      // no-contention case) → fall back to the free_slots >= N threshold, so this
+      // stays backward compatible.
+      const granted = signal.payload?.granted_wait_session_ids;
+      if (Array.isArray(granted)) {
+        if (waitSessionId == null || !granted.includes(waitSessionId)) return false;
+        // BOT-1577: a ranked grant is only valid until its 120s hold expires. This
+        // signal is durable — on a reconnect from an old cursor (or a slow wake) after
+        // the hold lapsed and the slot was re-granted to another waiter, event-stream
+        // replays the original grant. Reject it once expired — and reserve
+        // GRANT_CONSUME_MARGIN_MS (finalize feed-lag reprobe + the up-to-5s finalizeWait
+        // that runs before `botbuddy wait` exits), since a grant that lapses in that window
+        // is re-granted before the caller can start — so the original client does not start
+        // too (double-provision). A payload without grant_expires_at (older server) is accepted;
+        // a present-but-malformed expiry fails closed (parks) rather than matching forever.
+        if (!grantUnexpired(signal.payload?.grant_expires_at, GRANT_CONSUME_MARGIN_MS)) return false;
+        return true;
+      }
       const free = Number(signal.payload?.free_slots);
       return Number.isFinite(free) && free >= params.minSlots;
     }
@@ -901,6 +923,55 @@ export function matchFrame(frame, conditions, waitSessionId, sessionTenant) {
   return null;
 }
 
+/**
+ * BOT-1577: derive this wait's grant detail from a ranked container_capacity
+ * signal, for the receipt (`matched[].grant = {position, tier, score}`). Returns
+ * null when the signal is not a ranked capacity grant addressed to this wait
+ * (legacy broadcast, another host, or a payload without the grant list).
+ * `position` is 1-based in the server's grant order; tier/score come from the
+ * index-aligned granted_grants entry when present.
+ */
+// BOT-1577: a ranked capacity grant is valid only until its 120s hold expires
+// (payload.grant_expires_at, an ISO timestamp). `marginMs` reserves remaining-time before
+// the expiry: a grant accepted with less than the margin left could lapse between the
+// match and the terminal receipt — finalize() can spend up to FEED_PROBE_BUDGET_MS in the
+// feed-lag reprobe for a mixed capacity/linear wait — after which the periodic evaluator
+// re-grants the slot, so accepting it would double-provision (BOT-1577 P1). A payload
+// without the field (older server) is treated as valid for backward compatibility; an
+// unparseable value fails open (valid) rather than dropping a live grant.
+// Minimum hold time a grant must have left when accepted, so it survives the whole path
+// from acceptance to the caller actually PROVISIONING the slot (BOT-1577 P1):
+//   • finalize()'s feed-lag reprobe .......... FEED_PROBE_BUDGET_MS  (2s)
+//   • finalizeWait() runWait() awaits ......... 5s   (after the receipt, before exit)
+//   • the caller's docker preflight ........... 30s  (a single Docker command budget)
+// Below this, a delayed/replayed grant can lapse mid-preflight and be re-granted before
+// the caller starts, double-provisioning the slot. The 120s hold's remainder (~120−37s)
+// then covers the actual `supabase start`; a caller that provisions beyond that window is
+// the consumer's responsibility to re-validate at start (the SG start gate, BOT-1576).
+const GRANT_CONSUME_MARGIN_MS = 2000 + 5000 + 30000;
+function grantUnexpired(grantExpiresAt, marginMs = 0) {
+  if (grantExpiresAt == null) return true;          // absent (older server) ⇒ accept (legacy)
+  const t = Date.parse(grantExpiresAt);
+  if (!Number.isFinite(t)) return false;            // present but MALFORMED ⇒ fail closed (park)
+  return Date.now() + marginMs < t;
+}
+
+export function capacityGrantForReceipt(signal, waitSessionId) {
+  if (!signal || signal.signal_type !== "container_capacity" || waitSessionId == null) return null;
+  const granted = signal.payload?.granted_wait_session_ids;
+  if (!Array.isArray(granted)) return null;
+  const idx = granted.indexOf(waitSessionId);
+  if (idx < 0) return null;
+  if (!grantUnexpired(signal.payload?.grant_expires_at)) return null;  // BOT-1577: stale grant ⇒ no receipt
+  const grant = { position: idx + 1 };
+  const meta = Array.isArray(signal.payload?.granted_grants) ? signal.payload.granted_grants[idx] : null;
+  if (meta && typeof meta === "object") {
+    if (meta.tier != null) grant.tier = meta.tier;
+    if (meta.score != null) grant.score = meta.score;
+  }
+  return grant;
+}
+
 // ---------------------------------------------------------------------------
 // The wait loop.
 // ---------------------------------------------------------------------------
@@ -1425,16 +1496,20 @@ export async function runWaitLoop({
 
       const matched = matchFrame(frame, conditions, waitSessionId, sessionTenant);
       if (matched) {
+        const entry = {
+          condition_id: matched.id,
+          signal_type: signal.signal_type,
+          seq: signal.seq,
+          subject_key: signal.subject_key,
+          payload: signal.payload ?? null,
+          provenance: "spine",
+        };
+        // BOT-1577: a ranked capacity grant records this wait's position/tier/score.
+        const grant = capacityGrantForReceipt(signal, waitSessionId);
+        if (grant) entry.grant = grant;
         return finalize("matched", {
           exitCode: EXIT.MATCHED,
-          matched: [{
-            condition_id: matched.id,
-            signal_type: signal.signal_type,
-            seq: signal.seq,
-            subject_key: signal.subject_key,
-            payload: signal.payload ?? null,
-            provenance: "spine",
-          }],
+          matched: [entry],
         });
       }
     }

package/src/wait.mjs

@@ -90,6 +90,11 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       Host-shared; a silently-dead host is detected server-side
                                       (capacity_source_stale) via a host beacon — the client
                                       grace (default 900s) is a backstop, no longer the only guard.
+                                      Grants are RANKED (BOT-1577): when several waiters
+                                      contend, a freed slot is handed to the highest-scored
+                                      one and its receipt carries grant:{position,tier,score};
+                                      the others keep parking. Older servers broadcast without
+                                      the ranking (first-come). Needs cli >= 1.20.0.
   ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>
                         | scope=next[,branch=<name>][,workflow=<name>]}
                                       a PR's CI reaching a terminal conclusion (owner-scoped);