@botbuddy/cli 1.31.0 → 1.31.1

package/src/codex-bridge.mjs

@@ -14,7 +14,11 @@
 
 import { createHash, randomBytes } from "crypto";
 import { getConfig, SERVER_URL } from "./config.mjs";
+import { callToolJson } from "./api.mjs";
 import { resolveOwnerToken, resolveAgentKey } from "./cli-credentials.mjs";
+import { bootstrapHarnessSession, heartbeatHarnessSession } from "./session-bootstrap.mjs";
+import { clearHarnessSession } from "./session-bootstrap.mjs";
+import { worktreeRoot } from "./agent-state.mjs";
 import { green, red, cyan, dim, bold, yellow, die } from "./utils.mjs";
 import { VERSION } from "./version.mjs";
 
@@ -64,6 +68,115 @@ function isAddressInUseError(text) {
   return /address already in use|eaddrinuse|os error 48/i.test(text);
 }
 
+// BOT-1650: a ticketless investigation is a read-only contract. The sandbox is
+// the enforcement point — never let a `no_ticket_reason` thread mutate the
+// workspace, regardless of the requested (or defaulted) sandbox policy. The UI
+// param is not a trust boundary, so the bridge, not the caller, decides.
+export function resolveThreadStartSandbox(params = {}) {
+  if (params.no_ticket_reason) return "read-only";
+  return params.sandbox || "workspace-write";
+}
+
+// BOT-1650: only threads that completed bootstrap admission may relay lifecycle
+// upserts. A thread whose bootstrap failed never entered `bootstrappedThreads`
+// and has no `codex_threads` row; upserting one from a later lifecycle
+// notification (e.g. thread/archived) would recreate the unreachable dashboard
+// row the bootstrap gate is meant to suppress and point the bridge at it.
+export function shouldRelayThreadLifecycle(bootstrappedThreads, threadId) {
+  return !!threadId && !!bootstrappedThreads?.has?.(threadId);
+}
+
+// BOT-1650 (Codex round-35 P2): a per-turn model override must be written back to
+// the stored session so keepalive heartbeats send the CURRENT model, not the one
+// chosen at thread creation (which would overwrite agents.model and misattribute
+// the overridden turn on the dashboard). Only a SUCCESSFUL turn (no error result)
+// updates the stored model; a no-op override or an unknown thread is ignored.
+export function applyTurnModelOverride(bootstrappedSessions, threadId, model, result) {
+  if (!model || result?.error) return false;
+  const stored = bootstrappedSessions?.get?.(threadId);
+  if (!stored) return false;
+  stored.model = model;
+  return true;
+}
+
+// BOT-1650: retire a thread's admission only after its terminal (archived)
+// lifecycle update has persisted. relayPost returns the relay's error body (no
+// throw) on a transient 4xx/5xx, so a missing thread_id means the archived
+// status did not land. Closing the session first — or closing after an
+// unpersisted update — would drop the thread from the admission maps, and
+// shouldRelayThreadLifecycle would then gate out every replay, stranding the
+// dashboard row active/idle forever despite its session being closed. Post
+// first; retire only on confirmed persistence, otherwise retain admission so a
+// later archived notification (or shutdown cleanup) can re-post it.
+// BOT-1650: reconcile the initial thread-link upsert against an ambiguous
+// transport failure. codex-relay's upsert is idempotent (keyed by session +
+// codex_thread_id) and, on insert, points the bridge agent at the row — so a
+// lost response may hide a row that is already committed and reachable. Retry
+// once before the caller decides to retire; on a persisted result (first call
+// or retry) return it, otherwise re-throw the original transport error so the
+// caller retires the possibly-orphaned thread rather than admitting it blind.
+export async function reconcileThreadLink({ relayPost, linkPayload }) {
+  try {
+    return await relayPost("/bridge/thread-update", linkPayload);
+  } catch (error) {
+    const retried = await relayPost("/bridge/thread-update", linkPayload).catch(() => null);
+    if (retried?.thread_id) return retried;
+    throw error;
+  }
+}
+
+export async function relayThreadArchival({
+  threadId,
+  sessionId,
+  relayPost,
+  closeThread,
+  retryClose,
+  retryArchival = null,
+  log = console.error,
+}) {
+  const archived = await relayPost("/bridge/thread-update", {
+    session_id: sessionId,
+    codex_thread_id: threadId,
+    status: "archived",
+  }).catch((err) => ({ error: String(err) }));
+  if (!archived?.thread_id) {
+    // Retaining admission does not by itself guarantee a replay — the app
+    // server may emit only one thread/archived, and shutdown just retires the
+    // session without re-posting. Schedule an explicit retry so the terminal
+    // status eventually lands instead of leaving the row active/idle forever.
+    log("[bridge] archived lifecycle update did not persist; scheduling retry:", { threadId, error: archived?.error });
+    if (retryArchival) retryArchival(threadId);
+    return false;
+  }
+  if (!await closeThread(threadId)) retryClose(threadId);
+  return true;
+}
+
+// BOT-1650: a bridge shutdown is terminal for its harness threads, but a thread
+// whose `archived` status has NOT yet persisted still has a pending
+// retryThreadArchival timer. Calling closeBootstrappedThread directly on it
+// would retire the session and DISCARD that pending re-post — shouldRelayThread-
+// Lifecycle then gates out every replay and the dashboard row is stranded
+// active/idle forever. Route a pending-archival thread through the archival flush
+// (post archived, then close on persistence) instead; close the rest directly.
+// Returns true only once the thread is genuinely retired (no longer admitted),
+// so the shutdown loop knows when to stop retrying.
+export async function retireBootstrappedThreadOnShutdown(threadId, {
+  bootstrappedThreads,
+  pendingArchival,
+  flushArchival,
+  closeThread,
+}) {
+  if (pendingArchival.has(threadId)) {
+    await flushArchival(threadId);
+    // flushArchival retires the session itself once the archived status lands; a
+    // thread still admitted here (archival or its close unconfirmed) is retried
+    // by the shutdown loop's next pass.
+    return !bootstrappedThreads.has(threadId);
+  }
+  return closeThread(threadId);
+}
+
 export async function runBridge(args) {
   const cfg = getConfig(); // non-secret metadata only (agent_name)
   // BOT-1520: authenticate from the Keychain — the MCP key
@@ -186,6 +299,99 @@ export async function runBridge(args) {
   let initialized = false;
   const pendingRequests = new Map(); // id → { resolve, reject }
   const threads = new Map(); // codex_thread_id → bb_thread_id
+  const bootstrappedThreads = new Set();
+  const bootstrappedSessions = new Map();
+  // BOT-1650: threads whose terminal `archived` status has been attempted but has
+  // NOT yet persisted (a retryThreadArchival timer is outstanding). Shutdown must
+  // flush these before discarding admission so the terminal status is not dropped.
+  const pendingArchival = new Set();
+
+  // Keep admission closed until the server has actually retired the session.
+  // Otherwise a transient close failure leaves an unseen active ticket holder
+  // and the next thread's bootstrap is guaranteed to conflict.
+  async function closeBootstrappedThread(threadId) {
+    const session = bootstrappedSessions.get(threadId);
+    if (!session) {
+      bootstrappedThreads.delete(threadId);
+      return true;
+    }
+    // BOT-1650: the durable confirmation path is generation-fenced. A lost
+    // self-close response, or an expired/revoked tier-3 bearer, leaves the
+    // durable fallback as the only cleanup route, and the final API rejects a
+    // generated row without its `session_token_generation`. Carry the bootstrap
+    // generation so an active row is retired instead of returning
+    // `session_generation_required` and retrying admission indefinitely.
+    const closeArgs = {
+      session_id: session.session_id,
+      ...(session.session_token_generation
+        ? { session_token_generation: session.session_token_generation }
+        : {}),
+    };
+    try {
+      const close = await callToolJson("close_session", closeArgs, {
+        // A live session bearer can close only itself, so it remains the most
+        // reliable cleanup authority when the bridge's startup credential has
+        // expired or been revoked during a long-running task.
+        auth: { "x-agent-api-key": session.session_token },
+      });
+      if (!close?.ok || close.isError) {
+        // A revoked tier-3 token may mean a previous close succeeded but its
+        // response was lost. Only then use durable auth to confirm the outcome.
+        const confirmed = await callToolJson("close_session", closeArgs, {
+          auth: await authHeaders(),
+        });
+        if (!confirmed?.ok || confirmed.isError) throw new Error(confirmed?.error || "close_session rejected");
+      }
+      // The launcher may start a thread in a nested or sibling worktree. The
+      // runtime credential was persisted there, not necessarily at the bridge
+      // root, so retire precisely the state file that owns this session.
+      await clearHarnessSession(session.session_id, {
+        cwd: session.cwd,
+        sessionToken: session.session_token,
+      });
+      bootstrappedSessions.delete(threadId);
+      bootstrappedThreads.delete(threadId);
+      return true;
+    } catch (error) {
+      console.error("[bridge] retaining thread admission until session cleanup succeeds:", { threadId, error });
+      return false;
+    }
+  }
+
+  function retryCloseBootstrappedThread(threadId) {
+    setTimeout(async () => {
+      if (!bootstrappedThreads.has(threadId)) return;
+      if (!await closeBootstrappedThread(threadId)) retryCloseBootstrappedThread(threadId);
+    }, PING_INTERVAL_MS);
+  }
+
+  // Post a thread's archived status and track whether it persisted. The pending
+  // set lets shutdown flush an outstanding archival before discarding admission
+  // (BOT-1650) instead of closing the session and dropping the terminal status.
+  async function flushThreadArchival(threadId) {
+    const persisted = await relayThreadArchival({
+      threadId,
+      sessionId,
+      relayPost,
+      closeThread: closeBootstrappedThread,
+      retryClose: retryCloseBootstrappedThread,
+      retryArchival: retryThreadArchival,
+    });
+    if (persisted) pendingArchival.delete(threadId);
+    else pendingArchival.add(threadId);
+    return persisted;
+  }
+
+  // Re-post a thread's archived status when the first attempt did not persist.
+  // Runs only while the thread is still admitted (relayThreadArchival retires
+  // admission itself once the update lands), so this stops as soon as the
+  // terminal status is confirmed.
+  function retryThreadArchival(threadId) {
+    setTimeout(() => {
+      if (!bootstrappedThreads.has(threadId)) return;
+      void flushThreadArchival(threadId);
+    }, PING_INTERVAL_MS);
+  }
 
   // Generate a nonce for localhost verification
   const bridgeNonce = randomBytes(16).toString("hex");
@@ -293,13 +499,16 @@ export async function runBridge(args) {
         const threadId = payload.thread?.id;
         if (threadId) {
           console.log(`  ${cyan("◆")} Thread started: ${threadId}`);
-          const result = await relayPost("/bridge/thread-update", {
-            session_id: sessionId,
-            codex_thread_id: threadId,
-            status: "active",
-            model,
-          });
-          if (result?.thread_id) threads.set(threadId, result.thread_id);
+          // `thread/start` records the relay row only after bootstrap succeeds.
+          // A rejected bootstrap must never leave an unreachable dashboard thread.
+          if (shouldRelayThreadLifecycle(bootstrappedThreads, threadId)) {
+            await relayPost("/bridge/thread-update", {
+              session_id: sessionId,
+              codex_thread_id: threadId,
+              status: "active",
+              model,
+            });
+          }
         }
       }
 
@@ -315,7 +524,11 @@ export async function runBridge(args) {
         const usage = payload.turn?.usage || payload.usage;
         if (usage) {
           const threadId = payload.thread?.id || payload.threadId;
-          if (threadId) {
+          // A turn can complete on an unadmitted thread when the user drives the
+          // local app-server directly (bypassing the bridge's turn/start gate).
+          // Its usage upsert must not insert a codex_threads row for a thread
+          // whose bootstrap failed — same admission gate as every lifecycle event.
+          if (shouldRelayThreadLifecycle(bootstrappedThreads, threadId)) {
             const updatePayload = { session_id: sessionId, codex_thread_id: threadId };
             if (usage.input_tokens !== undefined) updatePayload.input_tokens = usage.input_tokens;
             if (usage.output_tokens !== undefined) updatePayload.output_tokens = usage.output_tokens;
@@ -354,7 +567,10 @@ export async function runBridge(args) {
       if (eventType === "thread/status/changed") {
         const threadId = payload.threadId;
         const status = payload.status?.type;
-        if (threadId && status) {
+        // Same admission gate as the other lifecycle upserts: a status change
+        // for an unadmitted thread (bootstrap failed or still pending) must not
+        // upsert a codex_threads row and point the bridge at an unreachable one.
+        if (status && shouldRelayThreadLifecycle(bootstrappedThreads, threadId)) {
           await relayPost("/bridge/thread-update", {
             session_id: sessionId,
             codex_thread_id: threadId,
@@ -363,6 +579,19 @@ export async function runBridge(args) {
         }
       }
 
+      // App-server emits archival as its own lifecycle notification; status
+      // changes are operational states such as active/idle, not terminal work.
+      if (eventType === "thread/archived") {
+        const threadId = payload.threadId || payload.thread?.id;
+        // Only retire + mark archived for admitted threads. An unadmitted thread
+        // (thread/start created the Codex thread but bootstrap failed) has no
+        // codex_threads row; upserting an archived status here would recreate
+        // the unreachable dashboard row the bootstrap gate suppresses.
+        if (shouldRelayThreadLifecycle(bootstrappedThreads, threadId)) {
+          await flushThreadArchival(threadId);
+        }
+      }
+
       // Forward event to BotBuddy
       const bbThreadId = payload.thread?.id ? threads.get(payload.thread.id) :
                          payload.threadId ? threads.get(payload.threadId) : null;
@@ -409,23 +638,94 @@ export async function runBridge(args) {
 
       switch (cmd.command) {
         case "thread/start": {
+          const threadCwd = cmd.params.cwd || repoPath;
+          const requestedWorktree = await worktreeRoot(threadCwd);
+          const activeInWorktree = [...bootstrappedSessions.values()].some(
+            (session) => session.cwd === requestedWorktree,
+          );
+          if (activeInWorktree) {
+            throw new Error("This bridge worktree already has an active bootstrapped thread; finish that thread or use a separate worktree before starting another.");
+          }
           result = await sendWs("thread/start", {
             model: cmd.params.model || model,
-            cwd: cmd.params.cwd || repoPath,
+            cwd: threadCwd,
             approvalPolicy: cmd.params.approval_policy || "never",
-            sandbox: cmd.params.sandbox || "workspace-write",
+            sandbox: resolveThreadStartSandbox(cmd.params),
           });
           // Track thread
           if (result?.thread?.id) {
-            const bbResult = await relayPost("/bridge/thread-update", {
+            // BOT-1650: the thread exists before its first turn, so bind and
+            // persist its short-lived credential now. A failure is surfaced to
+            // the command dispatcher and prevents a turn from starting without
+            // a wait-capable principal.
+            const bootstrap = await bootstrapHarnessSession({
+              name: `${cfg.agent_name || `codex-bridge-${host}`}-${result.thread.id.slice(0, 8)}`,
+              type: "codex",
+              harnessSessionId: result.thread.id,
+              codexThreadId: result.thread.id,
+              cwd: requestedWorktree,
+              model: cmd.params.model || model,
+              effort: cmd.params.effort || null,
+              branch: cmd.params.branch || null,
+              ticketId: cmd.params.ticket_id || null,
+              ticketUrl: cmd.params.ticket_url || null,
+              noTicketReason: cmd.params.no_ticket_reason || null,
+              prId: cmd.params.pr_id || null,
+              prNumber: cmd.params.pr_number ?? null,
+              prUrl: cmd.params.pr_url || null,
+              harness: "botbuddy-codex-bridge",
+              call: callToolJson,
+              callOptions: { auth: await authHeaders() },
+            });
+            if (bootstrap.ticket_signals?.concurrency) {
+              throw new Error(bootstrap.ticket_signals.concurrency.warning);
+            }
+            if (bootstrap.linkage?.status === "gap") {
+              throw new Error(bootstrap.linkage.warning || "Session bootstrap requires ticket attribution.");
+            }
+            // Own cleanup before any fallible relay linkage. A rejected fetch
+            // must not strand the just-minted secret/session outside the bridge
+            // lifecycle maps and let a second thread bypass admission.
+            bootstrappedThreads.add(result.thread.id);
+            bootstrappedSessions.set(result.thread.id, {
+              session_id: bootstrap.session_id,
+              session_token: bootstrap.session_token,
+              // BOT-1650: retain the generation so the durable close fallback in
+              // closeBootstrappedThread can fence its cleanup on this exact row.
+              session_token_generation: bootstrap.session_token_generation,
+              // Keep this thread's EFFECTIVE model so keepalive heartbeats persist
+              // it, not the bridge-wide default — otherwise a thread started on a
+              // non-default model (e.g. the UI picks o3) would have agents.model
+              // overwritten to the default on the first 15s heartbeat.
+              model: cmd.params.model || model,
+              cwd: requestedWorktree,
+            });
+            const linkPayload = {
               session_id: sessionId,
               codex_thread_id: result.thread.id,
               title: cmd.params.title,
               model: cmd.params.model || model,
               status: "idle",
-              cwd: cmd.params.cwd || repoPath,
-            });
-            if (bbResult?.thread_id) threads.set(result.thread.id, bbResult.thread_id);
+              cwd: threadCwd,
+            };
+            let bbResult;
+            try {
+              bbResult = await reconcileThreadLink({ relayPost, linkPayload });
+            } catch (error) {
+              if (!await closeBootstrappedThread(result.thread.id)) retryCloseBootstrappedThread(result.thread.id);
+              throw error;
+            }
+            if (!bbResult?.thread_id) {
+              if (!await closeBootstrappedThread(result.thread.id)) retryCloseBootstrappedThread(result.thread.id);
+              throw new Error("Bridge thread linkage failed; refusing to admit an unreachable thread.");
+            }
+            threads.set(result.thread.id, bbResult.thread_id);
+            result.bootstrap = {
+              agent_id: bootstrap.agent_id,
+              display_name: bootstrap.display_name,
+              session_id: bootstrap.session_id,
+              expires_at: bootstrap.expires_at,
+            };
           }
           break;
         }
@@ -436,11 +736,20 @@ export async function runBridge(args) {
             result = { error: "Thread not found" };
             break;
           }
+          if (!bootstrappedThreads.has(codexThreadId)) {
+            result = { error: "Thread session bootstrap did not complete; start a new thread after resolving its authentication or ticket conflict." };
+            break;
+          }
           result = await sendWs("turn/start", {
             threadId: codexThreadId,
             input: [{ type: "text", text: cmd.params.prompt || cmd.params.text || "" }],
             ...(cmd.params.model && { model: cmd.params.model }),
           });
+          // BOT-1650 (Codex round-35 P2): a per-turn model override must be written
+          // back to the stored session, or the 15s keepalive keeps sending the
+          // creation-time model and overwrites agents.model — misattributing the
+          // overridden turn on the dashboard and in effectiveness reporting.
+          applyTurnModelOverride(bootstrappedSessions, codexThreadId, cmd.params.model, result);
           break;
         }
 
@@ -496,6 +805,27 @@ export async function runBridge(args) {
     try {
       await relayPost("/bridge/ping", { session_id: sessionId });
     } catch {}
+    // The relay ping maintains the bridge connection, not the work-graph
+    // session created via the REST bootstrap. Refresh every active thread with
+    // its scoped tier-3 token so ticket-holder admission cannot stale it while
+    // Codex is working silently between BotBuddy calls.
+    await Promise.all([...bootstrappedSessions.entries()].map(async ([threadId, harnessSession]) => {
+      try {
+        await heartbeatHarnessSession({
+          session: harnessSession,
+          codexThreadId: threadId,
+          // Send this thread's effective model, not the bridge-wide default, so
+          // a keepalive never rewrites agents.model to the wrong value.
+          model: harnessSession.model ?? model,
+          call: callToolJson,
+          // BOT-1650 (round-30): mirror the server's expiry roll into this thread's
+          // worktree cache so a later relay wait keeps the bootstrap session.
+          cwd: harnessSession.cwd,
+        });
+      } catch (error) {
+        console.error("[bridge] bootstrapped session heartbeat failed:", { threadId, error });
+      }
+    }));
   }, PING_INTERVAL_MS);
 
   const pollInterval = setInterval(pollCommands, POLL_INTERVAL_MS);
@@ -505,6 +835,25 @@ export async function runBridge(args) {
     console.log(`\n${dim("→ Shutting down bridge...")}`);
     clearInterval(pingInterval);
     clearInterval(pollInterval);
+    // A bridge shutdown is terminal for its harness threads. Retire their
+    // per-thread session credentials before disconnecting so a sequential
+    // bridge does not collide with an orphaned live ticket holder. BOT-1650: a
+    // thread with an unpersisted archival must FLUSH it here (route through
+    // relayThreadArchival) before its admission is discarded, or the terminal
+    // status is dropped and the dashboard row is stranded active/idle.
+    while (bootstrappedThreads.size > 0) {
+      const closed = await Promise.all([...bootstrappedThreads].map((threadId) =>
+        retireBootstrappedThreadOnShutdown(threadId, {
+          bootstrappedThreads,
+          pendingArchival,
+          flushArchival: flushThreadArchival,
+          closeThread: closeBootstrappedThread,
+        })
+      ));
+      if (closed.every(Boolean)) break;
+      console.error(dim("→ Session cleanup did not complete; retaining bridge shutdown until it can be retried."));
+      await sleep(PING_INTERVAL_MS);
+    }
     try {
       await relayPost("/bridge/disconnect", { session_id: sessionId });
     } catch {}

package/src/commands.mjs

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { callTool, callToolJson, readResource } from "./api.mjs";
 import { doLogin } from "./auth.mjs";
 import { runBridge } from "./codex-bridge.mjs";
+import { bootstrapHarnessSession, clearHarnessSession, loadHarnessSession, withHarnessBootstrapLock } from "./session-bootstrap.mjs";
 import { loadConfig, getConfig, clearConfig, getConfigPath, SERVER_URL } from "./config.mjs";
 import { resolveOwnerToken, resolveAgentKey, clearOwnerToken } from "./cli-credentials.mjs";
 import { agentProfileKeyLabel } from "./credential-kinds.mjs";
@@ -38,6 +39,16 @@ export function shouldCheckForUpdates(argv) {
   return true;
 }
 
+const TICKET_KEY_RE = /^[A-Za-z][A-Za-z0-9]{1,9}-\d{1,6}$/;
+
+export function validateBootstrapLinkage(ticketId, noTicketReason) {
+  const ticket = typeof ticketId === "string" ? ticketId.trim() : "";
+  const reason = typeof noTicketReason === "string" ? noTicketReason.trim() : "";
+  if (!!ticket === !!reason) return "bb bootstrap requires exactly one of --ticket-id <ticket> or --no-ticket-reason <reason>";
+  if (ticket && !TICKET_KEY_RE.test(ticket)) return "bb bootstrap --ticket-id must be a ticket key like BOT-123";
+  return null;
+}
+
 export async function run(argv, {
   loadConfig: load = loadConfig,
   warnStale = maybeWarnStale,
@@ -49,6 +60,7 @@ export async function run(argv, {
 
   switch (command) {
     case "start": return cmdStart(args);
+    case "bootstrap": return cmdBootstrap(args);
     case "login": return cmdLogin(args, { errorLog });
     case "setup": return cmdSetup(args, { errorLog });
     case "logout": return cmdLogout();
@@ -129,6 +141,9 @@ ${dim(`Run everything as ${cyan("bb <command>")} — the short, preferred alias.
 
 ${bold("USAGE")}
   bb start                   Start BotBuddy (login + codex server + bridge)
+  bb bootstrap --session-id <uuid> (--ticket-id <BOT-n> | --no-ticket-reason <reason>)
+                             Internal launcher contract: persist a wait-capable
+                             harness session without printing its secret
 
 ${bold("OPTIONS")}
   start [options]
@@ -571,6 +586,144 @@ async function cmdStart(args) {
   return runBridge(args);
 }
 
+// BOT-1650: a harness/launcher calls this once after it knows its own session
+// UUID. It writes the short-lived token to the gitignored 0600 runtime file and
+// prints only non-secret metadata, so later `bb wait` calls need no exports.
+export async function closeStoredHarnessSession({
+  session,
+  durableAuth,
+  call = callToolJson,
+} = {}) {
+  const sessionAuth = { "x-agent-api-key": session.session_token };
+  // BOT-1650: the durable close path is generation-fenced. When the cached
+  // bearer has expired or been revoked while its row stays active, the durable
+  // owner/MCP credential is the only cleanup route — but the final
+  // `close_session` API rejects durable closure of a generated row unless
+  // `session_token_generation` is supplied (`session_generation_required`), so
+  // the bearer retry cannot authenticate either. Pass the cached generation so
+  // `bb bootstrap close` can clear the session and its runtime cache.
+  const closeArgs = {
+    session_id: session.session_id,
+    ...(session.session_token_generation
+      ? { session_token_generation: session.session_token_generation }
+      : {}),
+  };
+  let result;
+  let firstError;
+  try {
+    result = await call("close_session", closeArgs, { auth: durableAuth });
+  } catch (error) {
+    firstError = error;
+  }
+  const usedSessionBearer = durableAuth?.["x-agent-api-key"] === session.session_token;
+  // BOT-1650: a THROW from the durable attempt means the response was LOST — the
+  // durable close is generation-fenced and idempotent, so it may already have
+  // COMMITTED server-side, which also revokes the generated bearer. Falling
+  // straight to the session-bearer retry would then authenticate with a
+  // now-revoked credential, report a false failure, and keep the runtime cache.
+  // Re-issue the idempotent DURABLE request to confirm the ambiguous outcome
+  // first. A STRUCTURED rejection (result returned with !ok/isError) is a
+  // definite server refusal of the durable credential/args — the server did
+  // answer — so it skips this retry and falls through to the scoped bearer.
+  if (firstError && !usedSessionBearer) {
+    try {
+      result = await call("close_session", closeArgs, { auth: durableAuth });
+      firstError = undefined;
+    } catch (error) {
+      firstError = error;
+    }
+  }
+  // A locally unexpired owner/MCP credential may already be revoked remotely,
+  // while the exact cached bearer remains valid to retire its own session.
+  // Retry only with that scoped bearer; never widen the fallback credential.
+  if ((!result?.ok || result.isError || firstError) && !usedSessionBearer) {
+    result = await call("close_session", closeArgs, { auth: sessionAuth });
+    firstError = undefined;
+  }
+  if (firstError) throw firstError;
+  return result;
+}
+
+async function cmdBootstrap(args) {
+  if (args[0] === "close") {
+    return withHarnessBootstrapLock({}, async () => {
+      const session = await loadHarnessSession();
+      if (!session) {
+        console.log(JSON.stringify({ outcome: "no_session" }));
+        return;
+      }
+      const owner = await resolveOwnerToken({ getConfig });
+    // Match resolveCallAuth: a stored but expired owner token must never mask
+    // a usable MCP key or the exact session credential that needs cleanup.
+      const activeOwner = owner && !(owner.expiresAt && Date.now() >= owner.expiresAt) ? owner : null;
+      const agentKey = activeOwner ? null : await resolveAgentKey();
+      const durableAuth = activeOwner
+        ? { Authorization: `Bearer ${activeOwner.token}` }
+        : agentKey
+          ? { "x-agent-api-key": agentKey }
+          : { "x-agent-api-key": session.session_token };
+      const result = await closeStoredHarnessSession({ session, durableAuth });
+      if (!result?.ok || result.isError) die(result?.error || "bb bootstrap close failed");
+      await clearHarnessSession(session.session_id, { sessionToken: session.session_token, lock: false }); // already inside withHarnessBootstrapLock (non-reentrant)
+      console.log(JSON.stringify({ outcome: "closed", session_id: session.session_id }));
+    });
+  }
+  let harnessSessionId = null;
+  let type = "custom";
+  let codexThreadId = null;
+  let branch = null;
+  let ticketId = null;
+  let ticketUrl = null;
+  let noTicketReason = null;
+  let prId = null;
+  let prNumber = null;
+  let prUrl = null;
+  let model = null;
+  let effort = null;
+  let name = getConfig()?.agent_name || `botbuddy-${os.hostname()}`;
+  let nameExplicit = false;
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === "--session-id") harnessSessionId = args[++i] || null;
+    else if (args[i] === "--type") type = args[++i] || type;
+    else if (args[i] === "--codex-thread-id") codexThreadId = args[++i] || null;
+    else if (args[i] === "--name") { name = args[++i] || name; nameExplicit = true; }
+    else if (args[i] === "--branch") branch = args[++i] || null;
+    else if (args[i] === "--ticket-id") ticketId = args[++i] || null;
+    else if (args[i] === "--ticket-url") ticketUrl = args[++i] || null;
+    else if (args[i] === "--no-ticket-reason") noTicketReason = args[++i] || null;
+    else if (args[i] === "--pr-id") prId = args[++i] || null;
+    else if (args[i] === "--pr-number") prNumber = Number(args[++i]);
+    else if (args[i] === "--pr-url") prUrl = args[++i] || null;
+    else if (args[i] === "--model") model = args[++i] || null;
+    else if (args[i] === "--effort") effort = args[++i] || null;
+    else die("Usage: bb bootstrap --session-id <harness UUID> (--ticket-id <ticket> | --no-ticket-reason <reason>) [--type codex|claude|gpt|custom] [--codex-thread-id <UUID>] [--name <technical-name>] [--branch <branch>] [--ticket-url <url>] [--model <model>] [--effort <effort>]");
+  }
+  if (!harnessSessionId) die("bb bootstrap requires --session-id <harness UUID>");
+  const linkageError = validateBootstrapLinkage(ticketId, noTicketReason);
+  if (linkageError) die(linkageError);
+  ticketId = ticketId?.trim() || null;
+  noTicketReason = noTicketReason?.trim() || null;
+  if (!nameExplicit) name = `${name}-${harnessSessionId.slice(0, 8)}`;
+  const state = await bootstrapHarnessSession({
+    name,
+    type,
+    harnessSessionId,
+    codexThreadId,
+    branch,
+    ticketId,
+    ticketUrl,
+    noTicketReason,
+    prId,
+    prNumber: Number.isSafeInteger(prNumber) && prNumber > 0 ? prNumber : null,
+    prUrl,
+    model,
+    effort,
+    harness: `botbuddy-${type}-launcher`,
+  });
+  if (state.linkage?.status === "gap") die(state.linkage.warning || "bb bootstrap requires ticket attribution or --no-ticket-reason.");
+  console.log(JSON.stringify({ agent_id: state.agent_id, display_name: state.display_name, session_id: state.session_id, expires_at: state.expires_at }));
+}
+
 // 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