@botbuddy/cli 1.63.8 → 1.63.12

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.8",
-  "source_commit": "f26ae5e2838d2cd2bb8125f238e48ea9ae87c74c",
-  "source_sha256": "4e4cf641d3c4675efbf172dfa759d31c016d30700ca195f7b3cbc399459ede98",
+  "release_version": "1.63.12",
+  "source_commit": "0999216ee4f46a7800e4bcfa901de357d73bfed2",
+  "source_sha256": "02eb455df56f57ca100c1e063642427bc1db6876665d72d9ef582b1627d22df1",
   "target": "darwin-arm64",
-  "sha256": "cba79a67f58f0bde2d0f20b5c92c2734b468b0ca038ee83d020e325ab06c79fe"
+  "sha256": "bc6fb7a1e6f830a8eb7f3cbd9a593edeff9dcc404db6529546fa4ced95b3b86d"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.63.8",
-  "source_commit": "f26ae5e2838d2cd2bb8125f238e48ea9ae87c74c",
-  "source_sha256": "4e4cf641d3c4675efbf172dfa759d31c016d30700ca195f7b3cbc399459ede98",
+  "release_version": "1.63.12",
+  "source_commit": "0999216ee4f46a7800e4bcfa901de357d73bfed2",
+  "source_sha256": "02eb455df56f57ca100c1e063642427bc1db6876665d72d9ef582b1627d22df1",
   "target": "linux-x64",
-  "sha256": "bf0458ea4d5a2aa36d5de5b374283a3f21c677f42a9afe5f3dcaf1a74807809a"
+  "sha256": "281a33d005250533d777aebac92417485907118a67f841f708e96e6b759d45b3"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.63.8",
-  "source_commit": "f26ae5e2838d2cd2bb8125f238e48ea9ae87c74c",
-  "source_sha256": "4e4cf641d3c4675efbf172dfa759d31c016d30700ca195f7b3cbc399459ede98",
+  "release_version": "1.63.12",
+  "source_commit": "0999216ee4f46a7800e4bcfa901de357d73bfed2",
+  "source_sha256": "02eb455df56f57ca100c1e063642427bc1db6876665d72d9ef582b1627d22df1",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "cba79a67f58f0bde2d0f20b5c92c2734b468b0ca038ee83d020e325ab06c79fe",
+      "sha256": "bc6fb7a1e6f830a8eb7f3cbd9a593edeff9dcc404db6529546fa4ced95b3b86d",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "bf0458ea4d5a2aa36d5de5b374283a3f21c677f42a9afe5f3dcaf1a74807809a",
+      "sha256": "281a33d005250533d777aebac92417485907118a67f841f708e96e6b759d45b3",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/api.mjs

@@ -413,22 +413,24 @@ export function containerHostRegisterEndpoint(serverUrl = SERVER_URL) {
  * Programmatic client for the source-backed `POST mcp-server/container-hosts/register`
  * contract. It never adds a tenant pin and never manufactures an Edge user JWT.
  */
-export async function registerContainerHost(body, {
+export function registerContainerHost(body, options = {}) { return postContainerHostControl(body, options, "register", "container_host_register"); }
+export function daemonHandoverRequest(body, options = {}) { return postContainerHostControl(body, options, "handover", "daemon_handover"); }
+async function postContainerHostControl(body, {
   fetchImpl = fetch,
   auth: pinnedAuth = null,
   resolveAuth = resolveCallAuth,
   serverUrl = SERVER_URL,
   signal,
-} = {}) {
+} = {}, route, toolName) {
   if (!body || typeof body !== "object" || Array.isArray(body) || typeof fetchImpl !== "function") {
     return { ok: false, error: "invalid_request" };
   }
   let endpoint;
-  try { endpoint = containerHostRegisterEndpoint(serverUrl); }
+  try { endpoint = containerHostRegisterEndpoint(serverUrl).replace(/\/register$/, `/${route}`); }
   catch { return { ok: false, error: "endpoint_invalid" }; }
   let auth = pinnedAuth;
   if (!auth) {
-    const resolved = await resolveAuth({ toolName: "container_host_register", preferSession: false });
+    const resolved = await resolveAuth({ toolName, preferSession: false });
     if (resolved?.error || !resolved?.auth) return { ok: false, auth: true, error: resolved?.error?.error ?? "not_authenticated" };
     auth = resolved.auth;
   }

package/src/daemon/commands.mjs

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
 import { registerContainerHost } from "../api.mjs";
+import { upgradeDaemonHost } from "./handover.mjs";
 import { awaitHostApproval } from "./approval-wait.mjs";
 import { bootstrapFreshDaemon } from "./bootstrap.mjs";
 import { createBootstrapResumeStore } from "./bootstrap-resume.mjs";
@@ -48,6 +49,7 @@ export const daemonHelp = `Usage:
   bb daemon config-render '<json host policy>'
   bb daemon enroll '<json host-bound enrollment spec>'
   bb daemon bootstrap '<json fresh-host bootstrap spec>'
+  bb daemon upgrade '<json controlled host upgrade spec>'
 
 The Go payload is verified from the extracted universal package before sudo.
 Install runs the Go runtime's --check-config receipt before loading a native,
@@ -290,6 +292,7 @@ export async function cmdDaemon(args, {
   verifyRemoteIdentity = verifyRemoteServiceIdentity,
   verifyRemoteHelperIdentity = verifyRemoteHelperIdentityOnTarget,
   bootstrap = bootstrapFreshDaemon,
+  upgrade = upgradeDaemonHost,
   registerHost = registerContainerHost,
   createBootstrapIdentity = createRemoteBootstrapIdentity,
   inspectBootstrapIdentity = inspectRemoteBootstrapIdentity,
@@ -302,6 +305,11 @@ export async function cmdDaemon(args, {
     log(daemonHelp);
     return 0;
   }
+  if(args[0]==="upgrade"){
+    if(args.length!==2)fail("Usage: bb daemon upgrade '<json controlled host upgrade spec>'");
+    let spec;try{spec=JSON.parse(args[1]);}catch{fail("daemon_handover_spec_invalid");}
+    log(JSON.stringify(await upgrade(spec)));return 0;
+  }
   if (args[0] === "config-render") {
     if (args.length !== 2) {
       fail("Usage: bb daemon config-render '<json host policy>'");

package/src/daemon/handover.mjs

@@ -0,0 +1,220 @@
+// BOT-2057: the requester coordinates an authenticated immutable plan. The
+// target receives only the verified Go artifact and bounded native commands;
+// credentials remain in the target's existing nonroot private profile.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  callToolJson,
+  daemonHandoverRequest,
+  resolveCallAuth,
+} from "../api.mjs";
+import {
+  assertSshHost,
+  installedBinaryPath,
+  stageRemoteDaemonRelease,
+} from "./installer.mjs";
+import { validateDaemonRelease } from "./release.mjs";
+
+const fail = (code) => {
+  throw new Error(code);
+};
+const hostRE = /^bbh-[0-9a-f]{24}$/;
+const immutableBinaryRE =
+  /^\/opt\/botbuddy\/daemon\/releases\/[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?\/(?:linux-x64|darwin-arm64)\/botbuddy-daemon$/;
+
+export function nativeHandoverCommand(
+  { host, binary, mode, input },
+  { spawnImpl = spawn } = {},
+) {
+  if (
+    !immutableBinaryRE.test(binary) || !["inspect", "submit"].includes(mode)
+  ) fail("daemon_handover_command_invalid");
+  const flag = mode === "inspect"
+    ? "--native-handover-inspect"
+    : "--native-handover-submit";
+  let command = "sudo", args = ["-n", binary, flag];
+  if (host) {
+    assertSshHost(host);
+    command = "ssh";
+    args = [
+      "-o",
+      "BatchMode=yes",
+      "-o",
+      "ForwardAgent=no",
+      "-o",
+      "StrictHostKeyChecking=yes",
+      host,
+      "sudo",
+      ...args,
+    ];
+  }
+  // Every remote argv has a strict non-shell alphabet. JSON travels only on
+  // stdin; OpenSSH cannot shell-join an operator's plan or credential into code.
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "", bounded = true;
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error("daemon_handover_command_timeout"));
+    }, 60000);
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+      if (stdout.length > 65536) {
+        bounded = false;
+        child.kill("SIGTERM");
+      }
+    });
+    child.stderr.resume();
+    child.stdin.on("error", () => {});
+    child.on("error", () => {
+      clearTimeout(timer);
+      reject(new Error("daemon_handover_command_failed"));
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0 || !bounded) {
+        return reject(new Error("daemon_handover_command_failed"));
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        reject(new Error("daemon_handover_response_invalid"));
+      }
+    });
+    child.stdin.end(input ? JSON.stringify(input) : "");
+  });
+}
+
+export async function upgradeDaemonHost(spec, {
+  validateRelease = validateDaemonRelease,
+  stage = stageRemoteDaemonRelease,
+  resolveAuth = resolveCallAuth,
+  identity = callToolJson,
+  transition = daemonHandoverRequest,
+  native = nativeHandoverCommand,
+  uuid = randomUUID,
+} = {}) {
+  if (
+    !spec || typeof spec !== "object" || Array.isArray(spec) ||
+    Object.keys(spec).some((key) =>
+      ![
+        "platform",
+        "arch",
+        "sshHost",
+        "serviceUser",
+        "releaseRoot",
+        "expectedHostKey",
+        "tenant",
+        "resume",
+      ].includes(key)
+    ) || !["linux", "darwin"].includes(spec.platform) ||
+    typeof spec.serviceUser !== "string" || spec.serviceUser === "root" ||
+    !/^[a-z_][a-z0-9_-]*$/i.test(spec.serviceUser) ||
+    !hostRE.test(spec.expectedHostKey) || typeof spec.tenant !== "string" ||
+    !spec.tenant
+  ) fail("daemon_handover_spec_invalid");
+  if (typeof spec.sshHost !== "string") {
+    fail("daemon_handover_ssh_host_required");
+  }
+  assertSshHost(spec.sshHost);
+  const release = await validateRelease({ releaseRoot: spec.releaseRoot }, {
+    platform: spec.platform,
+    arch: spec.arch,
+  });
+  const resolved = await resolveAuth({
+    toolName: "daemon_handover",
+    preferSession: false,
+  });
+  if (resolved?.error || !resolved?.auth) fail("daemon_handover_auth_required");
+  // Pin one authenticated principal across inspection, plan creation and begin.
+  const auth = resolved.auth;
+  const who = await identity("whoami", {}, { auth, tenant: spec.tenant });
+  if (
+    !who?.ok || who?.isError || typeof who.data?.owner_email !== "string" ||
+    !who.data.owner_email.includes("@") || who.data?.tenant_id !== spec.tenant
+  ) fail("daemon_handover_owner_identity_unavailable");
+  const staged = await stage({
+    platform: spec.platform,
+    host: spec.sshHost,
+    user: spec.serviceUser,
+    release,
+  });
+  const binary = installedBinaryPath(release);
+  if (staged?.binary !== binary) fail("daemon_handover_stage_invalid");
+  let plan;
+  if (spec.resume) {
+    if (spec.resume === true) {
+      const saved = await transition({
+        action: "lookup",
+        host_key: spec.expectedHostKey,
+      }, { auth });
+      if (!saved?.ok || saved.data?.success !== true || !saved.data.plan) {
+        fail("daemon_handover_resume_unavailable");
+      }
+      plan = saved.data.plan;
+    } else plan = spec.resume;
+    if (
+      plan.host_key !== spec.expectedHostKey ||
+      plan.owner_email !== who.data.owner_email ||
+      plan.tenant_id !== who.data.tenant_id ||
+      plan.candidate?.artifact_sha256 !== `sha256:${release.sha256}` ||
+      plan.candidate?.version !== release.releaseVersion ||
+      plan.candidate?.source_commit !== release.sourceCommit ||
+      plan.candidate?.target !== release.target
+    ) fail("daemon_handover_resume_mismatch");
+  } else {
+    const observed = await native({
+      host: spec.sshHost,
+      binary,
+      mode: "inspect",
+    });
+    if (
+      observed?.host_key !== spec.expectedHostKey ||
+      observed?.service_user !== spec.serviceUser ||
+      !Number.isSafeInteger(observed.service_uid) || observed.service_uid <= 0
+    ) fail("daemon_handover_host_mismatch");
+    plan = {
+      version: 1,
+      rollout_id: uuid(),
+      host_key: observed.host_key,
+      owner_email: who.data.owner_email,
+      tenant_id: who.data.tenant_id,
+      machine_id: observed.machine_id,
+      engine_id: observed.engine_id,
+      service_uid: observed.service_uid,
+      config_sha256: observed.config_sha256,
+      previous_instance_id: observed.previous_instance_id,
+      previous: observed.previous,
+      candidate: {
+        version: release.releaseVersion,
+        source_commit: release.sourceCommit,
+        artifact_sha256: `sha256:${release.sha256}`,
+        target: release.target,
+      },
+    };
+  }
+  const begun = await transition({ action: "begin", plan }, { auth });
+  if (!begun?.ok || begun.data?.success !== true || !begun.data.authority_key) {
+    fail("daemon_handover_begin_refused");
+  }
+  if (begun.data.result) {
+    return {
+      outcome: "completed",
+      rollout_id: plan.rollout_id,
+      result: begun.data.result,
+    };
+  }
+  const queued = await native({
+    host: spec.sshHost,
+    binary,
+    mode: "submit",
+    input: { plan, authority_key: begun.data.authority_key },
+  });
+  if (queued?.queued !== true) fail("daemon_handover_submission_refused");
+  return {
+    outcome: "queued",
+    host_key: plan.host_key,
+    rollout_id: plan.rollout_id,
+    plan,
+  };
+}

package/src/stack-isolation.mjs

@@ -1273,7 +1273,7 @@ function mutateBoundClaims(stackDir, registryDir, mutate) {
  * This never deletes a container, volume, stack directory or another invocation's claim. */
 export function recoverLeasedStackClaim(stackDir, leaseId, proof, { registryDir = defaultPortRegistryDir() } = {}) {
   if (proof?.lease_id !== leaseId || proof.state !== "reaped" || proof.cleanup_verified !== true ||
-      !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence"].includes(proof.cleanup_proof) ||
+      !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence", "no_execution"].includes(proof.cleanup_proof) ||
       (proof.cleanup_proof === "signed_reap" && !proof.cleanup_receipt_id)) {
     return { released: false, reason: "accepted cleanup proof is unavailable" };
   }

package/src/wait-core.mjs

@@ -36,6 +36,9 @@ export const EXIT = Object.freeze({
   // refuses the stream with a typed `wait_abandoned` error frame; re-arm from next_cursor.
   ABANDONED: 11,
   LEASE_CLEANUP_FAILED: 12,
+  // BOT-2783: a Codex review was still not complete at its intervention deadline. The
+  // receipt's `error` carries the provenance (limit, its source, window, reason).
+  REVIEW_TIMEOUT: 13,
 });
 
 // BOT-2013: the uuid spellings Postgres accepts for a lease id (uuid_in), mirrored by the SQL
@@ -823,6 +826,44 @@ export function buildReceipt({
   return r;
 }
 
+// BOT-2783: the policy sources a review guard records, as an agent reads them.
+const REVIEW_TIMEOUT_SOURCE_LABEL = Object.freeze({ call: "this wait", repository: "repository", tenant: "tenant default" });
+
+/**
+ * BOT-2783: the typed REVIEW_TIMEOUT error for a pr-review frame that is a review
+ * guard's deadline diagnostic finding no review (`review_stalled` WITH a guard_id).
+ * Null for anything else: a recovered review or clean pass at the deadline is a real
+ * review (exit 0), and a legacy cron stall notice (no guard) keeps its old behaviour.
+ */
+export function reviewTimeoutDetail(signal, condition) {
+  const p = signal?.payload;
+  if (condition?.type !== "pr-review" || signal?.signal_type !== "pr_review") return null;
+  if (!p || p.transition !== "review_stalled" || typeof p.guard_id !== "string") return null;
+  const text = (v) => (typeof v === "string" && v.length > 0 ? v.slice(0, 512) : null);
+  return {
+    code: "REVIEW_TIMEOUT",
+    minutes: Number.isInteger(p.threshold_minutes) ? p.threshold_minutes : null,
+    source: REVIEW_TIMEOUT_SOURCE_LABEL[p.policy_source] ? p.policy_source : null,
+    started_at: text(p.started_at),
+    deadline: text(p.deadline),
+    reason: text(p.reason),
+    next_action: text(p.next_action),
+    guard_id: p.guard_id,
+    repo: text(p.repo),
+    pr_number: Number.isInteger(p.pr_number) ? p.pr_number : null,
+    commit_sha: text(p.commit_sha),
+  };
+}
+
+/** BOT-2783: the one stderr line for a review_timeout receipt (null for any other outcome). */
+export function reviewTimeoutNotice(receipt) {
+  if (receipt?.outcome !== "review_timeout" || !receipt.error || typeof receipt.error !== "object") return null;
+  const e = receipt.error;
+  const source = REVIEW_TIMEOUT_SOURCE_LABEL[e.source] ?? "unknown source";
+  const sha = typeof e.commit_sha === "string" ? e.commit_sha.slice(0, 7) : "?";
+  return `bb-wait: review timeout after ${e.minutes ?? "?"} min (${source}) on ${e.repo ?? "?"}#${e.pr_number ?? "?"}@${sha}: ${e.reason ?? "unknown"}`;
+}
+
 /** BOT-2013: the three lease-lost fields, each bounded, or null when absent. */
 function compactLeaseLostState(state) {
   if (!state || typeof state !== "object") return null;
@@ -833,7 +874,7 @@ function compactLeaseLostState(state) {
 }
 
 function compactCleanupState(state) {
-  if (!state || !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence"].includes(state.cleanup_proof)) return null;
+  if (!state || !["signed_reap", "never_provisioned", "local_exec_teardown", "pre_driver_absence", "no_execution"].includes(state.cleanup_proof)) return null;
   const short = (v) => typeof v === "string" ? v.slice(0, 64) : null;
   return Object.fromEntries(["lease_id", "lease_state", "reap_disposition", "cleanup_proof", "cleanup_receipt_id"]
     .filter((key) => state[key] != null).map((key) => [key, short(state[key])]));
@@ -938,6 +979,34 @@ export function truncateReceipt(receipt, maxBytes = 10240) {
     }
     return base;
   }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "review_timeout" &&
+      clone.error && typeof clone.error === "object") {
+    // BOT-2783: keep the actionable provenance (limit, its source, why, which
+    // guard/head) and add the window, repo and resume pointers only while they fit.
+    const e = clone.error;
+    const base = {
+      schema_version: clone.schema_version,
+      outcome: "review_timeout",
+      error: {
+        code: "REVIEW_TIMEOUT", minutes: e.minutes ?? null, source: e.source ?? null,
+        reason: typeof e.reason === "string" ? e.reason.slice(0, 64) : null,
+        guard_id: e.guard_id ?? null, pr_number: e.pr_number ?? null,
+        commit_sha: typeof e.commit_sha === "string" ? e.commit_sha.slice(0, 7) : null,
+      },
+      truncated: true,
+    };
+    for (const [key, value] of [["deadline", e.deadline], ["repo", e.repo], ["started_at", e.started_at]]) {
+      if (value == null) continue;
+      const candidate = { ...base, error: { ...base.error, [key]: value } };
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes) base.error[key] = value;
+    }
+    for (const key of ["next_cursor", "wait_session_id"]) {
+      if (clone[key] == null) continue;
+      const candidate = { ...base, [key]: clone[key] };
+      if (Buffer.byteLength(JSON.stringify(candidate)) <= maxBytes) base[key] = clone[key];
+    }
+    return base;
+  }
   if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "error") {
     const base = {
       schema_version: clone.schema_version,
@@ -1657,6 +1726,10 @@ export async function runWaitLoop({
     if (allocationFailure) {
       return finalize("error", { exitCode: EXIT.MANAGED_ALLOCATION_FAILED, matched: [entry], state: allocationFailure, error: allocationFailure.cleanup_error });
     }
+    const timeout = reviewTimeoutDetail(signal, condition);
+    if (timeout) {
+      return finalize("review_timeout", { exitCode: EXIT.REVIEW_TIMEOUT, matched: [entry], error: timeout });
+    }
     return finalize("matched", { exitCode: EXIT.MATCHED, matched: [entry] });
   };
 

package/src/wait-result.mjs

@@ -11,7 +11,8 @@ const MAX_ARTIFACT_BYTES = 256 * 1024;
 const MAX_RECEIPT_BYTES = 64 * 1024;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const COMMAND_STATUSES = new Set(["success", "failure", "cancelled", "timed_out", "owner_lost"]);
-const TERMINAL_OUTCOMES = new Set(["matched", "timeout", "error", "superseded", "lease_lost", "abandoned", "cancelled"]);
+// BOT-2783: review_timeout is terminal (exit 13, typed REVIEW_TIMEOUT provenance).
+const TERMINAL_OUTCOMES = new Set(["matched", "timeout", "error", "superseded", "lease_lost", "abandoned", "cancelled", "review_timeout"]);
 
 // Persisted != delivered. Await the stream callback before exiting, including
 // when a bounded receipt is larger than the pipe's immediately writable space.

package/src/wait.mjs

@@ -13,7 +13,7 @@
 // Usage:  botbuddy wait [--any] <condition>... [options]
 // Run     botbuddy wait --help for the condition grammar.
 
-import { EXIT, describeConditionErrors, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings, formatCiLatestRunNotice, formatUnknownWorkflowGuidance } from "./wait-core.mjs";
+import { EXIT, describeConditionErrors, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt, formatPrReviewSnapshotWarnings, formatCiLatestRunNotice, formatUnknownWorkflowGuidance, reviewTimeoutNotice } from "./wait-core.mjs";
 import { readAgentBinding, withPrincipalReceipt } from "./wait-profile.mjs";
 import { VERSION } from "./version.mjs";
 import { fileURLToPath } from "node:url";
@@ -111,9 +111,11 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       count), a Codex clean pass (payload.transition=clean_pass),
                                       the Codex usage-limit decline (transition=
                                       review_unavailable — no review is coming) or a Codex
-                                      review needing intervention after one backend diagnostic
-                                      (transition=review_stalled, review_available=false,
-                                      reason + next_action). Initial default: 10 min.
+                                      review still incomplete at its deadline after one backend
+                                      diagnostic: exit 13 REVIEW_TIMEOUT, receipt outcome
+                                      review_timeout, error = {minutes, source (call|repository|
+                                      tenant), started_at, deadline, reason, next_action,
+                                      guard_id}. Default: 15 min (Settings → Waits shows p50/p95).
                                       Edge-triggered: it wakes only on review activity AFTER
                                       arm, so arm BEFORE requesting the review. If the PR ALREADY
                                       has an outstanding review at arm, bb-wait prints a one-line
@@ -222,7 +224,8 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
 
 OPTIONS
   Review intervention: exact-head Codex waits have a durable one-shot diagnostic.
-  stall_minutes= overrides repository → tenant settings (initial default 10 min).
+  stall_minutes= overrides repository → tenant settings (default 15 min). At the
+  deadline with no review: exit 13 REVIEW_TIMEOUT (typed error + provenance).
   A missing/unbound backend guard is refused as review_guard_unsupported.
   It needs pr= + sha=. A result wakes immediately; a deadline never means approval.
   Reconnects/re-arms retain the deadline. This is separate from --timeout below.
@@ -280,7 +283,10 @@ OUTPUT
                 was parked — reaped after 180 s without a live stream,
                 or cancelled; receipt outcome abandoned +
                 state.status/reason — re-arm with --since <next_cursor>)
-                · 12 named lease cleanup failed.
+                · 12 named lease cleanup failed · 13 review timeout
+                (REVIEW_TIMEOUT: a Codex review still incomplete at its
+                deadline; receipt error carries minutes/source/reason —
+                use the fallback reviewer, never infer approval).
                 If the receipt has
                 reacquire_lock (claim=true), acquire_lock again FIRST and re-run
                 only on a queued/busy result (granted = you hold it — just resume);
@@ -751,7 +757,11 @@ async function registerWait(opts, conditions, deadlineIso) {
 // BOT-2013: wait_session_status has no lease_lost value. The session ends as a terminal
 // `error` and its stored receipt carries the precise outcome.
 export function cloudStatusForOutcome(outcome) {
-  return outcome === "lease_lost" ? "error" : outcome;
+  if (outcome === "lease_lost") return "error";
+  // BOT-2783: no review_timeout status either — the session ends `timeout` and the
+  // stored receipt (and the guard) carry the typed REVIEW_TIMEOUT provenance.
+  if (outcome === "review_timeout") return "timeout";
+  return outcome;
 }
 
 /** BOT-2013: the one stderr line for a lease_lost receipt (null for any other outcome). */
@@ -776,7 +786,7 @@ export function waitAbandonedNotice(receipt) {
 }
 
 function writeLeaseLostNotice(receipt) {
-  const notice = leaseLostNotice(receipt) ?? waitAbandonedNotice(receipt);
+  const notice = leaseLostNotice(receipt) ?? waitAbandonedNotice(receipt) ?? reviewTimeoutNotice(receipt);
   if (notice) process.stderr.write(`${notice}\n`);
 }
 
@@ -1547,8 +1557,9 @@ async function emitSavedWaitError(error) {
   process.exit(exitCode);
 }
 
-function exitForRecoveredOutcome(receipt) {
+export function recoveredExitCode(receipt) {
   if (receipt?.outcome === "matched") return EXIT.MATCHED;
+  if (receipt?.outcome === "review_timeout") return EXIT.REVIEW_TIMEOUT;
   if (receipt?.outcome === "lease_lost") return EXIT.LEASE_LOST;
   if (receipt?.outcome === "cancelled") return EXIT.MATCHED;
   if (receipt?.outcome === "timeout") return EXIT.TIMEOUT;
@@ -1610,7 +1621,7 @@ async function cancelSavedWait(id) {
             current = await store.update(id, {
               status: "cancelled",
               terminal_receipt: recovered,
-              exit_code: exitForRecoveredOutcome(recovered),
+              exit_code: recoveredExitCode(recovered),
               cancelled_at: new Date().toISOString(),
               cloud_cancel_pending: false,
               cloud_cancelled_at: new Date().toISOString(),
@@ -1621,7 +1632,7 @@ async function cancelSavedWait(id) {
             await store.update(id, {
               status: "terminal",
               terminal_receipt: recovered,
-              exit_code: exitForRecoveredOutcome(recovered),
+              exit_code: recoveredExitCode(recovered),
             });
             const conflict = new WaitCheckpointError(
               "wait_not_cancellable",
@@ -2107,7 +2118,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         const recoveredCancellation = recovered.outcome === "cancelled";
         await store.update(checkpoint.local_wait_id, {
           status: recoveredCancellation ? "cancelled" : "terminal", terminal_receipt: recovered,
-          exit_code: exitForRecoveredOutcome(recovered), cloud_wait_session_id: waitSessionId,
+          exit_code: recoveredExitCode(recovered), cloud_wait_session_id: waitSessionId,
           cloud_finalize_pending: false, cloud_finalized_at: new Date().toISOString(), cloud_finalize_error: null,
           ...(recoveredCancellation ? {
             cancelled_at: new Date().toISOString(),
@@ -2117,7 +2128,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
           } : {}),
         });
         await emitReceipt(recovered, { versioned: true });
-        process.exit(exitForRecoveredOutcome(recovered));
+        process.exit(recoveredExitCode(recovered));
       }
       // BOT-2468: the wait's dashboard deeplink, once, at arm time (and again on
       // `bb wait resume`, which re-registers). An agent that armed this in the