@botbuddy/cli 1.19.2 → 1.21.0

package/package.json

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

package/src/agent-key.mjs

@@ -0,0 +1,29 @@
+// BOT-1582 — the per-session agent key the CLI presents to the relay for
+// `botbuddy wait`/`run`/`test`/`pw`.
+//
+// register_agent mints this token (bound to the work-graph session it returns)
+// and the relay derives agent, tenant, and the arming session from it, so a
+// session that exports it needs no --profile/--session-id/--token.
+//
+// Prefix: `bb_agent_` + 64 lowercase hex, mirroring the server's SESSION_TOKEN_RE
+// (supabase/functions/_shared/sessionToken.ts). The BOT-1572 `bb_sess_` shape is
+// accepted as a legacy alias for one release (its hash is already on `sessions`).
+// This is a SHAPE check only — authorization is the server's hashed lookup.
+export const AGENT_KEY_RE = /^bb_(agent|sess)_[0-9a-f]{64}$/;
+
+// BOT-1582: the env var was renamed BOTBUDDY_SESSION_TOKEN → BOTBUDDY_AGENT_KEY.
+// The new name wins; the old one is honoured for one release so a session that
+// still exports it keeps working. Returns null when neither is set.
+//
+// An EMPTY/blank value counts as unset (not as a present-but-empty token): an env
+// template that declares BOTBUDDY_AGENT_KEY="" while a valid BOTBUDDY_SESSION_TOKEN
+// is still exported must fall through to the legacy name, or the one-release
+// compatibility guarantee breaks (Codex P2). So trim and skip blanks rather than
+// `??`, which would stop at the empty string.
+export function readAgentKeyEnv(env = process.env) {
+  const first = typeof env.BOTBUDDY_AGENT_KEY === "string" ? env.BOTBUDDY_AGENT_KEY.trim() : "";
+  if (first) return env.BOTBUDDY_AGENT_KEY;
+  const legacy = typeof env.BOTBUDDY_SESSION_TOKEN === "string" ? env.BOTBUDDY_SESSION_TOKEN.trim() : "";
+  if (legacy) return env.BOTBUDDY_SESSION_TOKEN;
+  return null;
+}

package/src/credential-kinds.mjs

@@ -17,11 +17,15 @@ export const CREDENTIAL_PREFIXES = [
   { prefix: "mcp_at_", kind: "oauth", label: "OAuth owner token" },
   { prefix: "bb_pat_", kind: "pat", label: "personal access token" },
   { prefix: "bb_cli_", kind: "cli", label: "client key" },
-  // BOT-1573/1582 transition: TODAY every live bb_agent_ secret is an older
-  // shared service carrier (this PR keeps them authenticating), and the actual
-  // per-session agent token is bb_sess_ (BOT-1572). So bb_agent_ classifies as
-  // the carrier — matching the UI adapter — NOT as an agent. Once BOT-1582 makes
-  // register_agent MINT bb_agent_, this flips to the agent kind.
+  // BOT-1573/1582 transition: bb_agent_ is now BOTH the per-session agent token
+  // (BOT-1582 renamed it from bb_sess_) AND the older shared service carrier, so
+  // the prefix ALONE can no longer tell them apart. Classification is display
+  // only (never auth), and mislabelling a live carrier as an agent is worse than
+  // the reverse, so bb_agent_ stays classified as the carrier — matching the UI
+  // adapter. bb_sess_ (in-flight BOT-1572 tokens, accepted one release) is the
+  // one unambiguously-a-session shape, so it keeps the agent kind. A
+  // shape-independent way to name a live bb_agent_ session token is deferred to
+  // the taxonomy/status work (BOT-1573).
   { prefix: "bb_agent_", kind: "svc", label: "carrier (legacy)" },
   { prefix: "bb_sess_", kind: "agent", label: "agent (session)" },
   { prefix: "bb_ci_", kind: "ci", label: "CI key" },

package/src/pw/coordinator.mjs

@@ -15,7 +15,7 @@ function laneCoordinator(kind, call, agentId) {
   return { kind, async status({ host, slot }) { const result = await call("list_resources", { host, subtype: "playwright_lane" }); const list = Array.isArray(result) ? result : result.resources ?? []; const resource = list.find((item) => item.name === `playwright_lane:${host}:${slot}` || String(item.slot) === String(slot)); /* BOT-1490: canonical_host is a TOP-LEVEL field the server echoes even on an empty page (not-held lane); owner_is_caller is per-row. Older servers send neither → null. */ const canonicalHost = (result && !Array.isArray(result) ? result.canonical_host : null) ?? null; return resource ? { held: resource.status !== "free", heldBy: resource.owner_agent_id ?? null, heldByName: resource.agents?.name ?? null, host: resource.host ?? null, name: resource.name ?? null, slot: resource.slot ?? null, canonicalHost, ownerIsCaller: resource.owner_is_caller ?? null } : { held: false, heldBy: null, heldByName: null, host: null, name: null, slot: null, canonicalHost, ownerIsCaller: null }; }, async emit(event) { await call("record_lane_event", event); }, agentId };
 }
 
-// BOT-1572: authenticate lock verification with a per-session `bb_sess_` token —
+// BOT-1572/1582: authenticate lock verification with a per-session `bb_agent_` token —
 // the server resolves it to the session agent (mcp-server authenticateAgent), so
 // `list_resources`/`record_lane_event` run AS the session, and holder matching
 // rides on the server's `owner_is_caller`. No machine profile is required.

package/src/pw/run.mjs

@@ -8,6 +8,7 @@ import { resolveAgentProfile } from "../wait-profile.mjs";
 import { readProfileIdentity } from "../agent-credential-store.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
 import { VERSION } from "../version.mjs";
+import { readAgentKeyEnv } from "../agent-key.mjs";
 // BOT-1488: canonicalize the raw hostname the SAME way acquire_resources does
 // server-side, so the lane name bb-pw builds/matches/prints is the one the lock
 // kernel actually stored ("jonos-mbp:8", not "Jonos-MBP.localdomain:8").
@@ -23,18 +24,19 @@ function redact(value, secretValues = []) { return secretValues.reduce((text, se
 async function readRegisteredAgentId() { try { await loadConfig(); const id = getConfig()?.agent_id; return typeof id === "string" && id ? id : null; } catch { return null; } }
 async function gate({ env, host, lane, deps }) {
   if (env.BB_PW_NO_LOCK === "1") return { allowed: true };
-  // BOT-1572: a per-session `bb_sess_` token authenticates lock verification AS
-  // the session agent — no machine profile needed. It takes precedence over the
+  // BOT-1572/1582: a per-session `bb_agent_` token authenticates lock verification
+  // AS the session agent — no machine profile needed. It takes precedence over the
   // profile path; holder matching then rides on the server's owner_is_caller
   // (plus any local session/registered agent id). The profile path stays intact
-  // for a session that has not adopted the token.
-  const sessionToken = deps.sessionToken ?? env.BOTBUDDY_SESSION_TOKEN ?? null;
+  // for a session that has not adopted the token. $BOTBUDDY_AGENT_KEY is the norm
+  // ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+  const sessionToken = deps.sessionToken ?? readAgentKeyEnv(env);
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
   const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
   let coordinator, selfAgentIds, callerId;
   if (sessionToken) {
     coordinator = deps.coordinator ?? createSessionTokenCoordinator({ token: sessionToken, fetchImpl: deps.fetch });
-    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_SESSION_TOKEN is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
+    if (coordinator.kind === "unverified") return { allowed: false, message: "bb-pw: $BOTBUDDY_AGENT_KEY is malformed. Re-register the agent, or set BB_PW_NO_LOCK=1 for local-only work." };
     selfAgentIds = new Set([sessionAgentId, registeredAgentId, coordinator.agentId].filter(Boolean));
     callerId = coordinator.agentId ?? sessionAgentId ?? "session-token";
   } else {
@@ -99,7 +101,7 @@ export async function runPw(argv, deps = {}) {
 async function runPwInner(argv, deps = {}) {
   const env = deps.env ?? process.env, stdout = deps.stdout ?? process.stdout, stderr = deps.stderr ?? process.stderr; let args = [...argv]; if (["--help", "-h"].includes(args[0])) { help(stdout); return 0; }
   if (["--version", "-v"].includes(args[0])) { stdout.write(`${versionLine()}\n`); return 0; }
-  // BOT-1572 (AC-8): --session-token / $BOTBUDDY_SESSION_TOKEN is accepted as a
+  // BOT-1572/1582 (AC-8): --session-token / $BOTBUDDY_AGENT_KEY is accepted as a
   // session identity alongside --session-id, so a token-armed session need not
   // pass an id. Holder matching still rides on the server's owner_is_caller and
   // the resolved agent ids (gate()).

package/src/run.mjs

@@ -14,6 +14,7 @@ import { spawn } from "child_process";
 import { fileURLToPath } from "url";
 import { callToolJson } from "./api.mjs";
 import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
+import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
@@ -24,14 +25,16 @@ const MAX_CAPTURE_BYTES = 8_192;
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
 
-// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
-const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
+// BOT-1582: the server's session-token shape (bb_agent_ + 64 hex) plus the
+// BOT-1572 bb_sess_ legacy alias, both accepted for one release.
+const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
 export function parseRunArgs(argv, env = process.env) {
-  // BOT-1572 (AC-8): $BOTBUDDY_SESSION_TOKEN authenticates the run and carries its
-  // session, so --session-id becomes optional (the relay derives it). $BOTBUDDY_SESSION_ID
+  // BOT-1572/1582 (AC-8): $BOTBUDDY_AGENT_KEY authenticates the run and carries its
+  // session, so --session-id becomes optional (the relay derives it). The old
+  // $BOTBUDDY_SESSION_TOKEN is still accepted for one release. $BOTBUDDY_SESSION_ID
   // is the default when a plain id is used (parity with `botbuddy test`).
-  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: env.BOTBUDDY_SESSION_TOKEN ?? null, environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
+  const opts = { sessionId: env.BOTBUDDY_SESSION_ID ?? null, sessionToken: readAgentKeyEnv(env), environment: null, category: "validation", kind: "other", expectedDuration: 0, timeout: DEFAULT_TIMEOUT_SECONDS, rerunReason: null, json: false };
   const errors = [];
   const separator = argv.indexOf("--");
   const flags = separator === -1 ? argv : argv.slice(0, separator);
@@ -66,8 +69,8 @@ export function parseRunArgs(argv, env = process.env) {
   // BOT-1572: a session token stands in for --session-id (the backend derives the
   // session from the token). A malformed token, or a plain id AND a differing
   // token, is a hard error.
-  if (opts.sessionToken && !SESSION_TOKEN_RE.test(opts.sessionToken)) errors.push("$BOTBUDDY_SESSION_TOKEN must match bb_sess_<64 hex>");
-  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_SESSION_TOKEN");
+  if (opts.sessionToken && !SESSION_TOKEN_RE.test(opts.sessionToken)) errors.push("$BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>");
+  if (!opts.sessionId && !opts.sessionToken) errors.push("--session-id is required (from register_agent), or set $BOTBUDDY_AGENT_KEY");
   if (!opts.environment || !["local", "preview", "staging", "production", "none"].includes(opts.environment)) errors.push("--environment must be local, preview, staging, production, or none");
   if (!command.length) errors.push("a workload is required after --");
   if (!Number.isInteger(opts.expectedDuration) || opts.expectedDuration < 0) errors.push("--expected-duration must be a non-negative integer");

package/src/test-lane.mjs

@@ -21,6 +21,7 @@ import { execFileSync } from "node:child_process";
 
 import { EXIT, launchRun, receiptPath, DEFAULT_TIMEOUT_SECONDS } from "./run.mjs";
 import { callToolJson } from "./api.mjs";
+import { readAgentKeyEnv } from "./agent-key.mjs";
 
 // EXIT.{OK,INVALID,BACKEND,INTERNAL} plus a --wait timeout code (AC-9).
 export const EXIT_TEST = Object.freeze({ ...EXIT, TIMEOUT: 2 });
@@ -36,9 +37,10 @@ const LANE_KIND_SET = new Set(LANE_KINDS);
 export function parseTestArgs(argv, { env = process.env } = {}) {
   const opts = {
     sessionId: env.BOTBUDDY_SESSION_ID ?? null,
-    // BOT-1572 (AC-8): a session token stands in for --session-id; it flows to the
-    // sub-invoked `run`/`wait` which derive the session from it.
-    sessionToken: env.BOTBUDDY_SESSION_TOKEN ?? null,
+    // BOT-1572/1582 (AC-8): a session token stands in for --session-id; it flows to
+    // the sub-invoked `run`/`wait` which derive the session from it. $BOTBUDDY_AGENT_KEY
+    // is the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release).
+    sessionToken: readAgentKeyEnv(env),
     environment: "local",
     ticket: null, pr: null, repo: null,
     laneKind: null,
@@ -136,8 +138,8 @@ export function defaultGitInfo({ cwd = process.cwd(), ticket = null, pr = null,
 // The production lane launcher: run the lane through the durable `botbuddy run`
 // worker, carrying the telemetry env into its detached child.
 async function defaultLaunchLane({ command, sessionId, sessionToken, environment, expectedDurationSeconds, childEnv, testRun, cwd, call }) {
-  // BOT-1572: pass --session-id only when a plain id is used; a token-only lane
-  // relies on the inherited $BOTBUDDY_SESSION_TOKEN (and an explicit --session-token
+  // BOT-1572/1582: pass --session-id only when a plain id is used; a token-only lane
+  // relies on the inherited $BOTBUDDY_AGENT_KEY (and an explicit --session-token
   // so the child never falls back to a machine credential).
   const argv = [
     ...(sessionId ? ["--session-id", sessionId] : []),
@@ -150,7 +152,7 @@ async function defaultLaunchLane({ command, sessionId, sessionToken, environment
 }
 
 function waitCommand(testRunId, sessionId, sessionToken) {
-  // BOT-1572: a token-armed session runs the wait with only $BOTBUDDY_SESSION_TOKEN.
+  // BOT-1572/1582: a token-armed session runs the wait with only $BOTBUDDY_AGENT_KEY.
   const idFlag = sessionId && !sessionToken ? ` --session-id ${sessionId}` : "";
   return `botbuddy wait 'test-run:id=${testRunId}'${idFlag} --heartbeat`;
 }
@@ -169,7 +171,7 @@ export async function launchTestLane(argv, {
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors }) };
   }
   if (!opts.sessionId && !opts.sessionToken) {
-    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID or $BOTBUDDY_SESSION_TOKEN)\n");
+    process.stderr.write("botbuddy test: --session-id is required (or set $BOTBUDDY_SESSION_ID or $BOTBUDDY_AGENT_KEY)\n");
     return { exitCode: EXIT_TEST.INVALID, line: JSON.stringify({ outcome: "rejected", errors: ["--session-id is required"] }) };
   }
 

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

@@ -18,13 +18,14 @@ import { resolveAgentProfile, withPrincipalReceipt, PROFILE_FILE } from "./wait-
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
+import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
 // implementation gets a typed, safe upgrade instruction.
 // BOT-1554: protocol 2 makes --session-id mandatory for every non-timer wait (the
 // server keeps MINIMUM_WAIT_PROTOCOL=1 so pre-2 installs are not 426'd).
-// BOT-1572: protocol 3 — a $BOTBUDDY_SESSION_TOKEN (bb_sess_) authenticates the
+// BOT-1572/1582: protocol 3 — a $BOTBUDDY_AGENT_KEY (bb_agent_) authenticates the
 // wait on its own; no profile / --session-id / --token needed (the relay derives
 // agent, tenant, and session from the token). Falls back to protocol-2 behaviour
 // when no session token is present.
@@ -33,8 +34,9 @@ const CLI_UPGRADE_COMMAND = latestPublicCliCommand("wait");
 const MIN_RECEIPT_MAX_BYTES = 512;
 // BOT-1554: identical to the server's session-id shape check.
 const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-// BOT-1572: identical to the server's session-token shape check (bb_sess_ + 64 hex).
-const SESSION_TOKEN_RE = /^bb_sess_[0-9a-f]{64}$/;
+// BOT-1582: the server's session-token shape (bb_agent_ + 64 hex), plus the
+// BOT-1572 bb_sess_ legacy alias, both accepted for one release.
+const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
 const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
@@ -90,6 +92,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);
@@ -159,10 +166,11 @@ function parseArgv(argv) {
     // BOT-1467: attribute this wait to the arming session's agent (the id from
     // register_agent) instead of the tenant-bound profile agent. Env fallback.
     sessionId: process.env.BOTBUDDY_SESSION_ID || null,
-    // BOT-1572: the per-session token. When present it is the ONLY credential —
-    // profile, --session-id, and --token are unnecessary. Env is the norm; the
-    // flag is for tests/overrides.
-    sessionToken: process.env.BOTBUDDY_SESSION_TOKEN || null,
+    // BOT-1572/1582: the per-session token. When present it is the ONLY credential —
+    // profile, --session-id, and --token are unnecessary. $BOTBUDDY_AGENT_KEY is
+    // the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release); the flag
+    // is for tests/overrides.
+    sessionToken: readAgentKeyEnv(process.env),
     help: false,
   };
   for (let i = 0; i < argv.length; i++) {
@@ -654,14 +662,15 @@ function profileErrorReceipt(profile, error) {
 // 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)",
+  // BOT-1582: $BOTBUDDY_AGENT_KEY (bb_agent_+64hex, renamed from
+  // $BOTBUDDY_SESSION_TOKEN) is minted by register_agent; the harness exports it
+  // at session start. The legacy var is still accepted for one release.
+  sessionToken: "register_agent → export BOTBUDDY_AGENT_KEY=<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)",
+  sessionTokenConflict: "unset --token — $BOTBUDDY_AGENT_KEY 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",
 });
@@ -684,7 +693,10 @@ function profileResolutionRecovery(errorCode) {
 // 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";
+// BOT-1582: $BOTBUDDY_AGENT_KEY is now the per-session token var (valid for
+// waits), so it is no longer named here; BOTBUDDY_AGENT_API_KEY remains a human
+// PAT that never authenticates a wait.
+const HUMAN_PAT_NOTE = "human PATs (e.g. 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}`;
 }
@@ -732,19 +744,19 @@ export async function runWait(argv) {
   const deadlineMs = Date.now() + timeoutSec * 1000;
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
-  // BOT-1572: a $BOTBUDDY_SESSION_TOKEN authenticates the wait on its own. When
+  // BOT-1572/1582: a $BOTBUDDY_AGENT_KEY authenticates the wait on its own. When
   // present it supersedes the profile + --session-id path entirely: the relay
   // derives agent, tenant, and session from the token. --profile / --session-id
   // are simply ignored; a conflicting explicit --token (a DIFFERENT credential)
   // 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>; ${RECOVERY.sessionToken}\n`);
+      process.stderr.write(`botbuddy wait: $BOTBUDDY_AGENT_KEY must match bb_agent_<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; ${RECOVERY.sessionTokenConflict}\n`);
+      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_KEY; ${RECOVERY.sessionTokenConflict}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
       process.exit(EXIT.INVALID);
     }
@@ -904,13 +916,13 @@ export async function runWait(argv) {
         ]);
         if (opts.useSessionToken || SESSION_TOKEN_ERRORS.has(err.errorCode)) {
           process.stderr.write(
-            `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_SESSION_TOKEN\n`,
+            `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_AGENT_KEY\n`,
           );
           emitReceipt(withPrincipalReceipt({
             schema_version: 1,
             outcome: "error",
             error: err.errorCode || "unauthorized",
-            recovery: "register_agent → export BOTBUDDY_SESSION_TOKEN=<session_token>",
+            recovery: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token>",
           }, opts.agentProfile, { sessionTenant, agentId: registeredAgentId, sessionId: registeredSessionId }));
           process.exit(EXIT.AUTH);
         }