@botbuddy/cli 1.63.33 → 1.63.37

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.33",
-  "source_commit": "70dd5a394a7180acebe24941d884cec93eb5f1cc",
-  "source_sha256": "16eed9e08035023447c0c964ce608a2a7324a24fdbe21df4de3085fda26f3bfc",
+  "release_version": "1.63.37",
+  "source_commit": "503ca85897b8b844ee5a841addcbb383c563de68",
+  "source_sha256": "16d04abbbc7838ae352f1cde6e5b7f76d47c2ae3723d47a0d79f3b1ebcc74c63",
   "target": "darwin-arm64",
-  "sha256": "41ea9976bf224497e18148142d93ae53b231e16d814ee0f7d406cc82d5a6d39f"
+  "sha256": "dc1147cf8c4554b973d31c14fe95d2edadf7623b23e9ac9d578d4e9a6de7f975"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.33",
-  "source_commit": "70dd5a394a7180acebe24941d884cec93eb5f1cc",
-  "source_sha256": "16eed9e08035023447c0c964ce608a2a7324a24fdbe21df4de3085fda26f3bfc",
+  "release_version": "1.63.37",
+  "source_commit": "503ca85897b8b844ee5a841addcbb383c563de68",
+  "source_sha256": "16d04abbbc7838ae352f1cde6e5b7f76d47c2ae3723d47a0d79f3b1ebcc74c63",
   "target": "linux-x64",
-  "sha256": "94e4da81775defe0589d339d1eac3f6885ee529ec4df71aa35809cb6d498c5b3"
+  "sha256": "f8c16854c6324625c2284a3707edafa0c4f79a0560a8cc7a97a2f952014b1900"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.63.33",
-  "source_commit": "70dd5a394a7180acebe24941d884cec93eb5f1cc",
-  "source_sha256": "16eed9e08035023447c0c964ce608a2a7324a24fdbe21df4de3085fda26f3bfc",
+  "release_version": "1.63.37",
+  "source_commit": "503ca85897b8b844ee5a841addcbb383c563de68",
+  "source_sha256": "16d04abbbc7838ae352f1cde6e5b7f76d47c2ae3723d47a0d79f3b1ebcc74c63",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "41ea9976bf224497e18148142d93ae53b231e16d814ee0f7d406cc82d5a6d39f",
+      "sha256": "dc1147cf8c4554b973d31c14fe95d2edadf7623b23e9ac9d578d4e9a6de7f975",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "94e4da81775defe0589d339d1eac3f6885ee529ec4df71aa35809cb6d498c5b3",
+      "sha256": "f8c16854c6324625c2284a3707edafa0c4f79a0560a8cc7a97a2f952014b1900",
       "mode": "0755"
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.63.33",
+  "version": "1.63.37",
   "description": "BotBuddy \u2014 Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/run.mjs

@@ -35,6 +35,11 @@ export const EXIT = Object.freeze({ OK: 0, AUTH: 3, INVALID: 4, BACKEND: 5, INTE
 export const DEFAULT_TIMEOUT_SECONDS = 8 * 60 * 60;
 export const TIMEOUT_GRACE_MS = 5_000;
 const MAX_CAPTURE_BYTES = 8_192;
+// BOT-2530: a detached worker holds a server-clocked liveness lease on its run.
+// It renews every 30 s; four missed renewals (120 s) let the server's reconciler
+// terminalize the run as owner_lost so a `command-run:` waiter always ends.
+export const WORKER_HEARTBEAT_TTL_SECONDS = 120;
+export const WORKER_HEARTBEAT_INTERVAL_MS = 30_000;
 // BOT-1510: how often the worker flushes lane case verdicts to the backend.
 // Well under AC-3's 5 s so a begin/verdict is visible within the window.
 const LANE_FLUSH_INTERVAL_MS = 2_500;
@@ -583,6 +588,7 @@ export async function launchRun(argv, {
     command_hash: commandFingerprint, ...(launchSourceSha ? { source_sha: launchSourceSha } : {}), environment_hash: environmentHash(cwd, opts.environment),
     environment: opts.environment, command_kind: opts.kind, expected_duration_seconds: opts.expectedDuration,
     rerun_reason: opts.rerunReason,
+    worker_heartbeat_ttl_seconds: WORKER_HEARTBEAT_TTL_SECONDS,
   });
   let registration = await effectiveCall("register_command", registerArgs());
   // A cached session can be revoked server-side before its local expiry.  The
@@ -610,7 +616,7 @@ export async function launchRun(argv, {
   // every callback is attributable to the same agent. It deliberately stays
   // outside child_env, receipts, and the workload's process environment.
   const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
-  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, command_hash: commandFingerprint, source_sha: launchSourceSha, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL, ...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
+  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, command_hash: commandFingerprint, source_sha: launchSourceSha, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), server_url: SERVER_URL, worker_heartbeat_ttl_seconds: WORKER_HEARTBEAT_TTL_SECONDS, ...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
   const [file, args] = workerInvocation(context);
   try {
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
@@ -623,7 +629,10 @@ export async function launchRun(argv, {
   }
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "launched", run_id: runId,
     ...(knownSession ? { session_id: knownSession } : { session_binding: "server_derived" }),
-    durable_owner: "detached_worker", receipt_path: receipt, reentry: "update_command_run publishes the terminal callback for this run_id", exit_code: EXIT.OK } };
+    durable_owner: "detached_worker", receipt_path: receipt, reentry: "update_command_run publishes the terminal callback for this run_id",
+    // BOT-2318: the exact pending wait for this run. Keep its result pending in
+    // the same work session; its return is what resumes the caller (BOT-2501).
+    wait_command: `bb wait 'command-run:id=${runId}'`, exit_code: EXIT.OK } };
 }
 
 export async function runWorker(contextFile, {
@@ -633,11 +642,14 @@ export async function runWorker(contextFile, {
   terminate = terminateProcessGroup,
   // BOT-2600: the bounded terminal delivery (see retryTerminalUpdate).
   sleep, now, terminalBudgetMs, startDelivery,
+  // BOT-2530: worker liveness lease renewal cadence (tests inject a fake timer).
+  workerHeartbeatIntervalMs = WORKER_HEARTBEAT_INTERVAL_MS, setIntervalFn = setInterval,
 } = {}) {
   const retry = { sleep, now, budgetMs: terminalBudgetMs, startDelivery };
   const context = JSON.parse(await readFile(contextFile, "utf8"));
   const callbackCall = callWithContextIdentity(context, call);
   const ownerHeartbeat = startOwnerHeartbeat(context, callbackCall);
+  const workerLease = startWorkerLease(context, callbackCall, { intervalMs: workerHeartbeatIntervalMs, setIntervalFn });
   const startedAt = new Date().toISOString();
   let timedOut = false;
   let child;
@@ -738,11 +750,44 @@ export async function runWorker(contextFile, {
     const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, callbackCall, retry);
     return receipt;
   } finally {
+    if (workerLease) await workerLease.stop();
     if (ownerHeartbeat) await ownerHeartbeat.stop();
     signalEmitter.removeListener("SIGTERM", cancellationHandler);
   }
 }
 
+// BOT-2530: renew this run's liveness lease while the worker lives. The first
+// renewal also moves a registered run to running. A rejected or failed renewal
+// is not retried specially: the next tick tries again, and a terminal run
+// refuses renewals server-side. Contexts sealed by an older launcher (no
+// declared lease) send nothing.
+export function startWorkerLease(context, call, { intervalMs = WORKER_HEARTBEAT_INTERVAL_MS, setIntervalFn = setInterval } = {}) {
+  if (!Number.isInteger(context.worker_heartbeat_ttl_seconds)) return null;
+  let stopped = false;
+  let chain = Promise.resolve();
+  const tick = () => {
+    chain = chain.then(async () => {
+      if (stopped) return;
+      try {
+        await call("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "running", worker_heartbeat: true }, {
+          signal: AbortSignal.timeout(DELIVERY_CALL_TIMEOUT_MS),
+          ...(typeof context.server_url === "string" && context.server_url ? { serverUrl: context.server_url } : {}),
+        });
+      } catch { /* the lease lapses only after several missed renewals */ }
+    });
+  };
+  tick();
+  const timer = setIntervalFn(tick, intervalMs);
+  timer.unref?.();
+  return { async stop() {
+    stopped = true;
+    clearInterval(timer);
+    let bound;
+    await Promise.race([chain, new Promise((resolve) => { bound = setTimeout(resolve, 2_000); bound.unref?.(); })]);
+    clearTimeout(bound);
+  } };
+}
+
 function startOwnerHeartbeat(context, call, { intervalMs = 5 * 60_000, setIntervalFn = setInterval } = {}) {
   // A detached worker must never acquire liveness through its ambient default
   // identity. It can only refresh the bearer sealed for its owner.

package/src/wait-core.mjs

@@ -46,6 +46,12 @@ export const EXIT = Object.freeze({
 // four, optionally wrapped in ONE pair of braces.
 const LEASE_UUID_SPELLING = /^(?:\{(?=.*\}$)|(?!.*\}$))((?:[0-9a-f]{4}-?){7}[0-9a-f]{4})\}?$/;
 
+// BOT-2318: bb run generates a lower-case UUID before register_command.
+const COMMAND_RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export const COMMAND_RUN_TERMINAL_STATUSES = Object.freeze(new Set([
+  "succeeded", "failed", "cancelled", "timed_out", "owner_lost", "invalidated",
+]));
+
 // BOT-2013: stack_lease frame states that mean the lease is gone, not granted.
 export const LEASE_LOST_STATES = Object.freeze(new Set(["reaping", "reaped", "reap_failed"]));
 // BOT-2400: the lease states a `lease:id=…,state=<s>` wait may target.
@@ -198,6 +204,18 @@ const VALIDATORS = {
     if (!p.id) throw new Error("test-run needs id=<run_id>");
     return { runId: String(p.id) };
   },
+  // BOT-2318: server binds this selector to the registering tenant, agent and work session.
+  "command-run": (p, raw) => {
+    const pair = /^\s*id\s*=\s*([0-9A-Fa-f-]+)\s*$/.exec(raw ?? "");
+    if (!pair || Object.keys(p).length !== 1 || p.id !== pair[1]) {
+      throw new Error("command-run needs exactly one id=<registered run id>");
+    }
+    const runId = pair[1].toLowerCase();
+    if (!COMMAND_RUN_ID.test(runId)) {
+      throw new Error("command-run id must be the canonical UUID that bb run printed");
+    }
+    return { runId };
+  },
   // BOT-2629: this is deliberately a dedicated condition rather than a raw
   // event escape hatch. The UUID is chosen before dispatch and the exact subject
   // prevents another run on the same idle/re-adopted lease waking this waiter.
@@ -620,7 +638,7 @@ export function parseConditions(specs) {
       return;
     }
     try {
-      const params = validator(parseParams(rawParams));
+      const params = validator(parseParams(rawParams), rawParams);
       conditions.push({ id: `c${index + 1}`, type, params });
     } catch (err) {
       errors.push({ spec, message: err.message });
@@ -1210,6 +1228,11 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
         prReviewFiltersMatch(signal, params, condition.review_guard);
     case "test-run":
       return signal.signal_type === "test_run" && signal.subject_key === `run:${params.runId}`;
+    case "command-run":
+      return signal.signal_type === "command_run" &&
+        signal.subject_key === `run:${params.runId}` &&
+        signal.payload?.run_id === params.runId &&
+        COMMAND_RUN_TERMINAL_STATUSES.has(signal.payload?.status);
     case "stack-run":
       return signal.signal_type === "stack_run" && signal.subject_key === `stack-run:${params.id}` &&
         signal.payload?.run_id === params.id && Number.isInteger(signal.payload?.exit_code);

package/src/wait.mjs

@@ -26,6 +26,7 @@ import { SETUP_BLOCK } from "./setup-block.mjs";
 import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
 import { realpath } from "node:fs/promises";
 import { deepLinkNotice, safeWebUrl } from "./deep-link.mjs";
+import { redactTelemetry } from "./telemetry-outbox.mjs";
 import { assertWaitObserver, readWaitResult, waitCompletionState, waitObserverId, writeWaitReceipt } from "./wait-result.mjs";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
@@ -152,6 +153,14 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       valid workflow=/workflow_id=/workflow_path= lines.
   test-run:id=<run_id>                a test run reaching a terminal status (owner-scoped);
                                       bb test <lane> prints the exact line to arm.
+  command-run:id=<run_id>             BOT-2318: the bb run you registered reaching a terminal
+                                      outcome (succeeded, failed, cancelled, timed_out,
+                                      owner_lost, invalidated). Exit 0 on any terminal outcome;
+                                      the receipt's status says how the command ended. Arm it
+                                      from the same work session that ran bb run, as the ONLY
+                                      condition, and keep this wait's result pending: its
+                                      return is what resumes your task. A run whose worker is
+                                      lost ends owner_lost (bb run inspect <run_id>).
   stack-run:id=<run UUID>             one named bb stack run reaching its terminal outcome
                                       (BOT-2629). Choose the UUID BEFORE dispatch and pass it as
                                       bb stack run --run-id <UUID>; the receipt carries exit_code,
@@ -481,6 +490,25 @@ async function reserveClaimQueueBoundary(opts, conditions) {
   }
 }
 
+// BOT-2855: the concrete next step for a typed registration refusal, or null when
+// there is none beyond the relay's own detail. Built from the parsed conditions
+// only (repo / PR number), never from a credential.
+export function registerRefusalRecovery(errorCode, conditions) {
+  const release = Array.isArray(conditions) ? conditions.find((c) => c?.type === "staging-release") : null;
+  const repo = release?.params?.repo ?? "<owner/repo>";
+  const pr = release?.params?.pr ?? "<n>";
+  const arm = `bb wait 'staging-release:repo=${repo},pr=${pr}'`;
+  if (errorCode === "pr_not_merged") {
+    return "staging-release arms only after the PR merges. Before the merge, wait for it with "
+      + `bb wait 'pr-state:repo=${repo},pr=${pr}' (or for its CI with bb wait 'ci:repo=${repo},scope=latest,pr=${pr}'), `
+      + `then arm ${arm}`;
+  }
+  if (errorCode === "pr_merge_sha_unresolved") {
+    return `the merge commit is not visible yet; retry ${arm} in a minute`;
+  }
+  return null;
+}
+
 async function registerWait(opts, conditions, deadlineIso) {
   // 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.
@@ -516,15 +544,34 @@ async function registerWait(opts, conditions, deadlineIso) {
     },
     body: JSON.stringify(registerBody),
   });
+  // BOT-2855: read an error body ONCE. Each status branch below inspects it and may
+  // fall through to the generic `!res.ok` error; a second `res.json()` on the consumed
+  // body threw, the catch turned it into `{}`, and the relay's typed reason (e.g.
+  // `pr_not_merged`) collapsed to `register responded 400`. Redact any credential a
+  // relay detail might echo before it can reach stderr or the receipt.
+  let errorBody = null;
+  let errorBodyIsJson = false;
+  const readErrorBody = async () => {
+    if (errorBody) return errorBody;
+    const text = await res.text().catch(() => "");
+    try {
+      const parsed = JSON.parse(text);
+      errorBodyIsJson = Boolean(parsed) && typeof parsed === "object" && !Array.isArray(parsed);
+      errorBody = errorBodyIsJson ? redactTelemetry(parsed) : {};
+    } catch {
+      errorBody = {};
+    }
+    return errorBody;
+  };
   if (res.status === 429) {
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     const err = new Error(body.detail || "wait_session_cap_exceeded");
     err.cap = true;
     err.errorCode = body.error || "wait_session_cap_exceeded";
     throw err;
   }
   if (res.status === 401) {
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     const err = new Error(body.detail || body.message || body.error || "unauthorized agent key");
     err.auth = true;
     err.errorCode = body.error || "unauthorized";
@@ -540,7 +587,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     // A TRANSIENT backend 400 (e.g. `register_failed` from the RPC) is NOT
     // caller-actionable — fall through to the existing live-only fallback so a valid
     // wait still arms (Codex round-7 P2).
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     const INVALID_CONDITION_CODES = new Set([
       "no_signal_source",
       "review_guard_registration_failed",
@@ -585,6 +632,15 @@ async function registerWait(opts, conditions, deadlineIso) {
       // caller-actionable hard stops, not the untracked live-only fallback.
       "chat_not_participant",
       "chat_participant_ambiguous",
+      // BOT-2855: BOT-1458 AC-3 — staging-release arms only for a merged PR. Before the
+      // merge the relay refuses it by design; the caller must wait for the merge first.
+      "pr_not_merged",
+      // BOT-2318: command-run targets are authorization-bound to the registering
+      // tenant, agent and work session, and the condition cannot be composed.
+      // Both refusals require the caller to change its target/conditions; falling
+      // back to an untracked wait would only hide that error behind a timeout.
+      "command_run_unavailable",
+      "command_run_single_condition_required",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {
       const err = new Error(body.detail || body.error);
@@ -595,7 +651,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     }
   }
   if (res.status === 404) {
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     if (body.error === "linear_issue_not_found") {
       const err = new Error(body.detail || body.error);
       err.invalidCondition = true;
@@ -618,7 +674,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     }
   }
   if (res.status === 403) {
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     if (new Set(["wait_tenant_unresolved", "wait_cross_tenant", "wait_tenant_mismatch", "wait_resume_identity_mismatch"]).has(body.error)) {
       const err = new Error(body.detail || body.error);
       err.invalidCondition = true;
@@ -641,7 +697,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     throw err;
   }
   if (res.status === 426) {
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     const err = new Error(body.detail || "this wait client is no longer supported");
     err.clientOutdated = true;
     err.errorCode = body.error || "client_outdated";
@@ -655,7 +711,7 @@ async function registerWait(opts, conditions, deadlineIso) {
     // unblocked wait would skip the server's initial evaluation and could resume a
     // coding session on a false already_unblocked. Surface the typed receipt and a
     // concrete exit code (5=backend/retryable, 4=invalid/not-found).
-    const body = await res.json().catch(() => ({}));
+    const body = await readErrorBody();
     if (body.error === "unblocked_projection_unresolved" || body.error === "unblocked_ticket_not_found") {
       const err = new Error(body.detail || body.error);
       err.hydrationRegister = true;
@@ -668,12 +724,20 @@ async function registerWait(opts, conditions, deadlineIso) {
     }
   }
   if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    const err = new Error(body.detail || body.message || body.error || `register responded ${res.status}`);
+    const body = await readErrorBody();
+    const typedCode = typeof body.error === "string" && body.error ? body.error : null;
+    const detail = [body.detail, body.message].find((v) => typeof v === "string" && v) ?? null;
+    const err = new Error(detail || typedCode ||
+      `register responded ${res.status}${errorBodyIsJson ? "" : " with a non-JSON body"}`);
+    // BOT-2855: keep the relay's typed reason for the caller and the receipt.
+    err.errorCode = typedCode || "register_failed";
+    err.httpStatus = res.status;
     if (body.error === "initial_eval_failed") {
       err.initialEval = true;
-      err.errorCode = body.error;
       err.detail = body.detail || "initial evaluation failed";
+    } else if (body.error === "pr_merge_sha_unresolved") {
+      // Merged, but neither the projection nor GitHub returned the merge commit yet.
+      err.retryableRegister = true;
     }
     throw err;
   }
@@ -2338,15 +2402,35 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           }
         }
         process.stderr.write(`bb-wait: invalid condition (${err.errorCode}) — ${err.message}\n`);
+        const recovery = registerRefusalRecovery(err.errorCode, conditions);
+        if (recovery) process.stderr.write(`bb-wait: next step: ${recovery}\n`);
         await emitReceipt({
           schema_version: 1,
           outcome: "error",
           error: err.errorCode,
+          error_code: err.errorCode,
           detail: String(err.message),
           ...(Array.isArray(err.candidates) && err.candidates.length > 0 ? { candidates: err.candidates } : {}),
+          ...(recovery ? { recovery } : {}),
         });
         process.exit(EXIT.INVALID);
       }
+      if (err && err.retryableRegister) {
+        // BOT-2855: a merged PR whose merge commit is not visible yet — retryable.
+        const recovery = registerRefusalRecovery(err.errorCode, conditions);
+        process.stderr.write(`bb-wait: wait-session registration failed (${err.errorCode}) — ${err.message}\n`);
+        if (recovery) process.stderr.write(`bb-wait: next step: ${recovery}\n`);
+        await emitReceipt({
+          schema_version: 1,
+          outcome: "error",
+          error: err.errorCode,
+          error_code: err.errorCode,
+          detail: String(err.message),
+          http_status: err.httpStatus ?? null,
+          ...(recovery ? { recovery } : {}),
+        });
+        process.exit(EXIT.BACKEND);
+      }
       if (err && err.initialEval) {
         process.stderr.write(`bb-wait: initial wait evaluation failed (${err.errorCode}) — ${err.detail}\n`);
         await emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.detail) });
@@ -2361,9 +2445,19 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
       // BOT-1338/1608: every non-timer wait is a relay-tracked, session-token wait.
       // If registration did not succeed, neither the server nor this client has
       // verified the session's tenant, so there is no safe untracked fallback.
-      process.stderr.write(`bb-wait: wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
+      // BOT-2855: name the relay's typed code (or register_failed when it sent none)
+      // and its status, so the caller can act on it instead of a bare status line.
+      const errorCode = (err && err.errorCode) || "register_failed";
+      process.stderr.write(`bb-wait: wait-session registration failed (${errorCode}) — failing closed, not arming untracked: ${err && err.message || err}\n`);
       await emitReceipt(withPrincipalReceipt(
-        { schema_version: 1, outcome: "error", error: "register_failed", detail: String(err && err.message || err) },
+        {
+          schema_version: 1,
+          outcome: "error",
+          error: "register_failed",
+          error_code: errorCode,
+          detail: String(err && err.message || err),
+          ...(err && Number.isInteger(err.httpStatus) ? { http_status: err.httpStatus } : {}),
+        },
         null,
         { sessionTenant: sessionTenant ?? null, agentId: null },
       ));