@botbuddy/cli 1.13.2 → 1.14.0

package/package.json

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

package/src/agent-credential-store.mjs

@@ -93,20 +93,59 @@ function writePasswordPrompt(command, args, password, spawnProcess) {
 export async function writeKeychainSecret(service, token, {
   spawnProcess = spawn,
   execFileImpl = execFileAsync,
-  readSecret = (svc) => readKeychainSecret(svc, { execFileImpl }),
+  keychain = null,
+  createOnly = false,
+  readSecret = (svc) => readKeychainSecret(svc, { execFileImpl, keychain }),
 } = {}) {
   if (!service) throw new ProfileCredentialStoreError("keychain write requires a service name");
+  // BOT-1569 (Codex P2): `-U` makes `add-generic-password` UPDATE an existing
+  // item. `login` wants that (re-login overwrites the owner token), but the
+  // config→Keychain migration must NOT: between its empty-slot read and this
+  // write, another process could complete a fresh login, and `-U` would then
+  // overwrite that newly-issued token with the stale config value. `createOnly`
+  // drops `-U` so the write CREATES only — `security` fails with "already exists"
+  // (mapped to `keychain_item_exists`) if the slot filled concurrently, and the
+  // migration refuses instead of downgrading.
+  const update = createOnly ? [] : ["-U"];
   try {
-    await writePasswordPrompt(
-      "security",
-      ["add-generic-password", "-U", "-s", service, "-a", userInfo().username, "-w"],
-      token,
-      spawnProcess,
-    );
+    if (keychain) {
+      // BOT-1570: an explicit keychain path is used only by the integration tests
+      // against a scratch `security create-keychain` (never the login keychain).
+      // `security -w` PROMPT mode reads the secret from stdin, but its optional
+      // argument greedily consumes the trailing [keychain] positional — so prompt
+      // mode and an explicit keychain cannot coexist. With a keychain path the
+      // value is written inline (throwaway scratch token); production (no keychain
+      // path) keeps the detached stdin double-feed that keeps the real credential
+      // off argv.
+      // `-A` grants every application access to the item without an ACL prompt.
+      // That is deliberately insecure and reserved for the throwaway scratch
+      // keychain the integration tests target — it keeps `security` fully
+      // headless (no SecurityAgent GUI dialog on the read-back). Production never
+      // takes this branch, so the login keychain is never written with `-A`.
+      await execFileImpl(
+        "security",
+        ["add-generic-password", ...update, "-A", "-s", service, "-a", userInfo().username, "-w", token, keychain],
+      );
+    } else {
+      await writePasswordPrompt(
+        "security",
+        ["add-generic-password", ...update, "-s", service, "-a", userInfo().username, "-w"],
+        token,
+        spawnProcess,
+      );
+    }
   } catch (error) {
+    const detail = String(error?.stderr ?? error?.message ?? error);
+    // createOnly: a concurrent writer already filled the slot. Surface a typed
+    // code so the migration refuses rather than overwriting the newer token.
+    if (createOnly && /already exists/i.test(detail)) {
+      throw new ProfileCredentialStoreError(
+        `the macOS Keychain already holds an item for ${service}`,
+        { cause: error, code: "keychain_item_exists" },
+      );
+    }
     // `security` cancels its authorization when the login keychain is locked in
     // a headless session; guide the user to unlock it rather than re-login.
-    const detail = String(error?.message ?? error);
     if (/authorization was cancell?ed/i.test(detail)) {
       throw new ProfileCredentialStoreError(
         "macOS Keychain authorization was canceled — unlock your login keychain (`security unlock-keychain`) and retry; a headless session needs it already unlocked",
@@ -128,20 +167,46 @@ export async function writeKeychainSecret(service, token, {
   }
 }
 
-export async function readKeychainSecret(service, { execFileImpl = execFileAsync } = {}) {
+// `security find-generic-password` exits non-zero both when the item is genuinely
+// absent (exit 44 / "could not be found") AND on a real failure (locked keychain,
+// authorization temporarily unavailable). The two must be distinguished by any
+// caller that would WRITE based on "absent" — treating a transient read failure
+// as "empty" can overwrite a live credential (BOT-1569 Codex P2).
+function isKeychainItemNotFound(error) {
+  // Only the ACTUAL not-found indicators: exit 44, or the "could not be found"
+  // message. The `SecKeychainSearchCopyNext` API-function prefix alone is NOT a
+  // sufficient signal — it can front other diagnostics — so every other failure
+  // stays fail-closed (Codex P2).
+  if (Number(error?.code) === 44) return true;
+  const detail = String(error?.stderr ?? error?.message ?? error ?? "");
+  return /could not be found/i.test(detail);
+}
+
+export async function readKeychainSecret(service, { execFileImpl = execFileAsync, keychain = null, strict = false } = {}) {
   if (!service) return null;
+  // BOT-1570: an explicit keychain path (scratch keychain, tests only) is the
+  // trailing positional `security` searches; production omits it and searches
+  // the default search list.
+  const args = ["find-generic-password", "-s", service, "-a", userInfo().username, "-w"];
+  if (keychain) args.push(keychain);
   try {
-    const { stdout } = await execFileImpl("security", ["find-generic-password", "-s", service, "-a", userInfo().username, "-w"]);
+    const { stdout } = await execFileImpl("security", args);
     return stdout.trim() || null;
-  } catch {
+  } catch (error) {
+    // Non-strict (default, back-compat): any failure reads as "no value". Strict:
+    // only a genuine not-found is null; a real read failure is re-thrown so the
+    // caller can fail closed instead of mistaking it for an empty slot.
+    if (strict && !isKeychainItemNotFound(error)) throw error;
     return null;
   }
 }
 
-export async function deleteKeychainSecret(service, { execFileImpl = execFileAsync } = {}) {
+export async function deleteKeychainSecret(service, { execFileImpl = execFileAsync, keychain = null } = {}) {
   if (!service) return false;
+  const args = ["delete-generic-password", "-s", service, "-a", userInfo().username];
+  if (keychain) args.push(keychain); // BOT-1570: scoped to the scratch keychain in tests
   try {
-    await execFileImpl("security", ["delete-generic-password", "-s", service, "-a", userInfo().username]);
+    await execFileImpl("security", args);
     return true;
   } catch {
     return false;

package/src/cli-credentials.mjs

@@ -50,6 +50,119 @@ export function sanitizeConfigSecrets(config, { platform = process.platform, exi
   return { config: out, changed };
 }
 
+// BOT-1569: migrate, never drop. `sanitizeConfigSecrets` only ever *removed* a
+// config.json `access_token` on a Keychain-available host — it never copied the
+// value into the Keychain first. So a `login` that stored the token in
+// config.json (Keychain unavailable/headless) lost the credential the next time
+// any command ran where the Keychain was reachable. This async variant is what
+// `loadConfig` runs: on a Keychain-available host it COPIES a config.json owner
+// token into the Keychain and read-back verifies it BEFORE removing it from
+// config.json; if the migration can't be verified (locked/failing Keychain) the
+// config copy is preserved so the sole live credential is never deleted. On a
+// host without a Keychain the token stays put (the documented fallback store).
+// `api_key` (written by the retired `register`) has no Keychain home and is
+// always dropped.
+export async function migrateConfigSecrets(config, {
+  platform = process.platform,
+  exists,
+  // `createOnly`: the migration write must not overwrite a token another process
+  // wrote after our empty-slot read (BOT-1569 Codex P2 TOCTOU).
+  keychainWrite = (value) => writeKeychainSecret(OWNER_TOKEN_SERVICE, value, { createOnly: true }),
+  // `strict`: a transient READ failure throws (fail closed) instead of reading as
+  // an empty slot, so the migration never overwrites a live stored token because
+  // the lookup momentarily failed (BOT-1569 Codex P2).
+  keychainRead = () => readKeychainSecret(OWNER_TOKEN_SERVICE, { strict: true }),
+  warn = (message) => console.error(message),
+} = {}) {
+  const out = { ...(config ?? {}) };
+  let changed = false;
+  let migrated = false;
+
+  if ("api_key" in out) { delete out.api_key; changed = true; }
+
+  const keychain = keychainAvailable(platform, exists);
+  if ("access_token" in out) {
+    const token = out.access_token;
+    if (!keychain) {
+      // Documented fallback store: keep the token in the 0600 config.json. This
+      // is the BOT-1569 fix — no BOTBUDDY_NO_KEYCHAIN needed to avoid data loss.
+    } else if (typeof token !== "string" || token.length === 0) {
+      // Not a live credential (null/empty/garbage) — safe to drop.
+      delete out.access_token; changed = true;
+    } else {
+      let existing = null;
+      let readFailed = false;
+      try {
+        existing = await keychainRead();
+      } catch (error) {
+        // Codex P2: a transient Keychain READ failure (locked keychain,
+        // authorization momentarily unavailable) must NOT be misread as an empty
+        // slot — that would let the migration overwrite a possibly-newer stored
+        // token with the config value. Fail closed: preserve both copies and try
+        // again on a later command once the Keychain is readable.
+        readFailed = true;
+        warn(
+          `⚠ Could not read the macOS Keychain to check for an existing owner token (${error?.message ?? error}); leaving the ~/.botbuddy/config.json copy in place. It will migrate once the Keychain is readable.`,
+        );
+      }
+      if (readFailed) {
+        // no write, no delete — nothing changes for access_token this pass.
+      } else if (existing === token) {
+        // Already migrated (this exact token is in the Keychain): drop the
+        // config copy without a redundant write.
+        delete out.access_token; changed = true; migrated = true;
+      } else if (typeof existing === "string" && existing.length > 0) {
+        // Codex P2: the Keychain already holds a DIFFERENT owner token. We cannot
+        // prove which is newer — and `login` always writes the Keychain FIRST, so
+        // overwriting it with the config value could DOWNGRADE a freshly-issued
+        // credential to an older one left on disk by a failed metadata save. Fail
+        // closed: never overwrite the Keychain, and keep the config copy too so
+        // NEITHER token is lost. resolveOwnerToken prefers the Keychain on darwin,
+        // so which token authenticates stays deterministic.
+        //
+        // Codex P2 (follow-up): the preserved metadata — `token_expires_at` — was
+        // written for the OLD (config) token. resolveOwnerToken pairs the Keychain
+        // token with config's expiry, so a stale past expiry from the old
+        // credential would make api.mjs/stack.mjs reject the still-valid Keychain
+        // token as expired. Disassociate the expiry (a null expiry skips the client
+        // precheck; the Keychain token's real lifetime is enforced server-side).
+        if ("token_expires_at" in out) { delete out.token_expires_at; changed = true; }
+        warn(
+          "⚠ A different owner token is already stored in the macOS Keychain; leaving the ~/.botbuddy/config.json copy in place (and clearing its stale expiry so the Keychain token is used) rather than overwriting it. Run `botbuddy logout` then `botbuddy login` to settle on a single authoritative credential.",
+        );
+      } else {
+        // Keychain empty: migrate the config token in and verify the read-back
+        // (AC2) BEFORE removing it from config.json.
+        try {
+          await keychainWrite(token);
+          if ((await keychainRead()) === token) {
+            delete out.access_token; changed = true; migrated = true;
+          } else {
+            warn(
+              "⚠ Could not migrate the owner token from ~/.botbuddy/config.json into the macOS Keychain (read-back did not match); leaving it in config.json. Run `botbuddy login` to re-establish it in the Keychain.",
+            );
+          }
+        } catch (error) {
+          if (error?.code === "keychain_item_exists") {
+            // Codex P2 TOCTOU: another process wrote a token between our empty-slot
+            // read and this create-only write. Never overwrite it — preserve the
+            // config copy so the concurrently-issued credential wins.
+            warn(
+              "⚠ Another owner token was written to the macOS Keychain concurrently; leaving the ~/.botbuddy/config.json copy in place rather than overwriting it. Re-run `botbuddy login` to settle on a single credential.",
+            );
+          } else {
+            // Fail-safe: a locked or failing Keychain must never cost the credential.
+            warn(
+              `⚠ Could not migrate the owner token from ~/.botbuddy/config.json into the macOS Keychain (${error?.message ?? error}); leaving it in config.json for now.`,
+            );
+          }
+        }
+      }
+    }
+  }
+  return { config: out, changed, migrated };
+}
+
 // Persist the owner OAuth token. Non-secret metadata always goes to config.json;
 // the token itself goes to the Keychain on darwin, or (with a warning) stays in
 // the 0600 config.json where no Keychain exists.

package/src/commands.mjs

@@ -31,7 +31,7 @@ export async function run(argv, {
   warnStale = maybeWarnStale,
   errorLog = (line) => console.error(line),
 } = {}) {
-  load();
+  await load();
   const [command, ...args] = argv;
   if (shouldCheckForUpdates(argv)) await warnStale({ version: VERSION });
 

package/src/config.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, chmodSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { sanitizeConfigSecrets } from "./cli-credentials.mjs";
+import { migrateConfigSecrets } from "./cli-credentials.mjs";
 
 const CONFIG_DIR = join(homedir(), ".botbuddy");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -14,28 +14,60 @@ export const SERVER_URL = process.env.BOTBUDDY_SERVER_URL
 
 let config = {};
 
-export function loadConfig({ platform = process.platform, warn = (m) => console.error(m) } = {}) {
+export async function loadConfig({ platform = process.platform, warn = (m) => console.error(m) } = {}) {
   let raw = {};
+  let rawText = null;
   try {
     if (existsSync(CONFIG_FILE)) {
-      raw = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+      rawText = readFileSync(CONFIG_FILE, "utf-8");
+      raw = JSON.parse(rawText);
     }
   } catch {
     raw = {};
   }
-  // BOT-1520 migration: never silently trust secrets left in a plaintext
-  // config.json by an older CLI. `api_key` (written by the retired `register`)
-  // is always dropped; `access_token` is dropped where a Keychain can hold it.
-  // Clear them at rest by rewriting the file, and tell the operator once.
-  const { config: sanitized, changed } = sanitizeConfigSecrets(raw, { platform });
-  // Adopt the sanitized config in memory unconditionally — a failed best-effort
+  // BOT-1520/BOT-1569 migration: never silently trust — or silently DROP —
+  // secrets left in a plaintext config.json. `api_key` (written by the retired
+  // `register`) is always dropped; a config.json owner `access_token` is MIGRATED
+  // into the Keychain (write + read-back) before removal, and preserved in
+  // config.json if the migration can't be verified or no Keychain is available.
+  const { config: sanitized, changed, migrated } = await migrateConfigSecrets(raw, { platform, warn });
+  // Adopt the migrated config in memory unconditionally — a failed best-effort
   // rewrite (read-only FS, permissions) must not drop the non-secret metadata.
   config = sanitized;
   if (changed) {
-    try { saveConfig(sanitized); } catch {} // best-effort: clear the secret at rest
-    warn(
-      "⚠ Removed a legacy plaintext credential from ~/.botbuddy/config.json. Run `botbuddy login` (and `botbuddy profile setup <profile>` for agents) to re-establish credentials in the Keychain.",
-    );
+    // BOT-1569 (Codex P2): the migration above can span real Keychain I/O, so a
+    // concurrent `botbuddy login` may have rewritten config.json (fresh
+    // client_id / token_expires_at) since our initial read. An unconditional
+    // whole-file save would clobber that newer metadata with our stale snapshot,
+    // and resolveOwnerToken would then pair the new Keychain token with an old
+    // expiry. Compare-and-swap: only rewrite if config.json is still byte-for-byte
+    // what we read; otherwise the newer on-disk file wins and the (idempotent)
+    // migration re-runs on the next command. Not a full lock — it narrows the
+    // window to an in-process read→write with no I/O between — but it closes the
+    // credential/metadata-clobber race.
+    let persisted = false;
+    try {
+      const nowText = existsSync(CONFIG_FILE) ? readFileSync(CONFIG_FILE, "utf-8") : null;
+      if (nowText === rawText) {
+        saveConfig(sanitized);
+        persisted = true;
+      } else if (nowText) {
+        // BOT-1569 (Codex P2): a concurrent writer (e.g. a `login` saving fresh
+        // client_id / token_expires_at) won the file. Don't keep our stale
+        // migration snapshot as the process-wide config — adopt the newer on-disk
+        // file so THIS command uses the fresh metadata (e.g. resolveOwnerToken
+        // pairs the new Keychain token with the new expiry). The idempotent
+        // migration re-runs on the next command to finish clearing any plaintext.
+        try { config = JSON.parse(nowText); } catch { /* malformed: keep sanitized */ }
+      }
+    } catch { /* best-effort: clear the secret at rest */ }
+    if (persisted) {
+      warn(
+        migrated
+          ? "✓ Migrated the owner token from ~/.botbuddy/config.json into the macOS Keychain."
+          : "⚠ Removed a legacy plaintext credential from ~/.botbuddy/config.json. Run `botbuddy login` (and `botbuddy profile setup <profile>` for agents) to re-establish credentials in the Keychain.",
+      );
+    }
   }
   return config;
 }

package/src/pw/run.mjs

@@ -20,7 +20,7 @@ function redact(value, secretValues = []) { return secretValues.reduce((text, se
 // profile agent the gate historically demanded. bb-pw is not always launched
 // through the `botbuddy` entrypoint (bb-pw.mjs imports runPw directly), so load
 // the config here rather than assuming it is already in memory.
-function readRegisteredAgentId() { try { loadConfig(); const id = getConfig()?.agent_id; return typeof id === "string" && id ? id : null; } catch { return null; } }
+async function readRegisteredAgentId() { try { await loadConfig(); const id = getConfig()?.agent_id; return typeof id === "string" && id ? id : null; } catch { return null; } }
 async function gate({ env, host, lane, deps }) {
   if (env.BB_PW_NO_LOCK === "1") return { allowed: true };
   let profile, identity;
@@ -39,7 +39,7 @@ async function gate({ env, host, lane, deps }) {
   // identity. A foreign operator's agent is in none of these, so the gate stays a
   // real refusal (AC-3).
   const sessionAgentId = deps.sessionId ?? env.BOTBUDDY_SESSION_ID ?? null;
-  const registeredAgentId = (deps.readSessionAgentId ?? readRegisteredAgentId)();
+  const registeredAgentId = await (deps.readSessionAgentId ?? readRegisteredAgentId)();
   const selfAgentIds = new Set([identity.agentId, sessionAgentId, registeredAgentId].filter(Boolean));
   try {
     const status = await coordinator.status({ host, slot: lane });

package/src/wait.mjs

@@ -22,9 +22,13 @@ import { latestPublicCliCommand } from "./public-invocation.mjs";
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
 // implementation gets a typed, safe upgrade instruction.
-export const WAIT_PROTOCOL_VERSION = 1;
+// 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).
+export const WAIT_PROTOCOL_VERSION = 2;
 const CLI_UPGRADE_COMMAND = latestPublicCliCommand("wait");
 const MIN_RECEIPT_MAX_BYTES = 512;
+// BOT-1554: identical to the server's session-id shape check.
+const SESSION_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
 
@@ -104,7 +108,8 @@ OPTIONS
   --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)
   --profile <name>      tenant-bound machine profile (normally read from .botbuddy-agent.json)
-  --session-id <uuid>   attribute this wait to the arming session (the work-graph session id from register_agent); default $BOTBUDDY_SESSION_ID
+  --session-id <uuid>   attribute this wait to the arming session (the work-graph session id from register_agent); default $BOTBUDDY_SESSION_ID.
+                        REQUIRED for any non-timer wait (a wait must name the work agent that armed it).
   --token <key>         explicit agent key override; otherwise the profile-specific env is used
   --help                show this help
 
@@ -248,6 +253,10 @@ async function registerWait(opts, conditions, deadlineIso) {
       // only ever park to timeout, so it's a hard stop, not the live-only fallback.
       "invalid_session_agent",
       "session_agent_requires_profile",
+      // BOT-1554: the server refuses a protocol-2 register with no session id (the
+      // CLI fails fast before this, but a mismatched/forced body could reach it) —
+      // a hard stop, never the untracked live-only fallback.
+      "session_id_required",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {
       const err = new Error(body.detail || body.error);
@@ -264,6 +273,16 @@ async function registerWait(opts, conditions, deadlineIso) {
       err.errorCode = body.error;
       throw err;
     }
+    // BOT-1554: the credential (or its session's agent) is a shared type='service'
+    // carrier — it can hold locks/MCP sessions but cannot be a wait's actor. Carry
+    // the carrier id so runWait can name it in the fix. Auth-shaped → exit 3.
+    if (body.error === "wait_actor_required") {
+      const err = new Error(body.detail || body.error);
+      err.auth = true;
+      err.errorCode = "wait_actor_required";
+      err.carrierAgentId = body.carrier_agent_id ?? null;
+      throw err;
+    }
     const err = new Error(body.detail || body.message || body.error || "forbidden");
     err.auth = true;
     err.errorCode = body.error || "forbidden";
@@ -637,6 +656,27 @@ export async function runWait(argv) {
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
   if (needsRelay) {
+    // BOT-1554: a relay wait MUST name its arming work-graph session. Fail fast —
+    // before any profile resolution or network call — so a wait can never be filed
+    // under whatever credential the machine holds (the "/waits all Megan" bug). A
+    // timer-only wait needs no relay and no session id (handled by !needsRelay).
+    if (!opts.sessionId) {
+      process.stderr.write(
+        "botbuddy wait: --session-id is required (or set $BOTBUDDY_SESSION_ID) — the work-graph session id returned by register_agent\n",
+      );
+      emitReceipt({
+        schema_version: 1,
+        outcome: "error",
+        error: "session_id_required",
+        recovery: "register_agent → export BOTBUDDY_SESSION_ID=<session_id>",
+      });
+      process.exit(EXIT.INVALID);
+    }
+    if (!SESSION_UUID.test(opts.sessionId)) {
+      process.stderr.write(`botbuddy wait: --session-id must be a uuid (got '${opts.sessionId}')\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_session_agent", detail: "session_id must be a uuid" });
+      process.exit(EXIT.INVALID);
+    }
     try {
       opts.agentProfile = await resolveAgentProfile({
         explicitProfile: opts.profile,
@@ -759,6 +799,33 @@ export async function runWait(argv) {
         process.exit(EXIT.INVALID);
       }
       if (err && err.auth) {
+        // BOT-1554: these are all SESSION-IDENTITY failures — the supplied session id
+        // (or the credential behind it) is a shared service carrier, an
+        // ended/foreign session, or a wrong-tenant session. Re-running profile setup
+        // and retrying with the SAME $BOTBUDDY_SESSION_ID just repeats the 403 (that
+        // command can't replace the parent shell's session variable), so lead with the
+        // reliable fix: register a WORK agent and export its NEW session id.
+        const SESSION_IDENTITY_ERRORS = new Set([
+          "wait_actor_required", "session_agent_forbidden", "session_agent_tenant_mismatch",
+        ]);
+        if (SESSION_IDENTITY_ERRORS.has(err.errorCode)) {
+          const cause = err.errorCode === "wait_actor_required"
+            ? `the wait was armed by a shared service carrier (${err.carrierAgentId})`
+            : err.errorCode === "session_agent_tenant_mismatch"
+              ? "the session id ($BOTBUDDY_SESSION_ID) resolves to a different tenant than this wait"
+              : "the session id ($BOTBUDDY_SESSION_ID) is not a live agent session you own";
+          process.stderr.write(
+            `botbuddy wait: ${cause}; register a work agent (register_agent) and export the returned id as $BOTBUDDY_SESSION_ID — re-running '${profileRecovery(opts.agentProfile)}' will not replace the shell's session variable\n`,
+          );
+          emitReceipt(withPrincipalReceipt({
+            schema_version: 1,
+            outcome: "error",
+            error: err.errorCode,
+            ...(err.carrierAgentId ? { carrier_agent_id: err.carrierAgentId } : {}),
+            recovery: "register_agent → export BOTBUDDY_SESSION_ID=<new session_id>",
+          }, opts.agentProfile, { sessionTenant: opts.agentProfile.tenant, agentId: null }));
+          process.exit(EXIT.AUTH);
+        }
         const error = typedProfileError(err.errorCode);
         process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run '${profileRecovery(opts.agentProfile)}'\n`);
         emitReceipt(profileErrorReceipt(opts.agentProfile, error));