@botbuddy/cli 1.31.0 → 1.31.1

package/src/session-bootstrap.mjs

@@ -0,0 +1,375 @@
+// BOT-1650 — the only CLI-side bridge between a harness and the tier-3 token.
+// It never prints or exports a secret; the runtime store is consumed by `bb wait`.
+
+import os from "node:os";
+import { callToolJson } from "./api.mjs";
+import { readAgentState, touchAgentStateExpiry, withStateLock, worktreeRoot, writeAgentState } from "./agent-state.mjs";
+import { clearAgentSessionIfMatches, drainPendingCleanup, recordPendingCleanup } from "./agent-cleanup.mjs";
+import { readAgentBinding } from "./wait-profile.mjs";
+import { resolveAgentKey, resolveOwnerToken } from "./cli-credentials.mjs";
+import { getConfig } from "./config.mjs";
+
+// BOT-1650 → BOT-1649 reconciliation: the harness session lives in the ONE
+// unified client cache (agent-state.mjs), written in main's `agent_session_token`
+// schema. These adapters map between the bootstrap RPC response shape (which uses
+// `session_token`) and the on-disk state, so `bb wait`/`run`/`test`/`pw` can
+// authenticate from the same file via resolveAgentSessionCredential.
+
+/** Read the per-worktree cache back in the RPC-shaped form the bridge expects. */
+export async function loadHarnessSession({ cwd = process.cwd() } = {}) {
+  const state = await readAgentState(cwd);
+  if (!state) return null;
+  return {
+    ...state,
+    session_token: state.agent_session_token,
+    ...(state.session_token_generation ? { session_token_generation: state.session_token_generation } : {}),
+  };
+}
+
+/** 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() } = {}) {
+  const root = await worktreeRoot(cwd);
+  let tenant;
+  try { tenant = (await readAgentBinding(root))?.tenant; } catch { tenant = undefined; }
+  const state = {
+    schema_version: 1,
+    agent_id: session.agent_id,
+    agent_session_token: session.session_token,
+    session_id: session.session_id ?? null,
+    ...(tenant ? { tenant } : {}),
+    host: os.hostname(),
+    worktree: root,
+    minted_at: new Date().toISOString(),
+    expires_at: session.expires_at,
+    // BOT-1650 (Codex round-28 P2): mark provenance so a TIMER wait only relays for
+    // a bootstrap-issued cache (the cross-shell receipt-of-principal contract). A
+    // bb setup / self-heal cache shares this schema but omits this marker, so a
+    // plain timer from such a shell stays fully offline.
+    harness_origin: "bootstrap_agent_session",
+    ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+  };
+  await writeAgentState(root, state);
+  // Return the RPC-shaped session so callers reading `.session_token` are unchanged.
+  return session;
+}
+
+/** Guarded, lock-free clear used inside the bootstrap transaction (re-exported so
+ * the Codex bridge and `bb setup` close path share one implementation). */
+export const clearHarnessSession = clearAgentSessionIfMatches;
+
+/** Serialize the whole remote-bootstrap-plus-save on the unified per-worktree
+ * state lock — the SAME `<agent-state>.lock` selfHealAgentSession takes — so a
+ * bootstrap and a self-heal can never both write the cache. */
+export async function withHarnessBootstrapLock({ cwd = process.cwd() } = {}, operation) {
+  const root = await worktreeRoot(cwd);
+  return withStateLock(root, {}, () => operation(root));
+}
+
+export async function durableCleanupOptions({
+  resolveAgentKeyFn = resolveAgentKey,
+  resolveOwnerTokenFn = resolveOwnerToken,
+  getConfigFn = getConfig,
+} = {}) {
+  const owner = await resolveOwnerTokenFn({ getConfig: getConfigFn });
+  if (owner && !(owner.expiresAt && owner.expiresAt <= Date.now())) {
+    return { auth: { Authorization: `Bearer ${owner.token}` } };
+  }
+  const agentKey = await resolveAgentKeyFn();
+  if (agentKey) return { auth: { "x-agent-api-key": agentKey } };
+  return null;
+}
+
+function cleanupError(response) {
+  return response?.data?.error || response?.data?.message || response?.error || "remote session cleanup could not be confirmed";
+}
+
+async function closeWithDurableCredential(call, args, options) {
+  try {
+    const response = await call("close_session", args, options);
+    return { response, closed: !!response?.ok && !response.isError };
+  } catch (error) {
+    return { response: null, closed: false, error };
+  }
+}
+
+// BOT-1650 (Codex round-24/25): a session was admitted but could not be retired.
+// Persist a cleanup marker so a later bootstrap retires it, then ALWAYS throw a
+// failure that preserves the primary cause, the retirement failure, AND any
+// persistence failure — never swallowing a marker-write failure (round-25 P2),
+// which would silently revert to leaving an orphaned holder. Never returns.
+async function recordOrphanAndFail({ session, cwd, retirementError, primaryError }) {
+  let persistError;
+  try {
+    await recordPendingCleanup(
+      { session_id: session.session_id, session_token_generation: session.session_token_generation },
+      { cwd },
+    );
+  } catch (error) {
+    persistError = error;
+  }
+  const parts = [];
+  if (primaryError) parts.push(primaryError.message);
+  parts.push(`the admitted session could not be retired: ${retirementError.message}`);
+  if (persistError) parts.push(`and its cleanup marker could not be persisted: ${persistError.message}`);
+  const err = new Error(parts.join("; "));
+  err.cause = primaryError ?? retirementError;
+  throw err;
+}
+
+// Keep a REST-bootstrapped harness alive without handing its durable setup
+// credential to the bridge. The session bearer is scoped to this exact session;
+// the server rejects a mismatched or ended session rather than refreshing an
+// unrelated agent-global heartbeat.
+export async function heartbeatHarnessSession({
+  session,
+  codexThreadId = null,
+  model = null,
+  call = callToolJson,
+  cwd = process.cwd(),
+  touchExpiry = touchAgentStateExpiry,
+} = {}) {
+  if (!session?.session_id || !session?.session_token) {
+    throw new Error("bootstrap heartbeat requires a stored session credential");
+  }
+  const response = await call("heartbeat", {
+    session_id: session.session_id,
+    ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+    ...(model ? { model } : {}),
+  }, { auth: { "x-agent-api-key": session.session_token } });
+  if (!response?.ok || response.isError) {
+    throw new Error(response?.data?.message || response?.error || "bootstrap heartbeat failed");
+  }
+  // BOT-1650 (Codex round-30 P2): the server just rolled this session's expiry
+  // forward, but the runtime cache still holds the ORIGINAL deadline. Without
+  // mirroring the renewal, a later relay wait on a long-lived bridge judges the
+  // cache stale and self-heals into a DIFFERENT work session — losing the harness
+  // principal and creating a second live holder. touchAgentStateExpiry extends the
+  // cache only while it still holds THIS exact bearer, so it never revives a
+  // replaced credential. Best-effort: a heartbeat that cannot refresh the cache is
+  // not itself a failure.
+  await touchExpiry(cwd, session.session_token).catch(() => {});
+  return response.data;
+}
+
+export async function bootstrapHarnessSession({
+  name,
+  type = "codex",
+  harnessSessionId,
+  codexThreadId = null,
+  cwd = process.cwd(),
+  branch = null,
+  ticketId = null,
+  ticketUrl = null,
+  noTicketReason = null,
+  prId = null,
+  prNumber = null,
+  prUrl = null,
+  model = null,
+  effort = null,
+  harness = type,
+  call = callToolJson,
+  callOptions = undefined,
+  resolveCleanupOptions = durableCleanupOptions,
+  store = saveHarnessSession,
+  transaction = withHarnessBootstrapLock,
+} = {}) {
+  if (!name || !harnessSessionId) throw new Error("bootstrap requires name and harnessSessionId");
+  const worktree = await worktreeRoot(cwd);
+  return transaction({ cwd: worktree }, async () => {
+    // BOT-1650 (Codex round-24): before admitting a new session, retry retiring
+    // any session a PRIOR bootstrap orphaned (its replacement retirement failed in
+    // a compound outage). The durable credential retires by id, so no bearer is
+    // needed. Best-effort — a missing durable credential just keeps the marker.
+    await drainPendingCleanup({
+      cwd: worktree,
+      retire: async (entry) => {
+        const opts = callOptions ?? await resolveCleanupOptions();
+        if (!opts) return false;
+        const closed = await closeWithDurableCredential(call, {
+          session_id: entry.session_id,
+          ...(entry.session_token_generation ? { session_token_generation: entry.session_token_generation } : {}),
+        }, opts);
+        return closed.closed;
+      },
+    }).catch(() => {});
+    const cached = await loadHarnessSession({ cwd: worktree });
+    // `expires_at` is a cache snapshot, not authority: an authenticated relay
+    // use can extend the server-side session after the file was written. Pass
+    // bootstrap straight through so the server reuses a still-live incarnation
+    // or rotates a truly expired one; never revoke an active wait from a stale
+    // local timestamp.
+    const response = await call("bootstrap_agent_session", {
+      name,
+      type,
+      harness_session_id: harnessSessionId,
+      host: os.hostname(),
+      worktree,
+      ...(branch ? { branch } : {}),
+      ...(ticketId ? { ticket_id: ticketId } : {}),
+      ...(ticketUrl ? { ticket_url: ticketUrl } : {}),
+      ...(noTicketReason ? { no_ticket_reason: noTicketReason } : {}),
+      ...(prId ? { pr_id: prId } : {}),
+      ...(prNumber != null ? { pr_number: prNumber } : {}),
+      ...(prUrl ? { pr_url: prUrl } : {}),
+      ...(codexThreadId ? { codex_thread_id: codexThreadId } : {}),
+      ...(model ? { model } : {}),
+      ...(effort ? { effort } : {}),
+      harness,
+    }, callOptions);
+    if (!response?.ok || response.isError) {
+      throw new Error(response?.data?.message || response?.error || "bootstrap_agent_session failed");
+    }
+    // Persist only the four session-secret fields. Ticket signals are intentionally
+    // returned to the launcher, never copied into the runtime credential file.
+    const { ticket_signals: ticketSignals, display_name: displayName, linkage, ...session } = response.data;
+    if (ticketSignals?.concurrency) throw new Error(ticketSignals.concurrency.warning || "Another live session holds this ticket.");
+    if (linkage?.status === "gap") throw new Error(linkage.warning || "Session bootstrap requires ticket attribution.");
+    // A new harness may be admitted only after an abandoned cache aged out of
+    // the server's liveness window. Before replacing that file, ask the server
+    // to retire the cached session *only if its authoritative holder-liveness
+    // window elapsed*. The file's timestamp is intentionally not authority:
+    // relay heartbeats can extend it after the snapshot was written.
+    if (cached && cached.session_id !== session.session_id) {
+      const cleanupOptions = callOptions ?? await resolveCleanupOptions();
+      if (!cleanupOptions) {
+        // BOT-1650 (Codex round-27): the new session was admitted but there is no
+        // durable credential to retire the OLD cached session, so the replacement
+        // cannot complete. Do not strand the NEW bearer (never persisted): self-close
+        // it with its own scoped token first, and if that cannot be confirmed record
+        // an orphan marker for a later bootstrap to drain — then fail closed. Matches
+        // the store()-failure path's no-durable-credential handling.
+        const primaryError = new Error("a replacement harness cache requires a durable credential to confirm remote session cleanup");
+        const direct = await closeWithDurableCredential(call, {
+          session_id: session.session_id,
+          ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+        }, { auth: { "x-agent-api-key": session.session_token } });
+        if (!direct.closed) {
+          await recordOrphanAndFail({
+            session,
+            cwd: worktree,
+            retirementError: new Error("no durable credential is available to retire the cached session, and the new session's self-close was not confirmed"),
+            primaryError,
+          });
+        }
+        throw primaryError;
+      }
+      const discardNewSession = async () => {
+        // A successful self-close revokes this tier-3 token before its response
+        // reaches us. If that response is lost, retrying the bearer loops on
+        // 401 forever; the durable setup credential is the authority that can
+        // confirm the idempotent close (including already_closed).
+        const closeArgs = {
+          session_id: session.session_id,
+          ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+        };
+        const direct = await closeWithDurableCredential(call, closeArgs, {
+          auth: { "x-agent-api-key": session.session_token },
+        });
+        if (direct.closed) return;
+        const confirmed = await closeWithDurableCredential(call, closeArgs, cleanupOptions);
+        if (confirmed.closed) return;
+        throw new Error(cleanupError(confirmed.response) || direct.error?.message || "new harness session cleanup could not be confirmed");
+      };
+      const cachedCloseArgs = {
+        session_id: cached.session_id,
+        if_stale: true,
+        ...(cached.session_token_generation ? { session_token_generation: cached.session_token_generation } : {}),
+      };
+      let retired;
+      try {
+        retired = await call("close_session", cachedCloseArgs, cleanupOptions);
+      } catch (error) {
+        // BOT-1650 (Codex round-22): a THROWN cached-close (e.g. its idempotent
+        // close committed but the response was lost) must not bypass cleanup and
+        // strand the newly-admitted session — whose bearer is neither returned nor
+        // persisted — while the active holder blocks a later bridge thread with
+        // agent_session_conflict. Retry once (if_stale is idempotent) to confirm
+        // the old close; if it still cannot be confirmed, retire the new session
+        // before propagating.
+        const confirm = await call("close_session", cachedCloseArgs, cleanupOptions).catch((retryError) => ({ ok: false, error: retryError?.message }));
+        if (!confirm?.ok || confirm.isError) {
+          // BOT-1650 (Codex round-23): if retiring the new session ALSO fails (e.g.
+          // the same outage hits its direct AND durable close), do NOT swallow that
+          // and claim cleanup succeeded — the replacement bearer would stay active
+          // and block the next bootstrap. Surface both failures; a fresh bootstrap
+          // retries retirement (the orphaned session ages out / is re-reconciled).
+          try {
+            await discardNewSession();
+          } catch (discardError) {
+            // BOT-1650 (Codex round-24/25): retirement failed, so the new session
+            // is admitted but unpersisted. Record a cleanup marker (id+generation,
+            // no bearer) for a later bootstrap to drain, and fail closed preserving
+            // the cached-close cause, the retirement failure, and any marker-write
+            // failure (never swallowed).
+            await recordOrphanAndFail({ session, cwd: worktree, retirementError: discardError, primaryError: error });
+          }
+          throw error;
+        }
+        retired = confirm;
+      }
+      if (!retired?.ok || retired.isError) {
+        try {
+          await discardNewSession();
+        } catch (discardError) {
+          // BOT-1650 (Codex round-24/25): retirement failed here too — record the
+          // orphan and fail closed (propagating any marker-write failure).
+          await recordOrphanAndFail({ session, cwd: worktree, retirementError: discardError });
+        }
+        throw new Error(retired?.data?.error || retired?.error || "cached harness session is still live or could not be retired");
+      }
+      await clearHarnessSession(cached.session_id, {
+        cwd: worktree,
+        sessionToken: cached.session_token,
+        lock: false, // already inside withHarnessBootstrapLock (the same state lock); re-locking would deadlock
+      });
+    }
+    let state;
+    try {
+      state = await store(session, { cwd: worktree });
+    } 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
+      // session and can self-close, so try it first — the durable OAuth/MCP
+      // credential may have expired or been revoked between bootstrap and
+      // cleanup, and using only that would strand an active session whose token
+      // was never returned or saved. Fall back to the durable credential just
+      // to confirm an ambiguous close (a lost tier-3 response that already
+      // revoked its own bearer).
+      const closeArgs = {
+        session_id: session.session_id,
+        ...(session.session_token_generation ? { session_token_generation: session.session_token_generation } : {}),
+      };
+      const direct = await closeWithDurableCredential(call, closeArgs, {
+        auth: { "x-agent-api-key": session.session_token },
+      });
+      if (direct.closed) throw error;
+      const cleanupOptions = callOptions ?? await resolveCleanupOptions();
+      if (!cleanupOptions) {
+        // BOT-1650 (Codex round-26): the fresh bearer could not self-close AND no
+        // durable credential is available to retire the admitted session — so it
+        // cannot be closed at all. Record the orphan (so a later bootstrap with a
+        // credential drains it) and fail closed, instead of throwing with no marker.
+        await recordOrphanAndFail({
+          session,
+          cwd: worktree,
+          retirementError: new Error("no durable credential is available to confirm session cleanup"),
+          primaryError: error,
+        });
+      }
+      const confirmed = await closeWithDurableCredential(call, closeArgs, cleanupOptions);
+      if (!confirmed.closed) {
+        // BOT-1650 (Codex round-25): the session was admitted but its credential
+        // could not be persisted AND neither the fresh-bearer nor the durable
+        // close confirmed retirement — an orphaned live holder unrelated to cache
+        // replacement (e.g. a Windows ACL-hardening failure in store()). Record it
+        // so a later bootstrap drains it, and fail closed preserving both causes.
+        const retirementError = new Error(cleanupError(confirmed.response) || direct.error?.message || "bootstrap persistence cleanup could not be confirmed");
+        await recordOrphanAndFail({ session, cwd: worktree, retirementError, primaryError: error });
+      }
+      throw error;
+    }
+    return { ...state, ...(displayName ? { display_name: displayName } : {}), ...(ticketSignals ? { ticket_signals: ticketSignals } : {}), ...(linkage ? { linkage } : {}) };
+  });
+}

package/src/wait.mjs

@@ -19,7 +19,7 @@ import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
-import { clearAgentState, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
+import { clearAgentState, hasBootstrapAgentSession, isRejectedCachedSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
 import { touchAgentStateExpiry } from "./agent-state.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
@@ -1505,7 +1505,11 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       : new WaitCheckpointError("wait_checkpoint_write_failed", String(error?.message ?? error)));
   }
 
-  const needsRelay = conditions.some((c) => c.type !== "timer");
+  // BOT-1650: a plain timer stays offline, but a timer from a bootstrapped harness
+  // registers so its terminal receipt proves the current session principal (the
+  // cross-shell bootstrap contract). Detected without a network self-heal.
+  const needsRelay = conditions.some((c) => c.type !== "timer")
+    || await hasBootstrapAgentSession({ cwd: process.cwd() });
   if (needsRelay) {
     try {
       const credential = await resolveAgentSessionCredential({ argv, env: process.env, cwd: process.cwd() });