@botbuddy/cli 1.30.0 → 1.30.1

package/package.json

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

package/src/agent-doctor.mjs

@@ -0,0 +1,93 @@
+// BOT-1649 — diagnose and repair a worktree's short-lived agent credential
+// without ever printing the token unless the operator explicitly requests an
+// export snippet for the current shell.
+import { readAgentBinding } from "./wait-profile.mjs";
+import { resolveOwnerToken } from "./cli-credentials.mjs";
+import { getConfig } from "./config.mjs";
+import { isAgentStateFresh, readAgentState } from "./agent-state.mjs";
+import { selfHealAgentSession } from "./agent-session.mjs";
+
+export function parseDoctorArgs(argv = []) {
+  const parsed = { fix: false, printExports: false, json: false, errors: [] };
+  for (const arg of argv) {
+    if (arg === "--fix") parsed.fix = true;
+    else if (arg === "--print-exports") parsed.printExports = true;
+    else if (arg === "--json") parsed.json = true;
+    else if (arg === "--help" || arg === "-h") parsed.help = true;
+    else parsed.errors.push(`unknown option: ${arg}`);
+  }
+  return parsed;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * BOT-1649 (Codex P2): a durable login token past its `expiresAt` can no longer
+ * mint a session — the server rejects it as `session_mint_failed`. Report it as
+ * `expired` (not `available`) so `--fix` does not try to repair the cache and the
+ * verdict points at `bb login` instead of a bogus binding repair.
+ */
+function clientKeyStatus(owner, nowMs) {
+  if (!owner?.token) return { status: "missing" };
+  if (typeof owner.expiresAt === "number" && owner.expiresAt <= nowMs) return { status: "expired" };
+  return { status: "available" };
+}
+
+/** Inspect a worktree credential. Only `exports` ever contains the secret. */
+export async function doctorAgentAuth({
+  cwd = process.cwd(), env = process.env, fix = false, printExports = false,
+  readState = readAgentState, isFresh = isAgentStateFresh, now = () => Date.now(),
+  binding = readAgentBinding, ownerToken = () => resolveOwnerToken({ getConfig }),
+  selfHeal = selfHealAgentSession,
+} = {}) {
+  const [state, bound, owner] = await Promise.all([
+    readState(cwd), binding(cwd).catch(() => null), ownerToken().catch(() => null),
+  ]);
+  const fresh = Boolean(state && isFresh(state, new Date()));
+  const report = {
+    schema_version: 1,
+    worktree: cwd,
+    binding: bound?.tenant ? { status: "available", tenant: bound.tenant } : { status: "missing" },
+    client_key: clientKeyStatus(owner, now()),
+    session: fresh
+      ? { status: "fresh", agent_id: state.agent_id, session_id: state.session_id, expires_at: state.expires_at }
+      : { status: state ? "stale" : "missing" },
+  };
+  let credential = fresh
+    ? { token: state.agent_session_token, sessionId: state.session_id, agentId: state.agent_id, source: "cache" }
+    : null;
+  if (!fresh && fix && report.binding.status === "available" && report.client_key.status === "available") {
+    try {
+      credential = await selfHeal({ cwd, env });
+      report.session = { status: credential.source === "minted" ? "minted" : credential.source, agent_id: credential.agentId ?? null, session_id: credential.sessionId ?? null };
+    } catch (error) {
+      report.session = { status: "repair_failed", error: error?.code ?? "agent_session_unavailable" };
+      report.recovery = error?.code === "client_key_required"
+        ? "run `bb login`, then `bb doctor --fix`"
+        : "repair .botbuddy-agent.json, then run `bb doctor --fix`";
+      return { exitCode: 3, report, exports: null };
+    }
+  }
+  if (!credential) {
+    const needsLogin = report.client_key.status === "missing" || report.client_key.status === "expired";
+    report.recovery = needsLogin
+      ? "run `bb login`, then `bb doctor --fix`"
+      : report.binding.status === "missing"
+        ? "add a valid .botbuddy-agent.json tenant binding, then run `bb doctor --fix`"
+        : "run `bb doctor --fix` to mint a replacement session";
+    return { exitCode: 3, report, exports: null };
+  }
+  const exports = printExports
+    ? [
+      `export BOTBUDDY_AGENT_SESSION_TOKEN=${shellQuote(credential.token)}`,
+      ...(credential.sessionId ? [`export BOTBUDDY_SESSION_ID=${shellQuote(credential.sessionId)}`] : []),
+    ].join("\n")
+    : null;
+  return { exitCode: 0, report, exports };
+}
+
+export function doctorHelp() {
+  return "bb doctor [--fix] [--print-exports] [--json]\n\nChecks the client key, repo binding, and cached agent session. --fix mints a replacement session; --print-exports prints its canonical shell exports.";
+}

package/src/agent-key.mjs

@@ -1,29 +1,34 @@
-// BOT-1582 — the per-session agent key the CLI presents to the relay for
+// BOT-1649 — the per-session agent token the CLI presents to the relay for
 // `botbuddy wait`/`run`/`test`/`pw`.
 //
 // register_agent mints this token (bound to the work-graph session it returns)
 // and the relay derives agent, tenant, and the arming session from it, so a
 // session that exports it needs no --profile/--session-id/--token.
 //
-// Prefix: `bb_agent_` + 64 lowercase hex, mirroring the server's SESSION_TOKEN_RE
-// (supabase/functions/_shared/sessionToken.ts). The BOT-1572 `bb_sess_` shape is
+// Prefix: `bb_sess_` + 64 lowercase hex, mirroring the server's SESSION_TOKEN_RE
+// (supabase/functions/_shared/sessionToken.ts). The prior `bb_agent_` shape is
 // accepted as a legacy alias for one release (its hash is already on `sessions`).
 // This is a SHAPE check only — authorization is the server's hashed lookup.
 export const AGENT_KEY_RE = /^bb_(agent|sess)_[0-9a-f]{64}$/;
 
-// BOT-1582: the env var was renamed BOTBUDDY_SESSION_TOKEN → BOTBUDDY_AGENT_KEY.
-// The new name wins; the old one is honoured for one release so a session that
-// still exports it keeps working. Returns null when neither is set.
+// BOT-1649: BOTBUDDY_AGENT_SESSION_TOKEN names the short-lived credential
+// honestly. BOTBUDDY_AGENT_KEY and BOTBUDDY_SESSION_TOKEN remain aliases for one
+// release. Returns null when none is set.
 //
 // An EMPTY/blank value counts as unset (not as a present-but-empty token): an env
 // template that declares BOTBUDDY_AGENT_KEY="" while a valid BOTBUDDY_SESSION_TOKEN
 // is still exported must fall through to the legacy name, or the one-release
 // compatibility guarantee breaks (Codex P2). So trim and skip blanks rather than
 // `??`, which would stop at the empty string.
-export function readAgentKeyEnv(env = process.env) {
-  const first = typeof env.BOTBUDDY_AGENT_KEY === "string" ? env.BOTBUDDY_AGENT_KEY.trim() : "";
-  if (first) return env.BOTBUDDY_AGENT_KEY;
+export function readAgentSessionTokenEnv(env = process.env) {
+  const canonical = typeof env.BOTBUDDY_AGENT_SESSION_TOKEN === "string" ? env.BOTBUDDY_AGENT_SESSION_TOKEN.trim() : "";
+  if (canonical) return env.BOTBUDDY_AGENT_SESSION_TOKEN;
+  const alias = typeof env.BOTBUDDY_AGENT_KEY === "string" ? env.BOTBUDDY_AGENT_KEY.trim() : "";
+  if (alias) return env.BOTBUDDY_AGENT_KEY;
   const legacy = typeof env.BOTBUDDY_SESSION_TOKEN === "string" ? env.BOTBUDDY_SESSION_TOKEN.trim() : "";
   if (legacy) return env.BOTBUDDY_SESSION_TOKEN;
   return null;
 }
+
+// Deprecated exported alias for downstream CLI integrations.
+export const readAgentKeyEnv = readAgentSessionTokenEnv;

package/src/agent-state.mjs

@@ -0,0 +1,166 @@
+// BOT-1649 — a per-worktree, gitignored cache for the short-lived agent session.
+// It deliberately holds a session token (mode 0600), never a durable client key.
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, parse } from "node:path";
+import { randomUUID } from "node:crypto";
+import { AGENT_KEY_RE } from "./agent-key.mjs";
+import { acquireStackLock } from "./stack-file-lock.mjs";
+
+// BOT-1649 (Codex round-4 P2): every mutation of the cache (self-heal mint, an
+// SSE keepalive expiry touch, logout's clear) must be serialized on ONE lock —
+// the same `<agent-state>.lock` selfHealAgentSession takes — so a delayed touch
+// can never rename a stale credential back over a newer mint or a logout delete.
+async function withStateLock(cwd, { timeoutMs } = {}, fn) {
+  const lockPath = `${await agentStatePath(cwd)}.lock`;
+  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const lease = await acquireStackLock(lockPath, timeoutMs ? { timeoutMs } : {});
+  try { return await fn(); } finally { lease.release(); }
+}
+
+export const AGENT_STATE_DIR = ".botbuddy";
+export const AGENT_STATE_FILE = "agent-state.json";
+export const AGENT_STATE_PATH = join(AGENT_STATE_DIR, AGENT_STATE_FILE);
+// A stable, per-machine random id kept under the user's home (not a worktree),
+// so every worktree on one machine shares it and two machines never do.
+export const MACHINE_ID_PATH = join(AGENT_STATE_DIR, "machine-id");
+
+async function exists(path) {
+  try { await readFile(path); return true; } catch { return false; }
+}
+
+/** Locate the nearest worktree metadata directory without ever escaping upward
+ * past a repository binding. A standalone caller falls back to its cwd. */
+export async function findAgentStateRoot(cwd = process.cwd()) {
+  let dir = cwd;
+  const root = parse(dir).root;
+  while (true) {
+    if (await exists(join(dir, ".botbuddy-agent.json")) || await exists(join(dir, AGENT_STATE_DIR))) return dir;
+    if (dir === root) return cwd;
+    dir = dirname(dir);
+  }
+}
+
+export async function agentStatePath(cwd = process.cwd()) {
+  return join(await findAgentStateRoot(cwd), AGENT_STATE_PATH);
+}
+
+function validState(value) {
+  return Boolean(value) && typeof value === "object" && value.schema_version === 1
+    && typeof value.agent_id === "string" && value.agent_id.length > 0
+    && typeof value.agent_session_token === "string" && AGENT_KEY_RE.test(value.agent_session_token)
+    && (typeof value.session_id === "string" || value.session_id === null)
+    && typeof value.tenant === "string" && value.tenant.length > 0
+    && typeof value.host === "string" && value.host.length > 0
+    && typeof value.worktree === "string" && value.worktree.length > 0
+    && typeof value.minted_at === "string" && !Number.isNaN(Date.parse(value.minted_at))
+    && typeof value.expires_at === "string" && !Number.isNaN(Date.parse(value.expires_at));
+}
+
+/** Never throw malformed cache contents into credential resolution. */
+export async function readAgentState(cwd = process.cwd()) {
+  try {
+    const value = JSON.parse(await readFile(await agentStatePath(cwd), "utf8"));
+    return validState(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomically replace cache content and ensure the destination remains owner-only. */
+export async function writeAgentState(cwd, state) {
+  if (!validState(state)) throw new Error("agent state is missing required fields");
+  const path = await agentStatePath(cwd);
+  const directory = dirname(path);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const temp = join(directory, `.${AGENT_STATE_FILE}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temp, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    await chmod(temp, 0o600);
+    await rename(temp, path);
+    await chmod(path, 0o600);
+  } finally {
+    try { await unlink(temp); } catch { /* rename or failed write already removed it */ }
+  }
+  return path;
+}
+
+/** The expiry must be more than skewSeconds away; exactly at the boundary is stale. */
+export function isAgentStateFresh(state, now = new Date(), skewSeconds = 300) {
+  if (!validState(state)) return false;
+  const expiresAt = Date.parse(state.expires_at);
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  return Number.isFinite(nowMs) && expiresAt - (skewSeconds * 1000) > nowMs;
+}
+
+export async function clearAgentState(cwd = process.cwd()) {
+  return withStateLock(cwd, {}, async () => {
+    try {
+      await unlink(await agentStatePath(cwd));
+      return true;
+    } catch (error) {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    }
+  });
+}
+
+// The session-token lifetime the server mints (SESSION_TOKEN_TTL_MS, 8 h). The
+// server rolls session_token_expires_at to now + this on every relay use.
+export const SESSION_TOKEN_TTL_MS = 8 * 60 * 60 * 1000;
+
+/**
+ * BOT-1649 (Codex P1): the server rolls `session_token_expires_at` forward on
+ * every relay use, but the local cache keeps its original deadline — so an
+ * actively-used session can be wrongly judged stale and re-minted, which revokes
+ * the token a concurrent wait still holds. After a successful relay use, mirror
+ * the server's roll into the cache (only when it still holds the SAME token we
+ * used, so we never extend a credential that isn't the one just accepted).
+ */
+export async function touchAgentStateExpiry(cwd, token, now = new Date(), ttlMs = SESSION_TOKEN_TTL_MS) {
+  if (!token) return false;
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) return false;
+  // Best-effort and fire-and-forget from the SSE loop: fail fast on contention
+  // (self-heal holds the lock across a network mint) rather than piling up.
+  try {
+    return await withStateLock(cwd, { timeoutMs: 3000 }, async () => {
+      // Re-read INSIDE the lock so a concurrent mint/clear that changed the token
+      // (or removed the cache) is seen — never resurrect a replaced/deleted cache.
+      const state = await readAgentState(cwd);
+      if (!state || state.agent_session_token !== token) return false;
+      await writeAgentState(cwd, { ...state, expires_at: new Date(nowMs + ttlMs).toISOString() });
+      return true;
+    });
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * BOT-1649 (Codex P1): the server's technical agent name must be globally
+ * unique, but `hostname()` + worktree path collide across two operators running
+ * standardized containers with the same hostname and checkout path — the second
+ * operator's first self-heal then fails with `agent_name_taken`. Fold in a
+ * persisted, per-machine random id (created once, mode 0600) so the name carries
+ * entropy no host-provided identifier can supply. Two machines never share it
+ * (separate filesystems); a read-only home degrades to a per-process id, which
+ * still avoids cross-machine collision.
+ */
+export async function resolveMachineId({
+  home = homedir(), read = readFile, write = writeFile, makeDir = mkdir,
+  setMode = chmod, newId = () => randomUUID(),
+} = {}) {
+  const path = join(home, MACHINE_ID_PATH);
+  try {
+    const existing = (await read(path, "utf8")).trim();
+    if (/^[0-9a-f-]{8,}$/i.test(existing)) return existing;
+  } catch { /* missing or unreadable — mint one below */ }
+  const id = newId();
+  try {
+    await makeDir(dirname(path), { recursive: true, mode: 0o700 });
+    await write(path, `${id}\n`, { encoding: "utf8", mode: 0o600 });
+    await setMode(path, 0o600);
+  } catch { /* a read-only home still yields a usable (if unpersisted) id */ }
+  return id;
+}

package/src/commands.mjs

@@ -1,4 +1,7 @@
 import os from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
 import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
 import { runBridge } from "./codex-bridge.mjs";
@@ -22,6 +25,8 @@ import { maybeWarnStale, cmdUpdate } from "./update-check.mjs";
 import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "./telemetry-config.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
+import { doctorAgentAuth, doctorHelp, parseDoctorArgs } from "./agent-doctor.mjs";
+import { clearAgentState, selfHealAgentSession } from "./agent-session.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)
@@ -45,8 +50,10 @@ export async function run(argv, {
   switch (command) {
     case "start": return cmdStart(args);
     case "login": return cmdLogin(args, { errorLog });
+    case "setup": return cmdSetup(args, { errorLog });
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
+    case "doctor": return cmdDoctor(args);
     case "update": return cmdUpdate();
     // Agent-only commands (used by MCP agents, not humans)
     case "heartbeat": return cmdHeartbeat(args);
@@ -133,8 +140,12 @@ ${bold("OPTIONS")}
 ${bold("AUTH")}
   login [--no-browser] [--tenant <slug>] [--caller <name>] [--caller-harness <h>] [--caller-ticket <ref>]
                              Authenticate via OAuth (opens browser + localhost callback)
+  setup [--no-browser] [--tenant <slug>]
+                             Bootstrap this bound worktree for variable-free waits
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
+  doctor [--fix] [--print-exports] [--json]
+                             Diagnose or repair the cached agent session
 
 ${bold("MCP CONFIG KEY")}
   mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
@@ -190,6 +201,23 @@ ${bold("OTHER")}
 ${SETUP_BLOCK}`);
 }
 
+export async function cmdDoctor(args, { log = (line) => console.log(line), errorLog = (line) => console.error(line) } = {}) {
+  const parsed = parseDoctorArgs(args);
+  if (parsed.help) { log(doctorHelp()); return 0; }
+  if (parsed.errors.length) { errorLog(`bb doctor: ${parsed.errors.join("; ")}`); return 4; }
+  const result = await doctorAgentAuth({ fix: parsed.fix, printExports: parsed.printExports });
+  if (parsed.json) {
+    log(JSON.stringify(result.report));
+  } else {
+    log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
+    log(`client key: ${result.report.client_key.status}`);
+    log(`agent session: ${result.report.session.status}`);
+    if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
+  }
+  if (result.exports) log(result.exports);
+  return result.exitCode;
+}
+
 // ─── BOT-876: generic tool access ───────────────────────────────
 
 async function cmdCall(args) {
@@ -290,19 +318,53 @@ export function parseLoginArgs(args) {
 // BOTBUDDY_CALLER* environment variables so an agent harness can advertise who it
 // is without every wrapper having to pass flags. A flag always wins over the env.
 // Returns only the three caller fields; empty values collapse to null.
-export function resolveCaller(parsed = {}, env = {}) {
-  const pick = (flagVal, envKey) => {
+function gitHint(cwd, args) {
+  try { return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 1_000 }).trim() || null; }
+  catch { return null; }
+}
+
+/** Best-effort display-only context. It is never an authorization input. */
+export function deriveCallerHint({ env = process.env, cwd = process.cwd() } = {}) {
+  let cachedAgentId = null;
+  try {
+    const path = join(cwd, ".botbuddy", "agent-state.json");
+    if (existsSync(path)) {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      cachedAgentId = typeof parsed?.agent_id === "string" && parsed.agent_id ? parsed.agent_id : null;
+    }
+  } catch { /* a malformed cache is not a login failure */ }
+  const branch = gitHint(cwd, ["branch", "--show-current"]);
+  const ticket = branch?.match(/(?:^|\/)((?:bot|ent)-\d+)(?:-|$)/i)?.[1]?.toUpperCase() ?? null;
+  const remote = gitHint(cwd, ["remote", "get-url", "origin"]);
+  const repo = remote?.match(/(?:github\.com[:/])([^/]+\/[^/.]+)(?:\.git)?$/i)?.[1] ?? null;
+  const harness = env.BOTBUDDY_CALLER_HARNESS
+    || (env.CLAUDE_CODE || env.CLAUDECODE ? "claude-code" : Object.keys(env).some((key) => key.startsWith("CODEX_")) ? "codex" : null);
+  return {
+    caller: env.BOTBUDDY_AGENT_NAME || (cachedAgentId ? `agent ${cachedAgentId}` : repo),
+    callerHarness: harness,
+    callerTicket: ticket ? `https://linear.app/botbuddy/issue/${ticket}` : null,
+  };
+}
+
+export function resolveCaller(parsed = {}, env = {}, { cwd = process.cwd(), derive = deriveCallerHint } = {}) {
+  const inferred = derive({ env, cwd });
+  const pick = (field, envKey, inferredValue) => {
+    const flagVal = parsed[field];
     // A flag that was PROVIDED wins over the environment, even when it is an
     // explicit empty `--caller=` — that is how a user clears a stale inherited
     // identity, so it must NOT fall back to the env. `null` means the flag was
     // omitted → fall back to the env var. Either way an empty result is null.
-    const raw = flagVal != null ? flagVal : env[envKey];
-    return typeof raw === "string" && raw !== "" ? raw : null;
+    if (flagVal != null) return typeof flagVal === "string" && flagVal !== "" ? flagVal : null;
+    if (Object.prototype.hasOwnProperty.call(env, envKey)) {
+      const raw = env[envKey];
+      return typeof raw === "string" && raw !== "" ? raw : null;
+    }
+    return inferredValue ?? null;
   };
   return {
-    caller: pick(parsed.caller, "BOTBUDDY_CALLER"),
-    callerHarness: pick(parsed.callerHarness, "BOTBUDDY_CALLER_HARNESS"),
-    callerTicket: pick(parsed.callerTicket, "BOTBUDDY_CALLER_TICKET"),
+    caller: pick("caller", "BOTBUDDY_CALLER", inferred.caller),
+    callerHarness: pick("callerHarness", "BOTBUDDY_CALLER_HARNESS", inferred.callerHarness),
+    callerTicket: pick("callerTicket", "BOTBUDDY_CALLER_TICKET", inferred.callerTicket),
   };
 }
 
@@ -328,6 +390,80 @@ async function cmdLogin(args, { errorLog = (line) => console.error(line) } = {})
   }
 }
 
+/** Bootstrap a bound worktree without exposing credential or registration steps. */
+export async function cmdSetup(args, {
+  login = doLogin,
+  binding = readAgentBinding,
+  clearState = clearAgentState,
+  selfHeal = selfHealAgentSession,
+  callerResolver = resolveCaller,
+  cwd = process.cwd(),
+  env = process.env,
+  log = (line) => console.log(line),
+  errorLog = (line) => console.error(line),
+} = {}) {
+  let options;
+  try {
+    options = parseLoginArgs(args);
+  } catch (error) {
+    if (!(error instanceof LoginUsageError)) throw error;
+    errorLog(error.message);
+    return error.exitCode === 2 ? 2 : 4;
+  }
+  if (options.help) {
+    log("bb setup [--no-browser] [--tenant <slug>]\n\nSigns in, verifies the committed .botbuddy-agent.json binding, and caches this worktree's session. After it succeeds, use `bb wait <condition>` with no credential flags or environment variables.");
+    return 0;
+  }
+  let bound;
+  try {
+    bound = await binding(cwd);
+  } catch (error) {
+    errorLog(`bb setup: ${error?.code ?? "invalid_binding"}; fix the committed .botbuddy-agent.json binding and retry.`);
+    return 4;
+  }
+  if (!bound?.tenant) {
+    errorLog("bb setup: no .botbuddy-agent.json binding found; run this from a configured project worktree.");
+    return 4;
+  }
+  if (options.tenant && options.tenant !== bound.tenant) {
+    errorLog(`bb setup: requested tenant ${options.tenant} does not match this worktree's ${bound.tenant} binding.`);
+    return 4;
+  }
+  const tenant = bound.tenant;
+  try {
+    // Login owns a machine/user credential, not a worktree tenant credential.
+    // The committed binding below is the only place setup scopes the minted
+    // session.  Forwarding --tenant here would overwrite a multi-tenant user's
+    // reusable client key with a tenant-sealed one.
+    await login({ noBrowser: options.noBrowser, ...callerResolver(options, env) });
+    // Setup is an explicit session bootstrap/repair command. Rotate before
+    // resolving so it cannot merely report an old cache as ready.
+    await clearState(cwd);
+    const session = await selfHeal({ cwd, env });
+    // BOT-1649 (Codex round-6 P1): register_agent reports any OTHER live session
+    // already holding this ticket (heartbeat < 15m) in `ticket_signals`. One
+    // ticket = one live session is a hard stop (AGENTS.md), so refuse to report
+    // the worktree ready — otherwise setup silently green-lights a second coding
+    // session on the ticket. The mint above re-adopts this worktree's own agent
+    // and is not itself a second holder.
+    const holders = session.ticketSignals?.concurrency?.holders;
+    if (Array.isArray(holders) && holders.length > 0) {
+      const warning = session.ticketSignals.concurrency.warning
+        || `another live session already holds ${tenant}'s ticket`;
+      const who = holders
+        .map((h) => `${h.agent ?? h.agent_id}${h.branch ? ` (${h.branch})` : ""}`)
+        .join(", ");
+      errorLog(`bb setup: ${warning} — held by ${who}. Do not start a second coding session on this ticket; hand off to the live holder or wait for it to finish.`);
+      return 5;
+    }
+    log(`bb setup: ${tenant} is ready (${session.source} worktree session). Run bb wait '<condition>'.`);
+    return 0;
+  } catch (error) {
+    errorLog(`bb setup: could not prepare this worktree (${error?.code ?? "setup_failed"}). Retry bb setup after completing sign-in.`);
+    return 3;
+  }
+}
+
 export function loginHelp(log = console.log) {
   log(`${bold("botbuddy login")} — authenticate via OAuth (browser + loopback callback)
 
@@ -338,10 +474,10 @@ ${bold("USAGE")}
 ${bold("TOKEN SCOPE")}
   By default login installs this machine's ${bold("client key (bb_cli_)")}: a user
   token that is not bound to a tenant and reaches every tenant you belong to —
-  each request pins one. ONE login serves ALL tenants; ${cyan("register_agent")} then
-  exchanges it for a per-session agent token. No per-tenant credential is needed
-  for normal use — mint a ${bold("bb_mcp_")} key per tenant (${cyan("botbuddy mcp setup")}) only
-  when a repo binds a distinct ${dim("mcp_env")}.
+  each request pins one. ONE login serves ALL tenants. For a project worktree,
+  use ${cyan("bb setup")} to finish setup and cache its session; normal waits need
+  no further credential commands. Mint a ${bold("bb_mcp_")} key per tenant (${cyan("botbuddy mcp setup")}) only
+  when configuring an MCP client.
   ${cyan("--tenant <slug>")} instead mints a ${bold("tenant token")} sealed to that one
   tenant (the MCP-session model); use it only when you want that guarantee.
 
@@ -592,9 +728,12 @@ export async function cmdStatus({
   log(`  Run: ${cyan("botbuddy start")}`);
 }
 
-async function cmdLogout() {
+export async function cmdLogout({ cwd = process.cwd(), clearState = clearAgentState } = {}) {
   clearConfig();
   await clearOwnerToken();
+  // The cached session is a bearer credential. Removing its durable precursor
+  // must also remove the per-worktree cache so logout cannot leave a live wait.
+  await clearState(cwd);
   console.log(`${green("✓")} Logged out. Credentials removed.`);
 }
 

package/src/credential-kinds.mjs

@@ -20,17 +20,10 @@ export const CREDENTIAL_PREFIXES = [
   // BOT-1607: the tier-2 MCP config key a .mcp.json presents (independently
   // revocable; minted by `botbuddy mcp`). Unambiguous by prefix.
   { prefix: "bb_mcp_", kind: "mcp", label: "MCP key" },
-  // BOT-1573/1582 transition: bb_agent_ is now BOTH the per-session agent token
-  // (BOT-1582 renamed it from bb_sess_) AND the older shared service carrier, so
-  // the prefix ALONE can no longer tell them apart. Classification is display
-  // only (never auth), and mislabelling a live carrier as an agent is worse than
-  // the reverse, so bb_agent_ stays classified as the carrier — matching the UI
-  // adapter. bb_sess_ (in-flight BOT-1572 tokens, accepted one release) is the
-  // one unambiguously-a-session shape, so it keeps the agent kind. A
-  // shape-independent way to name a live bb_agent_ session token is deferred to
-  // the taxonomy/status work (BOT-1573).
-  { prefix: "bb_agent_", kind: "svc", label: "carrier (legacy)" },
-  { prefix: "bb_sess_", kind: "agent", label: "agent (session)" },
+  // BOT-1649: the durable agent identity and the short-lived agent session are
+  // distinct by prefix. This table is display-only; authorization stays server-side.
+  { prefix: "bb_agent_", kind: "agent", label: "agent key" },
+  { prefix: "bb_sess_", kind: "agent_session", label: "agent session token" },
   { prefix: "bb_ci_", kind: "ci", label: "CI key" },
   { prefix: "bb_svc_", kind: "svc", label: "carrier (legacy)" },
   { prefix: "bb_ios_", kind: "ios", label: "device pairing token" },

package/src/pw/coordinator.mjs

@@ -5,7 +5,13 @@ function mcpCaller(authHeader, fetchImpl) {
   let id = 0;
   return async function call(name, args) {
     const response = await fetchImpl(SERVER_URL, { method: "POST", headers: { "content-type": "application/json", ...authHeader }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }) });
-    if (!response.ok) throw new Error(`BotBuddy lock verification returned HTTP ${response.status}`);
+    if (!response.ok) {
+      let payload = null;
+      try { payload = await response.json(); } catch { /* keep the HTTP diagnostic */ }
+      const error = new Error(payload?.error?.message ?? payload?.error ?? `BotBuddy lock verification returned HTTP ${response.status}`);
+      error.code = payload?.error?.code ?? payload?.error?.error ?? payload?.code ?? payload?.error ?? null;
+      throw error;
+    }
     const json = await response.json(); if (json.error) throw new Error(json.error.message || "BotBuddy lock verification failed");
     const text = json.result?.content?.find((item) => item.type === "text")?.text; try { return text ? JSON.parse(text) : {}; } catch { throw new Error("BotBuddy lock verification returned invalid JSON"); }
   };