@botbuddy/cli 1.40.3 → 1.40.5

package/package.json

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

package/src/agent-credential-store.mjs

@@ -2,6 +2,7 @@ import { userInfo } from "node:os";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { existsSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 
 const execFileAsync = promisify(execFile);
 
@@ -41,6 +42,28 @@ export class ProfileCredentialStoreError extends Error {
   }
 }
 
+export const KEYCHAIN_UNLOCK_GUIDANCE = "the macOS login Keychain is locked in this SSH session — run `security unlock-keychain ~/Library/Keychains/login.keychain-db` on this host, then re-run. Alternatively set `BOTBUDDY_NO_KEYCHAIN=1` to use the explicit 0600-file store.";
+
+// `security` reports this locked-SSH-session condition inconsistently: some
+// paths say authorization was canceled, while the failed write in BOT-2078 was
+// exit 36 / "User interaction is not allowed". Keep one classifier so every
+// Keychain reader and writer gives the same recovery rather than suggesting an
+// unnecessary new login.
+export function isLockedKeychainError(error) {
+  const detail = String(error?.stderr ?? error?.message ?? error ?? "");
+  return Number(error?.code) === 36
+    || /(?:security\s+)?exited\s+36\b/i.test(detail)
+    || /user interaction is not allowed/i.test(detail)
+    || /authorization was cancell?ed/i.test(detail);
+}
+
+function unavailableKeychainError(cause) {
+  return new ProfileCredentialStoreError(KEYCHAIN_UNLOCK_GUIDANCE, {
+    cause,
+    code: "client_key_unavailable",
+  });
+}
+
 function writePasswordPrompt(command, args, password, spawnProcess) {
   return new Promise((resolve, reject) => {
     // BOT-1566: `security -w` (prompt mode) reads the secret with
@@ -134,14 +157,7 @@ export async function writeKeychainSecret(service, token, {
         { cause: error, code: "keychain_item_exists" },
       );
     }
-    // `security` cancels its authorization when the login keychain is locked in
-    // a headless session; guide the user to unlock it rather than re-login.
-    if (/authorization was cancell?ed/i.test(detail)) {
-      throw new ProfileCredentialStoreError(
-        "macOS Keychain authorization was canceled — unlock your login keychain (`security unlock-keychain`) and retry; a headless session needs it already unlocked",
-        { cause: error },
-      );
-    }
+    if (isLockedKeychainError(error)) throw unavailableKeychainError(error);
     throw new ProfileCredentialStoreError(`could not write the credential to the macOS Keychain: ${detail}`, { cause: error });
   }
   const stored = await readSecret(service);
@@ -183,6 +199,12 @@ export async function readKeychainSecret(service, { execFileImpl = execFileAsync
     const { stdout } = await execFileImpl("security", args);
     return stdout.trim() || null;
   } catch (error) {
+    // Non-strict readers participate in durable-credential resolution, where a
+    // valid MCP key may still be available from the worktree environment. Keep
+    // their historical null result for a locked Keychain so that fallback stays
+    // reachable. Strict readers (login/migration paths) must surface unlock
+    // guidance instead of treating the inaccessible slot as empty.
+    if (strict && isLockedKeychainError(error)) throw unavailableKeychainError(error);
     // Non-strict (default, back-compat): any failure reads as "no value". Strict:
     // only a genuine not-found is null; a real read failure is re-thrown so the
     // caller can fail closed instead of mistaking it for an empty slot.
@@ -191,6 +213,29 @@ export async function readKeychainSecret(service, { execFileImpl = execFileAsync
   }
 }
 
+// Test the actual store before an OAuth flow creates a one-time authorization
+// grant. A fresh random service avoids touching any durable credential. The
+// cleanup attempt lives in finally so a successful probe never leaves a scratch
+// item behind, even if removal itself is denied.
+export async function preflightKeychainWrite({
+  platform = process.platform,
+  exists = existsSync,
+  env = process.env,
+  random = randomUUID,
+  writeSecret = writeKeychainSecret,
+  deleteSecret = deleteKeychainSecret,
+} = {}) {
+  if (!keychainAvailable(platform, exists, env)) return false;
+  const service = `BOTBUDDY_LOGIN_PREFLIGHT_${random()}`;
+  const probe = random();
+  try {
+    await writeSecret(service, probe);
+    return true;
+  } finally {
+    await deleteSecret(service).catch(() => false);
+  }
+}
+
 export async function deleteKeychainSecret(service, { execFileImpl = execFileAsync, keychain = null } = {}) {
   if (!service) return false;
   const args = ["delete-generic-password", "-s", service, "-a", userInfo().username];

package/src/agent-doctor.mjs

@@ -67,7 +67,7 @@ function prerequisiteRecovery(report) {
  * credential-store failure must point at unlocking the store — not `bb login` or a
  * binding repair — matching prerequisiteRecovery's wording.
  */
-function repairFailureRecovery(code, error = null) {
+export function repairFailureRecovery(code, error = null) {
   // BOT-1891: a tier-2 MCP key the server rejected (revoked/rotated) is replaced by
   // minting a new one and re-delivering it — not by `bb login`, which a Background
   // job cannot run anyway. Name the variable, never the value.
@@ -102,6 +102,19 @@ function applyStackLeaseCapability(report, capability) {
   }
 }
 
+/**
+ * Read the client key STRICTLY: a locked/failing credential store throws instead
+ * of reading as absent, so callers can tell "unlock it" from "sign in". Shared by
+ * `bb doctor` and `bb setup` (BOT-2067) so both classify the key identically.
+ */
+export function readClientKeyStrict() {
+  return resolveOwnerToken({
+    getConfig,
+    keychainRead: () => readKeychainSecret(CLIENT_KEY_SERVICE, { strict: true }),
+    keychainReadLegacy: () => readKeychainSecret(OWNER_TOKEN_SERVICE, { strict: true }),
+  });
+}
+
 /** Inspect a worktree credential. Only `exports` ever contains the secret. */
 export async function doctorAgentAuth({
   cwd = process.cwd(), env = process.env, fix = false, printExports = false,
@@ -111,11 +124,7 @@ export async function doctorAgentAuth({
   // probe distinguishes a locked/failing credential store (throws → `unavailable`)
   // from a genuinely absent key (`missing`) — the strict read must not live only
   // inside selfHeal, which the `--fix` gate skips when it reports the key missing.
-  ownerToken = () => resolveOwnerToken({
-    getConfig,
-    keychainRead: () => readKeychainSecret(CLIENT_KEY_SERVICE, { strict: true }),
-    keychainReadLegacy: () => readKeychainSecret(OWNER_TOKEN_SERVICE, { strict: true }),
-  }),
+  ownerToken = readClientKeyStrict,
   selfHeal = selfHealAgentSession,
   hostFn = hostname, machineUuidFn = machineUuid,
 } = {}) {

package/src/auth.mjs

@@ -17,6 +17,7 @@ import {
   pollDeviceToken,
 } from "./oauth-device.mjs";
 import { hostname as osHostname } from "node:os";
+import { preflightKeychainWrite } from "./agent-credential-store.mjs";
 
 // A login that could not complete. commands.mjs turns this into one terminal
 // error line; the core never calls process.exit so it stays unit-testable.
@@ -134,7 +135,17 @@ export async function doLogin(options = {}, deps = {}) {
     now = () => Date.now(),
     persist = persistOwnerToken,
     createReceiver = createLoopbackReceiver,
+    preflightKeychain = preflightKeychainWrite,
   } = deps;
+  // BOT-2078: minting a device grant before discovering that macOS cannot
+  // retain it wastes a human's one-time approval. Probe the active Keychain
+  // first; on Linux and explicit BOTBUDDY_NO_KEYCHAIN fallback this is a no-op.
+  try {
+    await preflightKeychain();
+  } catch (error) {
+    if (error?.code === "client_key_unavailable") throw new LoginError(error.message);
+    throw error;
+  }
   if (options.device === true) {
     return doDeviceLogin(options, { ...deps, serverUrl, fetchImpl, saveConfig, getConfig, log, errorLog, now, persist });
   }

package/src/commands.mjs

@@ -27,7 +27,7 @@ import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
-import { doctorAgentAuth, doctorHelp, parseDoctorArgs } from "./agent-doctor.mjs";
+import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
 import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
 import { runUsage, usageStatus } from "./usage/sync.mjs";
 import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
@@ -446,7 +446,10 @@ export function deriveCallerHint({ env = process.env, cwd = process.cwd(), git =
   return {
     caller: env.BOTBUDDY_AGENT_NAME || (cachedAgentId ? `agent ${cachedAgentId}` : repo),
     callerHarness: harness,
-    callerTicket: ticket ? `https://linear.app/botbuddy/issue/${ticket}` : null,
+    // BOT-2067: only a BOT ticket lives in the botbuddy Linear workspace. Any
+    // other prefix (ENT on a Supply Guard branch) is sent as plain text — the
+    // consent screen shows it unlinked rather than linking the wrong workspace.
+    callerTicket: ticket ? (ticket.startsWith("BOT-") ? `https://linear.app/botbuddy/issue/${ticket}` : ticket) : null,
   };
 }
 
@@ -495,9 +498,33 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
   }
 }
 
+// BOT-2067: setup's failure line names the recovery for THIS code. A server-side
+// mint failure is repaired by `bb doctor --fix` without a new sign-in (BOT-1789);
+// a rejected key needs a sign-in; store/binding failures keep the classifier
+// `bb doctor` uses. The error message itself is never printed (it may echo a
+// credential); only the code is.
+function setupFailureRecovery(error) {
+  const code = error?.code ?? "setup_failed";
+  if (code === "session_mint_failed" || code === "session_mint_invalid") {
+    return "the BotBuddy service could not mint a session (transient/server error); run `bb doctor --fix`, which repairs this worktree's session without signing in again";
+  }
+  if ((code === "session_mint_unauthorized" && error?.mintedWith !== "mcp_key") || code === "client_key_required") {
+    return "the server rejected this machine's sign-in; run `bb login`, then `bb setup`";
+  }
+  if (code === "tenant_binding_required" || code === "invalid_binding") {
+    return "fix the committed .botbuddy-agent.json binding, then retry `bb setup`";
+  }
+  if (code === "client_key_unavailable" || code === "session_mint_unauthorized") return repairFailureRecovery(code, error);
+  return "retry `bb setup`";
+}
+
+const SIGN_IN_REJECTED = new Set(["session_mint_unauthorized", "client_key_required"]);
+
 /** Bootstrap a bound worktree without exposing credential or registration steps. */
 export async function cmdSetup(args, {
   login = doLogin,
+  ownerToken = readClientKeyStrict,
+  now = () => Date.now(),
   binding = readAgentBinding,
   clearState = clearAgentState,
   selfHeal = selfHealAgentSession,
@@ -509,16 +536,19 @@ export async function cmdSetup(args, {
   log = (line) => console.log(line),
   errorLog = (line) => console.error(line),
 } = {}) {
+  // BOT-2067: `--relogin` is setup-only (forces a fresh sign-in); `bb login`
+  // always signs in, so its parser does not accept it.
+  const relogin = args.includes("--relogin");
   let options;
   try {
-    options = parseLoginArgs(args);
+    options = parseLoginArgs(args.filter((arg) => arg !== "--relogin"));
   } catch (error) {
     if (!(error instanceof LoginUsageError)) throw error;
     errorLog(error.message);
     return error.exitCode === 2 ? 2 : 4;
   }
   if (options.help) {
-    log("bb setup [--no-browser] [--tenant <slug>] [--device | --loopback]\n\nSigns in, verifies the committed .botbuddy-agent.json binding, and caches this worktree's session. Over SSH the sign-in uses a device code you approve from any browser (--device / --loopback force a mode). --loopback or --no-browser over SSH keeps the localhost callback on the remote host, so first forward its port with ssh -L <port>:127.0.0.1:<port> <host> (the port is in the printed URL), or setup times out. After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
+    log("bb setup [--relogin] [--no-browser] [--tenant <slug>] [--device | --loopback]\n\nVerifies the committed .botbuddy-agent.json binding and caches this worktree's session. It reuses this machine's existing sign-in (one per machine, valid 30 days) and signs in only when there is none, it expired, or the server rejects it; --relogin forces a fresh sign-in. Over SSH the sign-in uses a device code you approve from any browser (--device / --loopback force a mode). --loopback or --no-browser over SSH keeps the localhost callback on the remote host, so first forward its port with ssh -L <port>:127.0.0.1:<port> <host> (the port is in the printed URL), or setup times out. After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
     return 0;
   }
   let bound;
@@ -537,20 +567,55 @@ export async function cmdSetup(args, {
     return 4;
   }
   const tenant = bound.tenant;
+  // Login owns a machine/user credential, not a worktree tenant credential.
+  // The committed binding below is the only place setup scopes the minted
+  // session.  Forwarding --tenant here would overwrite a multi-tenant user's
+  // reusable client key with a tenant-sealed one.
+  const signIn = () => login({
+    noBrowser: options.noBrowser,
+    device: resolveLoginDevice(options, { env, platform }),
+    ...callerResolver(options, env),
+  });
   try {
-    // Login owns a machine/user credential, not a worktree tenant credential.
-    // The committed binding below is the only place setup scopes the minted
-    // session.  Forwarding --tenant here would overwrite a multi-tenant user's
-    // reusable client key with a tenant-sealed one.
-    await login({
-      noBrowser: options.noBrowser,
-      device: resolveLoginDevice(options, { env, platform }),
-      ...callerResolver(options, env),
-    });
+    // BOT-2067: the client key is per machine and lasts 30 days. Reuse it rather
+    // than putting an OAuth approval in front of the operator for every worktree.
+    let signedIn = false;
+    if (relogin) {
+      await signIn();
+      signedIn = true;
+    } else {
+      let owner;
+      try {
+        owner = await ownerToken();
+      } catch {
+        // A locked/failing store is not "signed out": signing in again would not
+        // help and would open a browser for nothing.
+        throw Object.assign(new Error("client key unreadable"), { code: "client_key_unavailable" });
+      }
+      const valid = owner?.token && !(typeof owner.expiresAt === "number" && owner.expiresAt <= now());
+      if (valid) {
+        const expires = typeof owner.expiresAt === "number" ? ` (expires ${new Date(owner.expiresAt).toISOString().slice(0, 10)})` : "";
+        log(`bb setup: using this machine's existing sign-in${expires}.`);
+      } else {
+        await signIn();
+        signedIn = true;
+      }
+    }
     // Setup is an explicit session bootstrap/repair command. Rotate before
     // resolving so it cannot merely report an old cache as ready.
     await clearState(cwd);
-    const session = await selfHeal({ cwd, env });
+    let session;
+    try {
+      session = await selfHeal({ cwd, env });
+    } catch (error) {
+      // A locally-valid key the server rejects (revoked, rotated) needs exactly
+      // one fresh sign-in and one retried mint. Never loop, and never re-sign a
+      // key this run just minted.
+      if (signedIn || !SIGN_IN_REJECTED.has(error?.code) || error?.mintedWith === "mcp_key") throw error;
+      errorLog(`bb setup: this machine's saved sign-in was rejected (${error.code}); signing in again.`);
+      await signIn();
+      session = await selfHeal({ cwd, env });
+    }
     // BOT-2058: register_agent reports any OTHER live session already holding
     // this ticket (heartbeat < 15m) in `ticket_signals`. This is advisory: a
     // previous harness can remain visible while a human intentionally resumes
@@ -569,7 +634,7 @@ export async function cmdSetup(args, {
     await reportUsageAgent(usageAgent, { cwd, log });
     return 0;
   } catch (error) {
-    errorLog(`bb setup: could not prepare this worktree (${error?.code ?? "setup_failed"}). Retry bb setup after completing sign-in.`);
+    errorLog(`bb setup: could not prepare this worktree (${error?.code ?? "setup_failed"}); ${setupFailureRecovery(error)}.`);
     return 3;
   }
 }