@botbuddy/cli 1.47.1 → 1.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbuddy/cli",
-  "version": "1.47.1",
+  "version": "1.49.0",
   "description": "BotBuddy — Swarm coordination CLI for multi-agent workflows",
   "type": "module",
   "bin": {

package/src/commands.mjs

@@ -30,6 +30,7 @@ import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation
 import { deliverExecutionEvent } from "./telemetry-delivery.mjs";
 import { doctorAgentAuth, doctorHelp, parseDoctorArgs, readClientKeyStrict, repairFailureRecovery } from "./agent-doctor.mjs";
 import { formatPublishIp, isLoopbackIp, probeEnginePublishIp, publishIpFix } from "./docker-publish-ip.mjs";
+import { cmdHost, fixHelperWorkers, formatHelperWorkersLines, inspectHelperWorkers } from "./helper-host.mjs";
 import { clearAgentState, selfHealAgentSession } from "./agent-session.mjs";
 import { runUsage, usageStatus } from "./usage/sync.mjs";
 import { installUsageAgent, usageAgentStatus } from "./usage/launchd.mjs";
@@ -83,6 +84,8 @@ export async function run(argv, {
     case "logout": return cmdLogout();
     case "status": return cmdStatus();
     case "doctor": return cmdDoctor(args);
+    // BOT-2367: this Mac's Helper host key, whatever the status file's age.
+    case "host": return cmdHost(args);
     case "update": return cmdUpdate();
     // Agent-only commands (used by MCP agents, not humans)
     case "heartbeat": return cmdHeartbeat(args);
@@ -188,7 +191,9 @@ ${bold("AUTH")}
   logout                     Remove saved credentials
   status                     Show current auth status (local metadata + server check)
   doctor [--fix] [--print-exports] [--json]
-                             Diagnose or repair the cached agent session
+                             Diagnose or repair the cached agent session; on macOS also
+                             reports duplicate Helper workers (--fix terminates them)
+  host key [--json]          This Mac's Helper host key, whatever the status file's age
 
 ${bold("MCP CONFIG KEY")}
   mcp setup [--env <NAME>] [--tenant <slug>] [--label <l>] [--expiry-days <n>]
@@ -257,6 +262,8 @@ export async function cmdDoctor(args, {
   log = (line) => console.log(line), errorLog = (line) => console.error(line),
   doctor = doctorAgentAuth, usageReport = doctorUsageSync, bootstrapReport = doctorBootstrapState,
   publishReport = () => probeEnginePublishIp(),
+  helperWorkersReport = async () => inspectHelperWorkers(),
+  helperWorkersFix = (report) => fixHelperWorkers(report),
 } = {}) {
   const parsed = parseDoctorArgs(args);
   if (parsed.help) { log(doctorHelp()); return 0; }
@@ -271,8 +278,18 @@ export async function cmdDoctor(args, {
   const usage = await usageReport().catch(() => null);
   // BOT-1945 (AC-3): informational, like usage sync — never changes the exit code.
   const bootstrap = await bootstrapReport().catch(() => null);
+  // BOT-2367: duplicate Helper workers / stale Helper locks (macOS). Reported on
+  // every run; `--fix` SIGTERMs a duplicate launchd is not running, then
+  // re-checks. Informational: never changes doctor's exit code.
+  let helperWorkers = await helperWorkersReport().catch(() => null);
+  let helperFix = null;
+  if (parsed.fix && helperWorkers?.status === "duplicate") {
+    helperFix = await helperWorkersFix(helperWorkers).catch(() => null);
+    const recheck = await helperWorkersReport().catch(() => null);
+    helperWorkers = recheck ? { ...recheck, fix: helperFix } : { ...helperWorkers, fix: helperFix };
+  }
   if (parsed.json) {
-    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}) }));
+    log(JSON.stringify({ ...result.report, ...(usage ? { usage_sync: usage } : {}), ...(bootstrap ? { bootstrap } : {}), ...(helperWorkers ? { helper_workers: helperWorkers } : {}) }));
   } else {
     log(`binding: ${result.report.binding.status}${result.report.binding.tenant ? ` (${result.report.binding.tenant})` : ""}`);
     log(`client key: ${result.report.client_key.status}`);
@@ -288,6 +305,7 @@ export async function cmdDoctor(args, {
     if (result.report.recovery) log(`recovery: ${result.report.recovery}`);
     if (bootstrap) log(formatBootstrapLine(bootstrap));
     if (usage) log(formatUsageSyncLine(usage));
+    for (const line of formatHelperWorkersLines(helperWorkers, helperFix)) log(line);
   }
   if (result.exports) log(result.exports);
   return result.exitCode;

package/src/helper-host.mjs

@@ -0,0 +1,223 @@
+// BOT-2367 — this Mac's BotBuddy Helper host key, and the `bb doctor` Helper
+// duplicate-worker / stale-lock check.
+//
+// The Helper writes `managed-container-host-status.json` with this machine's
+// `host_key` and `checked_at` (Apple-epoch seconds; there is no `updated_at`).
+// The host key is derived from the machine's P-256 identity and is static, so
+// it never depends on the file's age: `bb host key` returns it whatever the
+// age and reports freshness separately. On 2026-10-14 a 7-minute Helper job
+// tick aged the file past Supply Guard's 300 s limit on a healthy host and SG
+// refused to name the host (exit 4); Helper 0.2.37 refreshes the file on every
+// beacon, and this command gives wrappers a resolver that cannot fail that way.
+//
+// Read-only except `fixHelperWorkers`, which only SIGTERMs a
+// `botbuddyhelper-worker` process launchd is not running, and only when the
+// launchd PID was read twice and agreed (fail-closed otherwise).
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { basename, join } from "node:path";
+
+export const HELPER_WORKER_LABEL = "com.botbuddy.helper.worker";
+export const HELPER_WORKER_BINARY = "botbuddyhelper-worker";
+/** Supply Guard's freshness limit; Helper 0.2.37 refreshes every ~20 s. */
+export const HELPER_STATUS_FRESH_SECONDS = 300;
+const APPLE_REFERENCE_EPOCH_SECONDS = 978_307_200;
+const HOST_KEY_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const HELPER_LOCK_FILES = [".worker.lock", ".beacon.lock", ".metrics.lock"];
+const START_REMEDY = "start the BotBuddy Helper (open \"BotBuddy Helper.app\") so it writes this file";
+
+export function helperSupportDir(home = homedir()) {
+  return join(home, "Library", "Application Support", "BotBuddyHelper");
+}
+
+export function helperStatusPath(home = homedir()) {
+  return join(helperSupportDir(home), "managed-container-host-status.json");
+}
+
+/**
+ * `{ ok: true, host_key, checked_at, age_seconds, fresh, path }`, or
+ * `{ ok: false, code, path, message }` when the file is missing or names no
+ * well-formed host key. Freshness never decides whether the key is returned.
+ */
+export function readHelperHostKey({ home = homedir(), nowMs = Date.now(), readFile = (p) => readFileSync(p, "utf8") } = {}) {
+  const path = helperStatusPath(home);
+  let contents;
+  try {
+    contents = readFile(path);
+  } catch (error) {
+    return { ok: false, code: "HELPER_STATUS_MISSING", path, message: `could not read ${path} (${error?.code ?? "unreadable"}); ${START_REMEDY}` };
+  }
+  let status;
+  try {
+    status = JSON.parse(contents);
+  } catch {
+    status = null;
+  }
+  const hostKey = status?.host_key;
+  if (typeof hostKey !== "string" || !HOST_KEY_PATTERN.test(hostKey)) {
+    return { ok: false, code: "HELPER_STATUS_MALFORMED", path, message: `${path} names no well-formed host_key; ${START_REMEDY}` };
+  }
+  const checkedAt = status.checked_at;
+  if (!Number.isFinite(checkedAt)) {
+    return { ok: true, host_key: hostKey, checked_at: null, age_seconds: null, fresh: false, path };
+  }
+  const checkedAtMs = (checkedAt + APPLE_REFERENCE_EPOCH_SECONDS) * 1000;
+  const ageSeconds = Math.round((nowMs - checkedAtMs) / 1000);
+  return {
+    ok: true,
+    host_key: hostKey,
+    checked_at: new Date(checkedAtMs).toISOString(),
+    age_seconds: ageSeconds,
+    fresh: ageSeconds >= -60 && ageSeconds <= HELPER_STATUS_FRESH_SECONDS,
+    path,
+  };
+}
+
+const HOST_USAGE = "Usage: bb host key [--json]";
+
+export function hostHelp() {
+  return `${HOST_USAGE}
+
+Prints this Mac's managed-container host key from the BotBuddy Helper's status
+file, whatever the file's age: the key is this machine's static identity. A file
+older than ${HELPER_STATUS_FRESH_SECONDS} s still prints the key (exit 0) with a freshness warning on
+stderr. Exit 4 when the file is missing or names no host key.
+--json prints {host_key, checked_at, age_seconds, fresh, path}.`;
+}
+
+/** `bb host key [--json]` → exit code. */
+export async function cmdHost(args, {
+  log = (line) => console.log(line), errorLog = (line) => console.error(line),
+  read = () => readHelperHostKey(),
+} = {}) {
+  const [sub, ...rest] = args;
+  if (sub === "help" || sub === "--help" || sub === "-h") { log(hostHelp()); return 0; }
+  const json = rest.includes("--json");
+  const unknown = rest.filter((a) => a !== "--json");
+  if (sub !== "key" || unknown.length) { errorLog(HOST_USAGE); return 4; }
+  const r = read();
+  if (!r.ok) {
+    errorLog(`bb host key: ${r.code}: ${r.message}`);
+    return 4;
+  }
+  if (json) {
+    log(JSON.stringify({ host_key: r.host_key, checked_at: r.checked_at, age_seconds: r.age_seconds, fresh: r.fresh, path: r.path }));
+  } else {
+    log(r.host_key);
+  }
+  if (!r.fresh) {
+    const age = r.age_seconds == null ? "has no checked_at" : `is ${r.age_seconds} s old`;
+    errorLog(`bb host key: warning: the Helper status file ${age} (fresh is ≤ ${HELPER_STATUS_FRESH_SECONDS} s); the key is still this Mac's. ` +
+      `If the Helper is not running, check \`launchctl print gui/$(id -u)/${HELPER_WORKER_LABEL}\` and the worker log.`);
+  }
+  return 0;
+}
+
+// ── bb doctor: duplicate Helper workers and stale Helper locks ───────────────
+
+function defaultRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 });
+  return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+}
+
+/** `launchctl list <label>` → pid number, null (loaded, not running), or undefined (unreadable). */
+export function parseLaunchctlListPid(result) {
+  if (!result || result.status !== 0) return undefined;
+  const m = /"PID"\s*=\s*(\d+)\s*;/.exec(result.stdout);
+  return m ? Number(m[1]) : null;
+}
+
+/** `ps -axo pid=,comm=` → the pids of `botbuddyhelper-worker` processes. */
+export function parseWorkerPids(stdout) {
+  const pids = [];
+  for (const line of String(stdout).split("\n")) {
+    const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
+    if (m && basename(m[2]) === HELPER_WORKER_BINARY) pids.push(Number(m[1]));
+  }
+  return pids.sort((a, b) => a - b);
+}
+
+/** `lsof -F pcn` → Helper lock files held open by a process that is not a Helper process. */
+export function parseStaleLocks(stdout) {
+  const stale = [];
+  let pid = null; let command = null;
+  for (const line of String(stdout).split("\n")) {
+    const tag = line[0]; const value = line.slice(1);
+    if (tag === "p") { pid = Number(value); command = null; }
+    else if (tag === "c") command = value;
+    else if (tag === "n") {
+      const file = basename(value);
+      if (HELPER_LOCK_FILES.includes(file) && !/^botbuddyhelper/i.test(command ?? "")) {
+        stale.push({ file, pid, command });
+      }
+    }
+  }
+  return stale;
+}
+
+/**
+ * Read-only census of Helper worker processes against launchd's own job PID.
+ * A duplicate is a `botbuddyhelper-worker` launchd is not running. The launchd
+ * PID is read before and after `ps`; if launchd's answer is unreadable or
+ * changed (a tick started mid-check), nothing is called a duplicate.
+ */
+export function inspectHelperWorkers({ run = defaultRun, home = homedir(), platformFn = platform } = {}) {
+  if (platformFn() !== "darwin") return null;
+  const before = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const workers = parseWorkerPids(run("ps", ["-axo", "pid=,comm="]).stdout);
+  const after = parseLaunchctlListPid(run("launchctl", ["list", HELPER_WORKER_LABEL]));
+  const lockPaths = HELPER_LOCK_FILES.map((f) => join(helperSupportDir(home), f));
+  const lsof = run("lsof", ["+c", "0", "-F", "pcn", ...lockPaths]);
+  const staleLocks = parseStaleLocks(lsof.stdout);
+  const base = { launchd_pid: after ?? null, workers, duplicates: [], stale_locks: staleLocks };
+  if (before === undefined || after === undefined) {
+    return { status: "unknown", ...base, reason: `launchd job ${HELPER_WORKER_LABEL} is not readable in this session` };
+  }
+  if (before !== after) return { status: "unsettled", ...base, reason: "launchd started a worker tick during the check" };
+  const duplicates = workers.filter((pid) => pid !== after);
+  return { status: duplicates.length ? "duplicate" : "ok", ...base, duplicates };
+}
+
+function defaultIsAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+
+/** SIGTERM each duplicate (never launchd's worker); wait up to ~3 s for exit. */
+export async function fixHelperWorkers(report, {
+  kill = (pid, signal) => process.kill(pid, signal), isAlive = defaultIsAlive,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+} = {}) {
+  const result = { terminated: [], failed: [] };
+  if (report?.status !== "duplicate") return result;
+  for (const pid of report.duplicates) {
+    if (pid === report.launchd_pid) continue;
+    try { kill(pid, "SIGTERM"); } catch { /* already gone or not ours; checked below */ }
+  }
+  for (let i = 0; i < 30 && report.duplicates.some((pid) => isAlive(pid)); i++) await sleep(100);
+  for (const pid of report.duplicates) (isAlive(pid) ? result.failed : result.terminated).push(pid);
+  return result;
+}
+
+/** Human lines for `bb doctor`. */
+export function formatHelperWorkersLines(report, fix = null) {
+  if (!report) return [];
+  const lines = [];
+  const launchd = report.launchd_pid ? `launchd ${HELPER_WORKER_LABEL} pid ${report.launchd_pid}` : `launchd ${HELPER_WORKER_LABEL} idle between ticks`;
+  if (fix && (fix.terminated.length || fix.failed.length)) {
+    // A re-checked report (cmdDoctor attaches `fix`) already lists the survivors.
+    const running = report.fix ? report.workers.length : report.workers.length - fix.terminated.length;
+    for (const pid of fix.terminated) lines.push(`helper workers: terminated duplicate pid ${pid}; ${running} running (${launchd})`);
+    for (const pid of fix.failed) lines.push(`helper workers: could not terminate duplicate pid ${pid}; stop it with \`kill ${pid}\``);
+  } else if (report.status === "ok") {
+    lines.push(`helper workers: ${report.workers.length} running (${launchd})`);
+  } else if (report.status === "duplicate") {
+    lines.push(`helper workers: ${report.workers.length} running — duplicate pid ${report.duplicates.join(", ")} (${launchd}); fix: \`bb doctor --fix\` terminates the duplicate`);
+  } else {
+    lines.push(`helper workers: ${report.workers.length} running — ${report.reason}; not checked for duplicates${report.status === "unsettled" ? " (re-run bb doctor)" : ""}`);
+  }
+  for (const s of report.stale_locks) {
+    lines.push(`helper lock: ${s.file} is held open by pid ${s.pid} (${s.command}), not a Helper process, so the Helper cannot take it; stop pid ${s.pid}`);
+  }
+  return lines;
+}

package/src/wait-core.mjs

@@ -31,6 +31,10 @@ export const EXIT = Object.freeze({
   // BOT-2330: an exact managed-allocation cleanup failed. The waiter must not
   // report a successful terminal match when the signed Helper outcome failed.
   MANAGED_ALLOCATION_FAILED: 10,
+  // BOT-2360: the server ended this wait while the client was still parked on it — the
+  // liveness reaper abandoned it, it was cancelled, or its row is gone. The relay
+  // refuses the stream with a typed `wait_abandoned` error frame; re-arm from next_cursor.
+  ABANDONED: 11,
 });
 
 // BOT-2013: the uuid spellings Postgres accepts for a lease id (uuid_in), mirrored by the SQL
@@ -1756,6 +1760,20 @@ export async function runWaitLoop({
         if (parsed.error === "unauthorized" || parsed.error === "forbidden") {
           return finalize("error", { exitCode: EXIT.AUTH, error: parsed.error });
         }
+        // BOT-2360: the relay refuses a stream bound to a wait the server already ended
+        // (prod a0cd7b11 parked 54 min on one). Never reconnect to it: exit typed, with the
+        // confirmed cursor so a re-arm replays everything after it.
+        if (parsed.error === "wait_abandoned") {
+          return finalize("abandoned", {
+            exitCode: EXIT.ABANDONED,
+            error: "wait_abandoned",
+            state: {
+              wait_session_id: typeof parsed.wait_session_id === "string" ? parsed.wait_session_id : waitSessionId ?? null,
+              status: typeof parsed.status === "string" ? parsed.status : null,
+              reason: typeof parsed.reason === "string" ? parsed.reason : null,
+            },
+          });
+        }
         return finalize("error", { exitCode: EXIT.INTERNAL, error: parsed.error || "stream_error" });
       }
 

package/src/wait.mjs

@@ -180,7 +180,12 @@ OUTPUT
               8 superseded (wait replaced server-side) · 9 lease lost (a
                 lease:id= wait whose lease was reaped before it was granted;
                 receipt outcome lease_lost + reap_reason — request a new
-                lease). If the receipt has
+                lease) · 10 managed-allocation cleanup failed (BOT-2330)
+                · 11 abandoned (the server ended this wait while it
+                was parked — reaped after 180 s without a live stream,
+                or cancelled; receipt outcome abandoned +
+                state.status/reason — re-arm with --since <next_cursor>).
+                If the receipt has
                 reacquire_lock (claim=true), acquire_lock again FIRST and re-run
                 only on a queued/busy result (granted = you hold it — just resume);
                 otherwise re-run from the receipt's next_cursor. docs/agent-wait.md.
@@ -548,11 +553,28 @@ export function leaseLostNotice(receipt) {
     `(reap_reason=${st.reap_reason ?? "unknown"}) — request a new lease (exit ${EXIT.LEASE_LOST})`;
 }
 
+/**
+ * BOT-2360: the one stderr line for an `abandoned` receipt (null for any other outcome). The
+ * server ended this wait (its liveness reaper or a cancel) while the client was
+ * still parked; re-arming from next_cursor replays everything after the last frame consumed.
+ */
+export function waitAbandonedNotice(receipt) {
+  if (receipt?.outcome !== "abandoned") return null;
+  const st = receipt.state ?? {};
+  const since = receipt.next_cursor != null ? ` --since ${receipt.next_cursor}` : "";
+  return `bb-wait: wait ${st.wait_session_id ?? "?"} was ended server-side (status=${st.status ?? "abandoned"}, ` +
+    `reason=${st.reason ?? "unknown"}) — re-arm the same conditions with${since || " a fresh wait"} (exit ${EXIT.ABANDONED})`;
+}
+
 function writeLeaseLostNotice(receipt) {
-  const notice = leaseLostNotice(receipt);
+  const notice = leaseLostNotice(receipt) ?? waitAbandonedNotice(receipt);
   if (notice) process.stderr.write(`${notice}\n`);
 }
 
+// BOT-1228 / BOT-2360: outcomes whose wait_session the server already ended. The client
+// never finalizes them (finalize_wait_session only transitions from active).
+const SERVER_ENDED_OUTCOMES = new Set(["superseded", "abandoned"]);
+
 // Record the terminal outcome. Best-effort AND bounded: the receipt has already
 // been written to stdout before this runs, so a slow/failing finalize must never
 // delay the agent's wake or change the exit path. A short abort timeout caps how
@@ -596,7 +618,7 @@ async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
 // A real SSE connection to the relay's spine tail. Returns an async iterable of
 // parsed frames. Server emits `id: <seq>` per signal and replays `seq > since`
 // on connect, so a reconnect never loses an event.
-function makeConnect(opts) {
+export function makeConnect(opts) {
   // BOT-1649: mirror the relay's keepalive expiry roll into the 0600 cache. The
   // server bumps session_token_expires_at on connect and every keepalive, but
   // the cache keeps its register-time deadline — so a wait near the 8 h cap goes
@@ -633,16 +655,25 @@ function makeConnect(opts) {
     // signal tears the stalled socket down immediately, then the read rejects and
     // the stream ends so runWaitLoop reconnects.
     const ac = new AbortController();
-    const res = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${opts.token}`,
-        "x-agent-api-key": opts.token || "",
-        Accept: "text/event-stream",
-        // BOT-741: never let a proxy gzip-buffer an SSE stream.
-        "Accept-Encoding": "identity",
-      },
-      signal: ac.signal,
-    });
+    // BOT-2360: bound the wait for response headers. Unbounded, a connect that hangs on a
+    // loaded host or a stuck proxy sits silent past the wait reaper's grace (undici's own
+    // headers timeout is 300 s); bounded, the worst silent reconnect stays inside it.
+    const connectTimer = setTimeout(() => ac.abort(new Error("relay connect timed out")), waitConnectTimeoutMs());
+    let res;
+    try {
+      res = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${opts.token}`,
+          "x-agent-api-key": opts.token || "",
+          Accept: "text/event-stream",
+          // BOT-741: never let a proxy gzip-buffer an SSE stream.
+          "Accept-Encoding": "identity",
+        },
+        signal: ac.signal,
+      });
+    } finally {
+      clearTimeout(connectTimer);
+    }
     if (res.status === 401) return errorStream("unauthorized");
     if (res.status === 403) return errorStream("forbidden");
     if (!res.ok || !res.body) throw new Error(`relay responded ${res.status}`);
@@ -655,7 +686,7 @@ function makeConnect(opts) {
 // runs the global bb_wait_linear_feed_lagging RPC) whether the Linear ingest
 // feed is stale. Any failure -> false (non-fatal: the wait keeps its last known
 // degraded state rather than flapping on a probe blip).
-const FEED_LAG_PROBE_TIMEOUT_MS = 10_000;
+export const FEED_LAG_PROBE_TIMEOUT_MS = 10_000;
 
 function makeFeedLagProbe(opts) {
   // `issues` = the armed `linear` conditions' target ticket keys. The relay
@@ -715,9 +746,20 @@ function makeFeedLagProbe(opts) {
 // runWaitLoop reconnects from the cursor, which re-bumps wait_sessions.last_seen_at
 // (and, with --heartbeat, agents.last_heartbeat) before the reaper's grace.
 // 70s ≈ 2.3 missed keepalives — long enough to never false-trip on jitter, short
-// enough that the reconnect lands inside the 90s last_seen reap window.
+// enough that the reconnect lands inside the 180 s last_seen reap window (BOT-2360).
 export const DEFAULT_SSE_IDLE_TIMEOUT_MS = 70_000;
 
+// BOT-2360: the longest a (re)connect may wait for the relay's response headers. With the
+// idle watchdog (70 s), the backoff cap (15 s) and the feed-lag probe (10 s) it bounds a
+// healthy client's worst silent gap at 125 s, under the 180 s wait-reaper grace with 55 s
+// to spare (asserted in bot2360-abandoned-wait.test.mjs against the registered cron job).
+export const WAIT_CONNECT_TIMEOUT_MS = 30_000;
+
+function waitConnectTimeoutMs() {
+  const raw = Number(process.env.BOTBUDDY_WAIT_CONNECT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : WAIT_CONNECT_TIMEOUT_MS;
+}
+
 function sseIdleTimeoutMs() {
   const raw = Number(process.env.BOTBUDDY_WAIT_IDLE_TIMEOUT_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_SSE_IDLE_TIMEOUT_MS;
@@ -1194,7 +1236,7 @@ async function deliverTerminalFinalization(checkpoint) {
 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") {
+  if (SERVER_ENDED_OUTCOMES.has(checkpoint.terminal_receipt.outcome)) {
     return store.update(checkpoint.local_wait_id, {
       cloud_finalize_pending: false,
       cloud_finalized_at: new Date().toISOString(),
@@ -1296,6 +1338,7 @@ function exitForRecoveredOutcome(receipt) {
   if (receipt?.outcome === "cancelled") return EXIT.MATCHED;
   if (receipt?.outcome === "timeout") return EXIT.TIMEOUT;
   if (receipt?.outcome === "superseded") return EXIT.SUPERSEDED;
+  if (receipt?.outcome === "abandoned") return EXIT.ABANDONED;
   if (receipt?.error === "cursor_expired") return EXIT.CURSOR_EXPIRED;
   if (receipt?.error === "unauthorized" || receipt?.error === "forbidden") return EXIT.AUTH;
   return EXIT.BACKEND;
@@ -2095,7 +2138,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
             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"),
+            cloud_finalize_pending: Boolean(waitSessionId && !SERVER_ENDED_OUTCOMES.has(terminalReceipt.outcome)),
           });
           terminalPersistedFromFrame = true;
           return;
@@ -2125,7 +2168,7 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
         terminal_receipt: terminalReceipt,
         exit_code: exitCode,
         safe_cursor: terminalReceipt.next_cursor ?? checkpoint.safe_cursor ?? null,
-        cloud_finalize_pending: Boolean(waitSessionId && terminalReceipt.outcome !== "superseded"),
+        cloud_finalize_pending: Boolean(waitSessionId && !SERVER_ENDED_OUTCOMES.has(terminalReceipt.outcome)),
       });
     }
     emitReceipt(terminalReceipt, { versioned: true });
@@ -2134,7 +2177,8 @@ export async function runWait(argv, { recoveryLocalWaitId = null } = {}) {
     // 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") {
+    // BOT-2360: likewise `abandoned` — the relay refused the stream because the row is ended.
+    if (waitSessionId && !SERVER_ENDED_OUTCOMES.has(receipt.outcome)) {
       const finalized = await finalizeWait(opts, waitSessionId, terminalReceipt);
       try {
         checkpoint = await store.update(checkpoint.local_wait_id, finalized.delivered