@botbuddy/cli 1.9.2 → 1.13.0

package/package.json

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

package/src/agent-credential-store.mjs

@@ -43,17 +43,25 @@ function keychainService(profile) {
 // succeeded. It carries its own code so the CLI never mislabels a storage
 // failure as an auth failure (which would tell the user to re-`login`).
 export class ProfileCredentialStoreError extends Error {
-  constructor(message, { cause } = {}) {
+  constructor(message, { cause, code = "profile_credential_store_failed" } = {}) {
     super(message);
     this.name = "ProfileCredentialStoreError";
-    this.code = "profile_credential_store_failed";
+    this.code = code;
     if (cause !== undefined) this.cause = cause;
   }
 }
 
 function writePasswordPrompt(command, args, password, spawnProcess) {
   return new Promise((resolve, reject) => {
-    const child = spawnProcess(command, args, { stdio: ["pipe", "ignore", "pipe"] });
+    // BOT-1566: `security -w` (prompt mode) reads the secret with
+    // readpassphrase(3), which opens the CONTROLLING TERMINAL whenever the
+    // process has one — ignoring the piped stdin and silently storing whatever
+    // the human types at "password data for new item:". Spawning the child
+    // detached puts it in a new session with no controlling TTY, so
+    // readpassphrase falls back to stdin and the piped value is what lands.
+    // Headless (CI / agent harness) behaviour is unchanged: there was never a
+    // TTY to grab.
+    const child = spawnProcess(command, args, { stdio: ["pipe", "ignore", "pipe"], detached: true });
     let stderr = "";
     child.stderr.on("data", (chunk) => { stderr += chunk; });
     child.once("error", reject);
@@ -74,7 +82,19 @@ function writePasswordPrompt(command, args, password, spawnProcess) {
 // 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 } = {}) {
+//
+// BOT-1566: every write is verified by reading the item back and comparing it
+// byte-for-byte with what was written. `readSecret` is the seam (defaults to
+// the real `security find-generic-password`); a mismatch — the incident shape
+// where the Keychain held a typed password instead of the OAuth token — throws
+// `keychain_readback_mismatch` so callers fail loudly instead of announcing a
+// successful login. Only equality is asserted, never token shape: profile keys
+// (`bb_agent_…`) are not JWTs.
+export async function writeKeychainSecret(service, token, {
+  spawnProcess = spawn,
+  execFileImpl = execFileAsync,
+  readSecret = (svc) => readKeychainSecret(svc, { execFileImpl }),
+} = {}) {
   if (!service) throw new ProfileCredentialStoreError("keychain write requires a service name");
   try {
     await writePasswordPrompt(
@@ -95,6 +115,17 @@ export async function writeKeychainSecret(service, token, { spawnProcess = spawn
     }
     throw new ProfileCredentialStoreError(`could not write the credential to the macOS Keychain: ${detail}`, { cause: error });
   }
+  const stored = await readSecret(service);
+  if (stored !== token) {
+    // Never echo either value: the written token is a credential and the stored
+    // one may be a human's typed password.
+    throw new ProfileCredentialStoreError(
+      `macOS Keychain read-back verification failed for ${service}: the stored value differs from the credential written. `
+        + "If `security` prompted you for a password, delete the item (`security delete-generic-password -s "
+        + `${service}\`) and retry.`,
+      { code: "keychain_readback_mismatch" },
+    );
+  }
 }
 
 export async function readKeychainSecret(service, { execFileImpl = execFileAsync } = {}) {
@@ -117,10 +148,10 @@ export async function deleteKeychainSecret(service, { execFileImpl = execFileAsy
   }
 }
 
-export async function writeKeychain(profile, token, { spawnProcess = spawn } = {}) {
+export async function writeKeychain(profile, token, options = {}) {
   const service = keychainService(profile);
   if (!service) throw new ProfileCredentialStoreError(`unknown profile keychain service for "${profile}"`);
-  return writeKeychainSecret(service, token, { spawnProcess });
+  return writeKeychainSecret(service, token, options);
 }
 
 async function readKeychain(profile) {

package/src/api.mjs

@@ -71,7 +71,20 @@ export async function resolveCallAuth() {
   return { error: { ok: false, auth: true, error: "not_authenticated" } };
 }
 
-export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal, auth: pinnedAuth = null } = {}) {
+// BOT-1561: a multi-membership owner credential is tenant-ambiguous without an
+// explicit pin — the server (mcpSessionIdentity, BOT-1521) fails closed, so
+// stateless REST tools/call like whoami return no tenant_id. `tenant` pins the
+// call to a specific tenant by appending ?tenant=<slug> to the endpoint (the
+// same mechanism as the documented BOTBUDDY_SERVER_URL override), letting the
+// server resolve/confirm exactly that tenant.
+function toolEndpoint(tenant) {
+  if (!tenant) return SERVER_URL;
+  const url = new URL(SERVER_URL);
+  url.searchParams.set("tenant", tenant);
+  return url.toString();
+}
+
+export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, signal, auth: pinnedAuth = null, tenant = null } = {}) {
   let auth = pinnedAuth;
   if (!auth) {
     const resolved = await resolveCallAuth();
@@ -81,7 +94,7 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
   const body = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: toolName, arguments: args } };
   let res;
   try {
-    res = await fetchImpl(SERVER_URL, {
+    res = await fetchImpl(toolEndpoint(tenant), {
       method: "POST",
       headers: { "Content-Type": "application/json", ...auth },
       body: JSON.stringify(body),
@@ -90,7 +103,21 @@ export async function callToolJson(toolName, args = {}, { fetchImpl = fetch, sig
   } catch (err) {
     return { ok: false, status: null, error: `transport: ${err?.message ?? err}` };
   }
-  if (res.status === 401 || res.status === 403) return { ok: false, auth: true, status: res.status, error: "unauthorized" };
+  if (res.status === 401 || res.status === 403) {
+    // BOT-1561: a 401/403 can still carry a structured MCP error code in its
+    // JSON-RPC body (e.g. MCP_TENANT_MEMBERSHIP_REQUIRED from a connection
+    // tenant-pin refusal — index.ts serializes it as
+    // { error: { code: -32002, data: { code } } }). Surface that `code` so a
+    // caller can tell a tenant refusal apart from a plain credential failure.
+    // Best-effort: an opaque/bodyless 401/403 keeps the generic shape.
+    let code = null;
+    try {
+      const body = await res.json();
+      const raw = body?.error?.data?.code ?? body?.error?.code ?? body?.code ?? null;
+      if (typeof raw === "string" && raw) code = raw;
+    } catch { /* opaque body */ }
+    return { ok: false, auth: true, status: res.status, error: "unauthorized", ...(code ? { code } : {}) };
+  }
   let payload;
   try { payload = await res.json(); } catch { return { ok: false, status: res.status, error: "invalid_json" }; }
   if (payload.error?.message) return { ok: false, status: res.status, error: payload.error.message };

package/src/auth.mjs

@@ -50,7 +50,7 @@ function callbackErrorMessage(err) {
 
 // AC-1..AC-13: orchestrate the loopback authorization-code flow.
 //
-// options: { noBrowser }
+// options: { noBrowser, tenant }
 // deps (all injectable for tests): serverUrl, fetch, openBrowser, saveConfig,
 //   getConfig, log, errorLog, timeoutMs, now.
 export async function doLogin(options = {}, deps = {}) {
@@ -67,6 +67,8 @@ export async function doLogin(options = {}, deps = {}) {
     persist = persistOwnerToken,
   } = deps;
   const noBrowser = Boolean(options.noBrowser);
+  // BOT-1566: optional tenant preselection (validated by the argument parser).
+  const tenant = typeof options.tenant === "string" && options.tenant ? options.tenant : null;
 
   log(`${bold("BotBuddy OAuth Login")}\n`);
 
@@ -106,7 +108,7 @@ export async function doLogin(options = {}, deps = {}) {
 
     // AC-6/AC-7: build the authorization URL and always print it (headless users
     // open it themselves). The CLI never fetches /authorize.
-    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge });
+    const authUrl = buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, tenant });
     log("");
     log(dim("→ Authorize BotBuddy in your browser:"));
     log(`  ${cyan(authUrl)}`);
@@ -159,6 +161,9 @@ export async function doLogin(options = {}, deps = {}) {
     // 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.
+    // BOT-1566: a Keychain read-back mismatch (`keychain_readback_mismatch`)
+    // propagates from here, so login exits non-zero and the success line below
+    // is never printed for a credential that did not verifiably land.
     const { storedInKeychain } = await persist(
       { token: tokenData.access_token, expiresAt, clientId },
       { getConfig, saveConfig, warn: errorLog },

package/src/commands.mjs

@@ -14,16 +14,33 @@ import { green, red, cyan, dim, bold, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 import { bootstrapProfile, ProfileBootstrapError, profileBootstrapRecovery, profileShellRefresh } from "./profile-bootstrap.mjs";
 import { runPw } from "./pw/run.mjs";
+import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
+
+// BOT-1566 D2: the stale-CLI check runs for every command EXCEPT `wait` and any
+// invocation carrying `--json` — those are hot paths whose receipts (BOT-1229)
+// must not pay for a registry round-trip.
+export function shouldCheckForUpdates(argv) {
+  const [command] = argv;
+  if (command === "wait") return false;
+  if (argv.includes("--json")) return false;
+  return true;
+}
 
-export async function run(argv) {
-  loadConfig();
+export async function run(argv, {
+  loadConfig: load = loadConfig,
+  warnStale = maybeWarnStale,
+  errorLog = (line) => console.error(line),
+} = {}) {
+  load();
   const [command, ...args] = argv;
+  if (shouldCheckForUpdates(argv)) await warnStale({ version: VERSION });
 
   switch (command) {
     case "start": return cmdStart(args);
-    case "login": return cmdLogin(args);
+    case "login": return cmdLogin(args, { errorLog });
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
+    case "update": return cmdUpdate();
     // Agent-only commands (used by MCP agents, not humans)
     case "heartbeat": return cmdHeartbeat(args);
     case "lock": return cmdLock(args);
@@ -74,9 +91,10 @@ ${bold("OPTIONS")}
     --no-server              Don't auto-start codex app-server
 
 ${bold("AUTH")}
-  login [--no-browser]       Authenticate via OAuth (opens browser + localhost callback)
+  login [--no-browser] [--tenant <slug>]
+                             Authenticate via OAuth (opens browser + localhost callback)
   logout                     Remove saved credentials
-  status                     Show current auth status
+  status                     Show current auth status (local metadata + server check)
   profile setup <profile>    Mint/reconnect and securely store a tenant-bound agent key
 
 ${bold("TOOLS")}
@@ -112,6 +130,7 @@ ${bold("BROWSER LANES")}
 
 ${bold("OTHER")}
   locks -m [--host name]    Reserve typed local resources, including Playwright MCP lanes
+  update                     Install the latest @botbuddy/cli in the background via npm
   help                       Show this help
   version                    Show version`);
 }
@@ -141,15 +160,57 @@ async function cmdToolHelp(args) {
   console.log(formatDiscovery(await res.json(), { tool }));
 }
 
+// BOT-1566 C1: a tenant slug as the server accepts it on `?tenant=` — lowercase
+// alphanumerics and hyphens, 2–63 chars, not starting with a hyphen.
+export const TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;
+
+export class LoginUsageError extends Error {
+  constructor(message, { exitCode = 1 } = {}) {
+    super(message);
+    this.name = "LoginUsageError";
+    this.exitCode = exitCode;
+  }
+}
+
+// Parse `botbuddy login` options. `--tenant <slug>` / `--tenant=<slug>`
+// preselects the tenant on the OAuth picker; a malformed slug is a usage
+// error with exit code 2 (never sent to the server).
+export function parseLoginArgs(args) {
+  const out = { noBrowser: false, tenant: null, help: false };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") { out.help = true; continue; }
+    if (arg === "--no-browser") { out.noBrowser = true; continue; }
+    if (arg === "--tenant" || arg.startsWith("--tenant=")) {
+      const value = arg.startsWith("--tenant=") ? arg.slice("--tenant=".length) : args[++i];
+      if (typeof value !== "string" || !TENANT_SLUG_RE.test(value)) {
+        throw new LoginUsageError("error: --tenant must be a lowercase slug", { exitCode: 2 });
+      }
+      out.tenant = value;
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new LoginUsageError(`Unknown login option: ${arg}. Run ${cyan("botbuddy login --help")}.`);
+    }
+  }
+  return out;
+}
+
 // BOT-1383: login now runs the RFC 8252 loopback flow (opens the browser,
-// waits for the localhost callback). Parse --no-browser and print focused help.
-async function cmdLogin(args) {
-  if (args.includes("--help") || args.includes("-h")) return loginHelp();
-  const noBrowser = args.includes("--no-browser");
-  const unknown = args.find((a) => a.startsWith("-") && !["--no-browser", "--help", "-h"].includes(a));
-  if (unknown) die(`Unknown login option: ${unknown}. Run ${cyan("botbuddy login --help")}.`);
+// waits for the localhost callback). Parse --no-browser / --tenant and print
+// focused help.
+async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {}) {
+  let options;
   try {
-    await doLogin({ noBrowser });
+    options = parseLoginArgs(args);
+  } catch (err) {
+    if (!(err instanceof LoginUsageError)) throw err;
+    if (err.exitCode === 2) { errorLog(err.message); return 2; }
+    die(err.message);
+  }
+  if (options.help) return loginHelp();
+  try {
+    await doLogin({ noBrowser: options.noBrowser, tenant: options.tenant });
   } catch (err) {
     die(err.message);
   }
@@ -159,7 +220,7 @@ function loginHelp() {
   console.log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 
 ${bold("USAGE")}
-  botbuddy login [--no-browser]
+  botbuddy login [--no-browser] [--tenant <slug>]
 
 ${bold("HOW IT WORKS")}
   Starts a localhost callback listener on an ephemeral 127.0.0.1 port, opens
@@ -173,6 +234,10 @@ ${bold("OPTIONS")}
   --no-browser   Don't launch a browser; print the authorization URL to open
                  in a browser on THIS machine yourself. The callback listener
                  still runs on this machine's localhost.
+  --tenant <slug>
+                 Preselect a tenant (e.g. ${cyan("supply-guard")}) on the sign-in page when
+                 your account belongs to more than one. Must be a lowercase slug;
+                 membership is still enforced by the server.
 
 ${bold("NOTES")}
   • The authorization URL is always printed so you can open it manually.
@@ -216,34 +281,92 @@ async function cmdStart(args) {
   return runBridge(args);
 }
 
-async function cmdStatus() {
-  const cfg = getConfig();
-  const owner = await resolveOwnerToken({ getConfig });
+// BOT-1566 A4: after the local-metadata lines, ask the SERVER whether the stored
+// credential is actually accepted. `status` used to decode only local metadata,
+// so a Keychain item holding a typed password (the BOT-1566 incident) was
+// reported as "Authenticated". One extra line, never throws, exit code
+// unchanged:
+//   server: authenticated (<tenant slug>)   whoami resolved
+//   server: rejected (<error message>)      the server refused the credential
+//   server: unreachable                     network / transport failure
+//
+// The probe is bounded by STATUS_PROBE_TIMEOUT_MS: a server that accepts the
+// connection but stalls before headers must not hang this formerly local
+// diagnostic — an aborted fetch returns a `transport:` error → `unreachable`
+// (BOT-1566, Codex P2).
+const STATUS_PROBE_TIMEOUT_MS = 4000;
+
+async function logServerStatus(call, auth, log) {
+  let res;
+  try {
+    res = await call("whoami", {}, { auth, signal: AbortSignal.timeout(STATUS_PROBE_TIMEOUT_MS) });
+  } catch {
+    log(`  server: ${red("unreachable")}`);
+    return;
+  }
+  if (res?.ok && !res.isError) {
+    const slug = typeof res.data?.tenant_id === "string" && res.data.tenant_id ? res.data.tenant_id : "tenant unresolved";
+    log(`  server: ${green("authenticated")} (${slug})`);
+    return;
+  }
+  if (res?.ok && res.isError) {
+    log(`  server: ${red("rejected")} (${res.data?.error ?? res.data?.code ?? "tool error"})`);
+    return;
+  }
+  if (res?.status === null && /^transport:/.test(String(res?.error ?? ""))) {
+    log(`  server: ${red("unreachable")}`);
+    return;
+  }
+  log(`  server: ${red("rejected")} (${res?.error ?? "unknown error"})`);
+}
+
+export async function cmdStatus({
+  getConfig: getCfg = getConfig,
+  resolveOwnerToken: resolveOwner = resolveOwnerToken,
+  resolveAgentKey: resolveAgent = resolveAgentKey,
+  callToolJson: call = callToolJson,
+  log = (line) => console.log(line),
+  now = () => Date.now(),
+} = {}) {
+  const cfg = getCfg();
+  const owner = await resolveOwner({ getConfig: getCfg });
   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)}`);
+    log(`${green("✓")} Authenticated via OAuth ${dim("(Keychain)")}`);
+    if (cfg.agent_name) log(`  Agent: ${cyan(cfg.agent_name)}`);
+    if (cfg.client_id) log(`  Client: ${dim(cfg.client_id)}`);
     if (owner.expiresAt) {
-      const remaining = owner.expiresAt - Date.now();
+      const remaining = owner.expiresAt - now();
       if (remaining <= 0) {
-        console.log(`  Token: ${red("EXPIRED")} — run ${cyan("botbuddy start")}`);
+        log(`  Token: ${red("EXPIRED")} — run ${cyan("botbuddy start")}`);
       } else {
         const mins = Math.round(remaining / 60000);
         const label = mins > 60 ? `${Math.round(mins / 60)}h ${mins % 60}m` : `${mins}m`;
-        console.log(`  Token expires in: ${dim(label)}`);
+        log(`  Token expires in: ${dim(label)}`);
       }
     }
-    console.log(`  Config: ${dim(getConfigPath())}`);
+    log(`  Config: ${dim(getConfigPath())}`);
+    // BOT-1566 (Codex P2): match resolveCallAuth — an expired owner token defers
+    // to a valid profile agent key, so probe the credential real commands would
+    // actually use instead of reporting a false `server: rejected` on the dead
+    // bearer while authenticated commands still succeed via the key.
+    const ownerExpired = owner.expiresAt && owner.expiresAt <= now();
+    const fallbackKey = ownerExpired ? await resolveAgent() : null;
+    await logServerStatus(
+      call,
+      fallbackKey ? { "x-agent-api-key": fallbackKey } : { Authorization: `Bearer ${owner.token}` },
+      log,
+    );
     return;
   }
-  const agentKey = await resolveAgentKey();
+  const agentKey = await resolveAgent();
   if (agentKey) {
-    console.log(`${green("✓")} Authenticated via agent key ${dim("(Keychain profile store)")}`);
-    if (cfg.agent_name) console.log(`  Agent: ${cyan(cfg.agent_name)}`);
+    log(`${green("✓")} Authenticated via agent key ${dim("(Keychain profile store)")}`);
+    if (cfg.agent_name) log(`  Agent: ${cyan(cfg.agent_name)}`);
+    await logServerStatus(call, { "x-agent-api-key": agentKey }, log);
     return;
   }
-  console.log(`${red("✗")} Not authenticated`);
-  console.log(`  Run: ${cyan("botbuddy start")}`);
+  log(`${red("✗")} Not authenticated`);
+  log(`  Run: ${cyan("botbuddy start")}`);
 }
 
 async function cmdLogout() {

package/src/oauth-loopback.mjs

@@ -46,7 +46,7 @@ export function generateState() {
 
 // AC-6/AC-7: build the complete /authorize URL. The browser follows it; the CLI
 // never fetches it. `redirectUri` must be the exact loopback callback we bound.
-export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, scope = "read write lock" }) {
+export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, codeChallenge, scope = "read write lock", tenant = null }) {
   const url = new URL(`${serverUrl}/authorize`);
   url.searchParams.set("client_id", clientId);
   url.searchParams.set("redirect_uri", redirectUri);
@@ -55,6 +55,10 @@ export function buildAuthorizeUrl({ serverUrl, clientId, redirectUri, state, cod
   url.searchParams.set("state", state);
   url.searchParams.set("code_challenge", codeChallenge);
   url.searchParams.set("code_challenge_method", "S256");
+  // BOT-1566: `login --tenant <slug>` preselects the tenant. /authorize forwards
+  // it to the /mcp-auth picker as `requestedTenant`; membership is still
+  // enforced server-side at authorize_complete — this only preselects.
+  if (tenant) url.searchParams.set("tenant", tenant);
   return url.toString();
 }
 

package/src/profile-bootstrap.mjs

@@ -27,6 +27,15 @@ export function defaultProfileAgentName(profile) {
   return `${profile}-${host || "host"}-${suffix}`;
 }
 
+// A structured MCP error code can arrive on a tool result body (`data.code`) or,
+// for a 401/403, on the top-level auth receipt (`code`) that callToolJson lifts
+// out of the JSON-RPC error body (BOT-1561). Read whichever is present.
+function structuredCode(response) {
+  if (typeof response?.data?.code === "string") return response.data.code;
+  if (typeof response?.code === "string") return response.code;
+  return null;
+}
+
 function registrationCredential(data) {
   return typeof data?.agent_api_key === "string"
     ? data.agent_api_key
@@ -81,8 +90,27 @@ export async function bootstrapProfile(profileName, {
   const pinned = await resolveAuth();
   if (pinned?.error) throw new ProfileBootstrapError("profile_agent_required");
   const auth = pinned?.auth ?? null;
-  const identity = await call("whoami", {}, { auth });
-  const identityCode = typeof identity?.data?.code === "string" ? identity.data.code : null;
+  // BOT-1561: a multi-tenant owner's OAuth credential is tenant-ambiguous, so an
+  // unpinned whoami returns no tenant_id and BOT-1487's gate throws
+  // profile_tenant_unverified. Each profile already knows its tenant, so pin it
+  // on BOTH calls: whoami resolves/confirms exactly that tenant (the server
+  // refuses a non-member owner → profile_credential_wrong_tenant below), and
+  // register_agent mints in the pinned tenant. Preserves BOT-1487's fail-closed
+  // + single-credential pinning guarantees.
+  const tenant = profile.tenant;
+  const identity = await call("whoami", {}, { auth, tenant });
+  const identityCode = structuredCode(identity);
+  // BOT-1561: the server refuses the pin with MCP_TENANT_MEMBERSHIP_REQUIRED
+  // (HTTP 403) when the credential cannot register in the profile's tenant —
+  // either the owner is not a member, or a tenant-bound login is sealed to a
+  // DIFFERENT tenant (resolveHintedTenant never repoints a bound credential).
+  // callToolJson now preserves that code from the 403 body; map it to the
+  // wrong-tenant outcome so setup reports the accurate, actionable failure
+  // instead of the misleading profile_tenant_unverified the swallowed 403
+  // previously produced. register_agent never runs.
+  if (identityCode === "MCP_TENANT_MEMBERSHIP_REQUIRED") {
+    throw new ProfileBootstrapError("profile_credential_wrong_tenant");
+  }
   if (identityCode === "MCP_TENANT_SELECTION_REQUIRED" || identityCode === "MCP_TENANT_CONTEXT_IS_AUTH_ONLY") {
     throw new ProfileBootstrapError("profile_tenant_selection_required");
   }
@@ -100,14 +128,18 @@ export async function bootstrapProfile(profileName, {
     type: "codex",
     ...(reusableIdentity ? { agent_id: reusableIdentity } : {}),
   };
-  const response = await call("register_agent", args, { auth });
+  const response = await call("register_agent", args, { auth, tenant });
   const data = response?.data;
+  const responseCode = structuredCode(response);
   // Defense-in-depth: whoami above already gated on the tenant, so register_agent
   // should not return a tenant-context error here — but if the contract drifts,
   // surface its own actionable recovery, not the misleading
   // `profile_agent_required` → `botbuddy login` loop that keeps failing because
   // login itself is fine.
-  if (data?.code === "MCP_TENANT_CONTEXT_IS_AUTH_ONLY" || data?.code === "MCP_TENANT_SELECTION_REQUIRED") {
+  if (responseCode === "MCP_TENANT_MEMBERSHIP_REQUIRED") {
+    throw new ProfileBootstrapError("profile_credential_wrong_tenant");
+  }
+  if (responseCode === "MCP_TENANT_CONTEXT_IS_AUTH_ONLY" || responseCode === "MCP_TENANT_SELECTION_REQUIRED") {
     throw new ProfileBootstrapError("profile_tenant_selection_required");
   }
   if (!response?.ok || (response.isError && data?.code !== "FRESH_CONNECTION_REQUIRED")) {
@@ -173,6 +205,16 @@ export function profileBootstrapRecovery(code, profileName) {
   if (code === "profile_credential_persist_failed") {
     return `ensure ~/.botbuddy is writable and no other setup is running, then re-run: botbuddy profile setup ${profileName}`;
   }
+  if (code === "profile_credential_wrong_tenant") {
+    // BOT-1561: reached when the login is authorized for a different tenant (a
+    // tenant-bound token can't be repointed) or the owner isn't a member of the
+    // profile's tenant. The fix is to authenticate INTO the profile's tenant —
+    // not the bare login loop, which relogs into the same wrong tenant.
+    const tenant = getAgentProfile(profileName)?.tenant;
+    return tenant
+      ? `run botbuddy login and select the "${tenant}" tenant during authentication, then re-run: botbuddy profile setup ${profileName} (if you are not a member of "${tenant}", ask an admin for access)`
+      : `run botbuddy login and select the profile's tenant during authentication, then re-run: botbuddy profile setup ${profileName}`;
+  }
   if (code === "profile_tenant_unverified") {
     // whoami could not confirm the bound tenant, so registration was refused
     // before any mutation. Usually transient — retry; login only if it persists.

package/src/update-check.mjs

@@ -0,0 +1,127 @@
+// BOT-1566 D: stale-CLI warning + `botbuddy update`.
+//
+// The CLI is published to npm; a human running an old build gets no signal
+// that a fix already shipped (the BOT-1566 keychain bug was found on a CLI two
+// releases behind). `maybeWarnStale` prints ONE line to stderr when npm's
+// `latest` is newer than the running version. It is throttled through a 24h
+// JSON cache at ~/.botbuddy/update-check.json, bounded by a 1500 ms registry
+// timeout, and fail-open: any error (offline, registry down, unreadable cache)
+// is silent. It never writes to stdout — JSON receipts own stdout.
+//
+// `cmdUpdate` deliberately does NOT update in-process (BOT-1499: a self-update
+// that replaces its own running files can kill itself mid-install). It hands
+// off to a detached, unref'd `npm install -g` and exits 0.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { VERSION } from "./version.mjs";
+
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const NPM_LATEST_URL = "https://registry.npmjs.org/@botbuddy/cli/latest";
+export const NPM_LATEST_TIMEOUT_MS = 1500;
+export const UPDATE_COMMAND = "npm i -g @botbuddy/cli@latest";
+
+export function defaultUpdateCheckCachePath(home = homedir()) {
+  return join(home, ".botbuddy", "update-check.json");
+}
+
+function parseSemver(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(String(value ?? "").trim());
+  if (!match) return null;
+  return { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4] ?? null };
+}
+
+// True when `latest` is strictly greater than `current`. Numeric per segment;
+// a prerelease of the same core version ranks below the release. Unparseable
+// input is never "newer" — a garbage registry answer must not nag.
+export function isNewerVersion(latest, current) {
+  const a = parseSemver(latest);
+  const b = parseSemver(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a.parts[i] !== b.parts[i]) return a.parts[i] > b.parts[i];
+  }
+  if (a.prerelease && !b.prerelease) return false;
+  if (!a.prerelease && b.prerelease) return true;
+  return false;
+}
+
+export async function fetchLatestFromNpm({ fetchImpl = fetch, timeoutMs = NPM_LATEST_TIMEOUT_MS } = {}) {
+  const res = await fetchImpl(NPM_LATEST_URL, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`npm registry responded ${res.status}`);
+  const body = await res.json();
+  if (typeof body?.version !== "string") throw new Error("npm registry response carried no version");
+  return body.version;
+}
+
+async function readCache(cachePath) {
+  try {
+    const parsed = JSON.parse(await readFile(cachePath, "utf8"));
+    if (typeof parsed?.checkedAt !== "number") return null;
+    // `latest` is a version string, or null for a recorded-but-failed attempt
+    // (offline/registry-down) that still counts toward the 24h throttle.
+    if (parsed.latest !== null && typeof parsed.latest !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCache(cachePath, entry) {
+  await mkdir(dirname(cachePath), { recursive: true, mode: 0o700 });
+  await writeFile(cachePath, JSON.stringify(entry), { mode: 0o600 });
+}
+
+export async function maybeWarnStale({
+  version = VERSION,
+  fetchLatest = fetchLatestFromNpm,
+  now = () => Date.now(),
+  cachePath = defaultUpdateCheckCachePath(),
+  stderr = process.stderr,
+} = {}) {
+  try {
+    const cached = await readCache(cachePath);
+    let latest;
+    if (cached && now() - cached.checkedAt < UPDATE_CHECK_INTERVAL_MS) {
+      latest = cached.latest;
+    } else {
+      // BOT-1566 (Codex P2): run() awaits this for nearly every command, so a
+      // failed lookup (offline/registry-down/garbage) MUST still stamp the
+      // attempt — otherwise the throttle never engages and every invocation
+      // retries and can eat the full timeout. Retain any previously-known
+      // latest so we can still warn from it.
+      let fetched = null;
+      try {
+        fetched = await fetchLatest();
+      } catch {
+        fetched = null;
+      }
+      latest = typeof fetched === "string" ? fetched : (cached?.latest ?? null);
+      await writeCache(cachePath, { checkedAt: now(), latest });
+    }
+    if (typeof latest !== "string" || !isNewerVersion(latest, version)) return { warned: false, latest: latest ?? null };
+    stderr.write(`botbuddy: update available ${version} → ${latest}: ${UPDATE_COMMAND}\n`);
+    return { warned: true, latest };
+  } catch {
+    return { warned: false, latest: null };
+  }
+}
+
+// `botbuddy update` — hand off to npm and get out of the way.
+export function cmdUpdate({ version = VERSION, spawnImpl = spawn, log = (line) => console.log(line), platform = process.platform } = {}) {
+  log(`current: ${version}`);
+  // BOT-1566 (Codex P2): on Windows npm is the `npm.cmd` shim, and a shell-free
+  // spawn cannot execute .cmd scripts (Node docs) — it would ENOENT after we
+  // already claimed the update started. Select the platform-correct binary.
+  const npmBin = platform === "win32" ? "npm.cmd" : "npm";
+  const child = spawnImpl(npmBin, ["install", "-g", "@botbuddy/cli@latest"], { stdio: "inherit", detached: true });
+  child.unref();
+  log("updating in background — re-run botbuddy --version to confirm");
+  return 0;
+}

package/src/botbuddy-release-repair.json

@@ -1 +0,0 @@
-{"schema_version":1,"source_version":"1.9.0","source_identity":"8bc02282f116b4857951c61a187ad7894c3153b36559b46cd171df24b0af98c4"}