@botbuddy/cli 1.19.1 → 1.20.0

package/package.json

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

package/src/wait-core.mjs

@@ -576,13 +576,27 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     clone.detail_truncated = true;
   }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "error") {
-    return {
+    const base = {
       schema_version: clone.schema_version,
       outcome: "error",
       error: typeof clone.error === "string" ? clone.error.slice(0, 48) : "receipt_truncated",
       truncated: true,
       ...(clone.client ? { client: clone.client } : {}),
     };
+    // BOT-1590: the recovery hint is the whole point of an error receipt, so keep
+    // it (trimmed to whatever still fits the cap) rather than dropping it — a
+    // caller at the documented minimum cap must still get its one actionable line.
+    if (typeof clone.recovery === "string" && clone.recovery.length > 0) {
+      const room = maxBytes - Buffer.byteLength(JSON.stringify({ ...base, recovery: "" }));
+      if (room > 0) {
+        let recovery = clone.recovery;
+        while (recovery.length > 0 && Buffer.byteLength(recovery, "utf8") > room) {
+          recovery = recovery.slice(0, -1);
+        }
+        if (recovery.length > 0) base.recovery = recovery;
+      }
+    }
+    return base;
   }
   return clone;
 }
@@ -751,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;
     }
@@ -887,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.
 // ---------------------------------------------------------------------------
@@ -1411,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

@@ -14,7 +14,7 @@
 // Run     botbuddy wait --help for the condition grammar.
 
 import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
-import { resolveAgentProfile, withPrincipalReceipt } from "./wait-profile.mjs";
+import { resolveAgentProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.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);
@@ -643,10 +648,52 @@ function profileErrorReceipt(profile, error) {
     schema_version: 1,
     outcome: "error",
     error,
-    recovery: profileRecovery(profile),
+    recovery: profileCredentialRecovery(profile),
   }, profile, { sessionTenant: profile.tenant, agentId: null });
 }
 
+// BOT-1590: canonical one-line recoveries for every setup/auth/parameter error.
+// Each names the exact command to run and the source of any missing/invalid
+// value, so an agent (or a human) can self-serve without opening the docs. The
+// SAME string is written to stderr and the receipt `recovery` field that /waits
+// renders. Keep each to one line and never embed a secret value — names, slots,
+// and env-var names only.
+const RECOVERY = Object.freeze({
+  // $BOTBUDDY_SESSION_TOKEN (bb_sess_+64hex) is minted by register_agent; the
+  // harness exports it at session start.
+  sessionToken: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token> (the harness exports it at session start)",
+  // $BOTBUDDY_SESSION_ID is the work-graph session id returned by register_agent.
+  sessionId: "register_agent → export BOTBUDDY_SESSION_ID=<session_id> (the work-graph session id from register_agent)",
+  // A --token / session-token contradiction: the session token is the whole
+  // credential, so drop --token (never advise also setting a session id here).
+  sessionTokenConflict: "unset --token — $BOTBUDDY_SESSION_TOKEN is the whole credential (protocol 3)",
+  // Grammar/condition errors point at the help and the canonical doc.
+  conditions: "check the condition grammar: botbuddy wait --help / docs/agent-wait.md",
+});
+
+const KNOWN_PROFILES = "botbuddy-dev, supplyguard-dev";
+
+// profile_required / unknown_profile: name the file, a minimal example, and the
+// known profile names so the fix is a single edit (AC-3).
+function profileResolutionRecovery(errorCode) {
+  return errorCode === "unknown_profile"
+    ? `set a known profile in ${PROFILE_FILE} or pass --profile <name> — known profiles: ${KNOWN_PROFILES}`
+    : `add ${PROFILE_FILE} ({"schema_version":1,"profile":"botbuddy-dev"}) or pass --profile <name> — known profiles: ${KNOWN_PROFILES}`;
+}
+
+// A profile-credential error (missing/revoked/wrong-tenant): name the exact
+// setup command and the credential's real source, then rule out human PATs,
+// which are never valid for waits (AC-4). `botbuddy profile setup` stores the
+// key in the macOS Keychain under the profile env-var's name (it REQUIRES the
+// Keychain — ensureProfileCredentialBackend); on a non-Keychain host the
+// supported path is exporting that same profile env var directly, which
+// resolveAgentProfile reads. (The 0600 config.json store is the owner login
+// token's, not a profile credential's — a wait cannot consume it.)
+const HUMAN_PAT_NOTE = "human PATs (BOTBUDDY_AGENT_KEY / BOTBUDDY_AGENT_API_KEY) are not valid for waits";
+function profileCredentialRecovery(profile) {
+  return `${profileRecovery(profile)} (stores $${profile.tokenEnv} in the macOS Keychain; on a non-Keychain host export $${profile.tokenEnv} directly); ${HUMAN_PAT_NOTE}`;
+}
+
 export async function runWait(argv) {
   const opts = parseArgv(argv);
   const emitReceipt = (receipt, options = {}) => emit(receipt, {
@@ -671,7 +718,8 @@ export async function runWait(argv) {
   const { conditions, errors } = parseConditions(opts.conditions);
   if (errors.length > 0) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors });
+    process.stderr.write(`bb-wait: ${RECOVERY.conditions}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors, recovery: RECOVERY.conditions });
     process.exit(EXIT.INVALID);
   }
 
@@ -696,13 +744,13 @@ export async function runWait(argv) {
   // is a contradiction and is rejected.
   if (needsRelay && opts.sessionToken) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
-      process.stderr.write("botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>\n");
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token" });
+      process.stderr.write(`botbuddy wait: $BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>; ${RECOVERY.sessionToken}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
-      process.stderr.write("botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; pass only one\n");
-      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict" });
+      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_SESSION_TOKEN; ${RECOVERY.sessionTokenConflict}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
       process.exit(EXIT.INVALID);
     }
     opts.useSessionToken = true;
@@ -714,19 +762,19 @@ export async function runWait(argv) {
     // timer-only wait needs no relay and no session id (handled by !needsRelay).
     if (!opts.sessionId) {
       process.stderr.write(
-        "botbuddy wait: --session-id is required (or set $BOTBUDDY_SESSION_ID) — the work-graph session id returned by register_agent\n",
+        `botbuddy wait: --session-id is required (or set $BOTBUDDY_SESSION_ID) — the work-graph session id returned by register_agent; ${RECOVERY.sessionId}\n`,
       );
       emitReceipt({
         schema_version: 1,
         outcome: "error",
         error: "session_id_required",
-        recovery: "register_agent → export BOTBUDDY_SESSION_ID=<session_id>",
+        recovery: RECOVERY.sessionId,
       });
       process.exit(EXIT.INVALID);
     }
     if (!SESSION_UUID.test(opts.sessionId)) {
-      process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}')\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid" });
+      process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}'); ${RECOVERY.sessionId}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid", recovery: RECOVERY.sessionId });
       process.exit(EXIT.INVALID);
     }
     try {
@@ -735,14 +783,16 @@ export async function runWait(argv) {
         explicitToken: opts.token,
       });
     } catch (err) {
-      process.stderr.write(`bb-wait: ${err.message}\n`);
-      emitReceipt({ schema_version: 1, outcome: "error", error: err.code || "invalid_profile" });
+      const code = err.code || "invalid_profile";
+      const recovery = profileResolutionRecovery(code);
+      process.stderr.write(`bb-wait: ${err.message}; ${recovery}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
       process.exit(EXIT.INVALID);
     }
     opts.token = opts.agentProfile.token;
     if (!opts.token) {
       process.stderr.write(
-        `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run '${profileRecovery(opts.agentProfile)}'\n`,
+        `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run ${profileCredentialRecovery(opts.agentProfile)}\n`,
       );
       emitReceipt(profileErrorReceipt(opts.agentProfile, "profile_required"));
       process.exit(EXIT.AUTH);
@@ -897,7 +947,7 @@ export async function runWait(argv) {
           process.exit(EXIT.AUTH);
         }
         const error = typedProfileError(err.errorCode);
-        process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run '${profileRecovery(opts.agentProfile)}'\n`);
+        process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run ${profileCredentialRecovery(opts.agentProfile)}\n`);
         emitReceipt(profileErrorReceipt(opts.agentProfile, error));
         process.exit(EXIT.AUTH);
       }