@botbuddy/cli 1.59.1 → 1.59.4

package/package.json

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

package/src/run.mjs

@@ -215,6 +215,66 @@ export function commandHash(command) { return createHash("sha256").update(JSON.s
 export function environmentHash(cwd, environment) { return createHash("sha256").update(`${cwd}\0${environment}`).digest("hex"); }
 export function receiptPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.receipt.json`); }
 export function contextPath(runId) { return join(homedir(), ".botbuddy", "command-runs", `${runId}.context.json`); }
+function cancellationPath(contextFile) { return `${contextFile}.cancelled`; }
+
+async function markCancellation(contextFile, runId) {
+  try {
+    await writeFile(cancellationPath(contextFile), JSON.stringify({ run_id: runId, reason: "cancelled_before_workload_start", requested_at: new Date().toISOString() }), { mode: 0o600, flag: "wx" });
+    return true;
+  } catch (error) {
+    if (error?.code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+async function hasCancellationMarker(contextFile) {
+  try { await readFile(cancellationPath(contextFile), "utf8"); return true; } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function preWorkloadCancellationReceipt(context) {
+  const now = new Date().toISOString();
+  const receipt = {
+    schema_version: RUN_SCHEMA_VERSION,
+    run_id: context.run_id,
+    status: "cancelled",
+    started_at: now,
+    ended_at: now,
+    exit_code: null,
+    signal: "SIGTERM",
+    recovery_command: null,
+    bounded_log: "",
+    output_characters: 0,
+    reason: "cancelled_before_workload_start",
+  };
+  await writeJson(context.receipt_path, receipt);
+  return receipt;
+}
+
+async function retryCancellationHandoff(context, call, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
+  let attempts = 0;
+  let delay = 1_000;
+  for (;;) {
+    let result;
+    try {
+      result = await call("cancel_command_run", {
+        run_id: context.run_id,
+        run_credential: context.run_credential,
+        reason: "cancelled_before_workload_start",
+      });
+    } catch (error) { result = { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+    if (result?.ok && !result.isError && result.data?.status === "cancelled") return result;
+    attempts += 1;
+    await writeJson(context.context_path, {
+      ...context,
+      cancellation_handoff: { attempts, last_error: result?.error ?? result?.data?.error ?? "cancellation_handoff_rejected", next_retry_at: new Date(Date.now() + delay).toISOString() },
+    });
+    await sleep(delay);
+    delay = Math.min(delay * 2, 60_000);
+  }
+}
 
 async function writeJson(path, value) {
   await mkdir(dirname(path), { recursive: true });
@@ -222,7 +282,7 @@ async function writeJson(path, value) {
   // file, or a poller) never observes a torn/empty file mid-write. rename(2)
   // is atomic within a directory, so readers see either the old or the new
   // complete JSON, never a partial one.
-  const tmp = `${path}.${process.pid}.tmp`;
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
   await chmod(tmp, 0o600);
   await rename(tmp, path);
@@ -340,7 +400,12 @@ export async function launchRun(argv, {
   }
   const context = contextPath(runId);
   const receipt = receiptPath(runId);
-  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, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
+  // The detached worker has no ambient credential after its launcher exits.
+  // Seal the already-resolved owning session in the private (0600) context so
+  // 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, cwd, timeout_seconds: opts.timeout, receipt_path: receipt, launched_at: new Date().toISOString(), ...(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 });
@@ -351,25 +416,85 @@ export async function launchRun(argv, {
     await effectiveCall("update_command_run", { run_id: runId, run_credential: registration.data.run_credential, status: "owner_lost", invalidated_reason: `launcher_failed:${error instanceof Error ? error.message : String(error)}` });
     return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
   }
-  const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
   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 } };
 }
 
-export async function runWorker(contextFile, { spawnImpl = spawn, call = callToolJson } = {}) {
+export async function runWorker(contextFile, {
+  spawnImpl = spawn,
+  call = callToolJson,
+  signalEmitter = process,
+  terminate = terminateProcessGroup,
+} = {}) {
   const context = JSON.parse(await readFile(contextFile, "utf8"));
+  const callbackCall = callWithContextIdentity(context, call);
+  const ownerHeartbeat = startOwnerHeartbeat(context, callbackCall);
   const startedAt = new Date().toISOString();
   let timedOut = false;
   let child;
+  let cancellationStateWrite = Promise.resolve();
+  let contextWrite = Promise.resolve();
+  const persistWorkerContext = (state) => {
+    const next = contextWrite.then(() => writeJson(context.context_path, {
+      ...context,
+      worker_pid: process.pid,
+      ...state,
+    }));
+    contextWrite = next;
+    return next;
+  };
+  // `cancelRun` creates a durable marker before it acknowledges an unstarted
+  // cancellation. The worker owns its own process group, so SIGTERM is also
+  // the fence for the tiny interval after the final marker check: if spawn won
+  // that interval, the handler terminates the just-created workload instead.
+  const cancellationHandler = () => {
+    void hasCancellationMarker(context.context_path).then(async (marked) => {
+      if (!marked) {
+        // Preserve the old default SIGTERM behaviour for a signal that was not
+        // issued by `cancelRun` for this durable context.
+        signalEmitter.removeListener("SIGTERM", cancellationHandler);
+        process.kill(process.pid, "SIGTERM");
+        return;
+      }
+      if (child) {
+        terminate(child, "SIGTERM");
+        cancellationStateWrite = persistWorkerContext({ workload_pid: child.pid, worker_state: "cancelling_workload" });
+      } else {
+        cancellationStateWrite = persistWorkerContext({ worker_state: "cancelled_before_workload_start" });
+      }
+      await cancellationStateWrite;
+    }).catch(() => { /* the durable marker remains the source of truth for recovery */ });
+  };
+  signalEmitter.once("SIGTERM", cancellationHandler);
   try {
-    child = spawnImpl(context.command[0], context.command.slice(1), { cwd: context.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, ...(context.child_env ? { env: { ...process.env, ...context.child_env } } : {}) });
-  } catch (error) {
-    const endedAt = new Date().toISOString();
-    const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${error instanceof Error ? error.message : String(error)}` }, call);
-    if (context.test_run) await completeTestRun(context, { status: "owner_lost", exitCode: null, signal: null, startedAt, endedAt, call });
-    return receipt;
-  }
+    if (await hasCancellationMarker(context.context_path)) {
+      if (!context.cancellation_handoff?.accepted) await retryCancellationHandoff(context, callbackCall);
+      if (context.test_run) {
+        const endedAt = new Date().toISOString();
+        await completeTestRun(context, { status: "cancelled", exitCode: null, signal: "SIGTERM", startedAt: context.launched_at ?? endedAt, endedAt, call: callbackCall });
+      }
+      return await preWorkloadCancellationReceipt(context);
+    }
+    // Publish worker ownership before the first workload spawn. Cancellation
+    // can now signal this private process group instead of terminalizing the
+    // server run while a local worker still has authority to start work.
+    await persistWorkerContext({ worker_state: "starting" });
+    if (await hasCancellationMarker(context.context_path)) {
+      if (!context.cancellation_handoff?.accepted) await retryCancellationHandoff(context, callbackCall);
+      if (context.test_run) {
+        const endedAt = new Date().toISOString();
+        await completeTestRun(context, { status: "cancelled", exitCode: null, signal: "SIGTERM", startedAt: context.launched_at ?? endedAt, endedAt, call: callbackCall });
+      }
+      return await preWorkloadCancellationReceipt(context);
+    }
+    try {
+      child = spawnImpl(context.command[0], context.command.slice(1), { cwd: context.cwd, detached: true, stdio: ["ignore", "pipe", "pipe"], windowsHide: true, ...(context.child_env ? { env: { ...process.env, ...context.child_env } } : {}) });
+    } catch (error) {
+      const endedAt = new Date().toISOString();
+      const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${error instanceof Error ? error.message : String(error)}` }, callbackCall);
+      return receipt;
+    }
   // A failed spawn can report through the child `error` event on the next turn.
   // Subscribe before any filesystem I/O so a busy parallel test run (or a real
   // fast failure) cannot lose the sole terminal event.
@@ -381,32 +506,57 @@ export async function runWorker(contextFile, { spawnImpl = spawn, call = callToo
   const capture = boundedCapture();
   child.stdout?.on("data", (chunk) => capture.append(chunk));
   child.stderr?.on("data", (chunk) => capture.append(chunk));
-  await writeJson(context.context_path, { ...context, worker_pid: process.pid, workload_pid: child.pid });
+    await persistWorkerContext({ workload_pid: child.pid, worker_state: "running" });
   // BOT-1510: for a test lane, tail the reporter's NDJSON and flush per-case
   // verdicts while the child runs. The test process never touches the network.
-  const lane = context.test_run ? startLaneFlusher(context, call) : null;
+  const lane = context.test_run ? startLaneFlusher(context, callbackCall) : null;
   let killTimer;
   const timer = setTimeout(() => {
     timedOut = true;
-    terminateProcessGroup(child, "SIGTERM");
-    killTimer = setTimeout(() => terminateProcessGroup(child, "SIGKILL"), context.timeout_grace_ms ?? TIMEOUT_GRACE_MS);
+    terminate(child, "SIGTERM");
+    killTimer = setTimeout(() => terminate(child, "SIGKILL"), context.timeout_grace_ms ?? TIMEOUT_GRACE_MS);
   }, context.timeout_seconds * 1000);
-  const result = await completion;
-  clearTimeout(timer);
-  clearTimeout(killTimer);
-  if (lane) await lane.stop();
-  const endedAt = new Date().toISOString();
-  if (result.error) {
-    const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${result.error.message}`, output: capture.output, outputCharacters: capture.characters }, call);
-    if (context.test_run) await completeTestRun(context, { status: "owner_lost", exitCode: null, signal: null, startedAt, endedAt, call });
+    const result = await completion;
+    clearTimeout(timer);
+    clearTimeout(killTimer);
+    await cancellationStateWrite;
+    if (lane) await lane.stop();
+    const endedAt = new Date().toISOString();
+    if (result.error) {
+      const receipt = await finalize(context, { status: "owner_lost", startedAt, endedAt, exitCode: null, signal: null, reason: `workload_spawn_failed:${result.error.message}`, output: capture.output, outputCharacters: capture.characters }, callbackCall);
+      return receipt;
+    }
+    const status = terminalStatus({ ...result, timedOut });
+    const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, callbackCall);
     return receipt;
+  } finally {
+    if (ownerHeartbeat) await ownerHeartbeat.stop();
+    signalEmitter.removeListener("SIGTERM", cancellationHandler);
   }
-  const status = terminalStatus({ ...result, timedOut });
-  const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, call);
-  // AC-4/AC-5: complete the run (final flush → update_test_run status:completed →
-  // emit_test_run_signal fires → the armed `test-run:` wait wakes).
-  if (context.test_run) await completeTestRun(context, { status, exitCode: result.exitCode, signal: result.signal, startedAt, endedAt, call });
-  return receipt;
+}
+
+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.
+  if (typeof context.callback_session_token !== "string" || !context.callback_session_token) return null;
+  // A token-only launch intentionally omits its public session id. The server
+  // derives the exact active session from the sealed bearer, so it must still
+  // heartbeat rather than waiting for the eight-hour token window to lapse.
+  // Supplying an id when one was sealed retains the same explicit scope fence.
+  const heartbeatArgs = typeof context.callback_session_id === "string" && context.callback_session_id
+    ? { session_id: context.callback_session_id } : {};
+  let stopped = false;
+  let chain = Promise.resolve();
+  const tick = () => {
+    chain = chain.then(async () => {
+      if (stopped) return;
+      try { await call("heartbeat", heartbeatArgs); } catch { /* terminal delivery retains its own retry path */ }
+    });
+  };
+  tick();
+  const timer = setIntervalFn(tick, intervalMs);
+  timer.unref?.();
+  return { async stop() { stopped = true; clearInterval(timer); await chain; } };
 }
 
 // Periodic lane flusher: reduce the NDJSON events file to the current case state
@@ -496,6 +646,30 @@ function terminateProcessGroup(child, signal) {
   try { child.kill?.(signal); } catch { /* already exited */ }
 }
 
+function workerProcessGroupAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0 || process.platform === "win32") return false;
+  try { process.kill(-pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; }
+}
+
+async function waitForWorkerCancellation(contextFile, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), attempts = 25 } = {}) {
+  let latest = null;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try { latest = JSON.parse(await readFile(contextFile, "utf8")); } catch { /* the context is atomically replaced */ }
+    if (Number.isInteger(latest?.workload_pid) || latest?.worker_state === "cancelled_before_workload_start") return latest;
+    await sleep(20);
+  }
+  return latest;
+}
+
+async function sealedTerminalStatus(context) {
+  if (typeof context.terminal_update?.status === "string") return context.terminal_update.status;
+  if (!context.receipt_path) return null;
+  try {
+    const receipt = JSON.parse(await readFile(context.receipt_path, "utf8"));
+    return receipt?.run_id === context.run_id && typeof receipt.status === "string" ? receipt.status : null;
+  } catch { return null; }
+}
+
 function forwardTerminationSignals(child, signalEmitter) {
   let signal = null;
   let escalation = null;
@@ -525,15 +699,87 @@ function waitForChild(child) {
   });
 }
 
-export async function cancelRun(runId, { call = callToolJson } = {}) {
+export async function cancelRun(runId, {
+  call = callToolJson,
+  waitForCancellation = waitForWorkerCancellation,
+  killWorker = (pid) => process.kill(-pid, "SIGTERM"),
+  workerAlive = workerProcessGroupAlive,
+} = {}) {
   const context = JSON.parse(await readFile(contextPath(runId), "utf8"));
+  const callbackCall = callWithContextIdentity(context, call);
+  const sealedStatus = await sealedTerminalStatus(context);
+  if (sealedStatus) {
+    return { exitCode: EXIT.OK, receipt: {
+      schema_version: RUN_SCHEMA_VERSION,
+      outcome: "terminal_delivery_pending",
+      run_id: runId,
+      terminal_status: sealedStatus,
+      exit_code: EXIT.OK,
+    } };
+  }
+  const requestCancellation = async () => {
+    // No worker remains to publish the linked test-run terminal event. Complete
+    // it before revoking the one-run credential so an armed `test-run:` wait
+    // cannot be stranded active after the command cancellation is accepted.
+    if (context.test_run) {
+      const endedAt = new Date().toISOString();
+      await completeTestRun(context, {
+        status: "cancelled",
+        exitCode: null,
+        signal: "SIGTERM",
+        startedAt: context.launched_at ?? endedAt,
+        endedAt,
+        call: callbackCall,
+      });
+    }
+    let cancellation;
+    try {
+      cancellation = await callbackCall("cancel_command_run", {
+        run_id: context.run_id,
+        run_credential: context.run_credential,
+        reason: "cancelled_before_workload_start",
+      });
+    } catch (error) {
+      cancellation = { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (cancellation?.ok && !cancellation.isError && cancellation.data?.status === "cancelled") {
+      await writeJson(context.context_path ?? contextPath(runId), { ...context, cancellation_handoff: { accepted: true, accepted_at: new Date().toISOString() } });
+      return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
+    }
+    return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: cancellation?.error ?? cancellation?.data?.error ?? "cancellation_handoff_failed", exit_code: EXIT.BACKEND } };
+  };
   if (!Number.isInteger(context.workload_pid) || context.workload_pid <= 0) {
-    return { exitCode: EXIT.INVALID, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: "durable owner has not started a workload", exit_code: EXIT.INVALID } };
+    // The marker is durable and checked twice by the worker. It must exist
+    // before the terminal API transition so a launcher-returned worker cannot
+    // begin executing after cancellation has been acknowledged.
+    const contextFile = context.context_path ?? contextPath(runId);
+    try {
+      await markCancellation(contextFile, context.run_id);
+    } catch (error) {
+      return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: `cancellation_fence_failed:${error instanceof Error ? error.message : String(error)}`, exit_code: EXIT.INTERNAL } };
+    }
+    if (Number.isInteger(context.worker_pid) && context.worker_pid > 0) {
+      // A live worker may have claimed the interval after launcher handoff.
+      // Fence it first; its SIGTERM handler either records a no-workload
+      // acknowledgement (safe for cancel_command_run) or terminates the
+      // workload and keeps ownership of the final update_command_run callback.
+      try { killWorker(context.worker_pid); } catch (error) {
+        if (error?.code !== "ESRCH") return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: `cancellation_worker_fence_failed:${error instanceof Error ? error.message : String(error)}`, exit_code: EXIT.INTERNAL } };
+      }
+      const fenced = await waitForCancellation(contextFile);
+      if (Number.isInteger(fenced?.workload_pid) && fenced.workload_pid > 0) {
+        terminateProcessGroup({ pid: fenced.workload_pid }, "SIGTERM");
+        return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
+      }
+      if (fenced?.worker_state === "cancelled_before_workload_start" || !workerAlive(context.worker_pid)) return requestCancellation();
+      return { exitCode: EXIT.BACKEND, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "rejected", run_id: runId, error: "cancellation_worker_fence_unconfirmed", exit_code: EXIT.BACKEND } };
+    }
+    return requestCancellation();
   }
   try {
     process.kill(-context.workload_pid, "SIGTERM");
   } catch (error) {
-    await call("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "owner_lost", invalidated_reason: `cancel_owner_unreachable:${error instanceof Error ? error.message : String(error)}` });
+    await callbackCall("update_command_run", { run_id: context.run_id, run_credential: context.run_credential, status: "owner_lost", invalidated_reason: `cancel_owner_unreachable:${error instanceof Error ? error.message : String(error)}` });
     return { exitCode: EXIT.INTERNAL, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "owner_lost", run_id: runId, exit_code: EXIT.INTERNAL } };
   }
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
@@ -548,11 +794,28 @@ async function finalize(context, state, call) {
   const sha256 = createHash("sha256").update(await readFile(context.receipt_path)).digest("hex");
   const apiStatus = ({ success: "succeeded", failure: "failed", cancelled: "cancelled", timed_out: "timed_out", owner_lost: "owner_lost" })[state.status];
   const update = { run_id: context.run_id, run_credential: context.run_credential, status: apiStatus, exit_code: state.exitCode ?? undefined, invalidated_reason: state.reason ?? (state.status === "timed_out" ? "timeout" : state.status === "owner_lost" ? "owner_lost" : undefined), receipt_path: context.receipt_upload, receipt_content_type: "application/json", receipt_byte_size: bytes.size, receipt_sha256: sha256, output_characters: outputCharacters, truncated: outputCharacters > MAX_CAPTURE_BYTES };
+  // A locally durable receipt is enough to publish the linked test run. Do it
+  // before the command callback's intentionally unbounded retry: otherwise an
+  // auth outage (for example agent_identity_required) strands a 0-case run in
+  // active state forever even though its command has already failed locally.
+  if (context.test_run) await completeTestRun(context, { status: state.status, exitCode: state.exitCode, signal: state.signal, startedAt: state.startedAt, endedAt: state.endedAt, call });
   await retryTerminalUpdate(context, update, call);
   try { await unlink(context.context_path); } catch { /* receipt is authoritative; context cleanup is best effort */ }
   return receipt;
 }
 
+function callWithContextIdentity(context, call) {
+  const token = typeof context.callback_session_token === "string" && SESSION_TOKEN_RE.test(context.callback_session_token)
+    ? context.callback_session_token
+    : null;
+  // Old contexts cannot safely fall back to the machine-level owner key. Ask
+  // the API layer to require a session instead; the retained receipt/context
+  // makes recovery possible without attributing a callback to the wrong agent.
+  return (name, args) => call(name, args, token
+    ? { auth: { "x-agent-api-key": token } }
+    : { requireSessionToken: true });
+}
+
 export async function retryTerminalUpdate(context, update, call, { sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {}) {
   let attempts = 0;
   let delay = 1_000;

package/src/wait-core.mjs

@@ -676,9 +676,12 @@ export function parseSseFrames(buffer) {
 }
 
 // ---------------------------------------------------------------------------
-// Cursor — the spine `seq` is a non-negative integer; reject garbage loudly.
+// Cursor — replay uses JavaScript Numbers at the relay boundary, so only exact
+// non-negative safe integers can be replayed without changing the requested floor.
 // ---------------------------------------------------------------------------
 
+const MAX_SAFE_SIGNAL_SEQUENCE = BigInt(Number.MAX_SAFE_INTEGER);
+
 /**
  * @param {string|null|undefined} raw
  * @returns {{kind: "absent"} | {kind: "ok", value: string} | {kind: "invalid", raw: string}}
@@ -688,7 +691,9 @@ export function normalizeSince(raw) {
   const t = String(raw).trim();
   if (t === "") return { kind: "absent" };
   if (!/^\d+$/.test(t)) return { kind: "invalid", raw };
-  return { kind: "ok", value: String(BigInt(t)) };
+  const value = BigInt(t);
+  if (value > MAX_SAFE_SIGNAL_SEQUENCE) return { kind: "invalid", raw };
+  return { kind: "ok", value: String(value) };
 }
 
 // ---------------------------------------------------------------------------

package/src/wait.mjs

@@ -153,7 +153,7 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
 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)
+  --since <seq>         resume from a prior receipt's next_cursor (0..9007199254740991; replay what you missed)
   --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)
@@ -216,6 +216,7 @@ function parseArgv(argv) {
     mode: "any",
     timeout: 7200,
     since: null,
+    sinceProvided: false,
     receiptMaxBytes: 10240,
     heartbeat: false,
     url: process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1",
@@ -248,7 +249,7 @@ function parseArgv(argv) {
     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 === "--since") { opts.sinceProvided = true; opts.since = optionValue(); }
     else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
     else if (a === "--url") opts.url = optionValue();
     // BOT-1574: --token and --profile are RETIRED. A wait authenticates from
@@ -1572,6 +1573,19 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     process.exit(EXIT.INVALID);
   }
 
+  // BOT-2453: an explicit replay cursor is a request to replay, never permission
+  // to silently fall back to live-only. Validate it before creating a recoverable
+  // checkpoint, resolving credentials, registering a wait, or opening SSE.
+  if (opts.sinceProvided) {
+    const since = normalizeSince(opts.since);
+    if (since.kind !== "ok") {
+      process.stderr.write("bb-wait: --since must be a non-negative signal sequence <= 9007199254740991\n");
+      emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_since", cursor: opts.since });
+      process.exit(EXIT.INVALID);
+    }
+    opts.since = since.value;
+  }
+
   const { conditions, errors } = parseConditions(opts.conditions);
   if (errors.length > 0) {
     for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);