@botbuddy/cli 1.52.0 → 1.53.1

package/package.json

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

package/src/agent-doctor.mjs

@@ -83,6 +83,11 @@ export function repairFailureRecovery(code, error = null) {
   if (code === "agent_tenant_immutable") {
     return "this worktree's agent identity belongs to another tenant; run `bb setup` to register this tenant, then `bb doctor --fix`";
   }
+  // BOT-2415: the cached session names a different agent than the one holding this
+  // worktree's technical name. Deterministic: a retry repeats the same conflict.
+  if (code === "agent_name_conflict") {
+    return "this worktree's cached session (.botbuddy/agent-state.json) names a different agent than the one holding the worktree's technical name; move that file aside, then run `bb doctor --fix`";
+  }
   // BOT-1750 (Codex R9 P2): `session_mint_unauthorized` means a locally-unexpired
   // client key was revoked/rejected server-side — only a fresh login replaces it, so
   // point at `bb login`, not a binding repair (the binding is valid).

package/src/agent-session.mjs

@@ -14,7 +14,7 @@ import { readKeychainSecret } from "./agent-credential-store.mjs";
 import { getConfig } from "./config.mjs";
 import { acquireStackLock } from "./stack-file-lock.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
-import { agentStatePath, clearAgentState, isAgentStateFresh, readAgentState, resolveMachineId, worktreeRoot, writeAgentState } from "./agent-state.mjs";
+import { agentStatePath, cacheBelongsToHarness, clearAgentState, harnessSessionIdFromEnv, isAgentStateFresh, readAgentState, resolveMachineId, worktreeRoot, writeAgentState } from "./agent-state.mjs";
 import { machineUuid } from "./machine-id.mjs";
 import { machineHost } from "./machine-host.mjs";
 
@@ -184,7 +184,9 @@ export async function resolveAgentSessionCredential({
   const envToken = readAgentSessionTokenEnv(env);
   if (envToken) return { token: envToken, sessionId: explicitSessionId, agentId: null, source: "env" };
   const cached = await readState(cwd);
-  if (cached && isFresh(cached, new Date())) {
+  // BOT-2425: a cache written for another harness session (or before the harness
+  // id was recorded) is not this session's identity; re-resolve it instead.
+  if (cached && isFresh(cached, new Date()) && cacheBelongsToHarness(cached, harnessSessionIdFromEnv(env))) {
     warnLegacyResolvedToken(cached.agent_session_token, warn);
     return withIdentity({ token: cached.agent_session_token, sessionId: explicitSessionId ?? cached.session_id, agentId: cached.agent_id, source: "cache" }, cached);
   }
@@ -246,6 +248,10 @@ export async function selfHealAgentSession({
     // (`force` deliberately bypasses ordinary reuse for an explicit repair.)
     const current = await readState(cwd);
     const renewal = rejectedCredential !== null;
+    // BOT-2425: the harness session this process runs in (exported by the
+    // SessionStart hook). A cache belongs to it only when it recorded the same id.
+    const envHarness = harnessSessionIdFromEnv(env);
+    const ownCache = !!current && cacheBelongsToHarness(current, envHarness);
     let bound;
     let registrationWorktree = cwd;
     if (renewal) {
@@ -267,7 +273,7 @@ export async function selfHealAgentSession({
         return withIdentity({ token: current.agent_session_token, sessionId: sessionId ?? current.session_id, agentId: current.agent_id, source: "cache", ticketSignals: null, stackLeaseCapability: null }, current);
       }
     }
-    if (!force && !renewal && current && isFresh(current, now())) {
+    if (!force && !renewal && current && ownCache && isFresh(current, now())) {
       // A fresh cache is reused without a register call, so no capability verdict is
       // available here (bb doctor --fix forces a mint to (re)establish + report it).
       return withIdentity({ token: current.agent_session_token, sessionId: sessionId ?? current.session_id, agentId: current.agent_id, source: "cache", ticketSignals: null, stackLeaseCapability: null }, current);
@@ -318,6 +324,15 @@ export async function selfHealAgentSession({
     // can reconcile a replacement agent by thread identity if the cache is lost.
     const codexThreadId = env.CODEX_THREAD_ID || undefined;
     const prNumber = Number.parseInt(env.BOTBUDDY_PR_NUMBER ?? env.CODEX_PR_NUMBER ?? "", 10);
+    // BOT-2425: present the session-lifetime identity. The cached agent_id is only
+    // this session's when the cache belongs to its harness session; otherwise the
+    // harness id alone lets the server re-bind to the session's agent (the cloud
+    // match for a deleted file or another worktree). A renewal keeps the cache's
+    // own identity — it replaces a rejected token, it never changes the agent.
+    const presentedAgentId = renewal || ownCache ? current?.agent_id : undefined;
+    const presentedHarness = renewal
+      ? (ownCache ? envHarness ?? current?.harness_session_id : current?.harness_session_id) ?? null
+      : envHarness ?? (ownCache ? current?.harness_session_id : null) ?? null;
     const response = await call("register_agent", {
       name: workAgentName,
       type: "custom",
@@ -329,7 +344,11 @@ export async function selfHealAgentSession({
       machine_uuid: resolvedHardwareId || undefined,
       branch: currentBranch || undefined,
       ticket_id: ticketFromBranch(currentBranch),
-      agent_id: current?.agent_id ?? undefined,
+      agent_id: presentedAgentId ?? undefined,
+      // A rejected-token renewal may still own locks or leases under this agent.
+      // Ask the server to keep it; ordinary setup/doctor repair may adopt a holder.
+      ...(renewal ? { preserve_agent_identity: true } : {}),
+      harness_session_id: presentedHarness ?? undefined,
       harness: env.CLAUDE_CODE || env.CLAUDECODE ? "claude-code" : Object.keys(env).some((key) => key.startsWith("CODEX_")) ? "codex" : "cli",
       model: env.BOTBUDDY_MODEL || undefined,
       effort: env.BOTBUDDY_EFFORT || undefined,
@@ -356,8 +375,14 @@ export async function selfHealAgentSession({
       const typedCode = typeof response?.code === "string"
         ? response.code
         : typeof data.code === "string" ? data.code : null;
-      const code = typedCode === "agent_tenant_immutable"
+      // BOT-2415: a technical-name conflict is deterministic (the cached agent_id
+      // names a different agent than the one holding this worktree's name), so no
+      // retry fixes it. Recognise the typed refusal and an older server's raw 23505.
+      const nameConflict = typedCode === "agent_name_taken"
+        || /agents_name_key/.test(String(response?.error ?? data.error ?? ""));
+      const code = ["agent_tenant_immutable", "session_identity_mismatch"].includes(typedCode)
         ? typedCode
+        : nameConflict ? "agent_name_conflict"
         : response?.auth ? "session_mint_unauthorized" : "session_mint_failed";
       // BOT-1891: name the credential (never its value) so `bb doctor` can point a
       // rejected tier-2 key at rotation instead of `bb login`.
@@ -399,6 +424,8 @@ export async function selfHealAgentSession({
       expires_at: expiry.toISOString(),
       // BOT-1891: which durable credential minted this session (never the value).
       minted_with: mintedWith,
+      // BOT-2425: the harness session this identity belongs to.
+      ...(presentedHarness ? { harness_session_id: presentedHarness } : {}),
       // BOT-1945: the non-secret incarnation fence. The durable close_session
       // refuses a generated row without it, so a cache that drops it can never be
       // retired by `bb bootstrap` / `bb bootstrap close` once its bearer lapses.

package/src/agent-state.mjs

@@ -21,6 +21,29 @@ export async function withStateLock(cwd, { timeoutMs } = {}, fn) {
   try { return await fn(); } finally { lease.release(); }
 }
 
+/** BOT-2425: the harness session this shell belongs to, lower-cased; null when
+ * unknown. The SessionStart hook exports BOTBUDDY_HARNESS_SESSION_ID; Claude Code
+ * also sets CLAUDE_CODE_SESSION_ID in every shell it spawns. A subagent
+ * (CLAUDE_CODE_CHILD_SESSION=1) inherits its PARENT's session id, so it never
+ * claims that identity: it keeps its own worktree identity, exactly as before. */
+export function harnessSessionIdFromEnv(env = process.env) {
+  if (env?.CLAUDE_CODE_CHILD_SESSION === "1") return null;
+  for (const name of ["BOTBUDDY_HARNESS_SESSION_ID", "CLAUDE_CODE_SESSION_ID"]) {
+    const raw = typeof env?.[name] === "string" ? env[name].trim() : "";
+    if (raw) return UUID_RE.test(raw) ? raw.toLowerCase() : null;
+  }
+  return null;
+}
+
+/** BOT-2425: may this cache act as THIS harness session's identity? A cache is
+ * reusable when no harness session is known, or when it was written for exactly
+ * this one. A cache with no harness id (written before BOT-2425 or by another
+ * shell) or another session's id is not this session's identity. */
+export function cacheBelongsToHarness(state, harnessSessionId) {
+  if (!harnessSessionId) return true;
+  return typeof state?.harness_session_id === "string" && state.harness_session_id.toLowerCase() === harnessSessionId;
+}
+
 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);
@@ -90,6 +113,10 @@ function validState(value) {
   if (value.host !== undefined && !(typeof value.host === "string" && value.host.length > 0)) return false;
   if (value.worktree !== undefined && !(typeof value.worktree === "string" && value.worktree.length > 0)) return false;
   if (value.minted_at !== undefined && !(typeof value.minted_at === "string" && !Number.isNaN(Date.parse(value.minted_at)))) return false;
+  // BOT-2425: the harness session (Claude Code session / Codex thread) this
+  // cached identity belongs to — the session-lifetime identity key.
+  if (value.harness_session_id !== undefined
+    && !(typeof value.harness_session_id === "string" && UUID_RE.test(value.harness_session_id))) return false;
   // BOT-1650: the nonsecret incarnation fence for close/heartbeat idempotency.
   if (value.session_token_generation !== undefined
     && !(typeof value.session_token_generation === "string" && UUID_RE.test(value.session_token_generation))) return false;

package/src/commands.mjs

@@ -568,7 +568,7 @@ function setupFailureRecovery(error) {
   if (code === "tenant_binding_required" || code === "invalid_binding") {
     return "fix the committed .botbuddy-agent.json binding, then retry `bb setup`";
   }
-  if (code === "client_key_unavailable" || code === "session_mint_unauthorized") return repairFailureRecovery(code, error);
+  if (code === "client_key_unavailable" || code === "session_mint_unauthorized" || code === "agent_name_conflict") return repairFailureRecovery(code, error);
   return "retry `bb setup`";
 }
 

package/src/session-bootstrap.mjs

@@ -31,7 +31,7 @@ export async function loadHarnessSession({ cwd = process.cwd() } = {}) {
 /** Persist a bootstrap-issued session into the unified cache. The bootstrap RPC
  * does not echo the tenant, so derive it from the committed binding exactly as
  * selfHealAgentSession does; host/worktree/minted_at are derived locally. */
-export async function saveHarnessSession(session, { cwd = process.cwd(), machineHostFn = machineHost } = {}) {
+export async function saveHarnessSession(session, { cwd = process.cwd(), machineHostFn = machineHost, harnessSessionId = null } = {}) {
   const root = await worktreeRoot(cwd);
   let tenant;
   try { tenant = (await readAgentBinding(root))?.tenant; } catch { tenant = undefined; }
@@ -50,6 +50,9 @@ export async function saveHarnessSession(session, { cwd = process.cwd(), machine
     // so this marker no longer gates timer relaying; it still distinguishes a
     // bootstrap-issued cache for the bootstrap bridge's own reuse checks.
     harness_origin: "bootstrap_agent_session",
+    // BOT-2425: the session-lifetime identity key. Later CLI mints present it with
+    // the agent_id, and a cache from another harness session is never reused.
+    ...(typeof harnessSessionId === "string" && harnessSessionId ? { harness_session_id: harnessSessionId.toLowerCase() } : {}),
     ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
   };
   await writeAgentState(root, state);
@@ -390,7 +393,7 @@ export async function bootstrapHarnessSession({
     }
     let state;
     try {
-      state = await store(session, { cwd: worktree });
+      state = await store(session, { cwd: worktree, harnessSessionId });
     } catch (error) {
       // The server session is unusable if this harness cannot persist its only
       // credential. The freshly issued session bearer is scoped to this exact

package/src/stack.mjs

@@ -985,7 +985,7 @@ export function retryingStackCall({
 // taxonomy so automation sees AUTH/BACKEND, not a CLI-defect INTERNAL. Credential
 // problems are AUTH (3); a transport/server mint failure is BACKEND (5); anything
 // unrecognized stays INTERNAL (7).
-const AUTH_ERROR_CODES = new Set(["client_key_required", "client_key_unavailable", "tenant_binding_required", "session_token_malformed", "session_mint_unauthorized", "session_identity_mismatch"]);
+const AUTH_ERROR_CODES = new Set(["client_key_required", "client_key_unavailable", "tenant_binding_required", "session_token_malformed", "session_mint_unauthorized", "session_identity_mismatch", "agent_name_conflict"]);
 // BOT-1750 (Codex R11 P2): `session_mint_invalid` is an incompatible/malformed SERVER
 // response, not a credential problem — classify it with the transport/server failures.
 const BACKEND_ERROR_CODES = new Set(["session_mint_failed", "session_mint_invalid"]);
@@ -1423,6 +1423,7 @@ export const PARK_AUTH_BUDGET_MS = 5 * 60_000;
 // the regular auth budget; it is not evidence that the lease changed owner.
 const DEFINITIVE_REAUTH_CODES = new Set([
   "session_identity_mismatch", "client_key_required", "tenant_binding_required", "session_token_malformed", "agent_tenant_immutable",
+  "agent_name_conflict",
 ]);
 
 function abortableSleep(ms, signal) {

package/src/wait.mjs

@@ -20,6 +20,7 @@ import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { clearAgentState, hasAgentSessionRuntime, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
+import { repairFailureRecovery } from "./agent-doctor.mjs";
 import { touchAgentStateExpiry } from "./agent-state.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
@@ -1679,7 +1680,10 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       opts.credentialSource = credential.source;
     } catch (error) {
       const code = error?.code ?? "session_mint_failed";
-      const recovery = code === "client_key_required"
+      // BOT-2415: a stale cache naming another agent is not fixed by `bb setup` + retry.
+      const recovery = code === "agent_name_conflict"
+        ? repairFailureRecovery(code)
+        : code === "client_key_required"
         ? "run `bb setup` from this project worktree, then retry"
         : code === "tenant_binding_required"
         ? "run from a configured project worktree, then run `bb setup` and retry"