@botbuddy/cli 1.12.2 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.12.2",
+  "version": "1.13.1",
   "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/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/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/wait.mjs

@@ -399,6 +399,14 @@ function makeConnect(opts) {
     // the agent (and its locks) aren't reaped during a long wait.
     if (opts.heartbeat) url.searchParams.set("heartbeat", "1");
 
+    // BOT-1565: abort the fetch itself on idle. A silently half-open SSE body
+    // already has an `iterator.next()` pending, and `iterator.return()` queues
+    // BEHIND that read — it cannot cancel it until bytes/EOF eventually arrive,
+    // so it would leave the response locked and the socket open while we
+    // reconnect, leaking a connection per stall (Codex P2). Aborting the fetch's
+    // signal tears the stalled socket down immediately, then the read rejects and
+    // the stream ends so runWaitLoop reconnects.
+    const ac = new AbortController();
     const res = await fetch(url, {
       headers: {
         Authorization: `Bearer ${opts.token}`,
@@ -407,12 +415,13 @@ function makeConnect(opts) {
         // BOT-741: never let a proxy gzip-buffer an SSE stream.
         "Accept-Encoding": "identity",
       },
+      signal: ac.signal,
     });
     if (res.status === 401) return errorStream("unauthorized");
     if (res.status === 403) return errorStream("forbidden");
     if (!res.ok || !res.body) throw new Error(`relay responded ${res.status}`);
 
-    return sseFrameStream(res.body);
+    return sseFrameStream(res.body, { onIdle: () => ac.abort() });
   };
 }
 
@@ -468,14 +477,68 @@ function makeFeedLagProbe(opts) {
   };
 }
 
-async function* sseFrameStream(body) {
+// BOT-1565: a silently half-open SSE socket (a network blip, or a gateway/edge
+// connection-lifetime ceiling ~45–51 min) delivers no bytes AND no end-of-stream,
+// so a bare `for await` here would block forever and never reconnect. Meanwhile
+// the relay's last_seen_at keepalive stops bumping and the wait reaper abandons
+// the still-parked wait after its grace → /waits goes blank (BOT-1565). Guard
+// every read with an IDLE watchdog: the relay sends a keepalive comment every
+// ~30s (EVENT_STREAM_KEEPALIVE_MS), and every chunk (comment or frame) resets
+// the timer, so a healthy-but-quiet connection never trips it. If NOTHING
+// arrives for idleMs the connection is presumed dead: end the stream so
+// runWaitLoop reconnects from the cursor, which re-bumps wait_sessions.last_seen_at
+// (and, with --heartbeat, agents.last_heartbeat) before the reaper's grace.
+// 70s ≈ 2.3 missed keepalives — long enough to never false-trip on jitter, short
+// enough that the reconnect lands inside the 90s last_seen reap window.
+export const DEFAULT_SSE_IDLE_TIMEOUT_MS = 70_000;
+
+function sseIdleTimeoutMs() {
+  const raw = Number(process.env.BOTBUDDY_WAIT_IDLE_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SSE_IDLE_TIMEOUT_MS;
+}
+
+const SSE_IDLE = Symbol("sse_idle");
+
+export async function* sseFrameStream(body, { idleMs = sseIdleTimeoutMs(), onIdle = null } = {}) {
   const decoder = new TextDecoder();
   let buf = "";
-  for await (const chunk of body) {
-    buf += decoder.decode(chunk, { stream: true });
-    const { frames, rest } = parseSseFrames(buf);
-    buf = rest;
-    for (const f of frames) yield f;
+  const iterator = body[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      const nextP = iterator.next();
+      let timer;
+      const idle = new Promise((resolve) => { timer = setTimeout(() => resolve(SSE_IDLE), idleMs); });
+      let result;
+      try {
+        result = await Promise.race([nextP, idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (result === SSE_IDLE) {
+        // Presumed dead. onIdle() aborts the underlying fetch (makeConnect wires
+        // it to the request's AbortController) — the ONLY thing that actually
+        // tears a stalled socket down, since iterator.return() would queue behind
+        // the pending read and never fire until bytes/EOF arrive (Codex P2). The
+        // abort settles the pending read (rejects with AbortError); swallow it so
+        // it isn't an unhandled rejection, then end the stream to force a reconnect.
+        nextP.then(() => {}, () => {});
+        if (onIdle) onIdle();
+        return;
+      }
+      const { value: chunk, done } = result;
+      if (done) return;
+      buf += decoder.decode(chunk, { stream: true });
+      const { frames, rest } = parseSseFrames(buf);
+      buf = rest;
+      for (const f of frames) yield f;
+    }
+  } finally {
+    // Belt-and-braces release for the non-idle early-stop path (the consumer
+    // stopped iterating, e.g. runWaitLoop matched). On the idle path the fetch
+    // has already been aborted above, so the body is torn down regardless; this
+    // return() then resolves promptly instead of queuing behind a live read.
+    // Fire-and-forget + swallow: never let teardown block the generator's exit.
+    Promise.resolve(iterator.return?.()).then(() => {}, () => {});
   }
 }