@botbuddy/cli 1.8.7 → 1.9.0

package/package.json

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

package/src/agent-credential-store.mjs

@@ -12,8 +12,20 @@ const LOCK_MAX_ATTEMPTS = 100;
 const STALE_LOCK_MS = 30_000;
 const execFileAsync = promisify(execFile);
 
+// BOT-1520: is the macOS Keychain backend usable on this host? The CLI stores
+// durable secrets (profile agent keys, and the owner OAuth token) in the
+// Keychain on darwin; elsewhere callers fall back to a documented minimal
+// footprint. Keep this a pure predicate so both the profile store and the
+// owner-token store share one definition of "keychain available".
+export function keychainAvailable(platform = process.platform, exists = existsSync, env = process.env) {
+  // Escape hatch (headless CI where the login keychain can't unlock, or a
+  // deterministic test): force the documented non-Keychain fallback.
+  if (env?.BOTBUDDY_NO_KEYCHAIN === "1") return false;
+  return platform === "darwin" && exists("/usr/bin/security");
+}
+
 export function ensureProfileCredentialBackend({ platform = process.platform, exists = existsSync } = {}) {
-  if (platform !== "darwin" || !exists("/usr/bin/security")) {
+  if (!keychainAvailable(platform, exists)) {
     throw new Error("profile setup requires the macOS Keychain credential backend");
   }
 }
@@ -58,9 +70,12 @@ function writePasswordPrompt(command, args, password, spawnProcess) {
   });
 }
 
-export async function writeKeychain(profile, token, { spawnProcess = spawn } = {}) {
-  const service = keychainService(profile);
-  if (!service) throw new ProfileCredentialStoreError(`unknown profile keychain service for "${profile}"`);
+// BOT-1520: generic Keychain secret primitives keyed by an explicit service
+// name, so both the profile agent-key store and the owner OAuth-token store
+// share the single implementation of the `security -w` double-read prompt and
+// the actionable error mapping — no second copy to drift.
+export async function writeKeychainSecret(service, token, { spawnProcess = spawn } = {}) {
+  if (!service) throw new ProfileCredentialStoreError("keychain write requires a service name");
   try {
     await writePasswordPrompt(
       "security",
@@ -78,21 +93,43 @@ export async function writeKeychain(profile, token, { spawnProcess = spawn } = {
         { cause: error },
       );
     }
-    throw new ProfileCredentialStoreError(`could not write the profile credential to the macOS Keychain: ${detail}`, { cause: error });
+    throw new ProfileCredentialStoreError(`could not write the credential to the macOS Keychain: ${detail}`, { cause: error });
   }
 }
 
-async function readKeychain(profile) {
-  const service = keychainService(profile);
+export async function readKeychainSecret(service, { execFileImpl = execFileAsync } = {}) {
   if (!service) return null;
   try {
-    const { stdout } = await execFileAsync("security", ["find-generic-password", "-s", service, "-a", userInfo().username, "-w"]);
+    const { stdout } = await execFileImpl("security", ["find-generic-password", "-s", service, "-a", userInfo().username, "-w"]);
     return stdout.trim() || null;
   } catch {
     return null;
   }
 }
 
+export async function deleteKeychainSecret(service, { execFileImpl = execFileAsync } = {}) {
+  if (!service) return false;
+  try {
+    await execFileImpl("security", ["delete-generic-password", "-s", service, "-a", userInfo().username]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function writeKeychain(profile, token, { spawnProcess = spawn } = {}) {
+  const service = keychainService(profile);
+  if (!service) throw new ProfileCredentialStoreError(`unknown profile keychain service for "${profile}"`);
+  return writeKeychainSecret(service, token, { spawnProcess });
+}
+
+async function readKeychain(profile) {
+  // Honor the keychain escape hatch (BOTBUDDY_NO_KEYCHAIN / non-darwin) so the
+  // per-profile environment key is the sole credential source there.
+  if (!keychainAvailable()) return null;
+  return readKeychainSecret(keychainService(profile));
+}
+
 function profileCredentialStorePath(home = homedir()) {
   return join(home, ".botbuddy", "agent-profiles.json");
 }

package/src/api.mjs

@@ -1,23 +1,30 @@
 import { getConfig, SERVER_URL } from "./config.mjs";
+import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { die, cyan, dim, yellow, prettyJson } from "./utils.mjs";
 
-function authHeader() {
-  const cfg = getConfig();
-  if (cfg.access_token) {
-    if (cfg.token_expires_at && Date.now() >= cfg.token_expires_at) {
+// BOT-1520: auth headers come from the Keychain, never a plaintext config.json
+// secret. The owner OAuth token (from `botbuddy login`) is preferred; the
+// tenant-bound agent key (from `botbuddy profile setup`) is the fallback.
+async function authHeader() {
+  const owner = await resolveOwnerToken({ getConfig });
+  if (owner) {
+    if (owner.expiresAt && Date.now() >= owner.expiresAt) {
+      const agentKey = await resolveAgentKey();
+      if (agentKey) return { "x-agent-api-key": agentKey };
       die(`Token expired. Run: ${cyan("botbuddy login")} to re-authenticate.`);
     }
-    if (cfg.token_expires_at && cfg.token_expires_at - Date.now() < 5 * 60 * 1000) {
+    if (owner.expiresAt && owner.expiresAt - Date.now() < 5 * 60 * 1000) {
       console.error(`${yellow("⚠")} Token expires in <5 minutes. Run ${cyan("botbuddy login")} soon.`);
     }
-    return { Authorization: `Bearer ${cfg.access_token}` };
+    return { Authorization: `Bearer ${owner.token}` };
   }
-  if (cfg.api_key) return { "x-agent-api-key": cfg.api_key };
+  const agentKey = await resolveAgentKey();
+  if (agentKey) return { "x-agent-api-key": agentKey };
   die(`Not authenticated. Run: ${cyan("botbuddy login")}`);
 }
 
 export async function callTool(toolName, args = {}) {
-  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
   const body = {
     jsonrpc: "2.0",
     id: 1,
@@ -47,15 +54,19 @@ export async function callTool(toolName, args = {}) {
 //   * { ok:false, auth:true }  — not authenticated / token expired
 //   * { ok:false, status }     — HTTP/JSON-RPC/transport error (status may be null)
 export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal } = {}) {
-  const cfg = getConfig();
+  const owner = await resolveOwnerToken({ getConfig });
   let auth;
-  if (cfg.access_token) {
-    if (cfg.token_expires_at && Date.now() >= cfg.token_expires_at) return { ok: false, auth: true, error: "token_expired" };
-    auth = { Authorization: `Bearer ${cfg.access_token}` };
-  } else if (cfg.api_key) {
-    auth = { "x-agent-api-key": cfg.api_key };
+  if (owner && !(owner.expiresAt && Date.now() >= owner.expiresAt)) {
+    auth = { Authorization: `Bearer ${owner.token}` };
   } else {
-    return { ok: false, auth: true, error: "not_authenticated" };
+    const agentKey = await resolveAgentKey();
+    if (agentKey) {
+      auth = { "x-agent-api-key": agentKey };
+    } else if (owner) {
+      return { ok: false, auth: true, error: "token_expired" };
+    } else {
+      return { ok: false, auth: true, error: "not_authenticated" };
+    }
   }
   const body = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: toolName, arguments: args } };
   let res;
@@ -80,7 +91,7 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
 }
 
 export async function listResources() {
-  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/list", params: {} };
   const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();
@@ -88,7 +99,7 @@ export async function listResources() {
 }
 
 export async function readResource(uri) {
-  const headers = { "Content-Type": "application/json", ...authHeader() };
+  const headers = { "Content-Type": "application/json", ...(await authHeader()) };
   const body = { jsonrpc: "2.0", id: 1, method: "resources/read", params: { uri } };
   const res = await fetch(SERVER_URL, { method: "POST", headers, body: JSON.stringify(body) });
   const data = await res.json();

package/src/auth.mjs

@@ -1,4 +1,5 @@
 import { SERVER_URL, saveConfig as realSaveConfig, getConfig as realGetConfig } from "./config.mjs";
+import { persistOwnerToken } from "./cli-credentials.mjs";
 import { green, dim, cyan, yellow, bold, red } from "./utils.mjs";
 import {
   createLoopbackReceiver,
@@ -63,6 +64,7 @@ export async function doLogin(options = {}, deps = {}) {
     errorLog = (s) => console.error(s),
     timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS,
     now = () => Date.now(),
+    persist = persistOwnerToken,
   } = deps;
   const noBrowser = Boolean(options.noBrowser);
 
@@ -154,14 +156,19 @@ export async function doLogin(options = {}, deps = {}) {
       ? now() + tokenData.expires_in * 1000
       : now() + 24 * 60 * 60 * 1000; // default 24h if server omits expires_in
 
-    saveConfig({
-      ...getConfig(),
-      access_token: tokenData.access_token,
-      client_id: clientId,
-      token_expires_at: expiresAt,
-    });
-
-    log(`\n${green("✓")} Logged in successfully! Token saved to ${dim("~/.botbuddy/config.json")}`);
+    // BOT-1520: the durable secret goes to the Keychain (darwin); config.json
+    // keeps only non-secret metadata. On a non-darwin host without a Keychain,
+    // persistOwnerToken falls back to the 0600 config.json and warns.
+    const { storedInKeychain } = await persist(
+      { token: tokenData.access_token, expiresAt, clientId },
+      { getConfig, saveConfig, warn: errorLog },
+    );
+
+    log(
+      `\n${green("✓")} Logged in successfully! Token stored in ${
+        storedInKeychain ? "the macOS Keychain" : dim("~/.botbuddy/config.json")
+      }.`,
+    );
     return { clientId, redirectUri };
   } finally {
     // AC-11/AC-13: always release the socket so re-running login starts clean.

package/src/cli-credentials.mjs

@@ -0,0 +1,135 @@
+// BOT-1520: single source of truth for reading and writing the CLI's durable
+// secrets, so no secret ever lands in plaintext ~/.botbuddy/config.json on a
+// host with a Keychain.
+//
+// There are two secrets the CLI handles:
+//
+//   1. The owner OAuth access token minted by `botbuddy login`. On darwin it is
+//      stored in the login Keychain under a dedicated service; config.json keeps
+//      only its non-secret metadata (client_id, token_expires_at).
+//   2. The tenant-bound agent key minted by `botbuddy profile setup`, already
+//      stored in the profile Keychain store (agent-credential-store.mjs). The
+//      retired `botbuddy register` used to write this as a no-expiry `api_key`
+//      into config.json; it no longer exists.
+//
+// On a non-darwin host (no Keychain today) `login` falls back to a documented
+// minimal footprint: the token stays in the 0600 config.json and a warning is
+// printed. Agent/CI usage on any host works from the profile Keychain or the
+// per-profile environment key, never from a config.json secret.
+
+import {
+  keychainAvailable,
+  writeKeychainSecret,
+  readKeychainSecret,
+  deleteKeychainSecret,
+} from "./agent-credential-store.mjs";
+import { resolveAgentProfile } from "./wait-profile.mjs";
+
+// Dedicated Keychain service for the owner OAuth token. Distinct from the
+// per-profile agent-key services (BOTBUDDY_BB_AGENT_KEY / BOTBUDDY_SG_AGENT_KEY)
+// so the human owner session and the machine agent identity never collide.
+export const OWNER_TOKEN_SERVICE = "BOTBUDDY_OWNER_TOKEN";
+
+// Config keys that must never carry secret material at rest.
+const SECRET_CONFIG_KEYS = ["api_key", "access_token"];
+
+// Strip secret material from a config object. `api_key` is always removed (the
+// `register` path that wrote it is retired). `access_token` is removed only when
+// a Keychain is available to hold it instead; on a non-darwin host it remains
+// the documented fallback store, so it is preserved there.
+export function sanitizeConfigSecrets(config, { platform = process.platform, exists } = {}) {
+  const out = { ...(config ?? {}) };
+  let changed = false;
+  const keychain = keychainAvailable(platform, exists);
+  for (const key of SECRET_CONFIG_KEYS) {
+    if (!(key in out)) continue;
+    if (key === "access_token" && !keychain) continue; // documented non-darwin fallback
+    delete out[key];
+    changed = true;
+  }
+  return { config: out, changed };
+}
+
+// Persist the owner OAuth token. Non-secret metadata always goes to config.json;
+// the token itself goes to the Keychain on darwin, or (with a warning) stays in
+// the 0600 config.json where no Keychain exists.
+export async function persistOwnerToken(
+  { token, expiresAt, clientId },
+  {
+    platform = process.platform,
+    exists,
+    getConfig,
+    saveConfig,
+    keychainWrite = (value) => writeKeychainSecret(OWNER_TOKEN_SERVICE, value),
+    warn = (message) => console.error(message),
+  } = {},
+) {
+  if (typeof token !== "string" || token.length === 0) {
+    throw new Error("persistOwnerToken requires a non-empty token");
+  }
+  // Start from a sanitized copy so a stale on-disk secret is never carried
+  // forward, then layer on the fresh non-secret metadata.
+  const keychain = keychainAvailable(platform, exists);
+  const { config: base } = sanitizeConfigSecrets(getConfig(), { platform, exists });
+  const next = { ...base };
+  if (clientId !== undefined) next.client_id = clientId;
+  if (expiresAt !== undefined) next.token_expires_at = expiresAt;
+
+  if (keychain) {
+    await keychainWrite(token);
+    delete next.access_token;
+  } else {
+    warn(
+      "⚠ macOS Keychain unavailable on this host — storing the OAuth token in ~/.botbuddy/config.json (0600). This is the documented non-darwin fallback.",
+    );
+    next.access_token = token;
+  }
+  saveConfig(next);
+  return { storedInKeychain: keychain };
+}
+
+// Resolve the owner OAuth token for outbound auth. On darwin it comes from the
+// Keychain only — a stale config.json access_token is ignored, never silently
+// trusted (BOT-1520 AC5). On a non-darwin host the config.json fallback is the
+// legitimate store. Expiry metadata always comes from config.json.
+export async function resolveOwnerToken({
+  platform = process.platform,
+  exists,
+  getConfig,
+  keychainRead = () => readKeychainSecret(OWNER_TOKEN_SERVICE),
+} = {}) {
+  const cfg = getConfig() ?? {};
+  const expiresAt = typeof cfg.token_expires_at === "number" ? cfg.token_expires_at : null;
+  let token = null;
+  if (keychainAvailable(platform, exists)) {
+    token = await keychainRead();
+  } else if (typeof cfg.access_token === "string" && cfg.access_token) {
+    token = cfg.access_token;
+  }
+  if (!token) return null;
+  return { token, expiresAt };
+}
+
+// Remove the owner OAuth token from every store (`botbuddy logout`).
+export async function clearOwnerToken({
+  platform = process.platform,
+  exists,
+  keychainDelete = () => deleteKeychainSecret(OWNER_TOKEN_SERVICE),
+} = {}) {
+  if (keychainAvailable(platform, exists)) {
+    await keychainDelete();
+  }
+}
+
+// Resolve the tenant-bound agent key from the profile Keychain store (or the
+// per-profile environment key), without throwing when no profile is configured.
+// This is the sole source of the agent credential now that `register` is gone.
+export async function resolveAgentKey(options = {}) {
+  try {
+    const { token } = await resolveAgentProfile(options);
+    return token || null;
+  } catch (error) {
+    if (error?.code === "profile_required" || error?.code === "unknown_profile") return null;
+    throw error;
+  }
+}

package/src/codex-bridge.mjs

@@ -14,6 +14,7 @@
 
 import { createHash, randomBytes } from "crypto";
 import { getConfig, SERVER_URL } from "./config.mjs";
+import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { green, red, cyan, dim, bold, yellow, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 
@@ -64,10 +65,17 @@ function isAddressInUseError(text) {
 }
 
 export async function runBridge(args) {
-  const cfg = getConfig();
-  if (!cfg.api_key && !cfg.access_token) {
-    die(`Not authenticated. Run: ${cyan("botbuddy start")} or ${cyan("botbuddy login")}`);
+  const cfg = getConfig(); // non-secret metadata only (agent_name)
+  // BOT-1520: authenticate from the Keychain — the profile agent key
+  // (`botbuddy profile setup`) or the owner OAuth token (`botbuddy login`).
+  // Resolve ONCE here for the life of the bridge and cache it, so the relay
+  // helpers don't shell out to `security` on every request.
+  const agentKey = await resolveAgentKey();
+  const owner = agentKey ? null : await resolveOwnerToken({ getConfig });
+  if (!agentKey && !owner) {
+    die(`Not authenticated. Run: ${cyan("botbuddy start")} or ${cyan("botbuddy login")} (agents: ${cyan("botbuddy profile setup <profile>")}).`);
   }
+  bridgeAuth = { agentKey, owner };
 
   // Parse args
   let wsPort = 4500;
@@ -519,16 +527,27 @@ export async function runBridge(args) {
 
 // ─── HTTP helpers ───
 
-function authHeaders() {
-  const cfg = getConfig();
+// BOT-1520: resolved once by runBridge and reused, so the relay helpers never
+// shell out to `security` per request. Null until the bridge starts (or in a
+// direct unit-test call), in which case authHeaders resolves live.
+let bridgeAuth = null;
+
+// BOT-1520: the bridge is agent-context, so it prefers the tenant-bound agent
+// key from the profile Keychain store and falls back to the owner OAuth token.
+export async function authHeaders() {
   const headers = { "Content-Type": "application/json" };
-  if (cfg.api_key) headers["x-agent-api-key"] = cfg.api_key;
-  else if (cfg.access_token) headers["Authorization"] = `Bearer ${cfg.access_token}`;
+  const agentKey = bridgeAuth ? bridgeAuth.agentKey : await resolveAgentKey();
+  if (agentKey) {
+    headers["x-agent-api-key"] = agentKey;
+  } else {
+    const owner = bridgeAuth ? bridgeAuth.owner : await resolveOwnerToken({ getConfig });
+    if (owner) headers["Authorization"] = `Bearer ${owner.token}`;
+  }
   return headers;
 }
 
 async function relayPost(path, body) {
-  const headers = authHeaders();
+  const headers = await authHeaders();
   // Add HMAC signing if we have a session secret and session_id
   if (sessionSecret && body?.session_id) {
     const hmacHeaders = await signRequest(body.session_id);
@@ -545,7 +564,7 @@ async function relayPost(path, body) {
 async function relayGet(path) {
   const res = await fetch(`${RELAY_URL}${path}`, {
     method: "GET",
-    headers: authHeaders(),
+    headers: await authHeaders(),
   });
   return res.json();
 }

package/src/commands.mjs

@@ -1,7 +1,8 @@
 import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
 import { runBridge } from "./codex-bridge.mjs";
-import { loadConfig, getConfig, clearConfig, saveConfig, getConfigPath, SERVER_URL } from "./config.mjs";
+import { loadConfig, getConfig, clearConfig, getConfigPath, SERVER_URL } from "./config.mjs";
+import { resolveOwnerToken, resolveAgentKey, clearOwnerToken } from "./cli-credentials.mjs";
 import { buildAcquireResourcesPayload, LocksUsageError } from "./locks.mjs";
 import { CallUsageError, discoveryUrlFor, formatDiscovery, parseCallArgs } from "./discovery.mjs";
 import { cmdStack } from "./stack.mjs";
@@ -24,7 +25,6 @@ export async function run(argv) {
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
     // Agent-only commands (used by MCP agents, not humans)
-    case "register": return cmdRegister(args);
     case "heartbeat": return cmdHeartbeat(args);
     case "lock": return cmdLock(args);
     case "locks": return cmdLocks(args);
@@ -164,8 +164,10 @@ ${bold("USAGE")}
 ${bold("HOW IT WORKS")}
   Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
   your default browser at the BotBuddy authorization page, and waits for you to
-  sign in as an allowed user. On success the token is saved to
-  ${dim("~/.botbuddy/config.json")} and the browser tab can be closed.
+  sign in as an allowed user. On success the token is stored in the macOS
+  Keychain (only non-secret metadata is kept in ${dim("~/.botbuddy/config.json")})
+  and the browser tab can be closed. On a host without a Keychain the token
+  falls back to the 0600 config file and the tool tells you so.
 
 ${bold("OPTIONS")}
   --no-browser   Don't launch a browser; print the authorization URL to open
@@ -192,14 +194,17 @@ ${bold("RECOVERY")}
 
 async function cmdStart(args) {
   console.log(`${bold("botbuddy")} ${dim(`v${VERSION}`)}\n`);
-  const cfg = getConfig();
 
-  // Auto-login if not authenticated
+  // Auto-login if not authenticated. BOT-1520: credentials live in the Keychain
+  // (owner token from `login`, agent key from `profile setup`), so probe those
+  // rather than a plaintext config secret.
   try {
-    if (!cfg.access_token && !cfg.api_key) {
+    const owner = await resolveOwnerToken({ getConfig });
+    const agentKey = owner ? null : await resolveAgentKey();
+    if (!owner && !agentKey) {
       console.log(dim("→ No credentials found. Starting login...\n"));
       await doLogin();
-    } else if (cfg.token_expires_at && cfg.token_expires_at <= Date.now()) {
+    } else if (owner && owner.expiresAt && owner.expiresAt <= Date.now() && !(await resolveAgentKey())) {
       console.log(dim("→ Token expired. Re-authenticating...\n"));
       await doLogin();
     }
@@ -211,14 +216,15 @@ async function cmdStart(args) {
   return runBridge(args);
 }
 
-function cmdStatus() {
+async function cmdStatus() {
   const cfg = getConfig();
-  if (cfg.access_token) {
-    console.log(`${green("✓")} Authenticated via OAuth`);
+  const owner = await resolveOwnerToken({ getConfig });
+  if (owner) {
+    console.log(`${green("✓")} Authenticated via OAuth ${dim("(Keychain)")}`);
     if (cfg.agent_name) console.log(`  Agent: ${cyan(cfg.agent_name)}`);
     if (cfg.client_id) console.log(`  Client: ${dim(cfg.client_id)}`);
-    if (cfg.token_expires_at) {
-      const remaining = cfg.token_expires_at - Date.now();
+    if (owner.expiresAt) {
+      const remaining = owner.expiresAt - Date.now();
       if (remaining <= 0) {
         console.log(`  Token: ${red("EXPIRED")} — run ${cyan("botbuddy start")}`);
       } else {
@@ -228,17 +234,21 @@ function cmdStatus() {
       }
     }
     console.log(`  Config: ${dim(getConfigPath())}`);
-  } else if (cfg.api_key) {
-    console.log(`${green("✓")} Authenticated via API key`);
+    return;
+  }
+  const agentKey = await resolveAgentKey();
+  if (agentKey) {
+    console.log(`${green("✓")} Authenticated via agent key ${dim("(Keychain profile store)")}`);
     if (cfg.agent_name) console.log(`  Agent: ${cyan(cfg.agent_name)}`);
-  } else {
-    console.log(`${red("✗")} Not authenticated`);
-    console.log(`  Run: ${cyan("botbuddy start")}`);
+    return;
   }
+  console.log(`${red("✗")} Not authenticated`);
+  console.log(`  Run: ${cyan("botbuddy start")}`);
 }
 
-function cmdLogout() {
+async function cmdLogout() {
   clearConfig();
+  await clearOwnerToken();
   console.log(`${green("✓")} Logged out. Credentials removed.`);
 }
 
@@ -280,22 +290,6 @@ async function cmdAgentAuth(args) {
   console.log(`${green("✓")} ${result.profile} (${result.tenant}) machine credential ${result.removed ? "removed" : "was not present"}.`);
 }
 
-async function cmdRegister(args) {
-  const name = args[0];
-  if (!name) die("Usage: botbuddy register <name> [type]");
-  const type = args[1] || "custom";
-  const data = await callTool("register_agent", { name, type });
-  const text = data?.result?.content?.[0]?.text;
-  if (text) {
-    try {
-      const parsed = JSON.parse(text);
-      if (parsed.api_key) {
-        saveConfig({ ...getConfig(), api_key: parsed.api_key, agent_id: parsed.agent_id, agent_name: name });
-      }
-    } catch {}
-  }
-}
-
 function cmdHeartbeat(args) {
   return args[0] ? callTool("heartbeat", { current_task: args[0] }) : callTool("heartbeat");
 }

package/src/config.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
+import { sanitizeConfigSecrets } from "./cli-credentials.mjs";
 
 const CONFIG_DIR = join(homedir(), ".botbuddy");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -13,13 +14,28 @@ export const SERVER_URL = process.env.BOTBUDDY_SERVER_URL
 
 let config = {};
 
-export function loadConfig() {
+export function loadConfig({ platform = process.platform, warn = (m) => console.error(m) } = {}) {
+  let raw = {};
   try {
     if (existsSync(CONFIG_FILE)) {
-      config = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+      raw = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
     }
   } catch {
-    config = {};
+    raw = {};
+  }
+  // BOT-1520 migration: never silently trust secrets left in a plaintext
+  // config.json by an older CLI. `api_key` (written by the retired `register`)
+  // is always dropped; `access_token` is dropped where a Keychain can hold it.
+  // Clear them at rest by rewriting the file, and tell the operator once.
+  const { config: sanitized, changed } = sanitizeConfigSecrets(raw, { platform });
+  // Adopt the sanitized config in memory unconditionally — a failed best-effort
+  // rewrite (read-only FS, permissions) must not drop the non-secret metadata.
+  config = sanitized;
+  if (changed) {
+    try { saveConfig(sanitized); } catch {} // best-effort: clear the secret at rest
+    warn(
+      "⚠ Removed a legacy plaintext credential from ~/.botbuddy/config.json. Run `botbuddy login` (and `botbuddy profile setup <profile>` for agents) to re-establish credentials in the Keychain.",
+    );
   }
   return config;
 }

package/src/stack.mjs

@@ -29,6 +29,7 @@ import { basename, dirname, join, relative, isAbsolute } from "path";
 import { randomUUID } from "crypto";
 import { callToolJson } from "./api.mjs";
 import { SERVER_URL, getConfig } from "./config.mjs";
+import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
 import { runDockerWorkflow } from "./docker-hygiene.mjs";
 import { bold, dim, yellow } from "./utils.mjs";
 
@@ -350,13 +351,20 @@ export function parseSupabaseStatus(text) {
 
 // ── runtime (network / process) ──────────────────────────────────────────────
 
-function stackAuthHeader() {
-  const cfg = getConfig();
-  if (cfg.access_token) {
-    if (cfg.token_expires_at && Date.now() >= cfg.token_expires_at) return null;
-    return { Authorization: `Bearer ${cfg.access_token}`, "x-agent-api-key": cfg.api_key || "" };
+// BOT-1520: source both auth headers from the Keychain — the owner OAuth token
+// (`botbuddy login`) is preferred, the tenant-bound agent key
+// (`botbuddy profile setup`) is the fallback. No plaintext config.json secret.
+export async function stackAuthHeader() {
+  const agentKey = await resolveAgentKey();
+  const owner = await resolveOwnerToken({ getConfig });
+  if (owner) {
+    if (owner.expiresAt && Date.now() >= owner.expiresAt) {
+      if (agentKey) return { Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey };
+      return null;
+    }
+    return { Authorization: `Bearer ${owner.token}`, "x-agent-api-key": agentKey || "" };
   }
-  if (cfg.api_key) return { Authorization: `Bearer ${cfg.api_key}`, "x-agent-api-key": cfg.api_key };
+  if (agentKey) return { Authorization: `Bearer ${agentKey}`, "x-agent-api-key": agentKey };
   return null;
 }
 
@@ -676,7 +684,7 @@ export async function cmdUp(opts, {
       process.stderr.write(`${yellow("⚠")} stack: OrbStack preflight warns of interface pressure; cleanup is recommended before another stack.\n`);
     }
   }
-  const auth = authProvider();
+  const auth = await authProvider();
   if (!auth) return emitResult(buildReceipt({ command: "up", outcome: "error", error: "not authenticated — run `botbuddy login`" }), opts, EXIT.AUTH);
 
   const req = await callTool("request_stack_lease", {
@@ -966,7 +974,7 @@ export async function runStackLifecycle(opts, childArgv, adapters = {}) {
     touch: (leaseId) => callToolJson("touch_stack_lease", { lease_id: leaseId }),
     release: (leaseId, signal) => callToolJson("release_stack_lease", { lease_id: leaseId, disposition: "destroy" }, { signal }),
   };
-  const auth = adapters.auth ?? stackAuthHeader();
+  const auth = adapters.auth ?? await stackAuthHeader();
   const wait = adapters.wait ?? ((leaseId, done, failed, options) => waitForLease(leaseId, done, failed, options));
   // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- validated executable + argv only; shell is never used.
   const startChild = adapters.startChild ?? ((argv, env, cwd) => spawn(argv[0], argv.slice(1), { cwd, env, stdio: "inherit", detached: true }));

package/src/wait-core.mjs

@@ -611,6 +611,63 @@ export function foldFeedLag(degraded, lagging) {
   return degraded;
 }
 
+// ---------------------------------------------------------------------------
+// BOT-1539 — arm-time outstanding-review notice.
+//
+// `pr-review` / `pr-state` are edge-triggered: they wake only on a review event
+// delivered AFTER arm. When the relay reports (via `pr_review_snapshot` on the
+// register receipt) that a PR ALREADY has an outstanding review, warn the
+// operator on stderr so a silent park isn't mistaken for "no review yet". The
+// existing review will NOT re-wake this wait.
+// ---------------------------------------------------------------------------
+
+// Compact, human relative age (e.g. "27m ago", "3h ago", "2d ago"). Returns
+// null when the timestamp is absent or unparseable, so callers can omit the
+// phrase entirely.
+function relativeAge(iso, now) {
+  if (!iso) return null;
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return null;
+  const secs = Math.max(0, Math.round((now - then) / 1000));
+  if (secs < 60) return `${secs}s ago`;
+  const mins = Math.round(secs / 60);
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.round(mins / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+/**
+ * Build one stderr warning line per OUTSTANDING pr-review snapshot entry.
+ * Clean (not-outstanding) entries and empty/absent input yield no lines.
+ *
+ * @param {Array<{repo:string,pr:number,unresolved_threads:number,review_decision:string,pr_updated_at:string|null,existing_review_outstanding:boolean}>|null|undefined} snapshot
+ * @param {number} [now] epoch ms, for deterministic age formatting
+ * @returns {string[]}
+ */
+export function formatPrReviewSnapshotWarnings(snapshot, now = Date.now()) {
+  if (!Array.isArray(snapshot)) return [];
+  const lines = [];
+  for (const e of snapshot) {
+    if (!e || e.existing_review_outstanding !== true) continue;
+    const threads = typeof e.unresolved_threads === "number" ? e.unresolved_threads : 0;
+    const parts = [`pr-review armed: ${e.repo}#${e.pr} already has a review outstanding`];
+    if (threads > 0) {
+      parts.push(`${threads} unresolved review thread${threads === 1 ? "" : "s"}`);
+    }
+    if (e.review_decision && e.review_decision !== "unknown") {
+      parts.push(`review_decision=${e.review_decision}`);
+    }
+    const age = relativeAge(e.pr_updated_at, now);
+    if (age) parts.push(`last update ${age}`);
+    lines.push(
+      `${parts.join(" · ")}. This wait fires only on the NEXT review event; ` +
+      `the existing review will not re-wake it.`,
+    );
+  }
+  return lines;
+}
+
 // ---------------------------------------------------------------------------
 // Matching — does a spine signal frame satisfy a condition?
 // ---------------------------------------------------------------------------

package/src/wait.mjs

@@ -13,7 +13,7 @@
 // Usage:  botbuddy wait [--any] <condition>... [options]
 // Run     botbuddy wait --help for the condition grammar.
 
-import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt } from "./wait-core.mjs";
+import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings } from "./wait-core.mjs";
 import { resolveAgentProfile, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
@@ -52,7 +52,12 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       flip sets payload.mergeable_changed (no new condition).
   pr-review:repo=<owner/repo>[,pr=<n>]
                                       a new review comment, or a thread resolved/re-opened
-                                      (payload carries the unresolved-thread count)
+                                      (payload carries the unresolved-thread count).
+                                      Edge-triggered: it wakes only on review activity AFTER
+                                      arm. If the PR ALREADY has an outstanding review at arm,
+                                      bb-wait prints a one-line stderr notice (unresolved count,
+                                      review_decision, age) so a silent park isn't mistaken for
+                                      "no review yet" — the existing review will not re-wake it.
   test-run:id=<run_id>                a test run reaching a terminal status (owner-scoped)
   lease:id=<lease_id>                 a batch stack lease (BOT-1218) leaving the queue /
                                       becoming active — the zero-poll wake for a parked
@@ -273,6 +278,24 @@ async function registerWait(opts, conditions, deadlineIso) {
     err.minimumProtocol = body.minimum_wait_protocol ?? null;
     throw err;
   }
+  if (res.status === 409 || res.status === 404) {
+    // BOT-1523: `unblocked:<KEY>` hydration at registration could not arm the wait
+    // truthfully. These are NOT the untracked-live-only fallback: arming a live-only
+    // unblocked wait would skip the server's initial evaluation and could resume a
+    // coding session on a false already_unblocked. Surface the typed receipt and a
+    // concrete exit code (5=backend/retryable, 4=invalid/not-found).
+    const body = await res.json().catch(() => ({}));
+    if (body.error === "unblocked_projection_unresolved" || body.error === "unblocked_ticket_not_found") {
+      const err = new Error(body.detail || body.error);
+      err.hydrationRegister = true;
+      err.errorCode = body.error;
+      err.ticket = body.ticket ?? null;
+      err.retryable = body.retryable ?? null;
+      err.hydration = body.hydration ?? null;
+      err.notFound = body.error === "unblocked_ticket_not_found";
+      throw err;
+    }
+  }
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
     const err = new Error(body.detail || body.message || body.error || `register responded ${res.status}`);
@@ -316,6 +339,10 @@ async function registerWait(opts, conditions, deadlineIso) {
     // echoes session_agent_id only when it overrode the profile agent).
     sessionId: body.session_id ?? null,
     sessionAgentId: body.session_agent_id ?? null,
+    // BOT-1539: arm-time snapshot of already-outstanding code review for any
+    // pr-review/pr-state target. Report-only — surfaced on stderr so a silent
+    // edge-triggered park isn't mistaken for "no review yet".
+    prReviewSnapshot: Array.isArray(body.pr_review_snapshot) ? body.pr_review_snapshot : null,
   };
 }
 
@@ -600,6 +627,12 @@ export async function runWait(argv) {
       registeredAgentId = reg.agentId;
       registeredSessionAgentId = reg.sessionAgentId;
       registeredSessionId = reg.sessionId;
+      // BOT-1539: if any pr-review/pr-state target already has an outstanding
+      // review, tell the operator now (stderr, one line per PR). Purely
+      // informational — it does not change arming or exit semantics.
+      for (const line of formatPrReviewSnapshotWarnings(reg.prReviewSnapshot)) {
+        process.stderr.write(`bb-wait: ${line}\n`);
+      }
       // BOT-1184: adopt the server's canonical host for each lock condition so the
       // local matcher builds the same subject_key the availability/claim-grant
       // signals carry (armed under an alias like 'jono-mac', the signal uses the
@@ -678,6 +711,30 @@ export async function runWait(argv) {
         });
         process.exit(EXIT.INVALID);
       }
+      if (err && err.hydrationRegister) {
+        // BOT-1523: `unblocked:<KEY>` could not be hydrated from Linear at
+        // registration. Emit the typed receipt and a concrete exit: 4 (INVALID)
+        // for a not-found key, 5 (BACKEND) for a retryable backend/config reason.
+        const reason = err.hydration?.reason ?? (err.notFound ? "issue_not_found" : "unknown");
+        const tenant = opts.agentProfile?.tenant ?? "your-tenant";
+        const fix = err.notFound
+          ? "no Linear issue with that key exists in this workspace"
+          : reason === "no_linear_api_key"
+          ? `add LINEAR_API_KEY for tenant ${tenant} at /settings/integrations#linear`
+          : reason === "org_mismatch"
+          ? "the Linear issue belongs to a different Linear workspace than this tenant"
+          : "retry once Linear is reachable";
+        process.stderr.write(`bb-wait: unblocked:${err.ticket ?? "?"} cannot register — ${reason}; ${fix}\n`);
+        emitReceipt({
+          schema_version: 1,
+          outcome: "error",
+          error: err.errorCode,
+          ticket: err.ticket,
+          retryable: err.retryable,
+          hydration: err.hydration,
+        });
+        process.exit(err.notFound ? EXIT.INVALID : EXIT.BACKEND);
+      }
       if (err && err.invalidCondition) {
         // A rejected condition set is a configuration error, not a wait — fail closed
         // rather than arming an untracked wait that skips the server's initial