@botbuddy/cli 1.2.3 → 1.4.1

package/src/wait-core.mjs

@@ -0,0 +1,1266 @@
+// BOT-989 / BOT-1344 — public `botbuddy wait` pure engine.
+//
+// Everything in this module is dependency-free (Node >= 20 stdlib only) and
+// side-effect-free, so it runs in a fresh worktree with no `node_modules`
+// (BOT-904 lesson) and is exhaustively unit-testable without a server, a
+// database, or Docker. The network/main loop in scripts/bb-wait.mjs supplies a
+// real `connect()`; the wait SEMANTICS live here and are driven by an injected
+// `connect()` in tests.
+
+export const SCHEMA_VERSION = 1;
+
+// Stable process exit codes — the whole point of a silent-until-terminal wait
+// is that the caller reads the exit code, not a stream of chatter.
+export const EXIT = Object.freeze({
+  MATCHED: 0,
+  TIMEOUT: 2,
+  AUTH: 3,
+  INVALID: 4,
+  BACKEND: 5,
+  CURSOR_EXPIRED: 6,
+  INTERNAL: 7,
+  // BOT-1228: the wait was superseded server-side (a canonicalization / host rename
+  // marked its wait_session terminal). Distinct from a match or a plain timeout so the
+  // caller can tell "re-register under the new identity" apart from "your condition
+  // fired" — the harness re-invokes bb-wait on exit, which re-registers canonically.
+  SUPERSEDED: 8,
+});
+
+// BOT-1249: the internal CONTROL signal_type the reconciler emits when a wait's
+// resource identity is canonicalized away. runWaitLoop treats a wait_superseded frame
+// targeting its OWN wait_session as terminal (exit 8) before matchFrame sees it. It is
+// deliberately NOT in SIGNAL_TYPES: that list is the USER-ARMABLE allowlist
+// VALIDATORS.event checks, and a control signal must never be armable via
+// `event:type=wait_superseded` — a sibling session's supersession (ignored by the
+// own-session terminal branch because its wait_session_id differs) would otherwise match
+// that raw event condition and exit an unrelated wait as an ordinary match (Codex P2).
+export const WAIT_SUPERSEDED_SIGNAL_TYPE = "wait_superseded";
+
+// The USER-ARMABLE spine signal_type allowlist, for the `event:` escape hatch. The full
+// public.agent_signal_type enum is these PLUS the control types above
+// (WAIT_SUPERSEDED_SIGNAL_TYPE) — control types are intentionally excluded here so they
+// can't be armed on.
+export const SIGNAL_TYPES = Object.freeze([
+  "ci_run",
+  "pr_review",
+  "pr_state",
+  "linear_issue",
+  "chat_message",
+  "lock_availability",
+  "container_capacity",
+  "test_run",
+  "guidance_response",
+  "staging_gate",
+  "snapshot",
+  "ticket_unblocked",
+  "stack_lease",
+]);
+
+const LOCK_SUBTYPES = Object.freeze(["playwright_lane", "vite_port", "backend_port", "supabase_local"]);
+
+// ---------------------------------------------------------------------------
+// Condition grammar: `TYPE:key=val,key=val`
+// ---------------------------------------------------------------------------
+
+function parseParams(raw) {
+  const params = {};
+  for (const pair of raw.split(",")) {
+    const trimmed = pair.trim();
+    if (trimmed === "") continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) {
+      params[trimmed] = true; // bare flag
+      continue;
+    }
+    params[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return params;
+}
+
+function asBool(v) {
+  if (v === true) return true;
+  if (typeof v !== "string") return false;
+  return v === "true" || v === "1" || v === "yes";
+}
+
+// Validators return a normalized params object or throw an Error with a
+// human-actionable message. One validator per condition type.
+const VALIDATORS = {
+  timer(p) {
+    const hasDuration = p.duration !== undefined;
+    const hasDeadline = p.deadline !== undefined;
+    if (hasDuration === hasDeadline) {
+      throw new Error("timer needs exactly one of duration=<seconds> or deadline=<ISO>");
+    }
+    if (hasDuration) {
+      const n = Number(p.duration);
+      if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+        throw new Error("timer duration must be a positive integer number of seconds");
+      }
+      return { duration: n };
+    }
+    if (Number.isNaN(Date.parse(p.deadline))) {
+      throw new Error("timer deadline must be an ISO-8601 date-time");
+    }
+    return { deadline: p.deadline };
+  },
+  chat(p) {
+    if (!p.channel) throw new Error("chat needs channel=<id> or channel=*");
+    return { channel: String(p.channel), includeSelf: asBool(p.include_self) };
+  },
+  lock(p) {
+    if (!p.subtype) throw new Error("lock needs subtype=<" + LOCK_SUBTYPES.join("|") + ">");
+    if (!LOCK_SUBTYPES.includes(p.subtype)) {
+      throw new Error(`lock subtype must be one of ${LOCK_SUBTYPES.join(", ")}`);
+    }
+    if (!p.host) throw new Error("lock needs host=<hostname>");
+    // claim=true = ATOMIC claim-on-grant (BOT-1007): the server promotes the
+    // oldest live queued waiter to owner on release/reap and emits a grant signal
+    // targeted at that agent (payload.claim_granted=true), so the wait wakes
+    // already HOLDING the lock — no broadcast race. It presupposes the agent has
+    // already queued for the lock (acquire_lock while it was held); the grant
+    // promotes that queued row. claim=false (default) just waits for the lock to
+    // become free and leaves acquiring to the caller.
+    const claim = asBool(p.claim);
+    if (claim && p.slot === undefined) {
+      throw new Error("lock claim=true needs a specific slot=<n> (a grant hands you one named slot, not any-slot-on-host)");
+    }
+    return {
+      subtype: p.subtype,
+      host: String(p.host),
+      slot: p.slot !== undefined ? String(p.slot) : null,
+      claim,
+    };
+  },
+  "pr-state": (p) => parsePrTarget(p, "pr-state"),
+  "pr-review": (p) => parsePrTarget(p, "pr-review"),
+  // BOT-1063 — test-run: park on a test_run reaching a terminal status. The
+  // spine subject_key is `run:<id>` (mirrors the run:<id> convention noted on
+  // agent_signal_events.subject_key), so a condition just names the run id.
+  "test-run": (p) => {
+    if (!p.id) throw new Error("test-run needs id=<run_id>");
+    return { runId: String(p.id) };
+  },
+  // BOT-1063 — guidance: park on a command-post guidance RESPONSE to a request
+  // this agent raised (pairs with request_guidance). The signal is
+  // recipient-scoped to the requester and keyed by the request id.
+  guidance(p) {
+    if (!p.request) throw new Error("guidance needs request=<request_id>");
+    return { request: String(p.request) };
+  },
+  // BOT-1220 — lease: park on a batch stack lease (BOT-1218) leaving the queue /
+  // becoming active, so `botbuddy stack up` on a saturated host wakes zero-poll the
+  // instant it's granted in BOT-1187 order. The signal is recipient-scoped to the
+  // lease's owning agent and keyed `lease:<lease_id>` (mirrors the run:<id> shape).
+  lease(p) {
+    if (!p.id) throw new Error("lease needs id=<lease_id>");
+    return { id: String(p.id) };
+  },
+  // BOT-1064 — linear: wake on a logical state change of a named BOT-* issue.
+  // The spine subject_key is the issue identifier as stored on the tickets
+  // projection (upper-cased at write), so normalize to upper-case here too.
+  linear(p) {
+    if (!p.issue) throw new Error("linear needs issue=<KEY> (e.g. issue=BOT-123)");
+    const issue = String(p.issue).trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9]*-\d+$/.test(issue)) {
+      throw new Error("linear issue must be a ticket key like BOT-123");
+    }
+    return { issue };
+  },
+  // BOT-1065 — capacity: wake when a managed-container host reaches >= N free
+  // slots. Capacity is host-shared (no tenant), so `policy` is recorded for intent
+  // but matching is by free-slot threshold + optional host pin. `slots>=N` parses
+  // as the bare key `slots>` (parseParams splits on the first '='); `min_slots=N`
+  // is an alias. `stale_grace` bounds the wait: with no host beacon in the schema,
+  // if the threshold isn't reached within the grace the wait exits
+  // capacity_source_stale (degraded) rather than hanging forever.
+  capacity(p) {
+    if (!p.policy) throw new Error("capacity needs policy=<name>");
+    const rawMin = p["slots>"] ?? p.min_slots ?? p.slots;
+    if (rawMin === undefined) throw new Error("capacity needs slots>=<N> (e.g. slots>=1)");
+    const n = Number(rawMin);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+      throw new Error("capacity slots>= must be a positive integer");
+    }
+    const grace = p.stale_grace !== undefined ? Number(p.stale_grace) : 900;
+    if (!Number.isFinite(grace) || !Number.isInteger(grace) || grace <= 0) {
+      throw new Error("capacity stale_grace must be a positive integer number of seconds");
+    }
+    return {
+      policy: String(p.policy),
+      minSlots: n,
+      host: p.host !== undefined ? String(p.host) : null,
+      staleGraceSec: grace,
+    };
+  },
+  // BOT-1066 — ci: wake when a PR's CI reaches a terminal conclusion. Exactly one
+  // selector: scope=latest (follows the PR's latest run — needs pr=), run_id=<id>
+  // (pinned to one run), or sha=<sha> (pinned to a commit). repo= is always required.
+  ci(p) {
+    const repo = p.repo != null ? String(p.repo).trim() : null;
+    if (!repo || !repo.includes("/")) throw new Error("ci needs repo=<owner/repo>");
+    const selectors = ["scope", "run_id", "sha"].filter((k) => p[k] !== undefined);
+    if (selectors.length !== 1) {
+      throw new Error("ci needs exactly one of scope=latest | run_id=<id> | sha=<sha>");
+    }
+    if (p.scope !== undefined) {
+      if (p.scope !== "latest") throw new Error("ci scope must be 'latest' (or use run_id=/sha=)");
+      if (p.pr === undefined || !/^\d+$/.test(String(p.pr).trim())) {
+        throw new Error("ci scope=latest needs pr=<number>");
+      }
+      return { repo, scope: "latest", pr: String(p.pr).trim() };
+    }
+    if (p.run_id !== undefined) {
+      if (!String(p.run_id).trim()) throw new Error("ci run_id must be non-empty");
+      return { repo, scope: "run_id", runId: String(p.run_id).trim(), pr: p.pr != null ? String(p.pr).trim() : null };
+    }
+    if (!String(p.sha).trim()) throw new Error("ci sha must be non-empty");
+    return { repo, scope: "sha", sha: String(p.sha).trim(), pr: p.pr != null ? String(p.pr).trim() : null };
+  },
+  // BOT-1247 — unblocked: wake when a ticket's LAST open blocker clears (its
+  // open-blocker count transitions >0 → 0). Level-triggered: a ticket already
+  // unblocked (or never blocked) at registration is granted immediately with
+  // receipt reason `already_unblocked` (server-side eval_initial_wait_signals).
+  // Accepts the bare `unblocked:BOT-123` form the docs prescribe as well as the
+  // canonical `unblocked:ticket=BOT-123`. Tenant-scoped like `linear`.
+  unblocked(p) {
+    let ticket = p.ticket !== undefined ? String(p.ticket) : null;
+    if (ticket == null) {
+      // Bare form `unblocked:BOT-123` → parseParams yields { 'BOT-123': true }.
+      const bareKeys = Object.keys(p).filter((k) => p[k] === true);
+      if (bareKeys.length === 1) ticket = bareKeys[0];
+    }
+    if (!ticket) {
+      throw new Error("unblocked needs a ticket key, e.g. unblocked:BOT-123 (or unblocked:ticket=BOT-123)");
+    }
+    ticket = ticket.trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9]*-\d+$/.test(ticket)) {
+      throw new Error("unblocked ticket must be a ticket key like BOT-123");
+    }
+    return { ticket };
+  },
+  event(p) {
+    if (!p.type) throw new Error("event needs type=<signal_type>");
+    if (!SIGNAL_TYPES.includes(p.type)) {
+      throw new Error(`event type must be a known signal_type (${SIGNAL_TYPES.join(", ")})`);
+    }
+    return { type: p.type, subject: p.subject !== undefined ? String(p.subject) : null };
+  },
+};
+
+// pr-state / pr-review share a target grammar. The spine subject_key is
+// `owner/repo#number` (github-webhook / pr_state read model convention), so a
+// condition names an owner/repo and, optionally, a PR number. Accept three forms:
+//   repo=owner/repo,pr=123     — canonical
+//   pr=owner/repo#123          — combined convenience
+//   repo=owner/repo            — repo wildcard: wake on ANY of your PRs there
+// Omitting the number is the PR analogue of a lock condition without a slot.
+function parsePrTarget(p, label) {
+  let repo = p.repo != null ? String(p.repo).trim() : null;
+  let number = p.pr != null ? String(p.pr).trim()
+    : (p.number != null ? String(p.number).trim() : null);
+  // A combined `owner/repo#123` may arrive via either key; split off the number.
+  const carrier = number != null && number.includes("#") ? "number"
+    : (repo != null && repo.includes("#") ? "repo" : null);
+  if (carrier === "number") {
+    const hash = number.indexOf("#");
+    if (!repo) repo = number.slice(0, hash).trim();
+    number = number.slice(hash + 1).trim();
+  } else if (carrier === "repo") {
+    const hash = repo.indexOf("#");
+    if (number == null) number = repo.slice(hash + 1).trim();
+    repo = repo.slice(0, hash).trim();
+  }
+  if (!repo || !repo.includes("/")) {
+    throw new Error(`${label} needs repo=<owner/repo> (optionally pr=<number>, or pr=<owner/repo#number>)`);
+  }
+  if (number != null && number !== "" && !/^\d+$/.test(number)) {
+    throw new Error(`${label} pr number must be an integer`);
+  }
+  return { repo, number: number != null && number !== "" ? number : null };
+}
+
+// Does a spine subject_key (`owner/repo#number`) satisfy a pr target?
+function prSubjectMatches(subjectKey, params) {
+  if (typeof subjectKey !== "string") return false;
+  if (params.number != null) return subjectKey === `${params.repo}#${params.number}`;
+  return subjectKey.startsWith(`${params.repo}#`);
+}
+
+/**
+ * Parse and strictly validate a list of `TYPE:params` condition specs.
+ *
+ * On ANY validation failure, `conditions` is empty: partial arming is
+ * forbidden (a half-armed wait is worse than a rejected one). Each failure is
+ * reported with the offending spec and a message.
+ *
+ * @param {string[]} specs
+ * @returns {{conditions: object[], errors: {spec: string, message: string}[]}}
+ */
+export function parseConditions(specs) {
+  const errors = [];
+  const conditions = [];
+
+  if (!Array.isArray(specs) || specs.length === 0) {
+    return { conditions: [], errors: [{ spec: "", message: "at least one condition is required" }] };
+  }
+
+  specs.forEach((spec, index) => {
+    const colon = String(spec).indexOf(":");
+    const type = (colon === -1 ? String(spec) : String(spec).slice(0, colon)).trim();
+    const rawParams = colon === -1 ? "" : String(spec).slice(colon + 1);
+
+    const validator = VALIDATORS[type];
+    if (!validator) {
+      errors.push({ spec, message: `unknown condition type: ${type || "(empty)"}` });
+      return;
+    }
+    try {
+      const params = validator(parseParams(rawParams));
+      conditions.push({ id: `c${index + 1}`, type, params });
+    } catch (err) {
+      errors.push({ spec, message: err.message });
+    }
+  });
+
+  // A claim=true lock must be the SOLE condition. Server-side, a grant atomically
+  // hands over the lock and marks the wait matched; but the client independently
+  // wakes on whichever frame arrives first, so an --any wait mixing a claim with a
+  // timer/chat/pr condition could wake (and exit) on the OTHER condition while the
+  // server has already granted the lock — leaving the agent silently holding it.
+  // There is no single arbitration point across the two deciders, so we forbid the
+  // combination: a claim wait blocks until it's handed the lock (with --timeout as
+  // the only escape). claim=false locks and every other type still combine freely.
+  if (errors.length === 0) {
+    const claims = conditions.filter((c) => c.type === "lock" && c.params.claim);
+    if (claims.length > 0 && conditions.length > 1) {
+      errors.push({
+        spec: claims[0] ? `${claims[0].type}:...claim=true` : "claim",
+        message: "a lock claim=true must be the only condition (it can't be raced against other conditions; use --timeout to bound the wait)",
+      });
+    }
+  }
+
+  // Fail-closed: never arm a subset.
+  if (errors.length > 0) return { conditions: [], errors };
+  return { conditions, errors };
+}
+
+// ---------------------------------------------------------------------------
+// SSE frame parsing — split-safe, keepalive-aware, multi-line data.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse whatever complete SSE frames are present in `buffer`, returning them
+ * plus the unconsumed remainder (an incomplete trailing frame) to prepend to
+ * the next chunk. Comment/keepalive lines (starting `:`) are ignored.
+ *
+ * @param {string} buffer
+ * @returns {{frames: {id: string|null, event: string|null, data: string}[], rest: string}}
+ */
+export function parseSseFrames(buffer) {
+  const frames = [];
+  // Frames are separated by a blank line.
+  let idx;
+  let remaining = buffer;
+  while ((idx = remaining.indexOf("\n\n")) !== -1) {
+    const block = remaining.slice(0, idx);
+    remaining = remaining.slice(idx + 2);
+
+    let id = null;
+    let event = null;
+    const dataLines = [];
+    for (const line of block.split("\n")) {
+      if (line === "" || line.startsWith(":")) continue; // keepalive / comment
+      const colon = line.indexOf(":");
+      const field = colon === -1 ? line : line.slice(0, colon);
+      let value = colon === -1 ? "" : line.slice(colon + 1);
+      if (value.startsWith(" ")) value = value.slice(1);
+      if (field === "id") id = value;
+      else if (field === "event") event = value;
+      else if (field === "data") dataLines.push(value);
+    }
+    if (dataLines.length > 0 || id !== null || event !== null) {
+      frames.push({ id, event, data: dataLines.join("\n") });
+    }
+  }
+  return { frames, rest: remaining };
+}
+
+// ---------------------------------------------------------------------------
+// Cursor — the spine `seq` is a non-negative integer; reject garbage loudly.
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string|null|undefined} raw
+ * @returns {{kind: "absent"} | {kind: "ok", value: string} | {kind: "invalid", raw: string}}
+ */
+export function normalizeSince(raw) {
+  if (raw == null) return { kind: "absent" };
+  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)) };
+}
+
+// ---------------------------------------------------------------------------
+// Backoff — exponential with full jitter, capped.
+// ---------------------------------------------------------------------------
+
+export function nextBackoff(attempt, { baseMs = 500, capMs = 15000, rng = Math.random } = {}) {
+  const exp = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(rng() * (exp - baseMs)) + Math.min(baseMs, exp);
+}
+
+// ---------------------------------------------------------------------------
+// Receipt — the single JSON line handed back at terminal.
+// ---------------------------------------------------------------------------
+
+export function buildReceipt({
+  waitSessionId,
+  outcome,
+  startedAt,
+  endedAt,
+  reconnects = 0,
+  degraded = [],
+  matched = [],
+  state = {},
+  nextCursor = "0",
+  error = null,
+  // BOT-1228 (Codex round-4 P2): the claim re-queue hint lives at the TOP LEVEL, not in
+  // `state`, so truncateReceipt (which can collapse `state` to a marker under a small
+  // --receipt-max-bytes) never strips the only machine-readable "re-acquire the lock"
+  // instruction. It is tiny — a claim=true lock must be the SOLE condition, so this is
+  // at most one {subtype,host,slot}.
+  reacquireLock = null,
+}) {
+  const r = {
+    schema_version: SCHEMA_VERSION,
+    wait_session_id: waitSessionId ?? null,
+    outcome,
+    started_at: startedAt ?? null,
+    ended_at: endedAt ?? null,
+    reconnects,
+    degraded,
+    matched,
+    state,
+    next_cursor: nextCursor,
+  };
+  if (error) r.error = error;
+  if (Array.isArray(reacquireLock) && reacquireLock.length > 0) r.reacquire_lock = reacquireLock;
+  return r;
+}
+
+/**
+ * Enforce the receipt byte cap. Oversized matched-payloads collapse to a
+ * pointer (the `seq`, plus a `payload_truncated` marker); the caller re-fetches
+ * detail with the existing get_* tools if it needs the body.
+ */
+export function truncateReceipt(receipt, maxBytes = 10240) {
+  if (Buffer.byteLength(JSON.stringify(receipt)) <= maxBytes) return receipt;
+  const clone = JSON.parse(JSON.stringify(receipt));
+  for (const m of clone.matched ?? []) {
+    if (m.payload !== undefined) {
+      delete m.payload;
+      m.payload_truncated = true;
+    }
+  }
+  // If still over cap, drop the (potentially large) state snapshot to a marker.
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes) {
+    clone.state = { truncated: true };
+  }
+  // A matched signal's subject key can be caller-controlled through the raw
+  // event escape hatch. Keep the durable sequence pointer, but not an
+  // unbounded subject string, in a receipt promised to a bounded harness.
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && Array.isArray(clone.matched)) {
+    for (const match of clone.matched) {
+      if (typeof match?.subject_key === "string" && Buffer.byteLength(match.subject_key, "utf8") > 128) {
+        delete match.subject_key;
+        match.subject_key_truncated = true;
+      }
+    }
+  }
+  // Metadata added by public consumers (for example the CLI identity and
+  // tenant-attested principal) can push a previously-capped receipt just over
+  // the caller's boundary. Trim only null/default diagnostics next, preserving
+  // the terminal outcome and match pointer.
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.next_cursor == null) delete clone.next_cursor;
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.wait_session_id == null) delete clone.wait_session_id;
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && Array.isArray(clone.degraded) && clone.degraded.length === 0) {
+    delete clone.degraded;
+  }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.reconnects === 0) delete clone.reconnects;
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && Array.isArray(clone.matched)) {
+    clone.matched = clone.matched.map((match) => ({
+      condition_id: match?.condition_id ?? null,
+      signal_type: typeof match?.signal_type === "string" && Buffer.byteLength(match.signal_type, "utf8") <= 128
+        ? match.signal_type
+        : undefined,
+      seq: match?.seq ?? null,
+      match_truncated: true,
+    }));
+  }
+  // Argument and registration failures are receipts too. Their nested errors
+  // or server detail may contain arbitrary caller-controlled strings, so reduce
+  // those before handing one line back to a bounded agent harness.
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && Array.isArray(clone.errors)) {
+    delete clone.errors;
+    clone.errors_truncated = true;
+  }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && typeof clone.detail === "string") {
+    delete clone.detail;
+    clone.detail_truncated = true;
+  }
+  if (Buffer.byteLength(JSON.stringify(clone)) > maxBytes && clone.outcome === "error") {
+    return {
+      schema_version: clone.schema_version,
+      outcome: "error",
+      error: typeof clone.error === "string" ? clone.error.slice(0, 48) : "receipt_truncated",
+      truncated: true,
+      ...(clone.client ? { client: clone.client } : {}),
+    };
+  }
+  return clone;
+}
+
+// ---------------------------------------------------------------------------
+// BOT-1147 — feed-lag degradation marker (add/clear).
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold a Linear-feed-freshness reading into the receipt's `degraded` array,
+ * IN PLACE. `linear_feed_lagging` is added when the ingest feed is stale and
+ * REMOVED when it recovers — so a long-lived wait reports a lagging feed while
+ * it lags and stops reporting it on recovery, WITHOUT re-registration (BOT-1147
+ * AC-3). Idempotent: repeated same-state readings don't duplicate or thrash.
+ * @param {string[]} degraded  the receipt's degraded markers (mutated)
+ * @param {boolean|null|undefined} lagging  true = stale, false = fresh, and
+ *   null/undefined = INDETERMINATE (a failed probe): leave the last known state
+ *   untouched rather than clearing it (Codex BOT-1147 P2 — a transient probe
+ *   outage must not make a known-stale feed look healthy).
+ */
+export function foldFeedLag(degraded, lagging) {
+  if (lagging !== true && lagging !== false) return degraded; // indeterminate: no change
+  const i = degraded.indexOf("linear_feed_lagging");
+  if (lagging && i === -1) degraded.push("linear_feed_lagging");
+  else if (!lagging && i !== -1) degraded.splice(i, 1);
+  return degraded;
+}
+
+// ---------------------------------------------------------------------------
+// Matching — does a spine signal frame satisfy a condition?
+// ---------------------------------------------------------------------------
+
+function decodeSignal(frame) {
+  try {
+    return JSON.parse(frame.data);
+  } catch {
+    return null;
+  }
+}
+
+function conditionMatchesSignal(condition, signal, waitSessionId) {
+  const { type, params } = condition;
+  switch (type) {
+    case "timer":
+      return false; // timers fire on the deadline, never on a frame
+    case "chat":
+      return signal.signal_type === "chat_message" &&
+        (params.channel === "*" || signal.subject_key === params.channel);
+    case "lock": {
+      if (signal.signal_type !== "lock_availability") return false;
+      // A grant signal (claim_granted=true) is the server handing this specific
+      // waiter the lock; a plain availability is a broadcast. claim=true wants
+      // ONLY the grant; claim=false wants ONLY the broadcast. The grant is also
+      // recipient-scoped at the relay, so a broadcast waiter never even receives
+      // another agent's grant — this is the defense-in-depth in-code check.
+      const isGrant = signal.payload?.claim_granted === true;
+      if (params.claim !== isGrant) return false;
+      // A grant belongs to the exact wait_session it was issued for. `--since`
+      // can replay an OLDER grant for the same agent+lock (a prior, now-terminal
+      // wait); accepting it would let this new registration exit "holding" a lock
+      // it was never handed. Require the grant's wait_session_id to equal THIS
+      // registration's before treating it as ownership (Codex P1).
+      if (isGrant && signal.payload?.wait_session_id !== waitSessionId) return false;
+      if (params.slot != null) {
+        return signal.subject_key === `${params.subtype}:${params.host}:${params.slot}`;
+      }
+      // No slot ⇒ any slot on that host+subtype.
+      return signal.subject_key.startsWith(`${params.subtype}:${params.host}:`);
+    }
+    case "pr-state":
+      return signal.signal_type === "pr_state" && prSubjectMatches(signal.subject_key, params);
+    case "pr-review":
+      return signal.signal_type === "pr_review" && prSubjectMatches(signal.subject_key, params);
+    case "test-run":
+      return signal.signal_type === "test_run" && signal.subject_key === `run:${params.runId}`;
+    case "guidance":
+      return signal.signal_type === "guidance_response" && signal.subject_key === params.request;
+    case "lease":
+      // BOT-1220: recipient-scoped stack-lease transition (queued→provisioning, or
+      // →active). The relay only delivers it to the lease's owning agent, so any
+      // stack_lease frame for this lease id is ours to wake on.
+      return signal.signal_type === "stack_lease" && signal.subject_key === `lease:${params.id}`;
+    case "linear": {
+      if (signal.signal_type !== "linear_issue") return false;
+      // Identity (BOT-1260): prefer the STABLE Linear issue UUID when BOTH the wait
+      // (stamped at registration from the current `tickets` row) and the signal (emit
+      // payload) carry it, so an in-flight wait survives an external_id rename / team move
+      // (rename-proof) and a NEW issue that recycled the old key can't wake it (recycle-proof
+      // — a UUID mismatch beats key equality and short-circuits). Fall back to subject_key
+      // equality for a legacy signal row without `payload.linear_issue_id` (a `--since` replay
+      // of pre-migration rows) or an unresolvable registration that stamped no UUID (the key is
+      // not yet mirrored in `tickets`) — additive and deploy-order independent. Cross-tenant
+      // isolation rides on the BOT-1259 central guard (sessionTenant), so — unlike `unblocked`
+      // — a `linear` wait is NEVER failed closed on a missing stamp (back-compat: it worked
+      // key-only before this ticket). Mirrors the `unblocked` matcher shape below.
+      if (params.linear_issue_id != null && signal.payload?.linear_issue_id != null) {
+        return signal.payload.linear_issue_id === params.linear_issue_id;
+      }
+      return signal.subject_key === params.issue;
+    }
+    case "capacity": {
+      if (signal.signal_type !== "container_capacity") return false;
+      // Optional host pin: match the subject (host_key) or the payload host_key.
+      if (params.host != null && signal.subject_key !== params.host && signal.payload?.host_key !== params.host) {
+        return false;
+      }
+      // BOT-1148: a beacon-driven staleness transition (source_stale:true) is a
+      // dead-host signal, never a grant — a silently-dead host's derived free_slots
+      // cannot actually be served. The wait loop handles it separately (fold the
+      // capacity_source_stale marker / fast exit); it must not read as capacity here.
+      if (signal.payload?.source_stale === true) return false;
+      const free = Number(signal.payload?.free_slots);
+      return Number.isFinite(free) && free >= params.minSlots;
+    }
+    case "ci": {
+      if (signal.signal_type !== "ci_run") return false;
+      // Repo is pinned via the payload (subject may be run:<id> for uncorrelated runs).
+      if (String(signal.payload?.repo ?? "").toLowerCase() !== params.repo.toLowerCase()) return false;
+      if (params.scope === "run_id") return String(signal.payload?.run_id) === params.runId;
+      if (params.scope === "sha") return signal.payload?.head_sha === params.sha;
+      // scope=latest: the PR's run (by subject owner/repo#pr or payload pr_number).
+      return signal.subject_key === `${params.repo}#${params.pr}` ||
+        (signal.payload?.pr_number != null && String(signal.payload.pr_number) === params.pr);
+    }
+    case "unblocked": {
+      // Wakes on the ticket_unblocked spine signal for this ticket (the server emits both
+      // the genuine >0→0 transition and the level-triggered `already_unblocked` echo).
+      if (signal.signal_type !== "ticket_unblocked") return false;
+      // Tenant scope, FAIL CLOSED (Codex round-9 P1 + round-10 P1): two workspaces can each
+      // hold a ticket keyed `BOT-123`, and the relay legitimately streams ticket_unblocked
+      // from BOTH (the caller is authorized for both). The server stamps the wait's resolved
+      // workspace onto `params.tenant`; require the signal's tenant to match it. If NO tenant
+      // was stamped — an unblocked wait that armed untracked after a transient register_failed,
+      // or an older relay that echoes none — do NOT fall back to subject-only matching (that
+      // would wake on the wrong workspace's unblock): no tenant ⇒ no match.
+      if (params.tenant == null || signal.tenant_id !== params.tenant) return false;
+      // Identity (Codex round-10 P2): prefer the STABLE Linear issue UUID when both the wait
+      // (stamped at registration) and the signal (genuine emit payload) carry it, so an
+      // in-flight wait survives an external_id rename (issue moved Linear teams). The
+      // initial-eval echo carries no linear_issue_id and has no rename risk (it is
+      // immediate), so it falls back to the ticket key.
+      if (params.linear_issue_id != null && signal.payload?.linear_issue_id != null) {
+        return signal.payload.linear_issue_id === params.linear_issue_id;
+      }
+      return signal.subject_key === params.ticket;
+    }
+    case "event":
+      return signal.signal_type === params.type &&
+        (params.subject == null || signal.subject_key === params.subject);
+    default:
+      return false;
+  }
+}
+
+// BOT-1259: the ONE central tenant guard, applied before per-type dispatch. A
+// TENANTED spine signal (tenant_id set — linear_issue, ticket_unblocked, and any
+// tenant-stamped pr_review/ci_run) may only match a wait session resolved to that
+// SAME tenant; a session whose tenant is unknown (null) or different fails closed,
+// so no signal type — current or future, including the `event:` escape hatch — can
+// wake the wrong workspace. This centralizes what BOT-1247's `unblocked` matcher did
+// per-type (that per-type check stays as belt-and-braces). Tenantless signals
+// (host-shared lock_availability/container_capacity, owner/recipient-scoped
+// chat/pr_state/test_run/guidance) are NEVER blocked — they keep today's semantics
+// for any session (AC-5). `sessionTenant === undefined` opts a caller out of the
+// central guard: a pure unit test asserting a per-type matcher in isolation. The CLI
+// always threads the server-resolved tenant, so the guard is live for every real wait.
+export function signalTenantBlocked(signal, sessionTenant) {
+  if (sessionTenant === undefined) return false;
+  if (signal.tenant_id == null) return false;
+  // Mirror the relay's precedence (recipient > owner > tenant): a signal that is
+  // owner- or recipient-scoped keeps THAT isolation and is never tenant-fenced, even
+  // though owner-scoped pr_review/ci_run also carry a tenant_id — otherwise a caller who
+  // owns PRs in two workspaces would lose the authorized event for the workspace the wait
+  // didn't bind to (Codex R2-F1). `scope` is stamped by the relay; when it is absent (a
+  // pre-BOT-1259 relay, deploy skew), fall back to fencing any tenanted signal — fail closed.
+  if (signal.scope === "owner" || signal.scope === "recipient") return false;
+  return signal.tenant_id !== sessionTenant;
+}
+
+/**
+ * Return the first condition satisfied by this signal frame, or null.
+ * `waitSessionId` scopes claim grants to the current registration.
+ * `sessionTenant` (BOT-1259) is the wait session's server-resolved tenant; a
+ * tenanted signal only matches when it equals it (fail closed on null/mismatch).
+ * Omit it (undefined) to skip the central guard — see `signalTenantBlocked`.
+ * @returns {object|null}
+ */
+export function matchFrame(frame, conditions, waitSessionId, sessionTenant) {
+  const signal = decodeSignal(frame);
+  if (!signal) return null;
+  if (signalTenantBlocked(signal, sessionTenant)) return null;
+  for (const c of conditions) {
+    if (conditionMatchesSignal(c, signal, waitSessionId)) return c;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// The wait loop.
+// ---------------------------------------------------------------------------
+
+const nowIso = () => new Date().toISOString();
+
+// BOT-1147 (Codex P2): hard bound on how long a single Linear feed-freshness probe may
+// delay the wait — it runs before connecting and on every terminal finalize, outside the
+// deadline race, so an unbounded probe would blow past a short --timeout.
+const FEED_PROBE_BUDGET_MS = 2000;
+
+/**
+ * Run one wait to a terminal outcome, driven by an injected `connect(since)`
+ * that returns an async iterable of parsed SSE frames.
+ *
+ * Guarantees exercised by the tests:
+ *   - wakes on the first matching frame (MATCHED)
+ *   - fires on the wall deadline with a snapshot receipt (TIMEOUT)
+ *   - reconnects when the stream ends, resuming from the last seen seq, and
+ *     de-duplicates a repeated seq across the reconnect (exactly-once)
+ *   - maps server error frames to AUTH / CURSOR_EXPIRED
+ *   - gives up with BACKEND after the reconnect budget is exhausted
+ *
+ * @returns {Promise<{receipt: object, exitCode: number}>}
+ */
+/**
+ * Convert the `timer:` conditions into absolute-time alarms. A timer condition
+ * is a thing the caller ASKED to wake on, so it resolves to `matched` (exit 0) —
+ * distinct from the `--timeout` safety cap, which is `timeout` (exit 2).
+ * @returns {{conditionId: string, atMs: number}[]}
+ */
+export function timerAlarms(conditions, now = Date.now) {
+  const alarms = [];
+  for (const c of conditions) {
+    if (c.type !== "timer") continue;
+    if (c.params.duration != null) alarms.push({ conditionId: c.id, atMs: now() + c.params.duration * 1000 });
+    else if (c.params.deadline != null) alarms.push({ conditionId: c.id, atMs: Date.parse(c.params.deadline) });
+  }
+  return alarms;
+}
+
+export async function runWaitLoop({
+  waitSessionId,
+  conditions,
+  deadlineMs = null,
+  timers = null,
+  since = null,
+  connect,
+  backoff = (attempt) => nextBackoff(attempt),
+  sleep = null,
+  onFrame = null,
+  // BOT-1259: the wait session's server-resolved tenant (from the register echo). A
+  // tenanted spine signal only matches a session resolved to that tenant; `null` (the
+  // session's tenant could not be resolved) fails closed, and `undefined` (the caller
+  // did not thread a tenant) leaves the central guard off — see `signalTenantBlocked`.
+  sessionTenant = undefined,
+  // BOT-1259 AC-4: optional sink (msg:string) => void for the fail-closed drop line —
+  // a debug diagnostic, never an error. The CLI wires a stderr writer gated on
+  // BB_WAIT_DEBUG; tests inject a collector to assert the line.
+  debug = null,
+  maxReconnects = 50,
+  receiptMaxBytes = 10240,
+  now = Date.now,
+  // BOT-1147 AC-3: a `linear` wait truthfully degrades when the Linear webhook
+  // ingest feed stalls (the BOT-1016 silent-ingest failure mode). `feedLagProbe`
+  // is an async () => boolean (true = feed stale). It is polled once at start and
+  // on every (re)connect, and its reading folded into `degraded` (add on stale,
+  // clear on recovery). Injected so the CLI wires the real freshness query and a
+  // test drives it clock-controlled; omitted (null) = no probing.
+  feedLagProbe = null,
+  // BOT-1148: after a beacon-driven source_stale:true transition on a HOST-PINNED
+  // capacity wait, wait this long for a recovery (source_stale:false) before exiting
+  // capacity_source_stale. Absorbs threshold flap on the client (the server latch is
+  // the primary hysteresis); 0 = exit immediately on the stale signal. Injectable so
+  // a clock-controlled test can drive it. Not a grammar surface (no new condition name).
+  //
+  // Default MUST exceed the beacon evaluator's worst-case cadence (Codex P2). The
+  // recovery transition is emitted by the `* * * * *` (60s) eval_container_beacon_staleness
+  // cron, and claim_container_job only refreshes last_beacon_at — it does not itself emit
+  // recovery — so a host that resumes polling right after a stale emission has its
+  // recovery frame arrive up to ~60s later. A confirm shorter than that would exit the
+  // wait capacity_source_stale even though the host recovered seconds after the stale
+  // frame. 90s = 60s cron + margin.
+  beaconConfirmMs = 90_000,
+}) {
+  const startedAt = nowIso();
+  const seen = new Set();
+  // An omitted --since arms from the current high-water mark (live only): the
+  // relay must NOT replay history, or a brand-new wait would immediately match a
+  // long-past lock release. Only an explicit --since replays (cursor != null).
+  const sinceParsed = normalizeSince(since);
+  let cursor = sinceParsed.kind === "ok" ? sinceParsed.value : null;
+  const degraded = [];
+  let reconnects = 0;
+  let failures = 0;
+
+  // Internal one-shot alarms (the deadline, the pre-deadline feed probe, reconnect backoff)
+  // are REAL timers via the default sleep. Each exists only to resolve a race — once the loop
+  // terminates for any other reason (a granted frame, an error), a still-pending alarm timer
+  // would keep the event loop open until it expires. The CLI masks this with process.exit,
+  // but `pnpm test:bb-wait` and any library caller stay alive for the full window (Codex
+  // round-40 P2 measured ~92s vs ~6.5s). So track every default-sleep timer and clear the set
+  // at finalize. NOT unref'd: a pure --timeout wait (no signal, a test stream that refs
+  // nothing) relies on the deadline timer keeping the loop alive until it fires. An injected
+  // `sleep` (clock-controlled tests) resolves instantly and creates no timer to track.
+  const pendingAlarmTimers = new Set();
+  const sleepFn = sleep ?? ((ms) => new Promise((resolve) => {
+    const timer = setTimeout(() => { pendingAlarmTimers.delete(timer); resolve(); }, ms);
+    pendingAlarmTimers.add(timer);
+  }));
+  const clearPendingAlarmTimers = () => {
+    for (const timer of pendingAlarmTimers) clearTimeout(timer);
+    pendingAlarmTimers.clear();
+  };
+
+  const finalize = async (outcome, extra = {}) => {
+    // A terminal receipt supersedes any pending alarm/confirm window — cancel their timers so
+    // none outlives the wait and holds the event loop open (Codex round-40 P2). clearStale
+    // ConfirmTimer is defined further down but only reached at runtime, after setup completes.
+    clearPendingAlarmTimers();
+    clearStaleConfirmTimer?.();
+    // BOT-1147 (Codex P2): re-check Linear feed freshness before EVERY terminal receipt
+    // (timeout, capacity-stale, signal match, error) via this single finalization path —
+    // not just the alarm path — so a mixed wait (e.g. `linear` + `pr-review`) that
+    // terminates on the OTHER signal while Linear ingestion stalled still reports
+    // linear_feed_lagging. Cheap no-op unless a `linear` condition is armed; a failed
+    // probe leaves the last known lag state (foldFeedLag treats it as indeterminate).
+    await probeFeedLag();
+    const receipt = buildReceipt({
+      waitSessionId,
+      outcome,
+      startedAt,
+      endedAt: nowIso(),
+      reconnects,
+      degraded,
+      matched: extra.matched ?? [],
+      state: extra.state ?? { conditions: conditions.map((c) => ({ condition_id: c.id, type: c.type })) },
+      nextCursor: cursor,
+      error: extra.error ?? null,
+      reacquireLock: extra.reacquireLock ?? null,
+    });
+    return { receipt: truncateReceipt(receipt, receiptMaxBytes), exitCode: extra.exitCode };
+  };
+
+  // Fold the timer conditions and the --timeout cap into one earliest alarm.
+  // A timer condition firing is a MATCH (exit 0); the --timeout cap is a
+  // TIMEOUT (exit 2). With --any the earliest of the two always wins.
+  const alarms = (timers ?? timerAlarms(conditions, now))
+    .filter((a) => Number.isFinite(a.atMs))
+    .map((a) => ({ ...a, kind: "match" }));
+  if (deadlineMs != null) alarms.push({ kind: "timeout", atMs: deadlineMs });
+  // BOT-1065: a capacity condition degrades to a BOUNDED stale exit rather than
+  // hanging. There is no host self-report beacon in the schema (capacity is derived
+  // from permits), so we cannot observe silent helper death directly; the grace
+  // window is the truthful bound — if the requested free-slot threshold isn't
+  // reached within it, the wait exits with a capacity_source_stale error receipt
+  // (degraded) on an EXISTING exit code (5), never a new numeric code (AC 3).
+  for (const c of conditions) {
+    if (c.type === "capacity" && c.params.staleGraceSec != null) {
+      alarms.push({ kind: "stale", conditionId: c.id, atMs: now() + c.params.staleGraceSec * 1000 });
+    }
+  }
+  const earliest = alarms.length ? alarms.reduce((m, a) => (a.atMs < m.atMs ? a : m)) : null;
+
+  const fireAlarm = async () => {
+    // The terminal feed-freshness reprobe now lives in finalize() (the single
+    // finalization path), so every terminal receipt gets it — not just the alarm path.
+    if (!earliest) return null;
+    if (earliest.kind === "timeout") return finalize("timeout", { exitCode: EXIT.TIMEOUT });
+    if (earliest.kind === "stale") {
+      // Capacity source didn't deliver within the grace: degrade truthfully and
+      // exit with an error receipt (not a silent hang, not a plain timeout).
+      if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
+      return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
+    }
+    const condition = conditions.find((c) => c.id === earliest.conditionId);
+    return finalize("matched", {
+      exitCode: EXIT.MATCHED,
+      matched: [{
+        condition_id: earliest.conditionId,
+        signal_type: "timer",
+        seq: null,
+        subject_key: condition?.params?.deadline ?? `+${condition?.params?.duration}s`,
+        provenance: "timer",
+      }],
+    });
+  };
+
+  // A single promise that resolves when the earliest alarm passes.
+  const deadlinePromise = earliest == null
+    ? new Promise(() => {}) // no alarm: only a pushed signal can wake us
+    : sleepFn(Math.max(0, earliest.atMs - now())).then(() => ({ __deadline: true }));
+
+  // BOT-1147 AC-3: only probe when a linear condition is armed and a probe is
+  // wired — every other wait type is unaffected.
+  const feedLagActive = !!feedLagProbe && conditions.some((c) => c.type === "linear");
+
+  // BOT-1147 (Codex round-27 P2): the finalize() reprobe is deadline-relative and so is
+  // SKIPPED on a plain timeout (budget 0 at the deadline). If the feed is fresh at
+  // registration then stalls while the SSE connection stays open (no reconnect), the
+  // timeout receipt would keep the stale-unaware initial state. So schedule ONE probe
+  // FEED_PROBE_BUDGET_MS before the earliest terminal — it observes a mid-wait stall
+  // (or recovery) with a full budget and folds it, and the timeout still fires on time.
+  // Fires at most once (a single pre-deadline probe, not a re-arming timer, so an
+  // injected instant `sleep` in tests can't spin the race).
+  let preDeadlineProbeDone = false;
+  const preDeadlineProbePromise = (feedLagActive && earliest != null)
+    ? sleepFn(Math.max(0, earliest.atMs - now() - FEED_PROBE_BUDGET_MS)).then(() => ({ __feedProbe: true }))
+    : null;
+  // The specific issue key(s) the armed `linear` conditions target. Threaded into
+  // the probe so it scopes freshness to those issues' workspace(s) rather than the
+  // caller's whole membership union — a multi-tenant caller's fresh tenant A must
+  // not mask a stalled tenant B when the armed issue belongs to B (Codex round-22 P2).
+  const linearIssues = conditions
+    .filter((c) => c.type === "linear")
+    .map((c) => c.params?.issue)
+    .filter((x) => typeof x === "string" && x.length > 0);
+  const probeFeedLag = async () => {
+    if (!feedLagActive) return;
+    // Bound the probe DEADLINE-RELATIVELY (Codex P2): it is awaited before connecting AND on
+    // every terminal finalize, OUTSIDE the deadline race, so an unbounded/fixed-bounded probe
+    // could push even a --timeout 50ms receipt seconds past its deadline. Cap each probe to
+    // min(FEED_PROBE_BUDGET_MS, time remaining to the soonest terminal) and SKIP it entirely
+    // once the deadline has already passed (e.g. the terminal reprobe after a timeout). Uses a
+    // REAL timer (not the injected sleep) so clock-controlled tests with an instant probe are
+    // unaffected; on expiry the reading is indeterminate and the last known lag state is kept.
+    const target = earliest ? earliest.atMs : (deadlineMs != null ? deadlineMs : null);
+    const remaining = target != null ? target - now() : FEED_PROBE_BUDGET_MS;
+    const budgetMs = Math.max(0, Math.min(FEED_PROBE_BUDGET_MS, remaining));
+    if (budgetMs <= 0) return; // deadline reached — do not overrun it; leave the last state
+    let timer;
+    const budget = new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), budgetMs); });
+    try {
+      foldFeedLag(degraded, await Promise.race([feedLagProbe(linearIssues), budget]));
+    } catch {
+      // A probe failure must not break the wait — leave the last known state.
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  // BOT-1148: server-side, beacon-driven capacity staleness. On a container_capacity
+  // frame carrying source_stale:true whose host matches a HOST-PINNED capacity wait,
+  // fold capacity_source_stale and — unless a recovery (source_stale:false) arrives
+  // within beaconConfirmMs — exit 5 fast (server-driven) instead of grinding the full
+  // client stale_grace backstop. Un-pinned capacity waits ignore a single host's
+  // beacon signal: another live host may still serve them (AC-4), so they keep only
+  // the grace backstop. A recovery clears the marker and lets the wait continue
+  // without re-registration (AC-3), and may itself grant if it carries free_slots.
+  const hostPinnedCapacity = conditions.filter((c) => c.type === "capacity" && c.params.host != null);
+  // PER-HOST stale-confirm state (Codex P2): keyed by the pinned host_key. A recovery
+  // from host B must never cancel host A's pending confirm — with a single shared timer,
+  // an --any wait pinned to multiple hosts would miss A's fast-fail when B recovers.
+  const staleConfirm = new Map();  // hostKey -> atMs the confirm window elapses
+  let staleConfirmPromise = null;  // races the EARLIEST pending confirm across hosts
+  let staleConfirmTimer = null;    // handle for that race's real timer, so it can be cancelled
+  // Cancel any pending confirm timer. The race timer is a REAL setTimeout (not the injected
+  // `sleep`) precisely so it is cancellable: re-arming, a host recovery, or a terminal
+  // finalize supersedes the pending confirm, and an ORPHANED confirm timer would otherwise
+  // keep the process (and the checked-in `pnpm test:bb-wait` lane) alive for the full
+  // beaconConfirmMs window — the parent suite ran ~6.5s, this leak made it ~92s (Codex
+  // round-40 P2). Same "real timer, tracked so it can be cleared" discipline as the alarm
+  // timers above.
+  const clearStaleConfirmTimer = () => {
+    if (staleConfirmTimer != null) { clearTimeout(staleConfirmTimer); staleConfirmTimer = null; }
+  };
+  const beaconHostKey = (signal) => {
+    const match = hostPinnedCapacity.find(
+      (c) => c.params.host === signal.subject_key || c.params.host === signal.payload?.host_key,
+    );
+    return match ? match.params.host : null;
+  };
+  const armStaleConfirmRace = () => {
+    clearStaleConfirmTimer(); // supersede any prior pending confirm — never leak its timer
+    if (staleConfirm.size === 0) { staleConfirmPromise = null; return; }
+    const soonest = Math.min(...staleConfirm.values());
+    staleConfirmPromise = new Promise((resolve) => {
+      staleConfirmTimer = setTimeout(() => {
+        staleConfirmTimer = null;
+        resolve({ __staleConfirm: true });
+      }, Math.max(0, soonest - now()));
+    });
+  };
+  // Returns "continue" (skip this frame), "fallthrough" (let matchFrame see it), or
+  // "exit" (terminate immediately on a stale signal when beaconConfirmMs<=0).
+  const applyBeaconStale = (signal) => {
+    const stale = signal.payload.source_stale === true;
+    const hostKey = beaconHostKey(signal);
+    // Not a host this wait pins a `capacity` condition to (un-pinned / other host):
+    // fall through to matchFrame instead of swallowing the frame. A raw
+    // `event:type=container_capacity,subject=<host>` escape-hatch condition must be
+    // able to observe beacon-stale transitions (Codex round-23 P2); the `capacity`
+    // matcher already refuses to grant on a source_stale frame, so no false grant.
+    if (hostKey == null) return "fallthrough";
+    if (stale) {
+      if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
+      if (beaconConfirmMs <= 0) return "exit";
+      if (!staleConfirm.has(hostKey)) {
+        staleConfirm.set(hostKey, now() + beaconConfirmMs);
+        armStaleConfirmRace();
+      }
+      // Arm the confirm race, but DON'T consume the frame — fall through to matchFrame
+      // (Codex round-23/24 P2). A wait that pins a `capacity` condition to this host AND
+      // carries a raw `event:type=container_capacity,subject=<same-host>` must still let
+      // the raw condition wake on the transition. The `capacity` matcher refuses to
+      // grant on a source_stale frame (never a false grant), and a host-pinned-only wait
+      // simply finds no match here and keeps waiting on the confirm race as before.
+      return "fallthrough";
+    }
+    // Recovery for THIS host only: drop its confirm; keep the marker while any OTHER
+    // pinned host is still pending-stale. Fall through so a recovery carrying
+    // free_slots >= minSlots can grant normally.
+    staleConfirm.delete(hostKey);
+    if (staleConfirm.size === 0) {
+      const i = degraded.indexOf("capacity_source_stale");
+      if (i !== -1) degraded.splice(i, 1);
+    }
+    armStaleConfirmRace();
+    return "fallthrough";
+  };
+
+  while (true) {
+    if (earliest != null && now() >= earliest.atMs) {
+      return fireAlarm();
+    }
+
+    // Refresh feed-lag on start + every (re)connect, so a stalled feed is flagged
+    // and a recovered one clears — reflected in the terminal receipt / wait_session.
+    await probeFeedLag();
+
+    let stream;
+    try {
+      stream = await connect(cursor);
+    } catch (err) {
+      failures += 1;
+      degraded.push("backend_unreachable");
+      if (failures > maxReconnects) {
+        return finalize("error", { exitCode: EXIT.BACKEND, error: String(err && err.message || err) });
+      }
+      const waitMs = backoff(failures);
+      const raced = await Promise.race([
+        deadlinePromise,
+        sleepFn(waitMs).then(() => ({ __retry: true })),
+      ]);
+      if (raced && raced.__deadline) return fireAlarm();
+      continue;
+    }
+
+    const iterator = stream[Symbol.asyncIterator]();
+    let streamEnded = false;
+    // BOT-1148 (Codex P2): the pending iterator.next() is HOISTED across loop
+    // iterations. When a non-frame racer wins (a beacon-stale confirm that a recovery
+    // then cancels), we must NOT abandon the in-flight read and start a fresh one —
+    // the abandoned read would still consume the next frame and silently drop it (the
+    // grant could be that frame, hanging the wait). We only start a new read once the
+    // previous one has actually settled into a frame we consumed.
+    let pendingNext = null;
+    while (!streamEnded) {
+      if (!pendingNext) pendingNext = iterator.next();
+      const racers = [deadlinePromise, pendingNext];
+      if (staleConfirmPromise) racers.push(staleConfirmPromise);
+      if (preDeadlineProbePromise && !preDeadlineProbeDone) racers.push(preDeadlineProbePromise);
+      const raced = await Promise.race(racers);
+
+      if (raced && raced.__deadline) {
+        return fireAlarm();
+      }
+      // BOT-1147 (Codex round-27 P2): the pre-deadline feed probe fired. Fold a
+      // mid-wait stall/recovery into `degraded` before the imminent timeout receipt,
+      // then keep waiting — pendingNext stays in flight (hoisted), re-raced next
+      // iteration, so no frame is dropped. Fires at most once.
+      if (raced && raced.__feedProbe) {
+        preDeadlineProbeDone = true;
+        await probeFeedLag();
+        continue;
+      }
+      // BOT-1148: the beacon-stale confirm window elapsed. If still stale (no recovery
+      // cleared it), exit fast on the existing code 5; otherwise drop the settled
+      // confirm promise and keep waiting — pendingNext stays in flight, re-raced next
+      // iteration, so no frame is dropped.
+      if (raced && raced.__staleConfirm) {
+        // Any pinned host whose confirm window elapsed while STILL stale → fast-fail.
+        // A recovery from a different host already removed its own entry, so it can't
+        // suppress this one (Codex P2, per-host).
+        const anyDue = [...staleConfirm.values()].some((atMs) => now() >= atMs);
+        if (anyDue) {
+          if (!degraded.includes("capacity_source_stale")) degraded.push("capacity_source_stale");
+          return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
+        }
+        // A settled promise whose host recovered before firing: re-arm for the next
+        // pending host (if any) and keep waiting — pendingNext stays in flight.
+        armStaleConfirmRace();
+        continue;
+      }
+      // raced settled from pendingNext (a frame result) — consume it before the next read.
+      pendingNext = null;
+      const { value: frame, done } = raced;
+      if (done) {
+        streamEnded = true;
+        break;
+      }
+      if (!frame) continue;
+
+      // BOT-1067: a degraded marker frame (e.g. the relay fell back to bounded
+      // re-query polling during a Realtime outage) is folded into the receipt's
+      // degraded array. The wait CONTINUES — delivery is just late and flagged —
+      // so this is not terminal.
+      if (frame.event === "degraded") {
+        let parsed = {};
+        try { parsed = JSON.parse(frame.data); } catch { /* ignore */ }
+        const marker = parsed.degraded;
+        if (typeof marker === "string" && !degraded.includes(marker)) degraded.push(marker);
+        continue;
+      }
+
+      // Server-side error frames are terminal.
+      if (frame.event === "error") {
+        let parsed = {};
+        try { parsed = JSON.parse(frame.data); } catch { /* ignore */ }
+        if (parsed.error === "cursor_expired") {
+          return finalize("error", { exitCode: EXIT.CURSOR_EXPIRED, error: "cursor_expired" });
+        }
+        if (parsed.error === "unauthorized" || parsed.error === "forbidden") {
+          return finalize("error", { exitCode: EXIT.AUTH, error: parsed.error });
+        }
+        return finalize("error", { exitCode: EXIT.INTERNAL, error: parsed.error || "stream_error" });
+      }
+
+      const signal = decodeSignal(frame);
+      if (!signal || signal.seq == null) continue;
+      const seqKey = String(signal.seq);
+      if (seen.has(seqKey)) continue; // exactly-once across reconnects
+      seen.add(seqKey);
+      cursor = seqKey;
+      if (onFrame) onFrame(signal);
+
+      // BOT-1249: a `wait_superseded` spine signal targeting THIS registration is
+      // terminal (exit 8). reconcile_waits_to_canonical() emits it — in seq order,
+      // strictly AFTER any pre-supersession match — when this wait's resource identity
+      // was canonicalized away (a BOT-1184 alias merge / BOT-1224 host rename), so its
+      // in-memory (alias-keyed) conditions can never fire against the now-canonical
+      // signal keys. Exiting lets the harness re-invoke bb-wait, which re-registers
+      // under the canonical identity (the BOT-1184 register echo). This replaces the
+      // BOT-1228 out-of-band `event: superseded` frame: same outcome/exit, now delivered
+      // as a sequenced spine row so it can never overtake an earlier match. `cursor` is
+      // already advanced past it (above), so the re-armed wait resumes without a gap.
+      //
+      // Scoped to payload.wait_session_id — the same wait_session_id scoping the claim-
+      // grant path uses — so a `--since` replay of an OLDER supersession for a prior,
+      // now-terminal registration (a fresh registration is a new wait_session_id) is
+      // ignored rather than exiting this wait spuriously. The signal is recipient-scoped
+      // at the relay, so an agent's OTHER concurrent waits receive it too; this id check
+      // is why only the intended one treats it as terminal.
+      if (
+        signal.signal_type === WAIT_SUPERSEDED_SIGNAL_TYPE &&
+        waitSessionId != null &&
+        signal.payload && signal.payload.wait_session_id === waitSessionId
+      ) {
+        // Re-arm the re-registration from the wait's ORIGINAL arm cursor (cursor_start),
+        // NOT this supersession's seq. `seq` is allocated at INSERT, not COMMIT, and a
+        // live frame can overtake the replay backlog — so a supersession can be delivered
+        // to us AHEAD of a match that was actually eligible (a chat/pr/ci signal for a
+        // mixed `any` wait, or a canonical signal that arrived during the alias window).
+        // If we re-armed from the supersession's (higher) seq we'd skip that match on
+        // re-registration. cursor_start is the seq this wait armed from, so re-arming here
+        // gives the re-registered wait EXACTLY the coverage the original registration had
+        // — strictly better than re-arming from the last-seen (higher) cursor, which is
+        // all a normal same-wait reconnect gets. (The one residual gap — a match whose row
+        // was allocated a seq BELOW cursor_start but committed after registration read
+        // max(seq) — is the pre-existing BOT-989 register-after-emit race that any
+        // reconnect shares; it is out of scope here and tracked separately. We do NOT
+        // re-arm from 0, which would spuriously re-match stale pre-arm signals.) Falls
+        // back to the current cursor if the emitter didn't stamp cursor_start (defensive —
+        // reconcile always does).
+        const cs = signal.payload.cursor_start;
+        if (cs != null && /^\d+$/.test(String(cs))) cursor = String(cs);
+        // A superseded CLAIM wait lost its grantable queue entry: reconcile_waits_to_
+        // canonical() dequeues the queued resource_locks row before abandoning the
+        // session. A plain re-run re-registers the wait_session but does NOT recreate
+        // that queue row, so grant_free_lock would have nothing to promote and the
+        // re-armed claim would hang to --timeout. Surface the lock(s) to re-acquire so
+        // the caller re-queues (acquire_lock) BEFORE re-parking (BOT-1228 Codex round-3
+        // P1). Broadcast waits need no queue entry, so this is empty for them.
+        const reacquire = conditions
+          .filter((c) => c.type === "lock" && c.params.claim)
+          .map((c) => ({ subtype: c.params.subtype, host: c.params.host, slot: c.params.slot }));
+        return finalize("superseded", {
+          exitCode: EXIT.SUPERSEDED,
+          state: {
+            superseded: true,
+            status: typeof signal.payload.status === "string" ? signal.payload.status : null,
+          },
+          // Top-level (survives receipt truncation) — see buildReceipt.
+          reacquireLock: reacquire,
+        });
+      }
+
+      // BOT-1148: a beacon-driven capacity staleness transition is handled before the
+      // normal match — a stale signal is never itself a grant, and a fast exit / marker
+      // fold happens here (host-pinned) rather than through matchFrame.
+      if (signal.signal_type === "container_capacity" && signal.payload && "source_stale" in signal.payload) {
+        const disposition = applyBeaconStale(signal);
+        if (disposition === "exit") {
+          return finalize("error", { exitCode: EXIT.BACKEND, error: "capacity_source_stale" });
+        }
+        if (disposition === "continue") continue;
+        // "fallthrough": let matchFrame see the frame — a recovery may grant via
+        // free_slots, and a raw `event` condition may match a stale frame (the
+        // `capacity` matcher itself never grants on source_stale).
+      }
+
+      // BOT-1259 AC-3/AC-4: central tenant guard. A tenanted signal whose tenant is not
+      // this session's resolved tenant (or whose session tenant is unknown) never wakes
+      // it — fail closed, and surfaced as a debug line, not an error (the wait simply
+      // keeps waiting). Belt-and-braces with the server relay's authority-side filter.
+      if (signalTenantBlocked(signal, sessionTenant)) {
+        if (debug) {
+          debug(`bb-wait: dropped ${signal.signal_type} signal (seq ${signal.seq}) — tenant ${signal.tenant_id} ≠ session tenant ${sessionTenant ?? "(unresolved)"} [BOT-1259 fail-closed]`);
+        }
+        continue;
+      }
+
+      const matched = matchFrame(frame, conditions, waitSessionId, sessionTenant);
+      if (matched) {
+        return finalize("matched", {
+          exitCode: EXIT.MATCHED,
+          matched: [{
+            condition_id: matched.id,
+            signal_type: signal.signal_type,
+            seq: signal.seq,
+            subject_key: signal.subject_key,
+            payload: signal.payload ?? null,
+            provenance: "spine",
+          }],
+        });
+      }
+    }
+
+    // Stream ended without a match: reconnect from the cursor.
+    reconnects += 1;
+    if (reconnects > maxReconnects) {
+      return finalize("error", { exitCode: EXIT.BACKEND, error: "reconnect budget exhausted" });
+    }
+    const waitMs = backoff(reconnects);
+    const raced = await Promise.race([deadlinePromise, sleepFn(waitMs).then(() => ({ __retry: true }))]);
+    if (raced && raced.__deadline) return fireAlarm();
+  }
+}