@botbuddy/cli 1.59.8 → 1.59.10

package/bin/botbuddy.mjs

@@ -1,7 +1,16 @@
 #!/usr/bin/env node
 import { run } from "../src/commands.mjs";
+import { ensureRunDelivery } from "../src/run-delivery.mjs";
 
-run(process.argv.slice(2)).then((code) => {
+const argv = process.argv.slice(2);
+
+// BOT-2600: any `bb` invocation starts the single per-machine delivery process
+// when finished `bb run` commands still have an unsent terminal update. A stat
+// and two small reads when nothing changed; it never fails the command.
+const deliveryProcessArgs = argv[0] === "run" && (argv[1] === "--worker" || argv[1] === "--deliver");
+const delivery = deliveryProcessArgs ? Promise.resolve() : ensureRunDelivery().catch(() => {});
+
+delivery.then(() => run(argv)).then((code) => {
   if (typeof code === "number") process.exitCode = code;
 }).catch((err) => {
   console.error(`\x1b[31m✗\x1b[0m ${err?.message || err}`);

package/daemon-release/darwin-arm64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.59.8",
-  "source_commit": "d72599a3ac43155a4d66e30b2d73e5f2a46cf956",
-  "source_sha256": "5ccca5bc66c82f02e856a25c0cedf9056f69b3e72b95a668dc62a3dff4a0f72f",
+  "release_version": "1.59.10",
+  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
+  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
   "target": "darwin-arm64",
-  "sha256": "24810c0fd70f40e77d860b0c247f1a7112a6a2a09b8754c83c7ca50b023e38c1"
+  "sha256": "8c41e97c983e235c710b8624849998f0e231cdab27d7147499e5ba6e4e7e5abb"
 }

package/daemon-release/linux-x64.json

@@ -1,7 +1,7 @@
 {
-  "release_version": "1.59.8",
-  "source_commit": "d72599a3ac43155a4d66e30b2d73e5f2a46cf956",
-  "source_sha256": "5ccca5bc66c82f02e856a25c0cedf9056f69b3e72b95a668dc62a3dff4a0f72f",
+  "release_version": "1.59.10",
+  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
+  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
   "target": "linux-x64",
-  "sha256": "61b9f79104394a9fe11e43b25cf3aa3c84dc1538f44c4439b7ed0555b8e8b858"
+  "sha256": "92a173432e8a40e2ed5d91cd2a93a5fd0cfcd23c63b56ecec42d53127e272b7a"
 }

package/daemon-release/manifest.json

@@ -1,21 +1,21 @@
 {
   "schema_version": 1,
-  "release_version": "1.59.8",
-  "source_commit": "d72599a3ac43155a4d66e30b2d73e5f2a46cf956",
-  "source_sha256": "5ccca5bc66c82f02e856a25c0cedf9056f69b3e72b95a668dc62a3dff4a0f72f",
+  "release_version": "1.59.10",
+  "source_commit": "0a69b9e8cf14b345f8cc9e23e8ed68a8f240147c",
+  "source_sha256": "126242299e994c1e88bf377dbc0046672b5cdfe3c1454657f06abb64275b0301",
   "targets": {
     "darwin-arm64": {
       "goos": "darwin",
       "goarch": "arm64",
       "binary": "daemon/bin/darwin-arm64/botbuddy-daemon",
-      "sha256": "24810c0fd70f40e77d860b0c247f1a7112a6a2a09b8754c83c7ca50b023e38c1",
+      "sha256": "8c41e97c983e235c710b8624849998f0e231cdab27d7147499e5ba6e4e7e5abb",
       "mode": "0755"
     },
     "linux-x64": {
       "goos": "linux",
       "goarch": "amd64",
       "binary": "daemon/bin/linux-x64/botbuddy-daemon",
-      "sha256": "61b9f79104394a9fe11e43b25cf3aa3c84dc1538f44c4439b7ed0555b8e8b858",
+      "sha256": "92a173432e8a40e2ed5d91cd2a93a5fd0cfcd23c63b56ecec42d53127e272b7a",
       "mode": "0755"
     }
   }

package/package.json

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

package/src/api.mjs

@@ -385,9 +385,9 @@ export const SESSION_TOKEN_DENIED_TOOLS = new Set([
 // call to a specific tenant by appending ?tenant=<slug> to the endpoint (the
 // same mechanism as the documented BOTBUDDY_SERVER_URL override), letting the
 // server resolve/confirm exactly that tenant.
-function toolEndpoint(tenant) {
-  if (!tenant) return SERVER_URL;
-  const url = new URL(SERVER_URL);
+function toolEndpoint(tenant, base = SERVER_URL) {
+  if (!tenant) return base;
+  const url = new URL(base);
   url.searchParams.set("tenant", tenant);
   return url.toString();
 }
@@ -457,6 +457,9 @@ export async function registerContainerHost(body, {
 export async function callToolJson(toolName, args = {}, {
   fetchImpl = fetch, signal, auth: pinnedAuth = null, tenant = null, resolvePin = resolveDefaultTenantPin,
   requireSessionToken = false, resolveAuth = resolveCallAuth,
+  // BOT-2600: a delivery for a sealed run goes to the endpoint the run was
+  // registered with, not this process's ambient one.
+  serverUrl = SERVER_URL,
 } = {}) {
   let auth = pinnedAuth;
   let sessionTokenSelected = false;
@@ -481,7 +484,7 @@ export async function callToolJson(toolName, args = {}, {
   const body = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: toolName, arguments: args } };
   let res;
   try {
-    res = await fetchImpl(toolEndpoint(pin), {
+    res = await fetchImpl(toolEndpoint(pin, serverUrl), {
       method: "POST",
       headers: { "Content-Type": "application/json", ...auth },
       body: JSON.stringify(body),

package/src/config.mjs

@@ -9,8 +9,8 @@ const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 // BOT-876: overridable so the CLI can be pointed at a local Supabase stack
 // (`BOTBUDDY_SERVER_URL=http://127.0.0.1:56321/functions/v1/mcp-server`).
 // Production is the default; nothing changes for normal use.
-export const SERVER_URL = process.env.BOTBUDDY_SERVER_URL
-  || "https://api.bot-buddy.ai/functions/v1/mcp-server";
+export const DEFAULT_SERVER_URL = "https://api.bot-buddy.ai/functions/v1/mcp-server";
+export const SERVER_URL = process.env.BOTBUDDY_SERVER_URL || DEFAULT_SERVER_URL;
 
 let config = {};
 

package/src/fixtures/bot-2600-update-command-run-rejections-2026-10-20.json

@@ -0,0 +1,13 @@
+{
+  "source": "production MCP (api.bot-buddy.ai) via cli/src/api.mjs callToolJson, CLI worktree of BOT-2600",
+  "captured_at": "2026-10-20T19:15:53.070Z",
+  "note": "update_command_run for a random run id. Both requests are refused before any write; no credential value is recorded.",
+  "invalid_run_credential": {
+    "request": "x-agent-api-key: the caller's live session token; run_credential: 64 random hex",
+    "result": { "ok": true, "data": { "error": "run_credential_invalid" }, "isError": true }
+  },
+  "unknown_session_token": {
+    "request": "x-agent-api-key: bb_sess_ + 64 zeros",
+    "result": { "ok": false, "auth": true, "status": 401, "error": "unauthorized", "error_code": "session_token_revoked" }
+  }
+}

package/src/run-delivery.mjs

@@ -0,0 +1,496 @@
+// BOT-2600 — bounded terminal delivery for durable `bb run` commands.
+//
+// A detached `bb run` worker owns its workload and writes exactly one receipt.
+// Once that receipt is durable, publishing it (update_command_run) is only a
+// delivery problem, and it must not keep a resident Node process per run alive:
+// on 2026-10-20 one Mac had 142 finished workers (6 GB) retrying rejections
+// that could never succeed. So:
+//
+//   - the worker retries transient failures within a bounded monotonic budget
+//     and parks permanent rejections immediately, recording
+//     `terminal_update.parked` in its private context, then exits;
+//   - a single per-machine delivery process (`bb run --deliver`, guarded by a
+//     PID lock under ~/.botbuddy/) retries what is still retryable and exits
+//     when nothing retryable remains. Any `bb` invocation starts it on demand;
+//   - workers left by older CLI versions (which retry forever) are adopted:
+//     their delivery is taken over and the worker is stopped only when it is
+//     provably finished (exact command line, same user, terminal receipt, no
+//     child processes, already in its terminal retry loop).
+//
+// The receipt and context files stay authoritative; nothing is deleted except a
+// context whose delivery was accepted (exactly what the worker always did).
+// The identity model is unchanged (BOT-2052): a delivery is only ever sent with
+// the session token sealed for the run's owner, never an ambient credential.
+
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, link, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { execFile, spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
+import { AGENT_KEY_RE } from "./agent-key.mjs";
+import { DEFAULT_SERVER_URL } from "./config.mjs";
+
+/** The worker's own retry budget for transient failures (AC-1: ≤ 10 minutes). */
+export const TERMINAL_RETRY_BUDGET_MS = 10 * 60_000;
+/** One update_command_run attempt never waits longer than this. */
+export const DELIVERY_CALL_TIMEOUT_MS = 30_000;
+/** Transient attempts the delivery process makes before parking for good. */
+export const DELIVERY_MAX_ATTEMPTS = 50;
+/** The delivery process exits after this long even with retryable work left. */
+export const DELIVERY_LIFETIME_MS = 30 * 60_000;
+/** A non-forced `bb` invocation re-scans at most this often. */
+export const DELIVERY_RESCAN_COOLDOWN_MS = 60_000;
+const DELIVERY_FIRST_BACKOFF_MS = 30_000;
+const DELIVERY_MAX_BACKOFF_MS = 5 * 60_000;
+const STOP_GRACE_MS = 3_000;
+
+export const TERMINAL_RECEIPT_STATUSES = new Set(["success", "failure", "cancelled", "timed_out", "owner_lost"]);
+const API_STATUS = { success: "succeeded", failure: "failed", cancelled: "cancelled", timed_out: "timed_out", owner_lost: "owner_lost" };
+const MAX_CAPTURE_BYTES = 8_192;
+// The update_command_run arguments a persisted terminal_update may carry.
+const UPDATE_FIELDS = ["run_id", "run_credential", "status", "exit_code", "invalidated_reason", "receipt_path", "receipt_content_type", "receipt_byte_size", "receipt_sha256", "output_characters", "truncated"];
+
+// Never retried: decided locally without a request reaching the server (no
+// usable session token), or a definitive server state (a different terminal
+// status is already recorded; the payload itself is refused).
+const PERMANENT_ERRORS = new Set([
+  "session_token_required", "session_token_malformed", "not_authenticated", "token_expired",
+  "command_terminal_immutable", "artifact_required",
+]);
+// Trust boundary for server rejections. The server can answer with an auth or
+// credential rejection when its own lookup failed transiently (it discards the
+// read error: BOT-2611), so none of these is proof that a retry cannot
+// succeed. The worker parks every one at once and exits (it never spends its
+// retry budget on them), and the delivery process gives each a few spaced
+// attempts before parking it for good, so a recovered server recovers the
+// terminal result while a dead credential costs at most a handful of calls.
+const AMBIGUOUS_ERRORS = new Set([
+  "agent_identity_required", "authentication_required", "unauthorized", "run_credential_invalid",
+  "session_token_revoked", "credential_unknown",
+]);
+/** Delivery-process attempts for an ambiguous rejection before parking for good. */
+export const DELIVERY_AMBIGUOUS_MAX_ATTEMPTS = 5;
+const LOCAL_ENVIRONMENT_RE =/uv_os_get_passwd|\bENOENT\b|\bEACCES\b|\bEPERM\b/;
+
+export function commandRunsDir(home = homedir()) { return join(home, ".botbuddy", "command-runs"); }
+export function deliveryLockPath(home = homedir()) { return join(home, ".botbuddy", "run-delivery.lock"); }
+export function deliveryStatePath(home = homedir()) { return join(home, ".botbuddy", "run-delivery.json"); }
+
+function errorText(result) {
+  const value = result?.data?.error ?? result?.error ?? result?.code ?? null;
+  return typeof value === "string" && value ? value : "terminal_update_rejected";
+}
+
+export function terminalUpdateAccepted(result) {
+  return Boolean(result?.ok && !result.isError && result.data?.error == null && result.data?.accepted !== false);
+}
+
+/**
+ * Classify a failed update_command_run attempt.
+ * `parkNow` marks a retryable failure the worker must not spend its own
+ * budget on: it parks at once and only the delivery process retries it.
+ * @returns {{ reason: string, retryable: boolean, kind: string, parkNow?: boolean }}
+ */
+export function classifyTerminalUpdateFailure(result, thrown = null) {
+  if (thrown) {
+    const message = thrown instanceof Error ? thrown.message : String(thrown);
+    if (thrown?.code === "ERR_SYSTEM_ERROR" || LOCAL_ENVIRONMENT_RE.test(message)) {
+      return { reason: message, retryable: false, kind: "local_environment" };
+    }
+    return { reason: message, retryable: true, kind: "transient" };
+  }
+  const reason = errorText(result);
+  const codes = [result?.data?.error, result?.error, result?.code, result?.error_code].filter((v) => typeof v === "string");
+  if (codes.some((code) => PERMANENT_ERRORS.has(code))) return { reason, retryable: false, kind: "permanent_rejection" };
+  if (result?.auth === true || codes.some((code) => AMBIGUOUS_ERRORS.has(code))) return { reason, retryable: true, kind: "ambiguous_rejection", parkNow: true };
+  if (codes.some((code) => code.startsWith("usage:"))) return { reason, retryable: false, kind: "local_environment" };
+  // Transport failures, timeouts, 5xx/429 and anything unrecognised stay
+  // retryable; the budget (worker) or attempt cap (delivery process) bounds them.
+  return { reason, retryable: true, kind: "transient" };
+}
+
+/** The sealed owner's identity, never an ambient or machine-level credential. */
+export function callWithContextIdentity(context, call) {
+  const token = sealedToken(context);
+  // 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, extra = {}) => call(name, args, token
+    ? { ...extra, auth: { "x-agent-api-key": token } }
+    : { ...extra, requireSessionToken: true });
+}
+
+function sealedToken(context) {
+  return typeof context?.callback_session_token === "string" && AGENT_KEY_RE.test(context.callback_session_token)
+    ? context.callback_session_token : null;
+}
+
+export async function writeJsonAtomic(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  // Write-then-rename so a concurrent reader never observes a torn file.
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(tmp, JSON.stringify(value), { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+}
+
+function withTimeout(extra = {}) {
+  return { ...extra, signal: AbortSignal.timeout(DELIVERY_CALL_TIMEOUT_MS) };
+}
+
+/**
+ * The endpoint a run was registered with. A sealed token is only ever sent
+ * back there, whatever endpoint the delivery process itself was started with.
+ * Contexts written before BOT-2600 did not record it; the CLI's default
+ * (production) endpoint is the only one a context without an override could
+ * have been registered with by default, so it is used for those.
+ */
+export function contextServerUrl(context) {
+  return typeof context?.server_url === "string" && /^https?:\/\//.test(context.server_url) ? context.server_url : DEFAULT_SERVER_URL;
+}
+
+/** One update_command_run attempt with the sealed identity and a bounded wait. */
+export async function attemptTerminalUpdate(context, update, call) {
+  const identified = callWithContextIdentity(context, call);
+  try {
+    const result = await identified("update_command_run", update, withTimeout({ serverUrl: contextServerUrl(context) }));
+    if (terminalUpdateAccepted(result)) return { accepted: true, result };
+    return { accepted: false, result, failure: classifyTerminalUpdateFailure(result) };
+  } catch (error) {
+    return { accepted: false, result: null, failure: classifyTerminalUpdateFailure(null, error) };
+  }
+}
+
+export function parkedRecord(failure, by) {
+  return { reason: failure.reason, retryable: failure.retryable, kind: failure.kind, by, parked_at: new Date().toISOString() };
+}
+
+/** Rebuild the terminal update from a durable receipt (a worker that crashed first). */
+export async function terminalUpdateFromReceipt(context, receipt) {
+  const bytes = await readFile(context.receipt_path);
+  const outputCharacters = Number.isInteger(receipt.output_characters) ? receipt.output_characters : 0;
+  const reason = receipt.reason ?? (receipt.status === "timed_out" ? "timeout" : receipt.status === "owner_lost" ? "owner_lost" : undefined);
+  return {
+    run_id: context.run_id, run_credential: context.run_credential, status: API_STATUS[receipt.status],
+    exit_code: receipt.exit_code ?? undefined, invalidated_reason: reason ?? undefined,
+    receipt_path: context.receipt_upload, receipt_content_type: "application/json",
+    receipt_byte_size: bytes.length, receipt_sha256: createHash("sha256").update(bytes).digest("hex"),
+    output_characters: outputCharacters, truncated: outputCharacters > MAX_CAPTURE_BYTES,
+  };
+}
+
+function updateFromPersisted(terminalUpdate) {
+  const update = {};
+  for (const key of UPDATE_FIELDS) if (terminalUpdate[key] !== undefined) update[key] = terminalUpdate[key];
+  return update;
+}
+
+// ── processes ────────────────────────────────────────────────────────────────
+
+export function parseProcessList(text) {
+  const rows = [];
+  for (const line of String(text).split("\n")) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s(.*)$/.exec(line);
+    if (match) rows.push({ pid: Number(match[1]), ppid: Number(match[2]), uid: Number(match[3]), args: match[4].trim() });
+  }
+  return rows;
+}
+
+export function listProcessesWithPs() {
+  return new Promise((resolve, reject) => {
+    execFile("ps", ["-ww", "-A", "-o", "pid=,ppid=,uid=,args="], { maxBuffer: 32 * 1024 * 1024 }, (error, stdout) => {
+      if (error) reject(error); else resolve(parseProcessList(stdout));
+    });
+  });
+}
+
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+// Every process whose argument string names this context as its worker.
+function workersFor(processes, contextFile) {
+  const suffix = ` run --worker ${contextFile}`;
+  return processes.filter((proc) => proc.args.endsWith(suffix) || proc.args.includes(`${suffix} `));
+}
+
+// AC-4: exactly `<node> <…>botbuddy.mjs run --worker <this context>`, owned by
+// this user, and with no child process. The receipt/terminal checks are the
+// caller's, made on the same context read.
+export function isStoppableLegacyWorker(proc, { contextFile, uid, processes }) {
+  const suffix = ` run --worker ${contextFile}`;
+  if (!proc.args.endsWith(suffix)) return false;
+  if (!/^\S+\s+\S*botbuddy\.mjs$/.test(proc.args.slice(0, -suffix.length))) return false;
+  if (proc.uid !== uid) return false;
+  return !processes.some((other) => other.ppid === proc.pid);
+}
+
+async function stopLegacyWorker(pid, { contextFile, uid, listProcesses, killProcess, isAlive, sleep }) {
+  // Re-verify on a fresh listing right before signalling (PID reuse, a new child).
+  const fresh = await listProcesses();
+  const proc = fresh.find((candidate) => candidate.pid === pid);
+  if (!proc || !isStoppableLegacyWorker(proc, { contextFile, uid, processes: fresh })) return !proc;
+  killProcess(pid, "SIGTERM");
+  for (let waited = 0; waited < STOP_GRACE_MS; waited += 100) {
+    if (!isAlive(pid)) return true;
+    await sleep(100);
+  }
+  return !isAlive(pid);
+}
+
+// ── one drain pass ────────────────────────────────────────────────────────────
+
+/**
+ * Deliver every pending terminal update once.
+ * @returns {Promise<{ delivered: number, parked: number, pending: number, stopped: number, owned: number, wrote: boolean }>}
+ */
+export async function drainOnce({
+  home = homedir(), call, listProcesses = listProcessesWithPs, killProcess = (pid, signal) => process.kill(pid, signal),
+  isAlive = pidAlive, uid = process.getuid?.() ?? -1, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  listContexts = async () => (await readdir(commandRunsDir(home)).catch((error) => { if (error?.code === "ENOENT") return []; throw error; }))
+    .filter((name) => name.endsWith(".context.json")).sort(),
+  maxAttempts = DELIVERY_MAX_ATTEMPTS,
+} = {}) {
+  const totals = { delivered: 0, parked: 0, pending: 0, stopped: 0, owned: 0, wrote: false };
+  const names = await listContexts();
+  if (!names.length) return totals;
+  let processes = null;
+  for (const name of names) {
+    const contextFile = join(commandRunsDir(home), name);
+    const context = await readJson(contextFile);
+    // Deleted by a successful delivery mid-scan, or unreadable: not ours.
+    if (!context || typeof context.run_id !== "string" || typeof context.receipt_path !== "string") continue;
+    // A pre-workload cancellation is owned by the cancel handoff path. A
+    // marker written by a cancel that raced workload start leaves the worker
+    // owning a normal terminal update, which stays eligible here.
+    if (!context.terminal_update && await readFile(`${contextFile}.cancelled`).then(() => true, () => false)) continue;
+    const receipt = await readJson(context.receipt_path);
+    // Still executing (no terminal receipt yet): never touched.
+    if (!receipt || receipt.run_id !== context.run_id || !TERMINAL_RECEIPT_STATUSES.has(receipt.status)) continue;
+    const persisted = context.terminal_update ?? null;
+    if (persisted?.parked && persisted.parked.retryable === false) continue;
+    processes ??= await listProcesses();
+    const workers = workersFor(processes, contextFile).filter((proc) => isAlive(proc.pid));
+    if (workers.length && !persisted?.parked) {
+      // A bounded (current) worker owns its delivery until it parks it. A
+      // legacy worker is adopted only once it is provably in its terminal
+      // retry loop and stopping it cannot touch running work.
+      const legacyLoop = persisted && persisted.retry_budget_ms === undefined;
+      const stoppable = legacyLoop && workers.every((proc) => isStoppableLegacyWorker(proc, { contextFile, uid, processes }));
+      if (!stoppable) { totals.owned += 1; continue; }
+      let allStopped = true;
+      for (const proc of workers) {
+        if (await stopLegacyWorker(proc.pid, { contextFile, uid, listProcesses, killProcess, isAlive, sleep })) totals.stopped += 1;
+        else allStopped = false;
+      }
+      processes = null;
+      if (!allStopped) { totals.owned += 1; continue; }
+    }
+    // Re-read: a stopped legacy worker may have rewritten the context last.
+    const current = await readJson(contextFile);
+    if (!current) continue;
+    const update = current.terminal_update ? updateFromPersisted(current.terminal_update) : await terminalUpdateFromReceipt(current, receipt);
+    const previous = current.terminal_update ?? {};
+    const attempts = (Number.isInteger(previous.attempts) ? previous.attempts : 0) + 1;
+    const deliveryAttempts = (Number.isInteger(previous.delivery_attempts) ? previous.delivery_attempts : 0) + 1;
+    if (!sealedToken(current)) {
+      // No sealed owner: a delivery from this process could only use an
+      // ambient identity, which BOT-2052 forbids. Park it visibly instead.
+      const failure = { reason: "callback_session_token_missing", retryable: false, kind: "callback_session_token_missing" };
+      await writeJsonAtomic(contextFile, { ...current, terminal_update: { ...previous, ...update, parked: parkedRecord(failure, "delivery") } });
+      totals.parked += 1; totals.wrote = true;
+      continue;
+    }
+    const outcome = await attemptTerminalUpdate(current, update, call);
+    if (outcome.accepted) {
+      try { await unlink(contextFile); } catch { /* already removed */ }
+      totals.delivered += 1; totals.wrote = true;
+      continue;
+    }
+    let failure = outcome.failure;
+    const cap = failure.kind === "ambiguous_rejection" ? Math.min(maxAttempts, DELIVERY_AMBIGUOUS_MAX_ATTEMPTS) : maxAttempts;
+    if (failure.retryable && deliveryAttempts >= cap) failure = { ...failure, retryable: false, kind: "delivery_attempts_exhausted" };
+    await writeJsonAtomic(contextFile, { ...current, terminal_update: {
+      ...previous, ...update, attempts, delivery_attempts: deliveryAttempts, last_error: failure.reason,
+      parked: failure.retryable ? { ...(previous.parked ?? parkedRecord(failure, "delivery")), reason: failure.reason, retryable: true } : parkedRecord(failure, "delivery"),
+    } });
+    totals.wrote = true;
+    if (failure.retryable) totals.pending += 1; else totals.parked += 1;
+  }
+  return totals;
+}
+
+// ── the per-machine lock ──────────────────────────────────────────────────────
+
+/**
+ * Take the per-machine delivery lock. A lock whose holder PID is gone is stale
+ * and is taken over.
+ */
+export async function acquireDeliveryLock({ home = homedir(), pid = process.pid, isAlive = pidAlive } = {}) {
+  const lockFile = deliveryLockPath(home);
+  await mkdir(dirname(lockFile), { recursive: true });
+  const candidate = `${lockFile}.${pid}.${randomUUID()}.tmp`;
+  await writeFile(candidate, JSON.stringify({ pid, started_at: new Date().toISOString() }), { mode: 0o600 });
+  try {
+    for (let round = 0; round < 3; round++) {
+      try {
+        await link(candidate, lockFile); // atomic create-if-absent
+        return { acquired: true, holderPid: pid, release: async () => {
+          const holder = await readJson(lockFile);
+          if (holder?.pid === pid) await unlink(lockFile).catch(() => {});
+        } };
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+      }
+      const holder = await readJson(lockFile);
+      if (holder === null) continue; // released between link and read
+      const holderPid = holder?.pid;
+      if (Number.isInteger(holderPid) && isAlive(holderPid)) return { acquired: false, holderPid, release: async () => {} };
+      // Stale. Only the holder of the reclaim mutex may remove the lock file,
+      // so it can never move aside a lock another contender just acquired:
+      // while the lock file exists, nobody else can replace it (link fails),
+      // and no other reclaimer can run, so what we re-read is what we remove.
+      const reclaim = await acquireReclaimMutex(lockFile, candidate, isAlive);
+      if (!reclaim) return { acquired: false, holderPid: null, release: async () => {} };
+      try {
+        const current = await readJson(lockFile);
+        if (current && !(Number.isInteger(current.pid) && !isAlive(current.pid))) {
+          return { acquired: false, holderPid: current?.pid ?? null, release: async () => {} };
+        }
+        if (current) await unlink(lockFile).catch((error) => { if (error?.code !== "ENOENT") throw error; });
+      } finally {
+        await reclaim.release();
+      }
+    }
+    const holder = await readJson(lockFile);
+    return { acquired: false, holderPid: holder?.pid ?? null, release: async () => {} };
+  } finally {
+    await unlink(candidate).catch(() => {});
+  }
+}
+
+// The reclaim mutex serialises stale-lock removal. Its critical section is a
+// read and an unlink, so a reclaim file left by a crashed contender is taken
+// over only once its holder is dead AND it is older than RECLAIM_STALE_MS.
+// Trust boundary: two contenders racing to clear a crashed reclaimer's mutex
+// in the same instant is not defended further (it needs a crash inside a
+// sub-millisecond section plus concurrent contention).
+const RECLAIM_STALE_MS = 10_000;
+async function acquireReclaimMutex(lockFile, candidate, isAlive) {
+  const mutex = `${lockFile}.reclaim`;
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      await link(candidate, mutex);
+      return { release: () => unlink(mutex).catch(() => {}) };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+    const holder = await readJson(mutex);
+    if (holder === null) continue;
+    let ageMs = 0;
+    try { ageMs = Date.now() - (await stat(mutex)).mtimeMs; } catch { continue; }
+    const dead = !(Number.isInteger(holder?.pid) && isAlive(holder.pid));
+    if (!dead || ageMs < RECLAIM_STALE_MS) return null; // another contender is reclaiming
+    await unlink(mutex).catch(() => {});
+  }
+  return null;
+}
+
+async function dirMtimeMs(home) {
+  try { return (await stat(commandRunsDir(home))).mtimeMs; } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * The delivery process: hold the lock, drain until nothing retryable remains
+ * (or the lifetime cap), record the settled directory state, release, exit.
+ */
+export async function runDelivery({
+  home = homedir(), call, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => performance.now(),
+  lifetimeMs = DELIVERY_LIFETIME_MS, ...drainOptions
+} = {}) {
+  const lock = await acquireDeliveryLock({ home });
+  if (!lock.acquired) return { outcome: "held", holder_pid: lock.holderPid, delivered: 0, parked: 0, pending: 0, stopped: 0 };
+  const totals = { delivered: 0, parked: 0, pending: 0, stopped: 0, owned: 0 };
+  const started = now();
+  let backoff = DELIVERY_FIRST_BACKOFF_MS;
+  let settlePasses = 0;
+  try {
+    for (;;) {
+      const mtime = await dirMtimeMs(home);
+      const pass = await drainOnce({ home, call, sleep, ...drainOptions });
+      for (const key of ["delivered", "parked", "stopped"]) totals[key] += pass[key];
+      totals.pending = pass.pending;
+      totals.owned = pass.owned;
+      if (pass.pending === 0) {
+        // Our own writes move the directory mtime; one more pass confirms the
+        // directory is settled so `bb` invocations stop re-starting us.
+        if (pass.wrote && settlePasses++ < 3) continue;
+        // A delivery still owned by a live worker is not settled: if that
+        // worker dies before it writes again, the directory never changes, so
+        // leave the state open for a re-scan after the cooldown.
+        await writeJsonAtomic(deliveryStatePath(home), { dir_mtime_ms: pass.owned > 0 ? null : mtime, settled_at: new Date().toISOString(), owned: pass.owned });
+        return { outcome: "drained", ...totals };
+      }
+      settlePasses = 0;
+      if (now() - started + backoff > lifetimeMs) {
+        // Retryable work remains: leave the state unsettled so the next `bb`
+        // invocation starts a fresh delivery process.
+        await writeJsonAtomic(deliveryStatePath(home), { dir_mtime_ms: null, settled_at: null, pending: pass.pending });
+        return { outcome: "lifetime_exhausted", ...totals };
+      }
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, DELIVERY_MAX_BACKOFF_MS);
+    }
+  } finally {
+    await lock.release();
+  }
+}
+
+/**
+ * Called by every `bb` invocation (and by a worker that parked a retryable
+ * delivery): start the delivery process when the run directory changed since
+ * it last settled and no live process holds the lock. Cheap: a stat and two
+ * small reads. Never throws into the caller's command.
+ */
+export async function ensureRunDelivery({
+  home = homedir(), env = process.env, spawnImpl = spawn, isAlive = pidAlive, force = false, cooldownMs = DELIVERY_RESCAN_COOLDOWN_MS,
+} = {}) {
+  try {
+    if (env.BOTBUDDY_RUN_DELIVERY === "off") return { started: false, reason: "disabled" };
+    const mtime = await dirMtimeMs(home);
+    if (mtime === null) return { started: false, reason: "no_runs" };
+    const state = await readJson(deliveryStatePath(home));
+    if (!force && state && state.dir_mtime_ms === mtime) return { started: false, reason: "up_to_date" };
+    // A worker still inside its own retry budget rewrites its context on every
+    // attempt. Re-scanning on each of those changes is wasted work: the worker
+    // starts us itself (force) when it parks, so otherwise scan at most once
+    // per cooldown. Both times are this machine's filesystem clock.
+    if (!force && state) {
+      const stateAge = Date.now() - (await stat(deliveryStatePath(home))).mtimeMs;
+      if (stateAge >= 0 && stateAge < cooldownMs) return { started: false, reason: "cooldown" };
+    }
+    const holder = await readJson(deliveryLockPath(home));
+    if (Number.isInteger(holder?.pid) && isAlive(holder.pid)) return { started: false, reason: "held" };
+    const bin = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "botbuddy.mjs");
+    const child = spawnImpl(process.execPath, [bin, "run", "--deliver"], { detached: true, stdio: "ignore", cwd: home, windowsHide: true });
+    child.on?.("error", () => { /* best effort: the next invocation retries */ });
+    child.unref?.();
+    return { started: true, reason: "pending" };
+  } catch (error) {
+    return { started: false, reason: `error:${error instanceof Error ? error.message : String(error)}` };
+  }
+}

package/src/run.mjs

@@ -13,7 +13,9 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { performance } from "node:perf_hooks";
 import { callToolJson } from "./api.mjs";
+import { SERVER_URL } from "./config.mjs";
 import { parseLaneEvents, laneCaseCounts, flushLaneCases, buildLaneSummary, laneSummaryFilename } from "./test-lane-events.mjs";
 import { AGENT_KEY_RE, readAgentSessionTokenEnv, legacyAgentAliasHint } from "./agent-key.mjs";
 import { hasAgentSessionRuntime, isRejectedCachedMcpSession, resolveAgentSessionCredential, selfHealAgentSession } from "./agent-session.mjs";
@@ -23,6 +25,10 @@ import { createTelemetryOutbox } from "./telemetry-outbox.mjs";
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { attestTelemetryCredential, loadTelemetryIdentity } from "./telemetry-config.mjs";
 import { VERSION } from "./version.mjs";
+import {
+  TERMINAL_RETRY_BUDGET_MS, DELIVERY_CALL_TIMEOUT_MS, callWithContextIdentity, classifyTerminalUpdateFailure,
+  ensureRunDelivery, parkedRecord, runDelivery, terminalUpdateAccepted,
+} from "./run-delivery.mjs";
 
 export const RUN_SCHEMA_VERSION = 1;
 export const EXIT = Object.freeze({ OK: 0, AUTH: 3, INVALID: 4, BACKEND: 5, INTERNAL: 7 });
@@ -405,7 +411,7 @@ export async function launchRun(argv, {
   // every callback is attributable to the same agent. It deliberately stays
   // outside child_env, receipts, and the workload's process environment.
   const knownSession = opts.sessionId ?? managedCredential?.identity?.sessionId ?? managedCredential?.sessionId;
-  await writeJson(context, { schema_version: RUN_SCHEMA_VERSION, context_path: context, run_id: runId, run_credential: registration.data.run_credential, receipt_upload: registration.data.receipt_upload, command, 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 } : {}) });
+  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(), server_url: SERVER_URL,...(opts.sessionToken ? { callback_session_token: opts.sessionToken } : {}), ...(knownSession ? { callback_session_id: knownSession } : {}), ...(childEnv && Object.keys(childEnv).length ? { child_env: childEnv } : {}), ...(testRun ? { test_run: testRun } : {}) });
   const [file, args] = workerInvocation(context);
   try {
     const worker = spawnImpl(file, args, { detached: true, stdio: "ignore", windowsHide: true });
@@ -426,7 +432,10 @@ export async function runWorker(contextFile, {
   call = callToolJson,
   signalEmitter = process,
   terminate = terminateProcessGroup,
+  // BOT-2600: the bounded terminal delivery (see retryTerminalUpdate).
+  sleep, now, terminalBudgetMs, startDelivery,
 } = {}) {
+  const retry = { sleep, now, budgetMs: terminalBudgetMs, startDelivery };
   const context = JSON.parse(await readFile(contextFile, "utf8"));
   const callbackCall = callWithContextIdentity(context, call);
   const ownerHeartbeat = startOwnerHeartbeat(context, callbackCall);
@@ -492,7 +501,7 @@ export async function runWorker(contextFile, {
       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);
+      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, retry);
       return receipt;
     }
   // A failed spawn can report through the child `error` event on the next turn.
@@ -523,11 +532,11 @@ export async function runWorker(contextFile, {
     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);
+      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, retry);
       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);
+    const receipt = await finalize(context, { status, startedAt, endedAt, exitCode: result.exitCode, signal: result.signal, output: capture.output, outputCharacters: capture.characters }, callbackCall, retry);
     return receipt;
   } finally {
     if (ownerHeartbeat) await ownerHeartbeat.stop();
@@ -556,7 +565,14 @@ function startOwnerHeartbeat(context, call, { intervalMs = 5 * 60_000, setInterv
   tick();
   const timer = setIntervalFn(tick, intervalMs);
   timer.unref?.();
-  return { async stop() { stopped = true; clearInterval(timer); await chain; } };
+  // BOT-2600: an in-flight heartbeat must never hold a finished worker open.
+  return { async stop() {
+    stopped = true;
+    clearInterval(timer);
+    let bound;
+    await Promise.race([chain, new Promise((resolve) => { bound = setTimeout(resolve, 2_000); bound.unref?.(); })]);
+    clearTimeout(bound);
+  } };
 }
 
 // Periodic lane flusher: reduce the NDJSON events file to the current case state
@@ -785,7 +801,7 @@ export async function cancelRun(runId, {
   return { exitCode: EXIT.OK, receipt: { schema_version: RUN_SCHEMA_VERSION, outcome: "cancellation_requested", run_id: runId, exit_code: EXIT.OK } };
 }
 
-async function finalize(context, state, call) {
+async function finalize(context, state, call, retry = {}) {
   const boundedLog = String(state.output ?? "").slice(-8192);
   const outputCharacters = state.outputCharacters ?? String(state.output ?? "").length;
   const receipt = { schema_version: RUN_SCHEMA_VERSION, run_id: context.run_id, status: state.status, started_at: state.startedAt, ended_at: state.endedAt, exit_code: state.exitCode, signal: state.signal, recovery_command: state.status === "failure" ? `botbuddy run --session-id <new-session-id> --environment local -- ${context.command.map((x) => JSON.stringify(x)).join(" ")}` : null, bounded_log: boundedLog, output_characters: outputCharacters, reason: state.reason ?? null };
@@ -795,43 +811,77 @@ async function finalize(context, state, call) {
   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.
+  // before the command callback's retry: otherwise an auth outage (for example
+  // agent_identity_required) strands a 0-case run in active state 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 */ }
+  const delivery = await retryTerminalUpdate(context, update, call, retry);
+  // A parked delivery keeps its context: it is the durable record the
+  // per-machine delivery process (and an operator) reads.
+  if (delivery.delivered) {
+    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)) } = {}) {
+// BOT-2600: the terminal callback is bounded. The worker that owns the receipt
+// retries transient failures (transport, timeout, 5xx) within a monotonic
+// budget of at most ten minutes and parks a permanent rejection (no owning
+// identity, an invalid run credential, a local environment error) at once.
+// Either way it records `terminal_update.parked` in the private context and
+// returns so the worker process exits; a retryable parked delivery is handed to
+// the single per-machine delivery process (`bb run --deliver`).
+export async function retryTerminalUpdate(context, update, call, {
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = () => performance.now(),
+  budgetMs = TERMINAL_RETRY_BUDGET_MS,
+  startDelivery = () => ensureRunDelivery({ force: true }),
+} = {}) {
+  const started = now();
   let attempts = 0;
   let delay = 1_000;
   for (;;) {
-    let result;
-    try { result = await call("update_command_run", update); } catch (error) { result = { ok: false, error: error instanceof Error ? error.message : String(error) }; }
-    if (result?.ok && !result.isError && result.data?.error == null && result.data?.accepted !== false) return result;
+    let result = null;
+    let failure;
+    try {
+      result = await call("update_command_run", update, {
+        signal: AbortSignal.timeout(DELIVERY_CALL_TIMEOUT_MS),
+        // The endpoint this run was registered with (BOT-2600; sealed at launch).
+        ...(typeof context.server_url === "string" && context.server_url ? { serverUrl: context.server_url } : {}),
+      });
+      if (terminalUpdateAccepted(result)) return { delivered: true, attempts: attempts + 1, result };
+      failure = classifyTerminalUpdateFailure(result);
+    } catch (error) {
+      failure = classifyTerminalUpdateFailure(null, error);
+    }
     attempts += 1;
-    await writeJson(context.context_path, { ...context, terminal_update: { ...update, attempts, last_error: result?.error ?? result?.data?.error ?? "terminal_update_rejected", next_retry_at: new Date(Date.now() + delay).toISOString() } });
+    const exhausted = failure.retryable && !failure.parkNow && now() - started + delay > budgetMs;
+    if (!failure.retryable || failure.parkNow || exhausted) {
+      const parked = parkedRecord(exhausted ? { ...failure, kind: "retry_budget_exhausted" } : failure, "worker");
+      await writeJson(context.context_path, { ...context, terminal_update: { ...update, attempts, last_error: failure.reason, retry_budget_ms: budgetMs, parked } });
+      if (parked.retryable) { try { await startDelivery(); } catch { /* the next bb invocation starts it */ } }
+      return { delivered: false, attempts, parked, result };
+    }
+    await writeJson(context.context_path, { ...context, terminal_update: { ...update, attempts, last_error: failure.reason, retry_budget_ms: budgetMs, next_retry_at: new Date(Date.now() + delay).toISOString() } });
     await sleep(delay);
     delay = Math.min(delay * 2, 60_000);
   }
 }
 
 export async function cmdRun(args) {
-  if (args[0] === "--worker") { await runWorker(args[1]); return; }
+  if (args[0] === "--worker") {
+    await runWorker(args[1]);
+    // BOT-2600: the receipt is durable and its delivery is accepted or parked.
+    // Nothing may keep a finished worker resident; an unref'd guard exits even
+    // if a stray handle (a keep-alive socket) would otherwise hold the loop.
+    setTimeout(() => process.exit(process.exitCode ?? 0), 1_000).unref();
+    return;
+  }
+  if (args[0] === "--deliver") {
+    const result = await runDelivery({ call: callToolJson });
+    if (args.includes("--json")) oneLine({ schema_version: RUN_SCHEMA_VERSION, ...result }, false);
+    return;
+  }
   if (args[0] === "cancel") {
     const result = await cancelRun(args[1] ?? "");
     oneLine(result.receipt, false);

package/src/wait-core.mjs

@@ -287,9 +287,10 @@ const VALIDATORS = {
   // BOT-1507 — scope=next adds a fourth, LIVE-ONLY selector: it names no run or PR
   // (they must already exist at arm time) and wakes on the first terminal CI run for
   // the repo delivered AFTER the wait was armed — the post-merge / cron train case.
-  // Optional branch=/workflow= filter that first run; branch is valid only with
-  // scope=next. A workflow also pins a level-triggered sha= recovery to one
-  // canonical workflow identity.
+  // Optional branch=/workflow=/workflow_id=/workflow_path= filters narrow that
+  // first run; branch and stable workflow identities are valid only with
+  // scope=next. The legacy display-name filter also pins a level-triggered
+  // sha= recovery to one historical workflow.
   // BOT-1685 — scope=next also accepts an optional sha= FILTER (distinct from the
   // level-triggered sha= selector): a wait armed BEFORE re-dispatching a run for a
   // known commit then wakes on the NEXT terminal run for THAT commit, instead of
@@ -309,9 +310,13 @@ const VALIDATORS = {
     }
     const hasBranchFilter = p.branch !== undefined;
     const hasWorkflowFilter = p.workflow !== undefined;
+    const hasWorkflowIdFilter = p.workflow_id !== undefined;
+    const hasWorkflowPathFilter = p.workflow_path !== undefined;
     if (p.scope !== undefined) {
       if (p.scope === "latest") {
-        if (hasBranchFilter || hasWorkflowFilter) throw new Error("ci branch=/workflow= are only valid with scope=next");
+        if (hasBranchFilter || hasWorkflowFilter || hasWorkflowIdFilter || hasWorkflowPathFilter) {
+          throw new Error("ci branch=/workflow=/workflow_id=/workflow_path= are only valid with scope=next");
+        }
         if (p.pr === undefined || !/^\d+$/.test(String(p.pr).trim())) {
           throw new Error("ci scope=latest needs pr=<number>");
         }
@@ -329,12 +334,23 @@ const VALIDATORS = {
           if (v === "") throw new Error(`ci ${key}= must be non-empty`);
           return v;
         };
-        return { repo, scope: "next", branch: filter("branch"), workflow: filter("workflow"), sha: filter("sha"), pr: null };
+        const workflowId = filter("workflow_id");
+        const workflowPath = filter("workflow_path");
+        return {
+          repo,
+          scope: "next",
+          branch: filter("branch"),
+          workflow: filter("workflow"),
+          ...(workflowId == null ? {} : { workflowId }),
+          ...(workflowPath == null ? {} : { workflowPath }),
+          sha: filter("sha"),
+          pr: null,
+        };
       }
       throw new Error("ci scope must be 'latest' or 'next' (or use run_id=/sha=)");
     }
-    if (hasBranchFilter || (hasWorkflowFilter && p.sha === undefined)) {
-      throw new Error("ci branch= is only valid with scope=next; workflow= also accepts an exact sha selector");
+    if (hasBranchFilter || hasWorkflowIdFilter || hasWorkflowPathFilter || (hasWorkflowFilter && p.sha === undefined)) {
+      throw new Error("ci branch=/workflow_id=/workflow_path= are only valid with scope=next; legacy workflow= also accepts an exact sha selector");
     }
     if (p.run_id !== undefined) {
       if (!String(p.run_id).trim()) throw new Error("ci run_id must be non-empty");
@@ -343,7 +359,13 @@ const VALIDATORS = {
     if (!String(p.sha).trim()) throw new Error("ci sha must be non-empty");
     const workflow = p.workflow === undefined ? null : String(p.workflow).trim();
     if (p.workflow !== undefined && workflow === "") throw new Error("ci workflow= must be non-empty");
-    return { repo, scope: "sha", sha: String(p.sha).trim(), workflow, pr: p.pr != null ? String(p.pr).trim() : null };
+    return {
+      repo,
+      scope: "sha",
+      sha: String(p.sha).trim(),
+      workflow,
+      pr: p.pr != null ? String(p.pr).trim() : null,
+    };
   },
   "staging-green"(p) {
     const repo = p.repo != null ? String(p.repo).trim() : null;
@@ -1013,7 +1035,7 @@ export function formatUnknownWorkflowGuidance(detail, candidates) {
   const named = Array.isArray(candidates) ? candidates.filter((c) => typeof c === "string" && c.trim() !== "") : [];
   if (named.length === 0) return lines;
   lines.push("closest workflow names this repo has actually reported:");
-  for (const name of named) lines.push(`  workflow=${name}`);
+  for (const name of named) lines.push(`  ${name.includes("=") ? name : `workflow=${name}`}`);
   return lines;
 }
 
@@ -1152,16 +1174,20 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       if (params.scope === "run_id") return String(signal.payload?.run_id) === params.runId;
       if (params.scope === "sha") {
         if (signal.payload?.head_sha !== params.sha) return false;
-        if (params.workflow == null) return true;
-        const workflow = signal.payload?.workflow_name;
-        return typeof workflow === "string" && workflow.trim().toLowerCase() === params.workflow.trim().toLowerCase();
+        if (params.workflow != null) {
+          const workflow = signal.payload?.workflow_name;
+          if (typeof workflow !== "string" || workflow.trim().toLowerCase() !== params.workflow.trim().toLowerCase()) return false;
+        }
+        if (params.workflowId != null && String(signal.payload?.workflow_id ?? "").trim() !== params.workflowId) return false;
+        if (params.workflowPath != null && String(signal.payload?.workflow_path ?? "").trim() !== params.workflowPath) return false;
+        return true;
       }
       if (params.scope === "next") {
         // BOT-1507 — live-only: the first TERMINAL run for the repo. Never keys on
         // subject_key (it is run:<id> for post-merge runs and owner/repo#n for PR
         // runs — both are legitimate wakes); a null/empty conclusion is an
         // in-progress signal and never terminal. Optional branch/workflow filters:
-        // branch is exact, workflow is the GitHub display name (case/space-insensitive).
+        // branch/path/id are exact; the display name is case/space-insensitive.
         const conclusion = signal.payload?.conclusion;
         if (typeof conclusion !== "string" || conclusion.trim() === "") return false;
         // BOT-1685: an optional sha filter pins scope=next to a commit, so a
@@ -1174,6 +1200,8 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
             return false;
           }
         }
+        if (params.workflowId != null && String(signal.payload?.workflow_id ?? "").trim() !== params.workflowId) return false;
+        if (params.workflowPath != null && String(signal.payload?.workflow_path ?? "").trim() !== params.workflowPath) return false;
         return true;
       }
       // scope=latest: the PR's run (by subject owner/repo#pr or payload pr_number).