@botbuddy/cli 1.8.6 → 1.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.8.6",
+  "version": "1.8.8",
   "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/botbuddy-release-repair.json

@@ -1 +1 @@
-{"schema_version":1,"source_version":"1.8.3","source_identity":"8304ea6fbec329d54d6361cb6cbf5a6789331b0851d09caf151f0663ade18ec2"}
+{"schema_version":1,"source_version":"1.8.7","source_identity":"e6b611000678281287808866482334e5a40e265ef3c0328c4e85f53a5bf23cd0"}

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/pw/daemon.mjs

@@ -1,13 +1,62 @@
 import { spawn } from "node:child_process";
 import net from "node:net";
 import { createRequire } from "node:module";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
+import { normaliseLane } from "./args.mjs";
 export const daemonDir = (env = process.env) => env.BB_PW_DAEMON_DIR || join(homedir(), ".botbuddy", "pw-daemon");
 export function resolveCliBin(env = process.env) { if (env.BB_PW_CLI_BIN) return { cmd: "node", args: [env.BB_PW_CLI_BIN] }; const require = createRequire(import.meta.url); const pkg = require.resolve("@playwright/cli/package.json"), meta = JSON.parse(readFileSync(pkg, "utf8")), bin = typeof meta.bin === "string" ? meta.bin : meta.bin["playwright-cli"] || Object.values(meta.bin)[0]; return { cmd: "node", args: [join(dirname(pkg), bin)] }; }
 export function spawnExec(plan, env = process.env) { const { cmd, args } = resolveCliBin(env); return new Promise((resolve) => { const child = spawn(cmd, [...args, ...plan.execArgv], { stdio: "inherit", env: { ...env, PWTEST_DAEMON_SESSION_DIR: daemonDir(env) } }); child.on("exit", (code) => resolve(code ?? 1)); child.on("error", () => resolve(127)); }); }
-export function readSession(session, env = process.env) { const root = daemonDir(env); if (!existsSync(root)) return null; for (const item of readdirSync(root)) { try { return JSON.parse(readFileSync(join(root, item, `${session}.session`), "utf8")); } catch {} } return null; }
-export function sendToDaemon(socketPath, positional, { connect = net.createConnection, cwd = process.cwd(), timeoutMs = 30000 } = {}) { return new Promise((resolve) => { let done = false, buffer = "", socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => socket.write(JSON.stringify({ id: 1, method: "run", params: { args: { _: positional }, cwd } }) + "\n")); socket.on("data", (data) => { buffer += String(data); const newline = buffer.indexOf("\n"); if (newline < 0) return; try { const reply = JSON.parse(buffer.slice(0, newline)), text = reply.result?.text ?? ""; finish(reply.error || /^### Error\b/m.test(text) ? { ok: false, error: reply.error?.message ?? reply.error ?? text } : { ok: true, text }); } catch { finish({ ok: false, error: "bb-pw: malformed daemon reply" }); } }); socket.on("error", (error) => finish({ ok: false, error: error.message })); setTimeout(() => finish({ ok: false, error: "bb-pw: daemon socket timeout" }), timeoutMs).unref(); }); }
+// BOT-1522: playwright-cli keeps one sub-dir per invocation context under the
+// daemon dir, and only ever cleans up its OWN sub-dir's `<session>.session`. A
+// lane opened from another worktree whose daemon has since exited leaves a file
+// pointing at a socket that no longer exists — and it can sort before today's
+// live one. Selection is therefore by liveness, never by readdir order, and the
+// caller gets a remediation naming the lane and the command, never a raw syscall.
+export const laneOf = (session) => normaliseLane(session ?? "");
+// Any connect-phase failure means the daemon is not there to answer; name the
+// shape in prose so the syscall code never reaches the operator (AC-3/AC-6).
+const CONNECT_FAILURE = { ENOENT: "its socket is gone", ECONNREFUSED: "its socket refused the connection", ENOTSOCK: "its socket refused the connection", ECONNRESET: "the connection dropped", EPIPE: "the connection dropped" };
+const connectFailure = (error) => (error?.code ? CONNECT_FAILURE[error.code] ?? "the connection failed" : null);
+export function notRunningMessage(session, ignored = [], detail = null) {
+  const why = ignored.length ? `ignored stale session file(s): ${ignored.map((entry) => `${entry.file} [${entry.reason}]`).join(", ")}` : detail ?? "no session file found";
+  return `bb-pw: ${session} daemon is not running (${why}). Run \`bb-pw ${laneOf(session) || "<lane>"} open <url>\` first, then retry.`;
+}
+// Every `<root>/<sub>/<session>.session`, newest first. A file whose socket path
+// is ABSENT on disk is provably dead (the daemon's tmp dir is gone) and is
+// pruned; one whose socket EXISTS is kept — the daemon may be starting — and
+// liveness is decided by connecting (resolveSession), not by the file. Corrupt
+// JSON is left alone: it is not provably dead. Only this session's file is read,
+// so another lane's live daemon in the same sub-dir is never touched.
+export function scanSessions(session, env = process.env, { prune = true } = {}) {
+  const root = daemonDir(env), candidates = [], ignored = [];
+  if (!existsSync(root)) return { candidates, ignored };
+  for (const item of readdirSync(root)) {
+    const file = join(root, item, `${session}.session`);
+    let data; try { data = JSON.parse(readFileSync(file, "utf8")); } catch { continue; }
+    if (!data?.socketPath) { ignored.push({ file, reason: "no socket path" }); continue; }
+    if (!existsSync(data.socketPath)) { ignored.push({ file, reason: "socket missing" }); if (prune) { try { unlinkSync(file); } catch {} } continue; }
+    let mtimeMs = 0; try { mtimeMs = statSync(file).mtimeMs; } catch {}
+    candidates.push({ file, data, mtimeMs });
+  }
+  // Newest first; a deterministic path tiebreak so an mtime tie never falls back to readdir order.
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs || b.file.localeCompare(a.file));
+  return { candidates, ignored };
+}
+// Synchronous, back-compatible, READ-ONLY reader (reap.mjs): the newest session
+// whose socket path exists on disk. Pruning belongs to the socket path (socketRun).
+export function readSession(session, env = process.env) { return scanSessions(session, env, { prune: false }).candidates[0]?.data ?? null; }
+export function sendToDaemon(socketPath, positional, { connect = net.createConnection, cwd = process.cwd(), timeoutMs = 30000, session = null } = {}) { return new Promise((resolve) => { let done = false, buffer = "", socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => socket.write(JSON.stringify({ id: 1, method: "run", params: { args: { _: positional }, cwd } }) + "\n")); socket.on("data", (data) => { buffer += String(data); const newline = buffer.indexOf("\n"); if (newline < 0) return; try { const reply = JSON.parse(buffer.slice(0, newline)), text = reply.result?.text ?? ""; finish(reply.error || /^### Error\b/m.test(text) ? { ok: false, error: reply.error?.message ?? reply.error ?? text } : { ok: true, text }); } catch { finish({ ok: false, error: "bb-pw: malformed daemon reply" }); } }); socket.on("error", (error) => { const why = session ? connectFailure(error) : null; finish({ ok: false, error: why ? notRunningMessage(session, [], why) : error.message }); }); setTimeout(() => finish({ ok: false, error: "bb-pw: daemon socket timeout" }), timeoutMs).unref(); }); }
 export function socketAlive(socketPath, { connect = net.createConnection, timeoutMs = 1000 } = {}) { return new Promise((resolve) => { if (!socketPath) return resolve(false); let done = false, socket; const finish = (value) => { if (!done) { done = true; socket?.destroy(); resolve(value); } }; socket = connect(socketPath, () => finish(true)); socket.on("error", () => finish(false)); setTimeout(() => finish(false), timeoutMs).unref(); }); }
-export async function socketRun(plan, env = process.env) { const session = readSession(plan.session, env); return session?.socketPath ? sendToDaemon(session.socketPath, plan.socketArgs) : { ok: false, error: `bb-pw: no open daemon for ${plan.session}; open it first` }; }
+// Authoritative, async: the newest candidate whose socket actually ANSWERS.
+export async function resolveSession(session, env = process.env, { alive = socketAlive } = {}) {
+  const { candidates, ignored } = scanSessions(session, env);
+  for (const candidate of candidates) { if (await alive(candidate.data.socketPath)) return { session: candidate.data, ignored }; ignored.push({ file: candidate.file, reason: "did not answer" }); }
+  return { session: null, ignored };
+}
+export async function socketRun(plan, env = process.env, { alive, send = sendToDaemon } = {}) {
+  const { session, ignored } = await resolveSession(plan.session, env, { alive });
+  if (!session) return { ok: false, error: notRunningMessage(plan.session, ignored) };
+  return send(session.socketPath, plan.socketArgs, { session: plan.session });
+}

package/src/pw/run.mjs

@@ -7,6 +7,7 @@ import { canonicalizeHostString } from "./host.mjs";
 import { resolveAgentProfile } from "../wait-profile.mjs";
 import { readProfileIdentity } from "../agent-credential-store.mjs";
 import { loadConfig, getConfig } from "../config.mjs";
+import { VERSION } from "../version.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").
@@ -68,8 +69,22 @@ async function gate({ env, host, lane, deps }) {
     return { allowed: false, message: `bb-pw: could not verify lane lock ${laneName} (${error.message}). Set BB_PW_NO_LOCK=1 for local-only work.` };
   }
 }
+// BOT-1522: a stale global install (1.6.1 on the reporting host) replayed the
+// pre-BOT-1488 refusal and was indistinguishable from a code regression. Every
+// non-zero exit now names the bundled version, and --version exists at all, so
+// an agent can tell "old binary" from "real bug" without reading the source.
+const versionLine = () => `bb-pw (@botbuddy/cli v${VERSION})`;
 export async function runPw(argv, deps = {}) {
+  const stderr = deps.stderr ?? process.stderr;
+  const code = await runPwInner(argv, deps);
+  // Neutral: a refusal may be correct policy, not staleness — the line only lets
+  // the reader compare this binary against cli/package.json in their checkout.
+  if (code !== 0) stderr.write(`${versionLine()} — if your checkout's cli/package.json is newer, this global is stale: npm i -g @botbuddy/cli@latest, or run node cli/bin/bb-pw.mjs from the repo.\n`);
+  return code;
+}
+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; }
   while (args[0] === "--profile" || args[0] === "--session-id") { const flag = args[0]; if (!args[1]) { stderr.write(`bb-pw: ${flag} needs a value\n`); return 2; } deps = flag === "--profile" ? { ...deps, profile: args[1] } : { ...deps, sessionId: args[1] }; args = args.slice(2); }
   let plan; try { plan = planInvocation(args, env); } catch (error) { stderr.write(`${error.message}\n`); return 2; }
   const { spawnExec, socketRun } = deps.daemon ?? await import("./daemon.mjs");

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.mjs

@@ -273,6 +273,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}`);
@@ -678,6 +696,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