@botbuddy/cli 1.19.0 → 1.19.2

package/package.json

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

package/src/stack.mjs

@@ -665,6 +665,7 @@ export async function cmdUp(opts, {
   callTool = callToolJson,
   authProvider = stackAuthHeader,
   localProvisionFn = localProvision,
+  waitFn = waitForLease,
   emitResult = emit,
 } = {}) {
   let slot;
@@ -720,7 +721,7 @@ export async function cmdUp(opts, {
       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);
     }
     // Park zero-poll until the lease leaves the queue (granted in BOT-1187 order).
-    const parked = await waitForLease(leaseId, nonQueued, () => false, { timeoutSec: opts.timeout, auth });
+    const parked = await waitFn(leaseId, nonQueued, () => false, { timeoutSec: opts.timeout, auth });
     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);
@@ -762,36 +763,67 @@ export async function cmdUp(opts, {
         connection: connectionWithDockerTarget({}, localDockerTarget),
       });
       if (!reserved.ok || !reserved.data?.success) {
-        const cancelled = await callTool("cancel_unclaimed_stack_lease", { lease_id: leaseId });
-        const leaseCancellation = cancelled.ok && cancelled.data?.success
-          ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
-          : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
-        return emitResult(buildReceipt({
-          command: "up", outcome: "error", lease_id: leaseId, state, slot,
-          error: reserved.data?.code || reserved.error || "could not reserve the provision job for local execution",
-          lease_cancellation: leaseCancellation,
-        }), opts, EXIT.LEASE_FAILED);
-      }
-      let conn;
-      try {
-        conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
-      } catch (e) {
-        // Once the local provisioner has run, `supabase start` may have created
-        // (or fully started) containers even on a nonzero exit or a status-parse
-        // failure. Cancelling here would reap the lease and free the slot while
-        // that stack is still up — the exact orphaned/contended-slot hazard this
-        // change closes. Leave the lease FENCED (provisioning, reserved to us) so
-        // `botbuddy stack done` / the reaper tears the stack down first (BOT-1421
-        // review); do NOT cancel.
-        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
-      }
-      const act = await callTool("activate_stack_lease", { lease_id: leaseId, connection: conn });
-      if (!act.ok || !act.data?.success) {
-        return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
+        // A Helper can win the reservation race by taking the queued provision
+        // job between `request_stack_lease` and `reserve_stack_lease`. That is NOT
+        // a failure — nothing local has started, and the Helper owns (or is about
+        // to activate) a live stack for this same lease. Cancelling here would
+        // abandon that stack until idle reaping. Two shapes signal the takeover,
+        // both from `reserve_stack_lease` which checks lease state before job
+        // status (BOT-1587):
+        //   • PROVISION_JOB_HELPER_CLAIMED — Helper claimed the job, lease still
+        //     `provisioning`: wait for it to reach active.
+        //   • LEASE_NOT_PROVISIONING with state `active` — the Helper both claimed
+        //     AND activated before reserve acquired its locks: already live, so
+        //     skip the wait (the edge-triggered stream would park until timeout on
+        //     an already-active lease) and go straight to the read.
+        // Either way, follow the Helper to the shared authoritative final read
+        // below; only a genuine reserve failure is terminal.
+        const helperClaimed = reserved.data?.code === "PROVISION_JOB_HELPER_CLAIMED";
+        const helperAlreadyActive = reserved.data?.code === "LEASE_NOT_PROVISIONING" && reserved.data?.state === "active";
+        if (helperClaimed || helperAlreadyActive) {
+          if (!helperAlreadyActive) {
+            const active = await waitFn(leaseId, isActive, isReaped, { timeoutSec: opts.timeout, auth });
+            if (active.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `a Helper claimed the provision job but it did not reach active in ${opts.timeout}s` }), opts, EXIT.TIMEOUT);
+            if (active.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
+            if (active.failed) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
+            if (active.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
+          }
+          // Fall through to the authoritative `get_stack_lease` read below — do
+          // NOT run the local provisioner; the Helper owns this stack.
+        } else {
+          const cancelled = await callTool("cancel_unclaimed_stack_lease", { lease_id: leaseId });
+          const leaseCancellation = cancelled.ok && cancelled.data?.success
+            ? { success: true, state: cancelled.data.state, provision_job_cancelled: cancelled.data.provision_job_cancelled === true }
+            : { success: false, error: cancelled.error || cancelled.data?.code || "atomic cancellation failed" };
+          return emitResult(buildReceipt({
+            command: "up", outcome: "error", lease_id: leaseId, state, slot,
+            error: reserved.data?.code || reserved.error || "could not reserve the provision job for local execution",
+            lease_cancellation: leaseCancellation,
+          }), opts, EXIT.LEASE_FAILED);
+        }
+      } else {
+        let conn;
+        try {
+          conn = connectionWithDockerTarget(localProvisionFn(opts, localDockerTarget), localDockerTarget);
+        } catch (e) {
+          // Once the local provisioner has run, `supabase start` may have created
+          // (or fully started) containers even on a nonzero exit or a status-parse
+          // failure. Cancelling here would reap the lease and free the slot while
+          // that stack is still up — the exact orphaned/contended-slot hazard this
+          // change closes. Leave the lease FENCED (provisioning, reserved to us) so
+          // `botbuddy stack done` / the reaper tears the stack down first (BOT-1421
+          // review); do NOT cancel.
+          return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: e.message }), opts, EXIT.LEASE_FAILED);
+        }
+        const act = await callTool("activate_stack_lease", { lease_id: leaseId, connection: conn });
+        if (!act.ok || !act.data?.success) {
+          return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: act.error || act.data?.code || "activate failed" }), opts, EXIT.BACKEND);
+        }
       }
     } else {
-      const active = await waitForLease(leaseId, isActive, isReaped, { timeoutSec: opts.timeout, auth });
+      const active = await waitFn(leaseId, isActive, isReaped, { timeoutSec: opts.timeout, auth });
       if (active.timeout) return emitResult(buildReceipt({ command: "up", outcome: "timeout", lease_id: leaseId, state, slot, error: `provisioning did not reach active in ${opts.timeout}s (Helper may be down — retry with --local-exec)` }), opts, EXIT.TIMEOUT);
+      if (active.auth) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: "unauthorized on wait stream" }), opts, EXIT.AUTH);
       if (active.failed) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, state: active.state, error: "lease was reaped before it became active" }), opts, EXIT.LEASE_FAILED);
       if (active.error) return emitResult(buildReceipt({ command: "up", outcome: "error", lease_id: leaseId, error: active.error }), opts, EXIT.BACKEND);
     }

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;
 }

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";
@@ -643,10 +643,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 +713,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 +739,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 +757,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 +778,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 +942,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);
       }