@botbuddy/cli 1.29.4 → 1.30.1

package/src/wait.mjs

@@ -18,7 +18,9 @@ import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
-import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
+import { AGENT_KEY_RE, readAgentSessionTokenEnv } from "./agent-key.mjs";
+import { clearAgentState, 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";
 import { realpath } from "node:fs/promises";
@@ -28,7 +30,7 @@ import { realpath } from "node:fs/promises";
 // implementation gets a typed, safe upgrade instruction.
 // BOT-1554: protocol 2 makes --session-id mandatory for every non-timer wait (the
 // server keeps MINIMUM_WAIT_PROTOCOL=1 so pre-2 installs are not 426'd).
-// BOT-1572/1582: protocol 3 — a $BOTBUDDY_AGENT_KEY (bb_agent_) authenticates the
+// BOT-1649: protocol 3 — a $BOTBUDDY_AGENT_SESSION_TOKEN (bb_sess_) authenticates the
 // wait on its own; no profile / --session-id / --token needed (the relay derives
 // agent, tenant, and session from the token). Falls back to protocol-2 behaviour
 // when no session token is present.
@@ -36,10 +38,14 @@ export const WAIT_PROTOCOL_VERSION = 3;
 const CLI_UPGRADE_COMMAND = latestPublicCliCommand("wait");
 const MIN_RECEIPT_MAX_BYTES = 512;
 const MAX_RECEIPT_MAX_BYTES = 64 * 1024;
-// BOT-1582: the server's session-token shape (bb_agent_ + 64 hex), plus the
-// BOT-1572 bb_sess_ legacy alias, both accepted for one release.
+// BOT-1649: bb_sess_ is canonical; bb_agent_ remains accepted as a one-release
+// alias (BOT-1582/1572 shape: bb_(agent|sess)_ + 64 hex).
 const SESSION_TOKEN_RE = AGENT_KEY_RE;
 
+export function shouldRenewCachedSession(error, credentialSource, attempts) {
+  return isRejectedCachedSession(error, credentialSource, attempts);
+}
+
 export const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
 USAGE
@@ -122,25 +128,20 @@ OPTIONS
   --receipt-max-bytes <n>   cap the receipt (512..65536; default 10240; payloads truncate to pointers)
   --heartbeat           keep this agent session alive while waiting (so it is not reaped)
   --url <base>          relay base URL (default $BOTBUDDY_RELAY_URL or https://api.bot-buddy.ai/functions/v1)
-  --agent-key <token>   the bb_agent_ session token to authenticate this wait — a one-liner
-                        equivalent to exporting $BOTBUDDY_AGENT_KEY (which is the default).
-                        Only accepts a session token; a client/profile key is refused.
-                        (--session-token is the one-release legacy alias.)
-  --session-id <uuid>   attribute this wait to the arming session (the work-graph session id from register_agent); default $BOTBUDDY_SESSION_ID.
-                        Unnecessary when $BOTBUDDY_AGENT_KEY / --agent-key is set (the relay derives the session from the token).
+  --agent-session-token <token>  advanced override for a managed runner; normal worktrees do not need it.
+                        (--agent-key and --session-token are one-release aliases.)
+  --session-id <uuid>   advanced attribution override; normal worktrees derive it automatically.
   --help                show this help
   resume <local_wait_id>       recover one explicitly named saved wait
   cancel <local_wait_id>       explicitly stop one saved wait
   acknowledge <local_wait_id>  mark one saved terminal receipt read
 
 AUTH
-  A wait authenticates from the bb_agent_ session token (minted by register_agent):
-  export $BOTBUDDY_AGENT_KEY, or pass it inline with --agent-key for a one-liner
-  ($BOTBUDDY_SESSION_TOKEN / --session-token still accepted for one release).
-  --token and --profile are RETIRED (BOT-1574): they were untyped and could carry a
-  machine credential; use --agent-key, which only accepts a session token. The
-  per-machine client key (botbuddy login) is a setup credential, never a wait
-  credential.
+  In a configured project worktree, bb wait restores or renews its session automatically.
+  For first-time setup or repair, run bb setup once, then retry the same wait. No environment
+  variables, copied identifiers, or credential flags are needed for normal waits.
+  --token and --profile are RETIRED (BOT-1574); the session override above is for managed
+  runners only. The per-machine client key is a setup credential, never a wait credential.
 
 OUTPUT
   Exactly one JSON receipt line on stdout at exit, with client semver and
@@ -184,11 +185,10 @@ function parseArgv(argv) {
     // BOT-1467: attribute this wait to the arming session's agent (the id from
     // register_agent) instead of the tenant-bound profile agent. Env fallback.
     sessionId: process.env.BOTBUDDY_SESSION_ID || null,
-    // BOT-1572/1582: the per-session token. When present it is the ONLY credential —
-    // profile, --session-id, and --token are unnecessary. $BOTBUDDY_AGENT_KEY is
-    // the norm ($BOTBUDDY_SESSION_TOKEN still accepted for one release); the flag
-    // is for tests/overrides.
-    sessionToken: readAgentKeyEnv(process.env),
+    // BOT-1649: the per-session token. When present it is the ONLY credential —
+    // profile, --session-id, and --token are unnecessary.
+    // $BOTBUDDY_AGENT_SESSION_TOKEN is canonical; aliases remain accepted.
+    sessionToken: readAgentSessionTokenEnv(process.env),
     help: false,
     deadlineAt: null,
     resumeLocalWait: null,
@@ -218,13 +218,13 @@ function parseArgv(argv) {
     // following value so it is not mis-parsed as a condition, then fail fast in
     // runWait with a migration hint (AC3).
     else if (a === "--token" || a === "--profile") { opts.retiredFlag ??= a; optionValue(); }
-    // BOT-1574: --agent-key is the typed one-liner for the wait credential — it
-    // carries the bb_agent_ session token (equivalent to exporting
-    // $BOTBUDDY_AGENT_KEY), and NOTHING else: a client key / profile key is the
+    // BOT-1649: --agent-session-token is the canonical one-liner for the wait
+    // credential — it carries the bb_sess_ token (equivalent to exporting
+    // $BOTBUDDY_AGENT_SESSION_TOKEN), and NOTHING else: a client key / profile key is the
     // wrong shape and is refused invalid_session_token, so it can never smuggle a
     // machine credential onto a wait. --session-token is the one-release legacy
     // alias for the same value.
-    else if (a === "--agent-key" || a === "--session-token") opts.sessionToken = optionValue();
+    else if (a === "--agent-session-token" || a === "--agent-key" || a === "--session-token") opts.sessionToken = optionValue();
     else if (a === "--session-id") opts.sessionId = optionValue();
     else if (a === "--resume-local-wait") opts.resumeLocalWait = optionValue();
     else if (a.startsWith("--")) opts.unknown = a;
@@ -259,8 +259,8 @@ async function reserveClaimQueueBoundary(opts, conditions) {
 }
 
 async function registerWait(opts, conditions, deadlineIso) {
-  // BOT-1608: a relay wait authenticates from the per-session `bb_agent_` token
-  // ($BOTBUDDY_AGENT_KEY) — the relay derives agent, tenant, and session from it.
+  // BOT-1649: a relay wait authenticates from the per-session `bb_sess_` token
+  // ($BOTBUDDY_AGENT_SESSION_TOKEN) — the relay derives agent, tenant, and session from it.
   // The retired protocol-2 profile register (profile + expected_tenant) is gone
   // with the profile bridge; runWait fails closed before here if no session token.
   const registerBody = {
@@ -492,6 +492,21 @@ async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
 // parsed frames. Server emits `id: <seq>` per signal and replays `seq > since`
 // on connect, so a reconnect never loses an event.
 function makeConnect(opts) {
+  // BOT-1649: mirror the relay's keepalive expiry roll into the 0600 cache. The
+  // server bumps session_token_expires_at on connect and every keepalive, but
+  // the cache keeps its register-time deadline — so a wait near the 8 h cap goes
+  // locally stale ~5 min early while the server token is still valid, and a
+  // concurrent command would remint and reconcile away this running wait. Touch
+  // the cache on live-stream activity, throttled to at most one write / 4 min.
+  // touchAgentStateExpiry self-gates on a token match, so flag/env sources whose
+  // token isn't the cached one are a no-op.
+  let lastCacheTouch = 0;
+  const touchCache = () => {
+    const now = Date.now();
+    if (now - lastCacheTouch < 240_000) return;
+    lastCacheTouch = now;
+    void touchAgentStateExpiry(process.cwd(), opts.token).catch(() => {});
+  };
   return async function connect(since) {
     const sinceParam = normalizeSince(since);
     const url = new URL(`${opts.url.replace(/\/$/, "")}/event-stream`);
@@ -527,7 +542,7 @@ function makeConnect(opts) {
     if (res.status === 403) return errorStream("forbidden");
     if (!res.ok || !res.body) throw new Error(`relay responded ${res.status}`);
 
-    return sseFrameStream(res.body, { onIdle: () => ac.abort() });
+    return sseFrameStream(res.body, { onIdle: () => ac.abort(), onActivity: touchCache });
   };
 }
 
@@ -605,7 +620,7 @@ function sseIdleTimeoutMs() {
 
 const SSE_IDLE = Symbol("sse_idle");
 
-export async function* sseFrameStream(body, { idleMs = sseIdleTimeoutMs(), onIdle = null } = {}) {
+export async function* sseFrameStream(body, { idleMs = sseIdleTimeoutMs(), onIdle = null, onActivity = null } = {}) {
   const decoder = new TextDecoder();
   let buf = "";
   const iterator = body[Symbol.asyncIterator]();
@@ -633,6 +648,11 @@ export async function* sseFrameStream(body, { idleMs = sseIdleTimeoutMs(), onIdl
       }
       const { value: chunk, done } = result;
       if (done) return;
+      // A chunk (data frame OR a keepalive comment) means the relay is live and
+      // has just rolled the session's server-side expiry forward. Let the caller
+      // mirror that roll locally (BOT-1649) so a long wait's cache never goes
+      // stale ahead of the still-valid token.
+      if (onActivity) onActivity();
       buf += decoder.decode(chunk, { stream: true });
       const { frames, rest } = parseSseFrames(buf);
       buf = rest;
@@ -712,15 +732,14 @@ function emit(receipt, { versioned = false, maxBytes = null } = {}) {
 // renders. Keep each to one line and never embed a secret value — names, slots,
 // and env-var names only.
 export const RECOVERY = Object.freeze({
-  // BOT-1582: $BOTBUDDY_AGENT_KEY (bb_agent_+64hex, renamed from
-  // $BOTBUDDY_SESSION_TOKEN) is minted by register_agent; the harness exports it
-  // at session start. The legacy var is still accepted for one release.
-  sessionToken: "the tier-3 session token (bb_agent_) is minted by register_agent — export BOTBUDDY_AGENT_KEY=<session_token> (and BOTBUDDY_SESSION_ID=<session_id>); the harness exports both at session start. See docs/agent-connectivity.md",
-  // $BOTBUDDY_SESSION_ID is the work-graph session id returned by register_agent.
-  sessionId: "register_agent → export BOTBUDDY_SESSION_ID=<session_id> (the work-graph session id from register_agent)",
+  // BOT-1649: normal waits restore or mint their per-worktree session themselves.
+  // Keep recovery as one concise command; credential plumbing is intentionally
+  // hidden from agents and operators.
+  sessionToken: "run `bb setup` from this project worktree, then retry the same wait (or `bb doctor --fix` for diagnosis). See docs/agent-connectivity.md",
+  sessionId: "run `bb setup` from this project worktree, then retry the same wait",
   // A --token / session-token contradiction: the session token is the whole
   // credential, so drop --token (never advise also setting a session id here).
-  sessionTokenConflict: "unset --token — $BOTBUDDY_AGENT_KEY is the whole credential (protocol 3)",
+  sessionTokenConflict: "unset --token — the session credential is the whole credential (protocol 3)",
   // Grammar/condition errors point at the help and the canonical doc.
   conditions: "check the condition grammar: botbuddy wait --help / docs/agent-wait.md",
 });
@@ -745,7 +764,7 @@ async function reportSetupError(opts, { error, exitCode, conditions }) {
   // Never on the session-token path. A bb_agent_/bb_sess_ SESSION token cannot
   // authenticate at sensor-ingest (edgeAuth resolves only PATs / agent keys), so it
   // would only 401. Discriminate by the credential's SOURCE, not its shape: a
-  // session token arrives only via $BOTBUDDY_AGENT_KEY / --session-token
+  // session token arrives only via $BOTBUDDY_AGENT_SESSION_TOKEN / --agent-session-token
   // (opts.sessionToken), whereas a resolved PROFILE credential may legitimately be a
   // legacy bb_agent_ CARRIER key that ingest CAN authenticate — the two share a shape
   // (BOT-1582), so a shape check would wrongly drop the carrier case (Codex P1).
@@ -928,42 +947,89 @@ export function restoreCapacityStaleDeadlines(conditions, checkpoint) {
   return conditions;
 }
 
-async function deliverRecoveryAction(checkpoint, action) {
-  if (!checkpoint.cloud_wait_session_id) return { delivered: true };
-  const token = readAgentKeyEnv(process.env);
-  if (!token || !SESSION_TOKEN_RE.test(token)) {
-    return { delivered: false, error: "session_token_required" };
-  }
-  const baseUrl = checkpoint.relay_url || process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1";
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5_000);
+// BOT-1649 (Codex round-5 P1): recovery actions (cancel / finalize / acknowledge
+// / lookup) must authenticate with the SAME managed credential the arm used —
+// flag → env → 0600 cache → self-heal — not env alone. After the variable-free
+// `bb setup` flow the session token lives only in the worktree cache, so an
+// env-only read left cancel/finalize permanently `*_pending` and could orphan a
+// claim wait that later grabs its resource.
+export async function resolveRecoveryToken(cwd = process.cwd(), env = process.env) {
   try {
-    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/event-stream`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "x-agent-api-key": token,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ action, wait_session_id: checkpoint.cloud_wait_session_id }),
-      signal: controller.signal,
-    });
-    const body = await res.json().catch(() => ({}));
-    const resultKey = action === "acknowledge" ? "acknowledged" : "cancelled";
-    // The recovery endpoint is deliberately idempotent and uses a 200 response
-    // for a rejected state transition.  Only its explicit boolean proves that
-    // the cloud row changed; otherwise retain the local delivery outbox.
-    if (!res.ok || body?.[resultKey] !== true) {
-      return { delivered: false, error: body?.error || `${action}_not_applied` };
+    const credential = await resolveAgentSessionCredential({ argv: [], env, cwd });
+    const token = credential?.token ?? null;
+    return token && SESSION_TOKEN_RE.test(token) ? token : null;
+  } catch { return null; }
+}
+
+// BOT-1649 (Codex round-6 P1): every recovery call (cancel / finalize /
+// acknowledge / lookup) POSTs to /event-stream and must survive a
+// server-revoked CACHE token exactly like normal wait registration. Resolve the
+// credential WITH its source, and on a 401 session-token rejection of a
+// cache-sourced token, clear the 0600 cache, re-mint under the durable client
+// key, and retry the request once. Without this a locally cancelled/finalized
+// claim wait stays `*_pending` forever while its cloud row remains ACTIVE and
+// can still acquire the resource. Flag/env tokens are caller-owned and never
+// silently replaced; the re-mint source is "minted", so a second rejection
+// cannot loop. Returns one of: {error} (no usable token), {transportError:
+// "timeout"|"unavailable"}, or {ok, status, body}.
+async function postRecovery(relayUrl, payload, { cwd = process.cwd(), env = process.env } = {}) {
+  let credential = null;
+  try { credential = await resolveAgentSessionCredential({ argv: [], env, cwd }); } catch { credential = null; }
+  let token = credential?.token ?? null;
+  let source = credential?.source ?? null;
+  if (!token || !SESSION_TOKEN_RE.test(token)) return { error: "session_token_required" };
+  const baseUrl = relayUrl || env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1";
+  const url = `${baseUrl.replace(/\/$/, "")}/event-stream`;
+  let attempts = 0;
+  for (;;) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5_000);
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}`, "x-agent-api-key": token, "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      return { transportError: error?.name === "AbortError" ? "timeout" : "unavailable" };
     }
-    return { delivered: true };
-  } catch (error) {
-    return { delivered: false, error: error?.name === "AbortError" ? `${action}_timeout` : `${action}_unavailable` };
-  } finally {
     clearTimeout(timer);
+    const body = await res.json().catch(() => ({}));
+    // A revoked/expired session token returns a typed 401. Renew a cache token
+    // once (isRejectedCachedSession gates on source==="cache" && attempts===0).
+    if (res.status === 401 && isRejectedCachedSession({ code: body?.error }, source, attempts)) {
+      attempts += 1;
+      await clearAgentState(cwd);
+      let renewed = null;
+      try { renewed = await selfHealAgentSession({ cwd, env }); } catch { renewed = null; }
+      if (renewed?.token && SESSION_TOKEN_RE.test(renewed.token)) {
+        token = renewed.token;
+        source = renewed.source;
+        continue;
+      }
+    }
+    return { ok: res.ok, status: res.status, body };
   }
 }
 
+async function deliverRecoveryAction(checkpoint, action) {
+  if (!checkpoint.cloud_wait_session_id) return { delivered: true };
+  const result = await postRecovery(checkpoint.relay_url, { action, wait_session_id: checkpoint.cloud_wait_session_id });
+  if (result.error) return { delivered: false, error: result.error };
+  if (result.transportError) return { delivered: false, error: `${action}_${result.transportError}` };
+  const resultKey = action === "acknowledge" ? "acknowledged" : "cancelled";
+  // The recovery endpoint is deliberately idempotent and uses a 200 response
+  // for a rejected state transition.  Only its explicit boolean proves that
+  // the cloud row changed; otherwise retain the local delivery outbox.
+  if (!result.ok || result.body?.[resultKey] !== true) {
+    return { delivered: false, error: result.body?.error || `${action}_not_applied` };
+  }
+  return { delivered: true };
+}
+
 function checkpointNeedsRelay(checkpoint) {
   return checkpoint.conditions.some((condition) => condition.type !== "timer");
 }
@@ -972,85 +1038,51 @@ async function resolveRecoveryWaitSession(checkpoint, { reserveMissing = false }
   if (checkpoint.cloud_wait_session_id || !checkpointNeedsRelay(checkpoint)) {
     return { registration: null };
   }
-  const token = readAgentKeyEnv(process.env);
-  if (!token || !SESSION_TOKEN_RE.test(token)) {
-    return { error: "session_token_required" };
+  const result = await postRecovery(checkpoint.relay_url, {
+    action: reserveMissing ? "recover_cancel_absent" : "recover_lookup",
+    local_wait_id: checkpoint.local_wait_id,
+  });
+  if (result.error) return { error: result.error };
+  if (result.transportError) {
+    return { error: result.transportError === "timeout" ? "wait_recovery_lookup_timeout" : "wait_recovery_lookup_unavailable" };
   }
-  const url = checkpoint.relay_url || process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1";
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5_000);
-  try {
-    const res = await fetch(`${url.replace(/\/$/, "")}/event-stream`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "x-agent-api-key": token,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ action: reserveMissing ? "recover_cancel_absent" : "recover_lookup", local_wait_id: checkpoint.local_wait_id }),
-      signal: controller.signal,
-    });
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok) return { error: body?.error || "wait_recovery_lookup_failed" };
-    if (body?.found !== true) return { missing: true };
-    if (typeof body.wait_session_id !== "string" || !body.wait_session_id) {
-      return { error: "wait_session_id_unavailable" };
-    }
-    return {
-      registration: {
-        waitSessionId: body.wait_session_id,
-        cursorStart: body.cursor_start ?? null,
-        sessionTenant: checkpoint.tenant_id ?? null,
-        agentId: checkpoint.agent_id ?? null,
-        sessionId: checkpoint.arming_session_id ?? null,
-        sessionAgentId: null,
-        status: typeof body.status === "string" ? body.status : "active",
-        terminalReceipt: body.terminal_receipt && typeof body.terminal_receipt === "object" ? body.terminal_receipt : null,
-      },
-    };
-  } catch (error) {
-    return { error: error?.name === "AbortError" ? "wait_recovery_lookup_timeout" : "wait_recovery_lookup_unavailable" };
-  } finally {
-    clearTimeout(timer);
+  const body = result.body ?? {};
+  if (!result.ok) return { error: body?.error || "wait_recovery_lookup_failed" };
+  if (body?.found !== true) return { missing: true };
+  if (typeof body.wait_session_id !== "string" || !body.wait_session_id) {
+    return { error: "wait_session_id_unavailable" };
   }
+  return {
+    registration: {
+      waitSessionId: body.wait_session_id,
+      cursorStart: body.cursor_start ?? null,
+      sessionTenant: checkpoint.tenant_id ?? null,
+      agentId: checkpoint.agent_id ?? null,
+      sessionId: checkpoint.arming_session_id ?? null,
+      sessionAgentId: null,
+      status: typeof body.status === "string" ? body.status : "active",
+      terminalReceipt: body.terminal_receipt && typeof body.terminal_receipt === "object" ? body.terminal_receipt : null,
+    },
+  };
 }
 
 async function deliverTerminalFinalization(checkpoint) {
   if (!checkpoint.cloud_wait_session_id || !checkpoint.terminal_receipt) return { delivered: true };
-  const token = readAgentKeyEnv(process.env);
-  if (!token || !SESSION_TOKEN_RE.test(token)) return { delivered: false, error: "session_token_required" };
-  const baseUrl = checkpoint.relay_url || process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1";
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 5_000);
-  try {
-    const receipt = checkpoint.terminal_receipt;
-    const res = await fetch(`${baseUrl.replace(/\/$/, "")}/event-stream`, {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "x-agent-api-key": token,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({
-        action: "recover_finalize",
-        wait_session_id: checkpoint.cloud_wait_session_id,
-        status: receipt.outcome,
-        receipt,
-        reconnects: receipt.reconnects ?? 0,
-        degraded: receipt.degraded ?? [],
-      }),
-      signal: controller.signal,
-    });
-    const body = await res.json().catch(() => ({}));
-    if (!res.ok || body?.finalized !== true) {
-      return { delivered: false, error: body?.error || "finalize_not_applied" };
-    }
-    return { delivered: true };
-  } catch (error) {
-    return { delivered: false, error: error?.name === "AbortError" ? "finalize_timeout" : "finalize_unavailable" };
-  } finally {
-    clearTimeout(timer);
+  const receipt = checkpoint.terminal_receipt;
+  const result = await postRecovery(checkpoint.relay_url, {
+    action: "recover_finalize",
+    wait_session_id: checkpoint.cloud_wait_session_id,
+    status: receipt.outcome,
+    receipt,
+    reconnects: receipt.reconnects ?? 0,
+    degraded: receipt.degraded ?? [],
+  });
+  if (result.error) return { delivered: false, error: result.error };
+  if (result.transportError) return { delivered: false, error: `finalize_${result.transportError}` };
+  if (!result.ok || result.body?.finalized !== true) {
+    return { delivered: false, error: result.body?.error || "finalize_not_applied" };
   }
+  return { delivered: true };
 }
 
 async function flushPendingFinalization(store, checkpoint) {
@@ -1329,9 +1361,8 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   // a typed `unknown_option` receipt, then exit 4 — before any relay call.
   if (opts.retiredFlag) {
     process.stderr.write(
-      `botbuddy wait: ${opts.retiredFlag} is retired (it could carry a machine credential) — a wait authenticates from the bb_agent_ session token. `
-        + "Pass it typed with --agent-key <token>, or export $BOTBUDDY_AGENT_KEY (from register_agent), then: botbuddy wait '<condition>'. "
-        + "The per-machine client key (botbuddy login) is never a wait credential.\n",
+      `botbuddy wait: ${opts.retiredFlag} is retired — run bb wait from a configured worktree and it restores its session automatically. `
+        + "If setup is needed, run bb setup, then retry the same wait.\n",
     );
     emitReceipt({
       schema_version: 1,
@@ -1472,20 +1503,40 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   }
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
-  // BOT-1572/1582/1608: a relay wait authenticates from the per-session
-  // $BOTBUDDY_AGENT_KEY (bb_agent_) — the relay derives agent, tenant, and session
+  if (needsRelay) {
+    try {
+      const credential = await resolveAgentSessionCredential({ argv, env: process.env, cwd: process.cwd() });
+      opts.sessionToken = credential.token;
+      opts.sessionId = credential.sessionId ?? opts.sessionId;
+      opts.credentialSource = credential.source;
+    } catch (error) {
+      const code = error?.code ?? "session_mint_failed";
+      const recovery = 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"
+        : "run `bb setup` and retry";
+      process.stderr.write(`botbuddy wait: ${error?.message ?? error}; ${recovery}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: code, recovery });
+      await reportSetupError(opts, { error: code, exitCode: EXIT.AUTH, conditions });
+      process.exit(EXIT.AUTH);
+    }
+  }
+  // BOT-1649: a relay wait authenticates from the per-session
+  // $BOTBUDDY_AGENT_SESSION_TOKEN (bb_sess_; bb_agent_ remains a legacy alias)
+  // — the relay derives agent, tenant, and session
   // from the token. The retired protocol-2 profile register (profile + --session-id
   // + a tenant-bound carrier from `profile setup`) is gone with the profile bridge,
-  // so a relay wait with no session token now fails closed with an actionable fix.
+  // so an absent/stale cache self-heals before this validation.
   if (needsRelay && opts.sessionToken) {
     if (!SESSION_TOKEN_RE.test(opts.sessionToken)) {
-      process.stderr.write(`botbuddy wait: $BOTBUDDY_AGENT_KEY must match bb_agent_<64 hex>; ${RECOVERY.sessionToken}\n`);
+      process.stderr.write(`botbuddy wait: BOTBUDDY_AGENT_SESSION_TOKEN must match bb_sess_<64 hex> (bb_agent_ is a legacy prefix); ${RECOVERY.sessionToken}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_token", recovery: RECOVERY.sessionToken });
       await reportSetupError(opts, { error: "invalid_session_token", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
     }
     if (opts.token && opts.token !== opts.sessionToken) {
-      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_KEY; ${RECOVERY.sessionTokenConflict}\n`);
+      process.stderr.write(`botbuddy wait: --token conflicts with $BOTBUDDY_AGENT_SESSION_TOKEN; ${RECOVERY.sessionTokenConflict}\n`);
       emitReceipt({ schema_version: 1, outcome: "error", error: "session_token_conflict", recovery: RECOVERY.sessionTokenConflict });
       await reportSetupError(opts, { error: "session_token_conflict", exitCode: EXIT.INVALID, conditions });
       process.exit(EXIT.INVALID);
@@ -1495,7 +1546,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   } else if (needsRelay) {
     // No session token → the wait has no credential. Fail fast (before any network
     // call) so a wait is never filed under whatever machine credential is lying
-    // around. register_agent mints the token and the harness exports it.
+    // around. The normal recovery is the one-command worktree bootstrap.
     process.stderr.write(
       `botbuddy wait: a relay wait requires the per-session agent token — ${RECOVERY.sessionToken}, then: botbuddy wait '<condition>'\n`,
     );
@@ -1537,14 +1588,45 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
   let replayExpiredRecovery = false;
   if (needsRelay) {
     try {
-      // The reservation is made while this checkpoint is still live, on the
-      // database clock. An expired recovery with no reservation fails closed and
-      // cannot release a queue re-created by another logical wait.
+      // BOT-1656: the claim-queue reservation is made while this checkpoint is
+      // still live, on the database clock. An expired recovery with no
+      // reservation fails closed and cannot release a queue re-created by another
+      // logical wait. It happens once, before (and outside) the self-heal retry.
       if ((Date.now() < deadlineMs || recoveryLocalWaitId != null) &&
           conditions.some((condition) => condition.type === "lock" && condition.params?.claim === true)) {
         await reserveClaimQueueBoundary(opts, conditions);
       }
-      const reg = await registerWait(opts, conditions, new Date(deadlineMs).toISOString());
+      // BOT-1649: a revoked/expired token from the 0600 cache is recoverable:
+      // remove only that cache, re-adopt the public agent id under the client
+      // key, and retry registration exactly once. Explicit flags/env are never
+      // silently replaced because the caller owns those credentials. Re-register
+      // is idempotent on the checkpoint's logical_wait_id (BOT-1656), so the
+      // reservation above is not repeated.
+      let attempts = 0;
+      let reg;
+      for (;;) {
+        try {
+          reg = await registerWait(opts, conditions, new Date(deadlineMs).toISOString());
+          break;
+        } catch (error) {
+          if (!shouldRenewCachedSession(error, opts.credentialSource, attempts)) throw error;
+          attempts += 1;
+          await clearAgentState(process.cwd());
+          const credential = await selfHealAgentSession({ cwd: process.cwd(), env: process.env });
+          opts.sessionToken = credential.token;
+          opts.sessionId = credential.sessionId ?? opts.sessionId;
+          opts.credentialSource = credential.source;
+          opts.token = credential.token;
+        }
+      }
+      // BOT-1649 (Codex P1): the server just rolled this session's expiry forward
+      // on register. Mirror that roll into the 0600 cache so a token in active use
+      // is never judged locally stale and re-minted — a re-mint would revoke the
+      // token a concurrent wait still holds. Touch only the cache we actually used
+      // (source "cache"); a "minted" source already wrote a fresh deadline.
+      if (opts.credentialSource === "cache") {
+        await touchAgentStateExpiry(process.cwd(), opts.token).catch(() => {});
+      }
       waitSessionId = reg.waitSessionId;
       opts.waitSessionId = waitSessionId;
       sessionTenant = reg.sessionTenant;
@@ -1679,12 +1761,11 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         process.exit(EXIT.INVALID);
       }
       if (err && err.auth) {
-        // BOT-1574 (AC4): the relay refused a wait armed by the per-machine client
-        // key (or any owner/setup credential). The fix is never profile setup —
-        // register a work agent and export its session token.
+        // A per-machine client key cannot arm a wait directly. Keep the recovery
+        // to the normal worktree bootstrap rather than exposing session internals.
         if (err.errorCode === "client_key_cannot_wait") {
           process.stderr.write(
-            "botbuddy wait: a tier-1 client key (bb_cli_, botbuddy login) cannot arm a wait — you need the tier-3 session token: register_agent, export BOTBUDDY_AGENT_KEY=<session_token>, then re-run\n",
+            "botbuddy wait: this worktree needs a session; run bb setup, then retry the same wait\n",
           );
           emitReceipt({
             schema_version: 1,
@@ -1694,11 +1775,8 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           });
           process.exit(EXIT.AUTH);
         }
-        // BOT-1554: SESSION-IDENTITY failures — the session token (or the session
-        // id it carries) is a shared service carrier, an ended/foreign session, or
-        // a wrong-tenant session. Retrying with the SAME identity just repeats the
-        // 403, so lead with the reliable fix: register a WORK agent and export its
-        // NEW session token/id.
+        // Session-identity failures need a new worktree session. Do not make the
+        // caller reconstruct it by hand.
         const SESSION_IDENTITY_ERRORS = new Set([
           "wait_actor_required", "session_agent_forbidden", "session_agent_tenant_mismatch",
         ]);
@@ -1709,29 +1787,28 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
               ? "the session token resolves to a different tenant than this wait"
               : "the session token is not a live agent session you own";
           process.stderr.write(
-            `botbuddy wait: ${cause}; register a work agent (register_agent) and export the returned $BOTBUDDY_AGENT_KEY (and $BOTBUDDY_SESSION_ID)\n`,
+            `botbuddy wait: ${cause}; run bb setup, then retry the same wait\n`,
           );
           emitReceipt(withPrincipalReceipt({
             schema_version: 1,
             outcome: "error",
             error: err.errorCode,
             ...(err.carrierAgentId ? { carrier_agent_id: err.carrierAgentId } : {}),
-            recovery: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token>",
+            recovery: "run `bb setup`, then retry the same wait",
           }, null, { sessionTenant, agentId: null }));
           await reportSetupError(opts, { error: err.errorCode, exitCode: EXIT.AUTH, conditions });
           process.exit(EXIT.AUTH);
         }
         // Any other relay auth refusal (revoked/expired/rotated token, or the relay
-        // refusing to honour it) is fixed by RE-REGISTERING and exporting the new
-        // session token — the profile bridge and its recoveries are gone (BOT-1608).
+        // refusing to honour it) is repaired by the worktree bootstrap.
         process.stderr.write(
-          `botbuddy wait: session token rejected (${err.errorCode || "unauthorized"}) — re-register the agent and export the new $BOTBUDDY_AGENT_KEY\n`,
+          `botbuddy wait: session rejected (${err.errorCode || "unauthorized"}) — run bb setup, then retry the same wait\n`,
         );
         emitReceipt(withPrincipalReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode || "unauthorized",
-          recovery: "register_agent → export BOTBUDDY_AGENT_KEY=<session_token>",
+          recovery: "run `bb setup`, then retry the same wait",
         }, null, { sessionTenant, agentId: registeredAgentId, sessionId: registeredSessionId }));
         // Session-token path → reportSetupError self-skips (a bb_agent_ bearer
         // ingest cannot authenticate); called for allowlist symmetry.