@botbuddy/cli 1.29.2 → 1.29.4

package/src/wait.mjs

@@ -20,6 +20,8 @@ import { fileURLToPath } from "node:url";
 import { latestPublicCliCommand } from "./public-invocation.mjs";
 import { AGENT_KEY_RE, readAgentKeyEnv } from "./agent-key.mjs";
 import { SETUP_BLOCK } from "./setup-block.mjs";
+import { createWaitCheckpointStore, WaitCheckpointError } from "./wait-checkpoint.mjs";
+import { realpath } from "node:fs/promises";
 
 // A protocol is deliberately distinct from package semver: compatible pinned
 // clients keep working until the server raises this minimum, while a stale
@@ -33,6 +35,7 @@ import { SETUP_BLOCK } from "./setup-block.mjs";
 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.
 const SESSION_TOKEN_RE = AGENT_KEY_RE;
@@ -116,7 +119,7 @@ OPTIONS
   --any                 wake on the first matching condition (default; only mode in v1)
   --timeout <seconds>   max wait (default 7200; hard cap 28800). Timeout is exit 2, not an error.
   --since <seq>         resume from a prior receipt's next_cursor (replay what you missed)
-  --receipt-max-bytes <n>   cap the receipt (minimum 512; default 10240; payloads truncate to pointers)
+  --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
@@ -126,6 +129,9 @@ OPTIONS
   --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).
   --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):
@@ -184,6 +190,8 @@ function parseArgv(argv) {
     // is for tests/overrides.
     sessionToken: readAgentKeyEnv(process.env),
     help: false,
+    deadlineAt: null,
+    resumeLocalWait: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -200,6 +208,7 @@ function parseArgv(argv) {
     else if (a === "--any") opts.mode = "any";
     else if (a === "--heartbeat") opts.heartbeat = true;
     else if (a === "--timeout") opts.timeout = Number(optionValue());
+    else if (a === "--deadline-at") opts.deadlineAt = optionValue(); // internal recovery argv; never shown as public API
     else if (a === "--since") opts.since = optionValue();
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
     else if (a === "--url") opts.url = optionValue();
@@ -217,6 +226,7 @@ function parseArgv(argv) {
     // alias for the same value.
     else if (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;
     else opts.conditions.push(a);
   }
@@ -226,6 +236,28 @@ function parseArgv(argv) {
 // Register a wait_session on the relay (BOT-989 M2). Returns
 // {waitSessionId, cursorStart} on success. Profiled waits fail closed unless the
 // relay authenticates and attests their machine principal.
+async function reserveClaimQueueBoundary(opts, conditions) {
+  const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      "x-agent-api-key": opts.token || "",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      action: "reserve_claim_boundary",
+      client_version: VERSION,
+      wait_protocol_version: WAIT_PROTOCOL_VERSION,
+      local_wait_id: opts.localWaitId,
+      conditions,
+    }),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    throw new Error(body.detail || body.error || `claim_boundary_failed_${res.status}`);
+  }
+}
+
 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.
@@ -238,6 +270,11 @@ async function registerWait(opts, conditions, deadlineIso) {
     conditions,
     deadline: deadlineIso,
     mode: opts.mode,
+    ...(opts.localWaitId ? { local_wait_id: opts.localWaitId } : {}),
+    ...(opts.expectedAgentId ? {
+      expected_agent_id: opts.expectedAgentId,
+      expected_tenant_id: opts.expectedTenantId ?? null,
+    } : {}),
   };
   const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
     method: "POST",
@@ -298,6 +335,8 @@ async function registerWait(opts, conditions, deadlineIso) {
       // 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",
+      "wait_resume_identity_invalid",
+      "wait_resume_identity_mismatch",
     ]);
     if (INVALID_CONDITION_CODES.has(body.error)) {
       const err = new Error(body.detail || body.error);
@@ -308,7 +347,7 @@ async function registerWait(opts, conditions, deadlineIso) {
   }
   if (res.status === 403) {
     const body = await res.json().catch(() => ({}));
-    if (new Set(["wait_tenant_unresolved", "wait_cross_tenant", "wait_tenant_mismatch"]).has(body.error)) {
+    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;
       err.errorCode = body.error;
@@ -399,6 +438,13 @@ async function registerWait(opts, conditions, deadlineIso) {
     // pr-review/pr-state target. Report-only — surfaced on stderr so a silent
     // edge-triggered park isn't mistaken for "no review yet".
     prReviewSnapshot: Array.isArray(body.pr_review_snapshot) ? body.pr_review_snapshot : null,
+    status: typeof body.status === "string" ? body.status : "active",
+    // A canonicalized alias wait was deliberately abandoned and already has a
+    // sequenced wait_superseded signal. Preserve that terminal state and replay
+    // the signal; treating it as a reaper abandonment would resurrect an
+    // unmatchable alias registration.
+    recoveryError: typeof body.recovery_error === "string" ? body.recovery_error : null,
+    terminalReceipt: body.terminal_receipt && typeof body.terminal_receipt === "object" ? body.terminal_receipt : null,
   };
 }
 
@@ -428,11 +474,15 @@ async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
       }),
       signal: ac.signal,
     });
-    if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok || body?.finalized !== true) {
       process.stderr.write(`bb-wait: finalize (non-fatal) returned ${res.status}\n`);
+      return { delivered: false, error: body?.error || (res.ok ? "finalize_not_applied" : `finalize_http_${res.status}`) };
     }
+    return { delivered: true };
   } catch (err) {
     process.stderr.write(`bb-wait: finalize (non-fatal) failed: ${err && err.message || err}\n`);
+    return { delivered: false, error: err?.name === "AbortError" ? "finalize_timeout" : "finalize_unavailable" };
   } finally {
     clearTimeout(timer);
   }
@@ -619,6 +669,34 @@ function withClientIdentity(receipt) {
   };
 }
 
+function publicWaitReceipt(receipt, {
+  sessionTenant = null,
+  agentId = null,
+  sessionAgentId = null,
+  sessionId = null,
+  maxBytes = 10240,
+} = {}) {
+  return truncateReceipt(withClientIdentity(withPrincipalReceipt(receipt, null, {
+    sessionTenant,
+    agentId,
+    sessionAgentId,
+    sessionId,
+  })), maxBytes);
+}
+
+// A recovered terminal receipt can originate from a server timeout before the
+// client reconnects. Its cursor is only the server's registration frontier; a
+// newer locally-persisted safe cursor is already known to be replayed and is
+// therefore the correct continuation point for the next wait.
+function preserveCheckpointCursor(receipt, safeCursor, createdAt = null) {
+  const saved = typeof safeCursor === "string" ? safeCursor : String(safeCursor ?? "");
+  const current = typeof receipt?.next_cursor === "string" ? receipt.next_cursor : String(receipt?.next_cursor ?? "");
+  const withCursor = /^\d+$/.test(saved) && /^\d+$/.test(current) && BigInt(saved) > BigInt(current)
+    ? { ...receipt, next_cursor: saved }
+    : receipt;
+  return !withCursor?.started_at && typeof createdAt === "string" ? { ...withCursor, started_at: createdAt } : withCursor;
+}
+
 function emit(receipt, { versioned = false, maxBytes = null } = {}) {
   const enriched = versioned ? receipt : withClientIdentity(receipt);
   const bounded = Number.isSafeInteger(maxBytes) && maxBytes >= MIN_RECEIPT_MAX_BYTES
@@ -758,7 +836,486 @@ async function sendSetupErrorEvent(opts, { error, exitCode, conditions }, signal
   });
 }
 
-export async function runWait(argv) {
+function checkpointStore() {
+  // State is intentionally bound to the current worktree.  A caller may point
+  // cwd at another checkout only by explicitly starting there; we never follow
+  // an arbitrary state-file path supplied in argv.
+  return createWaitCheckpointStore({ root: process.cwd() });
+}
+
+function inventoryEntry(checkpoint) {
+  const id = checkpoint.local_wait_id;
+  const terminal = checkpoint.status === "terminal";
+  const pendingCancellation = checkpoint.status === "cancelled" && checkpoint.cloud_cancel_pending === true;
+  const pendingAcknowledgement = checkpoint.status === "acknowledged" && checkpoint.cloud_ack_pending === true;
+  return {
+    local_wait_id: id,
+    status: checkpoint.status,
+    conditions: checkpoint.conditions?.map((c) => ({ condition_id: c.id, type: c.type })) ?? [],
+    ticket: checkpoint.ticket ?? null,
+    created_at: checkpoint.created_at ?? null,
+    deadline_at: checkpoint.deadline_at ?? null,
+    receipt_available: terminal && checkpoint.terminal_receipt != null,
+    recovery_argv: pendingCancellation
+      ? ["wait", "cancel", id]
+      : pendingAcknowledgement ? ["wait", "acknowledge", id] : ["wait", "resume", id],
+    cancel_argv: terminal || pendingAcknowledgement ? null : ["wait", "cancel", id],
+    acknowledge_argv: terminal || pendingAcknowledgement ? ["wait", "acknowledge", id] : null,
+  };
+}
+
+async function inspectSavedWaits(argv = []) {
+  const rawOffset = argv[0] === "--offset" ? Number(argv[1]) : 0;
+  if (!Number.isSafeInteger(rawOffset) || rawOffset < 0 || argv.length > (argv[0] === "--offset" ? 2 : 0)) {
+    process.stderr.write("bb-wait: usage: bb wait [--offset <n>]\n");
+    process.exit(EXIT.INVALID);
+  }
+  const inventory = await checkpointStore().list({ offset: rawOffset });
+  // Never let a non-interactive agent accidentally acquire an owner or consume
+  // a result.  The inventory deliberately omits receipt bodies and shell text.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    process.stdout.write(`${JSON.stringify({
+      schema_version: 1,
+      outcome: "saved_waits",
+      waits: inventory.items.map(inventoryEntry),
+      has_more: inventory.has_more,
+      ...(inventory.next_offset != null ? { next_offset: inventory.next_offset, next_page_argv: ["wait", "--offset", String(inventory.next_offset)] } : {}),
+    })}\n`);
+    process.exit(EXIT.MATCHED);
+  }
+  if (inventory.items.length === 0) {
+    process.stdout.write(HELP);
+    process.exit(EXIT.MATCHED);
+  }
+  // A TTY gets discovery guidance without an implicit selection. This is a
+  // deliberately conservative menu: a restart must name an ID before mutation.
+  process.stdout.write("Saved bb waits:\n");
+  for (const item of inventory.items) {
+    process.stdout.write(`  ${item.local_wait_id}  ${item.status}  ${item.deadline_at ?? ""}\n`);
+  }
+  process.stdout.write("Run `bb wait resume <local_wait_id>`, `bb wait cancel <local_wait_id>`, or `bb wait acknowledge <local_wait_id>`. Ctrl-C leaves saved waits unchanged.\n");
+  process.exit(EXIT.MATCHED);
+}
+
+export function resumedSpecs(checkpoint) {
+  const specs = Array.isArray(checkpoint.condition_specs) ? [...checkpoint.condition_specs] : [];
+  if (specs.length === 0) throw new WaitCheckpointError("wait_checkpoint_invalid", "checkpoint has no recoverable condition arguments");
+  let timerIndex = 0;
+  return specs.map((spec) => {
+    if (!String(spec).startsWith("timer:")) return spec;
+    const fireAt = checkpoint.timer_deadlines?.[timerIndex++];
+    if (typeof fireAt !== "string") throw new WaitCheckpointError("wait_checkpoint_invalid", "timer checkpoint has no original fire time");
+    return `timer:deadline=${fireAt}`;
+  });
+}
+
+export function restoreCapacityStaleDeadlines(conditions, checkpoint) {
+  const capacity = conditions.filter((condition) => condition.type === "capacity");
+  if (capacity.length === 0) return conditions;
+  const deadlines = checkpoint.capacity_stale_deadlines;
+  const createdMs = Date.parse(checkpoint.created_at);
+  if (!Array.isArray(deadlines) || deadlines.length !== capacity.length || !Number.isFinite(createdMs)) {
+    throw new WaitCheckpointError("wait_checkpoint_invalid", "capacity checkpoint has no original stale-grace deadlines");
+  }
+  for (let index = 0; index < capacity.length; index++) {
+    const deadlineMs = Date.parse(deadlines[index]);
+    const maximum = createdMs + capacity[index].params.staleGraceSec * 1000 + 1_000;
+    if (!Number.isFinite(deadlineMs) || deadlineMs > maximum) {
+      throw new WaitCheckpointError("wait_checkpoint_invalid", "capacity stale-grace deadline exceeds its original budget");
+    }
+    capacity[index].params.staleDeadlineMs = deadlineMs;
+  }
+  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);
+  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` };
+    }
+    return { delivered: true };
+  } catch (error) {
+    return { delivered: false, error: error?.name === "AbortError" ? `${action}_timeout` : `${action}_unavailable` };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function checkpointNeedsRelay(checkpoint) {
+  return checkpoint.conditions.some((condition) => condition.type !== "timer");
+}
+
+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 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);
+  }
+}
+
+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);
+  }
+}
+
+async function flushPendingFinalization(store, checkpoint) {
+  if (!checkpoint.cloud_wait_session_id || !checkpoint.terminal_receipt ||
+      (checkpoint.cloud_finalize_pending === false && checkpoint.cloud_finalized_at)) return checkpoint;
+  if (checkpoint.terminal_receipt.outcome === "superseded") {
+    return store.update(checkpoint.local_wait_id, {
+      cloud_finalize_pending: false,
+      cloud_finalized_at: new Date().toISOString(),
+      cloud_finalize_error: null,
+    });
+  }
+  const delivered = await deliverTerminalFinalization(checkpoint);
+  return store.update(checkpoint.local_wait_id, delivered.delivered
+    ? { cloud_finalize_pending: false, cloud_finalized_at: new Date().toISOString(), cloud_finalize_error: null }
+    : { cloud_finalize_pending: true, cloud_finalize_error: delivered.error });
+}
+
+async function flushPendingAcknowledgement(store, checkpoint) {
+  if (!checkpoint.cloud_ack_pending || !checkpoint.cloud_wait_session_id) return checkpoint;
+  checkpoint = await flushPendingFinalization(store, checkpoint);
+  if (checkpoint.cloud_finalize_pending) {
+    return store.update(checkpoint.local_wait_id, { cloud_ack_pending: true, cloud_ack_error: "finalize_pending" });
+  }
+  const delivered = await deliverRecoveryAction(checkpoint, "acknowledge");
+  if (delivered.delivered) {
+    return store.update(checkpoint.local_wait_id, {
+      cloud_ack_pending: false,
+      cloud_acknowledged_at: new Date().toISOString(),
+      cloud_ack_error: null,
+    });
+  }
+  return store.update(checkpoint.local_wait_id, { cloud_ack_pending: true, cloud_ack_error: delivered.error });
+}
+
+async function resumeSavedWait(id) {
+  const store = checkpointStore();
+  let checkpoint;
+  try { checkpoint = await store.read(id); }
+  catch (error) { return emitSavedWaitError(error); }
+  if (!(await sameWorktree(checkpoint.worktree, process.cwd()))) {
+    return emitSavedWaitError(new WaitCheckpointError("wait_resume_identity_mismatch", "saved wait belongs to a different worktree"));
+  }
+  if (checkpoint.status === "terminal") {
+    let fence;
+    try {
+      fence = await store.acquireFence(id);
+      checkpoint = await store.read(id);
+      if (checkpoint.status !== "terminal") {
+        throw new WaitCheckpointError("wait_not_resumable", `saved wait ${id} is ${checkpoint.status}`);
+      }
+      checkpoint = await flushPendingFinalization(store, checkpoint);
+      checkpoint = await flushPendingAcknowledgement(store, checkpoint);
+    } catch (error) {
+      return emitSavedWaitError(error);
+    } finally {
+      await fence?.release();
+    }
+    process.stdout.write(`${JSON.stringify(checkpoint.terminal_receipt)}\n`);
+    process.exit(Number.isInteger(checkpoint.exit_code) ? checkpoint.exit_code : EXIT.INTERNAL);
+  }
+  if (["cancelled", "acknowledged"].includes(checkpoint.status)) {
+    return emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", `saved wait ${id} is ${checkpoint.status}`));
+  }
+  const remaining = Date.parse(checkpoint.deadline_at) - Date.now();
+  if (!Number.isFinite(remaining)) return emitSavedWaitError(new WaitCheckpointError("wait_checkpoint_invalid", "saved wait deadline is invalid"));
+  // Preserve the original absolute deadline. A resumed wait is never granted a
+  // fresh timeout budget; the core loop settles it immediately if already due.
+  const args = [
+    ...resumedSpecs(checkpoint),
+    "--deadline-at", checkpoint.deadline_at,
+    "--resume-local-wait", checkpoint.local_wait_id,
+    "--receipt-max-bytes", String(checkpoint.receipt_max_bytes ?? 10240),
+  ];
+  if (checkpoint.safe_cursor != null) args.push("--since", String(checkpoint.safe_cursor));
+  if (checkpoint.heartbeat) args.push("--heartbeat");
+  if (checkpoint.relay_url) args.push("--url", checkpoint.relay_url);
+  return runWait(args, { recoveryLocalWaitId: checkpoint.local_wait_id });
+}
+
+async function sameWorktree(first, second) {
+  try { return await realpath(first) === await realpath(second); }
+  catch { return false; }
+}
+
+function emitSavedWaitError(error) {
+  const code = error?.code ?? "wait_checkpoint_invalid";
+  const exitCode = code === "wait_checkpoint_write_failed" ? EXIT.INTERNAL : EXIT.INVALID;
+  process.stderr.write(`bb-wait: ${error?.message ?? code}\n`);
+  process.stdout.write(`${JSON.stringify({
+    schema_version: 1,
+    outcome: "error",
+    error: code,
+    ...(error?.localWaitId ? { local_wait_id: error.localWaitId } : {}),
+    ...(Array.isArray(error?.recoveryArgv) ? { recovery_argv: error.recoveryArgv } : {}),
+    ...(typeof error?.recovery === "string" ? { recovery: error.recovery } : {}),
+  })}\n`);
+  process.exit(exitCode);
+}
+
+function exitForRecoveredOutcome(receipt) {
+  if (receipt?.outcome === "matched") return EXIT.MATCHED;
+  if (receipt?.outcome === "cancelled") return EXIT.MATCHED;
+  if (receipt?.outcome === "timeout") return EXIT.TIMEOUT;
+  if (receipt?.outcome === "superseded") return EXIT.SUPERSEDED;
+  if (receipt?.error === "cursor_expired") return EXIT.CURSOR_EXPIRED;
+  if (receipt?.error === "unauthorized" || receipt?.error === "forbidden") return EXIT.AUTH;
+  return EXIT.BACKEND;
+}
+
+async function cancelSavedWait(id) {
+  try {
+    const store = checkpointStore();
+    let current = await store.read(id);
+    if (current.status === "terminal" || current.status === "acknowledged") {
+      const conflict = new WaitCheckpointError(
+        "wait_not_cancellable",
+        `saved wait ${id} is ${current.status} and cannot be cancelled`,
+      );
+      conflict.localWaitId = id;
+      if (current.status === "terminal") conflict.recoveryArgv = ["wait", "resume", id];
+      throw conflict;
+    }
+    // Refuse to cancel underneath a surviving waiter. A crashed owner is
+    // reclaimed by the same process-instance fence used for resume.
+    const fence = await store.acquireFence(id);
+    try {
+      current = await store.read(id);
+      if (current.status === "terminal" || current.status === "acknowledged") {
+        const conflict = new WaitCheckpointError(
+          "wait_not_cancellable",
+          `saved wait ${id} is ${current.status} and cannot be cancelled`,
+        );
+        conflict.localWaitId = id;
+        if (current.status === "terminal") conflict.recoveryArgv = ["wait", "resume", id];
+        throw conflict;
+      }
+      let delivered;
+      const resolution = await resolveRecoveryWaitSession(current, { reserveMissing: true });
+      if (resolution.registration) {
+        const reg = resolution.registration;
+        current = await store.update(id, {
+          cloud_wait_session_id: reg.waitSessionId,
+          cursor_start: reg.cursorStart,
+          tenant_id: reg.sessionTenant ?? null,
+          agent_id: reg.agentId ?? null,
+          arming_session_id: reg.sessionId ?? null,
+        });
+        if (reg.terminalReceipt) {
+          const recovered = preserveCheckpointCursor(publicWaitReceipt(reg.terminalReceipt, {
+            sessionTenant: reg.sessionTenant,
+            agentId: reg.agentId,
+            sessionAgentId: reg.sessionAgentId,
+            sessionId: reg.sessionId,
+            maxBytes: current.receipt_max_bytes,
+          }), current.safe_cursor, current.created_at);
+          if (recovered.outcome === "cancelled") {
+            current = await store.update(id, {
+              status: "cancelled",
+              terminal_receipt: recovered,
+              exit_code: exitForRecoveredOutcome(recovered),
+              cancelled_at: new Date().toISOString(),
+              cloud_cancel_pending: false,
+              cloud_cancelled_at: new Date().toISOString(),
+              cloud_cancel_error: null,
+            });
+            delivered = { delivered: true };
+          } else {
+            await store.update(id, {
+              status: "terminal",
+              terminal_receipt: recovered,
+              exit_code: exitForRecoveredOutcome(recovered),
+            });
+            const conflict = new WaitCheckpointError(
+              "wait_not_cancellable",
+              `saved wait ${id} is terminal and cannot be cancelled`,
+            );
+            conflict.localWaitId = id;
+            conflict.recoveryArgv = ["wait", "resume", id];
+            throw conflict;
+          }
+        }
+      } else if (resolution.error) {
+        delivered = { delivered: false, error: resolution.error };
+      } else if (resolution.missing) {
+        // The original process never reached registration. A lookup must never
+        // create/evaluate a new claim merely to cancel it.
+        delivered = { delivered: true };
+      }
+      delivered ??= await deliverRecoveryAction(current, "cancel");
+      if (delivered.error === "wait_claim_grant_recovery_required") {
+        // The grant committed before the former process could save its
+        // receipt. Keep (or restore) a resumable checkpoint so the held
+        // resource is visible and its grant can be replayed.
+        current = await store.update(id, {
+          status: "armed",
+          cancelled_at: null,
+          cloud_cancel_pending: false,
+          cloud_cancel_error: delivered.error,
+        });
+        const conflict = new WaitCheckpointError(
+          "wait_claim_grant_recovery_required",
+          `saved wait ${id} already holds a committed claim; resume it to replay the grant`,
+        );
+        conflict.localWaitId = id;
+        conflict.recoveryArgv = ["wait", "resume", id];
+        throw conflict;
+      }
+      current = await store.update(id, {
+        status: "cancelled",
+        cancelled_at: new Date().toISOString(),
+        cloud_cancel_pending: checkpointNeedsRelay(current) && !delivered.delivered,
+        ...(delivered.delivered
+          ? { cloud_cancelled_at: new Date().toISOString(), cloud_cancel_error: null }
+          : { cloud_cancel_error: delivered.error }),
+      });
+    } finally {
+      await fence.release();
+    }
+    process.stdout.write(`${JSON.stringify({
+      schema_version: 1, outcome: "cancelled", local_wait_id: id,
+      ...(current.cloud_cancel_pending ? { cloud_cancel_pending: true } : {}),
+    })}\n`);
+    process.exit(EXIT.MATCHED);
+  } catch (error) { return emitSavedWaitError(error); }
+}
+
+async function acknowledgeSavedWait(id) {
+  let fence;
+  try {
+    const store = checkpointStore();
+    // A terminal checkpoint can exist briefly while its original owner is still
+    // responsible for emitting the receipt. Never hide or mutate that result
+    // until the same process-instance fence used by resume proves ownership.
+    fence = await store.acquireFence(id);
+    let checkpoint = await store.read(id);
+    if (checkpoint.status === "terminal") checkpoint = await flushPendingFinalization(store, checkpoint);
+    checkpoint = await store.acknowledge(id, {
+      cloudAckPending: Boolean(checkpoint.cloud_wait_session_id),
+    });
+    if (checkpoint.cloud_wait_session_id) {
+      checkpoint = await flushPendingAcknowledgement(store, checkpoint);
+    }
+    process.stdout.write(`${JSON.stringify({
+      schema_version: 1, outcome: "acknowledged", local_wait_id: id,
+      ...(checkpoint.cloud_ack_pending ? { cloud_ack_pending: true } : {}),
+    })}\n`);
+    await fence.release();
+    fence = null;
+    process.exit(EXIT.MATCHED);
+  } catch (error) {
+    await fence?.release();
+    return emitSavedWaitError(error);
+  }
+}
+
+export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
+  if (argv.length === 0 || argv[0] === "--offset") return inspectSavedWaits(argv);
+  if (argv[0] === "resume") {
+    const id = argv[1];
+    if (!id || argv.length > 2) return emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "select exactly one saved wait: bb wait resume <local_wait_id>"));
+    return resumeSavedWait(id);
+  }
+  if (argv[0] === "cancel") return argv.length === 2 ? cancelSavedWait(argv[1]) : emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "usage: bb wait cancel <local_wait_id>"));
+  if (argv[0] === "acknowledge") return argv.length === 2 ? acknowledgeSavedWait(argv[1]) : emitSavedWaitError(new WaitCheckpointError("wait_not_resumable", "usage: bb wait acknowledge <local_wait_id>"));
   const opts = parseArgv(argv);
   const emitReceipt = (receipt, options = {}) => emit(receipt, {
     ...options,
@@ -795,6 +1352,22 @@ export async function runWait(argv) {
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.missing });
     process.exit(EXIT.INVALID);
   }
+  if ((opts.resumeLocalWait != null || opts.deadlineAt != null) &&
+      (recoveryLocalWaitId == null || opts.resumeLocalWait !== recoveryLocalWaitId)) {
+    process.stderr.write("bb-wait: saved wait recovery options are internal; use bb wait resume <local_wait_id>\n");
+    emitReceipt({
+      schema_version: 1,
+      outcome: "error",
+      error: "wait_not_resumable",
+      recovery_argv: ["wait", "resume", opts.resumeLocalWait ?? "<local_wait_id>"],
+    });
+    process.exit(EXIT.INVALID);
+  }
+  if (opts.deadlineAt != null && !opts.resumeLocalWait) {
+    process.stderr.write("bb-wait: --deadline-at is reserved for saved wait recovery\n");
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: "--deadline-at" });
+    process.exit(EXIT.INVALID);
+  }
 
   const { conditions, errors } = parseConditions(opts.conditions);
   if (errors.length > 0) {
@@ -812,13 +1385,91 @@ export async function runWait(argv) {
     emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_timeout" });
     process.exit(EXIT.INVALID);
   }
-  if (!Number.isSafeInteger(opts.receiptMaxBytes) || opts.receiptMaxBytes < MIN_RECEIPT_MAX_BYTES) {
-    process.stderr.write(`bb-wait: --receipt-max-bytes must be an integer of at least ${MIN_RECEIPT_MAX_BYTES}\n`);
-    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_receipt_max_bytes", minimum: MIN_RECEIPT_MAX_BYTES });
+  if (!Number.isSafeInteger(opts.receiptMaxBytes) || opts.receiptMaxBytes < MIN_RECEIPT_MAX_BYTES ||
+      opts.receiptMaxBytes > MAX_RECEIPT_MAX_BYTES) {
+    process.stderr.write(`bb-wait: --receipt-max-bytes must be an integer from ${MIN_RECEIPT_MAX_BYTES} through ${MAX_RECEIPT_MAX_BYTES}\n`);
+    emitReceipt({
+      schema_version: 1, outcome: "error", error: "invalid_receipt_max_bytes",
+      minimum: MIN_RECEIPT_MAX_BYTES, maximum: MAX_RECEIPT_MAX_BYTES,
+    });
     process.exit(EXIT.INVALID);
   }
   const timeoutSec = Math.min(opts.timeout, 28800); // 8h hard cap (session-budget gate)
-  const deadlineMs = Date.now() + timeoutSec * 1000;
+  const deadlineMs = opts.deadlineAt == null ? Date.now() + timeoutSec * 1000 : Date.parse(opts.deadlineAt);
+  if (!Number.isFinite(deadlineMs)) {
+    emitReceipt({ schema_version: 1, outcome: "error", error: "wait_checkpoint_invalid" });
+    process.exit(EXIT.INVALID);
+  }
+
+  // A valid wait gets a durable identity BEFORE its first remote side effect.
+  // Credentials are intentionally absent: resume always obtains fresh session
+  // credentials through register_agent/the normal environment bootstrap.
+  const store = checkpointStore();
+  let checkpoint;
+  try {
+    if (opts.resumeLocalWait) {
+      checkpoint = await store.read(opts.resumeLocalWait);
+      if (!(await sameWorktree(checkpoint.worktree, process.cwd()))) throw new WaitCheckpointError("wait_resume_identity_mismatch", "saved wait belongs to a different worktree");
+      if (!["preparing", "armed", "interrupted"].includes(checkpoint.status)) {
+        throw new WaitCheckpointError("wait_not_resumable", `saved wait is ${checkpoint.status}`);
+      }
+      const createdMs = Date.parse(checkpoint.created_at);
+      const savedDeadlineMs = Date.parse(checkpoint.deadline_at);
+      if (opts.deadlineAt !== checkpoint.deadline_at || !Number.isFinite(createdMs) ||
+          !Number.isFinite(savedDeadlineMs) || savedDeadlineMs > createdMs + 28_800_000) {
+        throw new WaitCheckpointError("wait_checkpoint_invalid", "saved wait deadline exceeds its original eight-hour cap");
+      }
+      const expectedSpecs = resumedSpecs(checkpoint);
+      if (expectedSpecs.length !== opts.conditions.length ||
+          expectedSpecs.some((spec, index) => spec !== opts.conditions[index])) {
+        throw new WaitCheckpointError("wait_checkpoint_invalid", "saved wait conditions differ from the recovery invocation");
+      }
+      restoreCapacityStaleDeadlines(conditions, checkpoint);
+    } else {
+      let relayUrl = null;
+      try {
+        const parsedUrl = new URL(opts.url);
+        // A bearer URL is a secret. Retain only the endpoint origin/path used for
+        // recovery; query strings, fragments, and userinfo never touch disk.
+        parsedUrl.username = ""; parsedUrl.password = ""; parsedUrl.search = ""; parsedUrl.hash = "";
+        relayUrl = parsedUrl.toString().replace(/\/$/, "");
+      } catch { throw new WaitCheckpointError("wait_checkpoint_write_failed", "relay URL cannot be stored safely"); }
+      const timerDeadlines = conditions.filter((condition) => condition.type === "timer").map((condition) =>
+        condition.params.deadline ?? new Date(Date.now() + condition.params.duration * 1000).toISOString());
+      const capacityStaleDeadlines = conditions.filter((condition) => condition.type === "capacity").map((condition) =>
+        new Date(Date.now() + condition.params.staleGraceSec * 1000).toISOString());
+      checkpoint = await store.create({
+        local_wait_id: `wait-${crypto.randomUUID()}`,
+        deadline_at: new Date(deadlineMs).toISOString(),
+        conditions,
+        condition_specs: opts.conditions,
+        timer_deadlines: timerDeadlines,
+        capacity_stale_deadlines: capacityStaleDeadlines,
+        heartbeat: opts.heartbeat,
+        receipt_max_bytes: opts.receiptMaxBytes,
+        relay_url: relayUrl,
+        worktree: process.cwd(),
+      });
+    }
+    // A live process retains this fence until exit. The file records a PID and
+    // its start identity, so a reused PID cannot become evidence of ownership.
+    // Recovery takes the fence before changing state or opening another SSE
+    // subscriber for this logical wait.
+    const fence = await store.acquireFence(checkpoint.local_wait_id);
+    checkpoint = await store.update(checkpoint.local_wait_id, {
+      owner_fence: fence.owner,
+      ...(opts.resumeLocalWait ? { resumed_at: new Date().toISOString() } : {}),
+    });
+    opts.localWaitId = checkpoint.local_wait_id;
+    if (opts.resumeLocalWait) {
+      opts.expectedAgentId = typeof checkpoint.agent_id === "string" ? checkpoint.agent_id : null;
+      opts.expectedTenantId = typeof checkpoint.tenant_id === "string" ? checkpoint.tenant_id : null;
+    }
+  } catch (error) {
+    return emitSavedWaitError(error instanceof WaitCheckpointError
+      ? error
+      : new WaitCheckpointError("wait_checkpoint_write_failed", String(error?.message ?? error)));
+  }
 
   const needsRelay = conditions.some((c) => c.type !== "timer");
   // BOT-1572/1582/1608: a relay wait authenticates from the per-session
@@ -882,8 +1533,17 @@ export async function runWait(argv) {
   // BOT-1467: the session agent the relay attributed the wait to (when overridden).
   let registeredSessionAgentId = null;
   let registeredSessionId = null;
+  let replayMatchedClaim = false;
+  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.
+      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());
       waitSessionId = reg.waitSessionId;
       opts.waitSessionId = waitSessionId;
@@ -891,6 +1551,55 @@ export async function runWait(argv) {
       registeredAgentId = reg.agentId;
       registeredSessionAgentId = reg.sessionAgentId;
       registeredSessionId = reg.sessionId;
+      // A freshly minted session token may represent the same immutable agent,
+      // but never a different tenant/agent or worktree. Check before exposing a
+      // result or opening the SSE stream.
+      if ((checkpoint.agent_id && checkpoint.agent_id !== registeredAgentId) ||
+          (checkpoint.tenant_id != null && checkpoint.tenant_id !== sessionTenant)) {
+        throw new WaitCheckpointError("wait_resume_identity_mismatch", "fresh session does not own this saved wait");
+      }
+      // A lock grant is committed as a durable spine signal and terminalizes the
+      // cloud wait without a receipt. Replaying from cursor_start/safe_cursor is
+      // therefore the recovery path for a receipt-less matched claim.
+      replayMatchedClaim = reg.status === "matched" && !reg.terminalReceipt && hasClaim;
+      replayExpiredRecovery = Boolean(
+        opts.resumeLocalWait && Date.now() >= deadlineMs && (
+          (!hasClaim && reg.status === "active") ||
+          (reg.status === "abandoned" && reg.recoveryError === "wait_superseded")
+        ),
+      );
+      if (["matched", "timeout", "error"].includes(reg.status) && !reg.terminalReceipt && !replayMatchedClaim) {
+        throw new WaitCheckpointError("wait_resume_result_unavailable", "cloud wait is terminal but has no recoverable receipt");
+      }
+      const abandonedClaim = reg.status === "abandoned"
+        ? checkpoint.conditions.find((condition) => condition.type === "lock" && condition.params?.claim === true)
+        : null;
+      if (abandonedClaim && reg.recoveryError !== "wait_superseded") {
+        const error = new WaitCheckpointError("wait_claim_requeue_required", "reacquire the claimed resource before resuming this abandoned wait");
+        error.localWaitId = checkpoint.local_wait_id;
+        error.recovery = `call acquire_lock for ${abandonedClaim.params.subtype}:${abandonedClaim.params.host}:${abandonedClaim.params.slot}, then: bb wait resume ${checkpoint.local_wait_id}`;
+        throw error;
+      }
+      if (reg.terminalReceipt) {
+        const recovered = preserveCheckpointCursor(publicWaitReceipt(reg.terminalReceipt, {
+          sessionTenant, agentId: registeredAgentId, sessionAgentId: registeredSessionAgentId,
+          sessionId: registeredSessionId, maxBytes: opts.receiptMaxBytes,
+        }), checkpoint.safe_cursor, checkpoint.created_at);
+        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,
+          cloud_finalize_pending: false, cloud_finalized_at: new Date().toISOString(), cloud_finalize_error: null,
+          ...(recoveredCancellation ? {
+            cancelled_at: new Date().toISOString(),
+            cloud_cancel_pending: false,
+            cloud_cancelled_at: new Date().toISOString(),
+            cloud_cancel_error: null,
+          } : {}),
+        });
+        emitReceipt(recovered, { versioned: true });
+        process.exit(exitForRecoveredOutcome(recovered));
+      }
       // BOT-1539: if any pr-review/pr-state target already has an outstanding
       // review, tell the operator now (stderr, one line per PR). Purely
       // informational — it does not change arming or exit semantics.
@@ -941,6 +1650,16 @@ export async function runWait(argv) {
       // Arm from the registration high-water mark unless the caller pinned an
       // explicit --since (resume). cursor_start replays the register→connect gap.
       if (opts.since == null && reg.cursorStart != null) effectiveSince = String(reg.cursorStart);
+      checkpoint = await store.update(checkpoint.local_wait_id, {
+        status: "armed",
+        cloud_wait_session_id: waitSessionId,
+        cursor_start: reg.cursorStart,
+        safe_cursor: effectiveSince,
+        tenant_id: sessionTenant ?? null,
+        agent_id: registeredAgentId ?? null,
+        arming_session_id: registeredSessionId ?? null,
+        conditions,
+      });
       if (hasClaim && waitSessionId == null) {
         process.stderr.write("bb-wait: claim=true registration returned no wait_session_id; refusing to arm an unmatchable claim wait\n");
         emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
@@ -1066,6 +1785,7 @@ export async function runWait(argv) {
         emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.detail) });
         process.exit(EXIT.INTERNAL);
       }
+      if (err instanceof WaitCheckpointError) return emitSavedWaitError(err);
       if (hasClaim) {
         process.stderr.write(`bb-wait: claim=true wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
         emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
@@ -1084,48 +1804,114 @@ export async function runWait(argv) {
     }
   }
 
+  if (!needsRelay) {
+    try {
+      checkpoint = await store.update(checkpoint.local_wait_id, { status: "armed", safe_cursor: effectiveSince, conditions });
+    } catch (error) { return emitSavedWaitError(error); }
+  }
+
   const connect = needsRelay ? makeConnect(opts) : async () => offlineStream();
   // BOT-1147 AC-3: wire the feed-freshness probe only when a linear condition is
   // armed against the relay (runWaitLoop no-ops the probe for other wait types).
   const feedLagProbe = needsRelay && conditions.some((c) => c.type === "linear")
     ? makeFeedLagProbe(opts)
     : null;
+  const buildPublicReceipt = (receipt) => publicWaitReceipt(receipt, {
+    sessionTenant,
+    agentId: registeredAgentId,
+    sessionAgentId: registeredSessionAgentId,
+    sessionId: registeredSessionId,
+    maxBytes: opts.receiptMaxBytes,
+  });
+  let terminalPersistedFromFrame = false;
 
   try {
+    // A committed claim grant is authoritative even if recovery starts after the
+    // original deadline. It must keep replaying until the durable grant arrives
+    // (or the transport fails non-terminally); a fixed grace would persist a false
+    // timeout while the resource remains held. Non-claim expired recovery retains
+    // a bounded transport grace while it replays pre-deadline signals.
+    const loopDeadlineMs = replayMatchedClaim ? null : replayExpiredRecovery ? Date.now() + 10_000 : deadlineMs;
     const { receipt, exitCode } = await runWaitLoop({
       waitSessionId,
       conditions,
-      deadlineMs,
+      deadlineMs: loopDeadlineMs,
+      replayOnlyThroughMs: replayExpiredRecovery ? deadlineMs : null,
       since: effectiveSince,
       connect,
       feedLagProbe,
       receiptMaxBytes: opts.receiptMaxBytes,
+      startedAt: checkpoint.created_at,
       // BOT-1259: fail-closed tenant scope for the central guard, plus a debug sink
       // (opt-in via BB_WAIT_DEBUG) that surfaces each fail-closed drop without turning
       // it into an error.
       sessionTenant,
+      onFrame: async (_signal, state) => {
+        if (state?.terminalReceipt) {
+          // The core has evaluated this frame as a match. Save its bounded result
+          // before returning to the caller, so SIGKILL cannot lose a match between
+          // decode and stdout.
+          const terminalReceipt = buildPublicReceipt(state.terminalReceipt);
+          checkpoint = await store.update(checkpoint.local_wait_id, {
+            status: "terminal",
+            terminal_receipt: terminalReceipt,
+            exit_code: state.exitCode,
+            safe_cursor: terminalReceipt.next_cursor ?? state.cursor ?? checkpoint.safe_cursor,
+            cloud_finalize_pending: Boolean(waitSessionId && terminalReceipt.outcome !== "superseded"),
+          });
+          terminalPersistedFromFrame = true;
+          return;
+        }
+        checkpoint = await store.update(checkpoint.local_wait_id, { safe_cursor: state?.cursor ?? checkpoint.safe_cursor });
+      },
       debug: process.env.BB_WAIT_DEBUG ? (msg) => process.stderr.write(`${msg}\n`) : null,
     });
-    // Emit the wake receipt FIRST — it is the terminal result the harness reads.
-    // Finalization is best-effort telemetry and must never gate or delay it.
-    const terminalReceipt = truncateReceipt(
-      withClientIdentity(withPrincipalReceipt(receipt, null, {
-        sessionTenant,
-        agentId: registeredAgentId,
-        sessionAgentId: registeredSessionAgentId,
-        sessionId: registeredSessionId,
-      })),
-      opts.receiptMaxBytes,
-    );
+    // Build the same bounded public receipt used by the frame-time durable write.
+    // Cloud finalization is best-effort telemetry and must never gate stdout.
+    const terminalReceipt = buildPublicReceipt(receipt);
+    if (replayExpiredRecovery && receipt.error === "replay_incomplete") {
+      // A replay grace only limits this process, never the durable logical wait.
+      // Keep the checkpoint resumable and leave the active cloud row untouched.
+      checkpoint = await store.update(checkpoint.local_wait_id, {
+        status: "interrupted",
+        safe_cursor: terminalReceipt.next_cursor ?? checkpoint.safe_cursor ?? null,
+      });
+      emitReceipt(terminalReceipt, { versioned: true });
+      process.exit(exitCode);
+    }
+    // Receipt first, stdout second, cloud finalization last. A killed harness can
+    // always re-read this exact terminal result without opening a new wait.
+    if (!terminalPersistedFromFrame) {
+      checkpoint = await store.update(checkpoint.local_wait_id, {
+        status: "terminal",
+        terminal_receipt: terminalReceipt,
+        exit_code: exitCode,
+        safe_cursor: terminalReceipt.next_cursor ?? checkpoint.safe_cursor ?? null,
+        cloud_finalize_pending: Boolean(waitSessionId && terminalReceipt.outcome !== "superseded"),
+      });
+    }
     emitReceipt(terminalReceipt, { versioned: true });
     // BOT-1228: a `superseded` outcome means an external actor already terminalized
     // this wait_session server-side (reconcile_waits_to_canonical → abandoned, with
     // ended_at/updated_at stamped). Skip the client finalize: the row is already
     // terminal (finalize_wait_session only transitions from active, so it'd be a
     // no-op) and `superseded` isn't a wait_session_status enum value anyway.
-    if (waitSessionId && receipt.outcome !== "superseded") await finalizeWait(opts, waitSessionId, terminalReceipt);
+    if (waitSessionId && receipt.outcome !== "superseded") {
+      const finalized = await finalizeWait(opts, waitSessionId, terminalReceipt);
+      try {
+        checkpoint = await store.update(checkpoint.local_wait_id, finalized.delivered
+          ? { cloud_finalize_pending: false, cloud_finalized_at: new Date().toISOString(), cloud_finalize_error: null }
+          : { cloud_finalize_pending: true, cloud_finalize_error: finalized.error });
+      } catch (error) {
+        // The terminal receipt was already durable and emitted. Leave its
+        // pending marker in place for recovery; never emit a second receipt.
+        process.stderr.write(`bb-wait: finalize checkpoint update (non-fatal) failed: ${error?.message ?? error}\n`);
+      }
+    }
     process.exit(exitCode);
   } catch (err) {
+    try { if (checkpoint?.local_wait_id) await store.update(checkpoint.local_wait_id, { status: "interrupted" }); } catch { /* retain original diagnostic state */ }
+    if (err instanceof WaitCheckpointError) return emitSavedWaitError(err);
     process.stderr.write(`bb-wait: ${err && err.stack || err}\n`);
     emitReceipt({ schema_version: 1, outcome: "error", error: "internal" });
     process.exit(EXIT.INTERNAL);