@botbuddy/cli 1.2.3 → 1.4.1

package/src/wait.mjs

@@ -0,0 +1,727 @@
+#!/usr/bin/env node
+// BOT-989 / BOT-1344 — `botbuddy wait`: the public aggregated agent wait interface.
+//
+// Park on a set of conditions (a lock coming free, a chat reply, a build
+// finishing, a plain deadline) and wake EXACTLY ONCE with one machine-readable
+// JSON receipt on stdout. Zero polling, zero tokens spent while waiting: the
+// process blocks on a pushed SSE stream and the agent harness (Claude Code
+// `run_in_background`, Codex background exec) is re-invoked when it exits.
+//
+// Dependency-free (Node >= 20 stdlib only). All wait semantics live in
+// ./wait-core.mjs; this file is just argv + a real `connect()` + I/O.
+//
+// Usage:  botbuddy wait [--any] <condition>... [options]
+// Run     botbuddy wait --help for the condition grammar.
+
+import { EXIT, parseConditions, parseSseFrames, runWaitLoop, normalizeSince, truncateReceipt } from "./wait-core.mjs";
+import { resolveAgentProfile, withPrincipalReceipt } from "./wait-profile.mjs";
+import { VERSION } from "./version.mjs";
+import { fileURLToPath } from "node:url";
+
+// A protocol is deliberately distinct from package semver: compatible pinned
+// clients keep working until the server raises this minimum, while a stale
+// implementation gets a typed, safe upgrade instruction.
+export const WAIT_PROTOCOL_VERSION = 1;
+const CLI_UPGRADE_COMMAND = "npx --yes @botbuddy/cli@latest wait";
+const MIN_RECEIPT_MAX_BYTES = 512;
+
+const HELP = `botbuddy wait — one wait command instead of a polling loop (BOT-989)
+
+USAGE
+  botbuddy wait [--any] <condition>... [options]
+
+CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the first)
+  timer:duration=<seconds>            wake after N seconds (DB-clocked server-side)
+  timer:deadline=<ISO-8601>           wake at an absolute time
+  chat:channel=<id>|*                 new Direct Chat message (or * = any channel you are in;
+                                      you are never woken by your own messages)
+  lock:subtype=<t>,host=<h>[,slot=<s>][,claim=true]
+                                      a resource lock becomes available
+                                      subtype ∈ playwright_lane|vite_port|backend_port|supabase_local
+                                      claim=true (needs slot=): ATOMIC claim-on-grant — queue for the
+                                      lock (acquire_lock while it's held), then wait; the server hands
+                                      you the lock and wakes you already HOLDING it (no acquire race).
+                                      Must be the ONLY condition (use --timeout to bound it); can't be
+                                      raced against other conditions. Omit claim to just wait for
+                                      availability and acquire it yourself.
+  pr-state:repo=<owner/repo>[,pr=<n>] a PR state transition (open/draft/merged/closed,
+                                      checks, review decision, unresolved threads, mergeable).
+                                      Omit pr= to wake on ANY of your PRs in the repo;
+                                      or pass pr=<owner/repo#n> in one value. A conflict/clean
+                                      flip sets payload.mergeable_changed (no new condition).
+  pr-review:repo=<owner/repo>[,pr=<n>]
+                                      a new review comment, or a thread resolved/re-opened
+                                      (payload carries the unresolved-thread count)
+  test-run:id=<run_id>                a test run reaching a terminal status (owner-scoped)
+  lease:id=<lease_id>                 a batch stack lease (BOT-1218) leaving the queue /
+                                      becoming active — the zero-poll wake for a parked
+                                      \`botbuddy stack up\` (recipient-scoped to the owner).
+                                      Level-triggered: an already-granted lease wakes at once.
+  guidance:request=<post_id>          a command-post guidance request being answered
+                                      (scoped to the asking agent; fetch the body with
+                                      get_guidance_response)
+  linear:issue=<KEY>                  a BOT-* issue changing state, a new comment, or an
+                                      assignee change (e.g. issue=BOT-123; tenant-scoped).
+                                      Flags linear_feed_lagging if the ingest feed has stalled.
+  unblocked:<KEY>                     a ticket's LAST open blocker clearing (open-blocker
+                                      count >0 → 0): a blocker moving to Done/Canceled/Duplicate
+                                      or the final blocks relation removed. Level-triggered —
+                                      already-unblocked (or never-blocked) at registration
+                                      grants immediately (payload.reason=already_unblocked).
+                                      Tenant-scoped. Also accepts unblocked:ticket=<KEY>.
+  capacity:policy=<p>,slots>=<N>[,host=<h>][,stale_grace=<sec>]
+                                      a managed-container host reaching >= N free slots.
+                                      Host-shared; a silently-dead host is detected server-side
+                                      (capacity_source_stale) via a host beacon — the client
+                                      grace (default 900s) is a backstop, no longer the only guard.
+  ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>}
+                                      a PR's CI reaching a terminal conclusion (owner-scoped);
+                                      GitHub Actions or an external check_suite provider.
+                                      A repo with no CI feed is rejected (no_signal_source).
+  event:type=<signal_type>[,subject=<key>]
+                                      raw signal-spine match (escape hatch)
+
+OPTIONS
+  --any                 wake on the first matching condition (default; only mode in v1)
+  --timeout <seconds>   max wait (default 7200; hard cap 28800). Timeout is exit 2, not an error.
+  --since <seq>         resume from a prior receipt's next_cursor (replay what you missed)
+  --receipt-max-bytes <n>   cap the receipt (minimum 512; default 10240; payloads truncate to pointers)
+  --heartbeat           keep this agent session alive while waiting (so it is not reaped)
+  --url <base>          relay base URL (default $BOTBUDDY_RELAY_URL or https://api.bot-buddy.ai/functions/v1)
+  --profile <name>      tenant-bound machine profile (normally read from .botbuddy-agent.json)
+  --token <key>         explicit agent key override; otherwise the profile-specific env is used
+  --help                show this help
+
+OUTPUT
+  Exactly one JSON receipt line on stdout at exit, with client semver and
+  protocol identity. Diagnostics go to stderr.
+  Exit codes: 0 matched · 2 timeout · 3 auth · 4 invalid conditions ·
+              5 backend unavailable · 6 cursor expired · 7 internal ·
+              8 superseded (wait replaced server-side). 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.
+
+EXAMPLES
+  # wait for a Playwright lane to free up, then acquire it yourself
+  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP' --timeout 1800
+
+  # queue for a specific lane and be HANDED it when it frees (no acquire race):
+  #   acquire_lock (gets queued) → bb-wait claim=true → wake already holding lane 3
+  botbuddy wait 'lock:subtype=playwright_lane,host=Jonos-MBP,slot=3,claim=true' --timeout 1800 --heartbeat
+
+  # wait for a chat reply on any channel, or 20 minutes, whichever first
+  botbuddy wait --any 'chat:channel=*' 'timer:duration=1200' --heartbeat
+
+  # after pushing review fixes, wait for the next review comment or a state change
+  botbuddy wait --any 'pr-review:repo=bot-buddy/botbuddy-webapp,pr=425' \\
+                'pr-state:repo=bot-buddy/botbuddy-webapp,pr=425' --timeout 3600
+`;
+
+function parseArgv(argv) {
+  const opts = {
+    conditions: [],
+    mode: "any",
+    timeout: 7200,
+    since: null,
+    receiptMaxBytes: 10240,
+    heartbeat: false,
+    url: process.env.BOTBUDDY_RELAY_URL || "https://api.bot-buddy.ai/functions/v1",
+    token: null,
+    profile: null,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const optionValue = () => {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        opts.missing ??= a;
+        return null;
+      }
+      i += 1;
+      return value;
+    };
+    if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--any") opts.mode = "any";
+    else if (a === "--heartbeat") opts.heartbeat = true;
+    else if (a === "--timeout") opts.timeout = Number(optionValue());
+    else if (a === "--since") opts.since = optionValue();
+    else if (a === "--receipt-max-bytes") opts.receiptMaxBytes = Number(optionValue());
+    else if (a === "--url") opts.url = optionValue();
+    else if (a === "--token") opts.token = optionValue();
+    else if (a === "--profile") opts.profile = optionValue();
+    else if (a.startsWith("--")) opts.unknown = a;
+    else opts.conditions.push(a);
+  }
+  return opts;
+}
+
+// Register a wait_session on the relay (BOT-989 M2). Returns
+// {waitSessionId, cursorStart} on success. Profiled waits fail closed unless the
+// relay authenticates and attests their machine principal.
+async function registerWait(opts, conditions, deadlineIso) {
+  const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.token}`,
+      "x-agent-api-key": opts.token || "",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      action: "register",
+      profile: opts.agentProfile.name,
+      expected_tenant: opts.agentProfile.tenant,
+      client_version: VERSION,
+      wait_protocol_version: WAIT_PROTOCOL_VERSION,
+      conditions,
+      deadline: deadlineIso,
+      mode: opts.mode,
+    }),
+  });
+  if (res.status === 429) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.detail || "wait_session_cap_exceeded");
+    err.cap = true;
+    err.errorCode = body.error || "wait_session_cap_exceeded";
+    throw err;
+  }
+  if (res.status === 401) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.detail || body.message || body.error || "unauthorized agent key");
+    err.auth = true;
+    err.errorCode = body.error || "unauthorized";
+    throw err;
+  }
+  if (res.status === 400) {
+    // Only a CALLER-ACTIONABLE condition rejection is a hard stop — arming an untracked
+    // live-only wait can never recover it, and it would skip the server's initial
+    // evaluation (silently missing an already-satisfied condition). These are the
+    // conditions the server refuses by design: BOT-1066 `no_signal_source` (uncovered
+    // CI repo) and BOT-1247 `unblocked_cross_tenant` / `unblocked_requires_tenant`
+    // (an unblocked:<TICKET> a single tenant-scoped wait session can't serve).
+    // A TRANSIENT backend 400 (e.g. `register_failed` from the RPC) is NOT
+    // caller-actionable — fall through to the existing live-only fallback so a valid
+    // wait still arms (Codex round-7 P2).
+    const body = await res.json().catch(() => ({}));
+    const INVALID_CONDITION_CODES = new Set([
+      "no_signal_source",
+      "unblocked_cross_tenant",
+      "unblocked_requires_tenant",
+      "wait_tenant_unresolved",
+      "wait_cross_tenant",
+      "wait_tenant_mismatch",
+      // BOT-1259: a `linear` condition set spanning multiple workspaces can't bind one
+      // tenant; the server rejects it (register one wait per workspace) — a hard stop, not
+      // a transient error, so don't fall back to an untracked live-only wait.
+      "linear_cross_tenant",
+      // BOT-1259: a multi-workspace caller arming a workspace-scoped condition the server
+      // can't bind to one workspace (ci / pr-review / bare tenant-primary event). A hard
+      // stop — arming it untracked would only ever park to timeout.
+      "tenant_ambiguous",
+    ]);
+    if (INVALID_CONDITION_CODES.has(body.error)) {
+      const err = new Error(body.detail || body.error);
+      err.invalidCondition = true;
+      err.errorCode = body.error;
+      throw err;
+    }
+  }
+  if (res.status === 403) {
+    const body = await res.json().catch(() => ({}));
+    if (new Set(["wait_tenant_unresolved", "wait_cross_tenant", "wait_tenant_mismatch"]).has(body.error)) {
+      const err = new Error(body.detail || body.error);
+      err.invalidCondition = true;
+      err.errorCode = body.error;
+      throw err;
+    }
+    const err = new Error(body.detail || body.message || body.error || "forbidden");
+    err.auth = true;
+    err.errorCode = body.error || "forbidden";
+    throw err;
+  }
+  if (res.status === 426) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.detail || "this wait client is no longer supported");
+    err.clientOutdated = true;
+    err.errorCode = body.error || "client_outdated";
+    err.upgradeCommand = body.upgrade_command || CLI_UPGRADE_COMMAND;
+    err.minimumProtocol = body.minimum_wait_protocol ?? null;
+    throw err;
+  }
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const err = new Error(body.detail || body.message || body.error || `register responded ${res.status}`);
+    if (body.error === "initial_eval_failed") {
+      err.initialEval = true;
+      err.errorCode = body.error;
+      err.detail = body.detail || "initial evaluation failed";
+    }
+    throw err;
+  }
+  const body = await res.json();
+  if (body.profile !== opts.agentProfile.name || typeof body.agent_id !== "string" || !body.agent_id) {
+    const err = new Error("relay did not attest the tenant-bound agent profile");
+    err.auth = true;
+    err.errorCode = "profile_not_enforced";
+    throw err;
+  }
+  if (body.session_tenant !== opts.agentProfile.tenant) {
+    const err = new Error(
+      `profile expects ${opts.agentProfile.tenant} but registration resolved ${body.session_tenant ?? "no tenant"}`,
+    );
+    err.auth = true;
+    err.errorCode = "profile_tenant_mismatch";
+    throw err;
+  }
+  return {
+    waitSessionId: body.wait_session_id ?? null,
+    cursorStart: body.cursor_start ?? null,
+    // BOT-1184: the server canonicalizes lock-condition hosts on register and
+    // echoes them here so the client matches the canonical subject_key.
+    conditions: Array.isArray(body.conditions) ? body.conditions : null,
+    // BOT-1259: the wait session's server-resolved tenant. The client threads this
+    // into the central tenant guard so a tenanted signal only wakes a session resolved
+    // to that same workspace. `session_tenant: null` is a genuinely tenantless session
+    // (matches only tenantless signals); an ABSENT field (a pre-BOT-1259 relay) collapses
+    // to null too — fail closed on tenanted signals until the wait re-arms against the
+    // new relay (the deploy-skew case, acceptable because waits are short-lived).
+    sessionTenant: body.session_tenant ?? null,
+    agentId: body.agent_id ?? null,
+  };
+}
+
+// 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
+// long we linger, and a non-2xx response is reported (not silently dropped) so a
+// session left `active` shows up in diagnostics rather than as a phantom wait.
+async function finalizeWait(opts, waitSessionId, receipt, timeoutMs = 5000) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${opts.token}`,
+        "x-agent-api-key": opts.token || "",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        action: "finalize",
+        wait_session_id: waitSessionId,
+        status: receipt.outcome,
+        receipt,
+        reconnects: receipt.reconnects ?? 0,
+        degraded: receipt.degraded ?? [],
+      }),
+      signal: ac.signal,
+    });
+    if (!res.ok) {
+      process.stderr.write(`bb-wait: finalize (non-fatal) returned ${res.status}\n`);
+    }
+  } catch (err) {
+    process.stderr.write(`bb-wait: finalize (non-fatal) failed: ${err && err.message || err}\n`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// 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) {
+  return async function connect(since) {
+    const sinceParam = normalizeSince(since);
+    const url = new URL(`${opts.url.replace(/\/$/, "")}/event-stream`);
+    url.searchParams.set("tables", "agent_signal_events");
+    if (sinceParam.kind === "ok") url.searchParams.set("since", sinceParam.value);
+    // Bind the SSE to the registered wait_session so the relay bumps its
+    // last_seen_at on connect + keepalive (abandoned detection).
+    if (opts.waitSessionId) url.searchParams.set("wait_session", opts.waitSessionId);
+    // --heartbeat rides the live SSE connection itself: event-stream bumps
+    // agents.last_heartbeat on connect and every keepalive when heartbeat=1, so
+    // the agent (and its locks) aren't reaped during a long wait.
+    if (opts.heartbeat) url.searchParams.set("heartbeat", "1");
+
+    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",
+      },
+    });
+    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}`);
+
+    return sseFrameStream(res.body);
+  };
+}
+
+// BOT-1147 AC-3: the real Linear-feed freshness probe. Asks the relay (which
+// 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;
+
+function makeFeedLagProbe(opts) {
+  // `issues` = the armed `linear` conditions' target ticket keys. The relay
+  // resolves them to their owning workspace(s) (within the caller's tenant scope)
+  // so freshness reflects the targeted tenant, not the caller's membership union
+  // (Codex round-22 P2). Omitted/empty -> the relay falls back to the caller's
+  // tenant scope, then to the global feed.
+  return async function feedLagProbe(issues = []) {
+    // Return null (INDETERMINATE) on any failure — a non-2xx, invalid JSON, a
+    // transport error, or the relay's own {lagging:false, probe_error:true} RPC-error
+    // response — so foldFeedLag leaves the last known lag state untouched. Returning
+    // false here would clear a known linear_feed_lagging marker on a transient outage
+    // and make a stale feed look healthy right before a terminal receipt (Codex P2).
+    //
+    // BOUNDED (Codex P2): the wait loop awaits this before connecting AND on every
+    // terminal finalize, OUTSIDE the deadline race, so an unbounded probe that accepts
+    // the connection but stalls before responding would hang even an already-matched
+    // signal or an expired --timeout forever. A 10s abort caps it; expiry is treated as
+    // the same indeterminate result (leave the last known lag state).
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FEED_LAG_PROBE_TIMEOUT_MS);
+    try {
+      const res = await fetch(`${opts.url.replace(/\/$/, "")}/event-stream`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${opts.token}`,
+          "x-agent-api-key": opts.token || "",
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          action: "linear_feed_status",
+          ...(Array.isArray(issues) && issues.length > 0 ? { issues } : {}),
+        }),
+        signal: ac.signal,
+      });
+      if (!res.ok) return null;
+      const body = await res.json();
+      if (body?.probe_error) return null;
+      return body?.lagging === true;
+    } catch {
+      return null; // transport error OR AbortError on the 10s timeout → indeterminate
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+async function* sseFrameStream(body) {
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of body) {
+    buf += decoder.decode(chunk, { stream: true });
+    const { frames, rest } = parseSseFrames(buf);
+    buf = rest;
+    for (const f of frames) yield f;
+  }
+}
+
+function errorStream(error) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      yield { id: "", event: "error", data: JSON.stringify({ error }) };
+    },
+  };
+}
+
+// timer-only waits need no network; return a stream that never yields so the
+// deadline is the only terminal.
+function offlineStream() {
+  return { async *[Symbol.asyncIterator]() { await new Promise(() => {}); } };
+}
+
+function withClientIdentity(receipt) {
+  return {
+    ...receipt,
+    client: { package: "@botbuddy/cli", version: VERSION, wait_protocol: WAIT_PROTOCOL_VERSION },
+  };
+}
+
+function emit(receipt, { versioned = false, maxBytes = null } = {}) {
+  const enriched = versioned ? receipt : withClientIdentity(receipt);
+  const bounded = Number.isSafeInteger(maxBytes) && maxBytes >= MIN_RECEIPT_MAX_BYTES
+    ? truncateReceipt(enriched, maxBytes)
+    : enriched;
+  process.stdout.write(JSON.stringify(bounded) + "\n");
+}
+
+function profileRecovery(profile) {
+  return `npx --yes @botbuddy/cli@latest profile setup ${profile.name}`;
+}
+
+function typedProfileError(errorCode) {
+  switch (String(errorCode ?? "").toLowerCase()) {
+    case "agent_key_required": return "profile_agent_required";
+    case "agent_tenant_required": return "profile_credential_unbound";
+    case "profile_tenant_mismatch": return "profile_credential_wrong_tenant";
+    case "unauthorized": return "profile_credential_revoked";
+    default: return errorCode;
+  }
+}
+
+function profileErrorReceipt(profile, error) {
+  return withPrincipalReceipt({
+    schema_version: 1,
+    outcome: "error",
+    error,
+    recovery: profileRecovery(profile),
+  }, profile, { sessionTenant: profile.tenant, agentId: null });
+}
+
+export async function runWait(argv) {
+  const opts = parseArgv(argv);
+  const emitReceipt = (receipt, options = {}) => emit(receipt, {
+    ...options,
+    maxBytes: opts.receiptMaxBytes,
+  });
+  if (opts.help) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
+  if (opts.unknown) {
+    process.stderr.write(`bb-wait: unknown option ${opts.unknown}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.unknown });
+    process.exit(EXIT.INVALID);
+  }
+  if (opts.missing) {
+    process.stderr.write(`bb-wait: option ${opts.missing} requires a value\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_arguments", option: opts.missing });
+    process.exit(EXIT.INVALID);
+  }
+
+  const { conditions, errors } = parseConditions(opts.conditions);
+  if (errors.length > 0) {
+    for (const e of errors) process.stderr.write(`bb-wait: invalid condition '${e.spec}': ${e.message}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_conditions", errors });
+    process.exit(EXIT.INVALID);
+  }
+
+  if (!Number.isFinite(opts.timeout) || opts.timeout <= 0) {
+    process.stderr.write("bb-wait: --timeout must be a positive number of seconds\n");
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_timeout" });
+    process.exit(EXIT.INVALID);
+  }
+  if (!Number.isSafeInteger(opts.receiptMaxBytes) || opts.receiptMaxBytes < MIN_RECEIPT_MAX_BYTES) {
+    process.stderr.write(`bb-wait: --receipt-max-bytes must be an integer of at least ${MIN_RECEIPT_MAX_BYTES}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "invalid_receipt_max_bytes", minimum: MIN_RECEIPT_MAX_BYTES });
+    process.exit(EXIT.INVALID);
+  }
+  const timeoutSec = Math.min(opts.timeout, 28800); // 8h hard cap (session-budget gate)
+  const deadlineMs = Date.now() + timeoutSec * 1000;
+
+  const needsRelay = conditions.some((c) => c.type !== "timer");
+  if (needsRelay) {
+    try {
+      opts.agentProfile = await resolveAgentProfile({
+        explicitProfile: opts.profile,
+        explicitToken: opts.token,
+      });
+    } catch (err) {
+      process.stderr.write(`bb-wait: ${err.message}\n`);
+      emitReceipt({ schema_version: 1, outcome: "error", error: err.code || "invalid_profile" });
+      process.exit(EXIT.INVALID);
+    }
+    opts.token = opts.agentProfile.token;
+    if (!opts.token) {
+      process.stderr.write(
+        `botbuddy wait: profile '${opts.agentProfile.name}' has no tenant-bound agent credential; run '${profileRecovery(opts.agentProfile)}'\n`,
+      );
+      emitReceipt(profileErrorReceipt(opts.agentProfile, "profile_required"));
+      process.exit(EXIT.AUTH);
+    }
+  }
+
+  // A claim=true wait is meaningless without a tracked registration: the server
+  // only grants a lock to an agent with an ACTIVE matching wait_session, and the
+  // client only accepts a grant whose wait_session_id equals THIS registration's.
+  // So a null id could never match a grant — it could only time out — while the
+  // server may have registered and granted. Claim waits therefore fail CLOSED on
+  // any registration failure rather than using the untracked-wait fallback below.
+  const hasClaim = conditions.some((c) => c.type === "lock" && c.params.claim);
+
+  // Register the wait_session before connecting (BOT-989 M2). This records the
+  // wait for telemetry/abandoned-detection and returns the spine high-water mark
+  // to arm `since` from, closing the register-after-emit race. A cap rejection is
+  // a hard stop; for a non-claim wait, any other registration failure degrades to
+  // an untracked (but still functional) wait. Timer-only waits never touch the relay.
+  let waitSessionId = null;
+  let effectiveSince = opts.since;
+  // BOT-1259: the server-resolved tenant for this wait session, threaded into the
+  // central tenant guard (runWaitLoop). Undefined until a successful register echo;
+  // an untracked live-only fallback (no register) leaves the guard OFF, matching its
+  // pre-BOT-1259 behaviour for a wait the server never scoped.
+  let sessionTenant;
+  let registeredAgentId = null;
+  if (needsRelay) {
+    try {
+      const reg = await registerWait(opts, conditions, new Date(deadlineMs).toISOString());
+      waitSessionId = reg.waitSessionId;
+      opts.waitSessionId = waitSessionId;
+      sessionTenant = reg.sessionTenant;
+      registeredAgentId = reg.agentId;
+      // BOT-1184: adopt the server's canonical host for each lock condition so the
+      // local matcher builds the same subject_key the availability/claim-grant
+      // signals carry (armed under an alias like 'jono-mac', the signal uses the
+      // canonical 'jonos-mbp'). Patch host by condition id — preserving every
+      // other client-side param type — rather than wholesale-replacing the parsed
+      // conditions. Only 'lock' conditions are canonicalized server-side.
+      if (Array.isArray(reg.conditions)) {
+        const canonHost = new Map();
+        // BOT-1247: the server stamps the resolved workspace (round-9 P1) and the stable
+        // Linear issue UUID (round-10 P2) onto each `unblocked` condition; carry both onto
+        // the local condition so the matcher can require the signal's tenant to match (no
+        // waking on another workspace's identically-keyed unblock) and key off the
+        // immutable issue id (surviving an external_id rename mid-wait).
+        const unblockedScope = new Map();
+        // BOT-1260: the server stamps the stable Linear issue UUID onto each `linear`
+        // condition whose key is mirrored in `tickets`; carry it onto the local condition so
+        // the matcher keys off the immutable id (surviving an external_id rename mid-wait,
+        // and refusing a recycled key). No `tenant` is stamped for `linear` — its cross-tenant
+        // isolation rides on the central guard's sessionTenant (BOT-1259), not a per-type param.
+        const linearScope = new Map();
+        for (const rc of reg.conditions) {
+          if (rc && rc.type === "lock" && rc.params && typeof rc.params.host === "string") {
+            canonHost.set(rc.id, rc.params.host);
+          }
+          if (rc && rc.type === "unblocked" && rc.params && typeof rc.params.tenant === "string") {
+            unblockedScope.set(rc.id, { tenant: rc.params.tenant, linear_issue_id: rc.params.linear_issue_id ?? null });
+          }
+          if (rc && rc.type === "linear" && rc.params && typeof rc.params.linear_issue_id === "string") {
+            linearScope.set(rc.id, rc.params.linear_issue_id);
+          }
+        }
+        for (const c of conditions) {
+          if (c.type === "lock" && canonHost.has(c.id)) c.params.host = canonHost.get(c.id);
+          if (c.type === "unblocked" && unblockedScope.has(c.id)) {
+            const s = unblockedScope.get(c.id);
+            c.params.tenant = s.tenant;
+            if (s.linear_issue_id) c.params.linear_issue_id = s.linear_issue_id;
+          }
+          if (c.type === "linear" && linearScope.has(c.id)) c.params.linear_issue_id = linearScope.get(c.id);
+        }
+      }
+      // Arm from the registration high-water mark unless the caller pinned an
+      // explicit --since (resume). cursor_start replays the register→connect gap.
+      if (opts.since == null && reg.cursorStart != null) effectiveSince = String(reg.cursorStart);
+      if (hasClaim && waitSessionId == null) {
+        process.stderr.write("bb-wait: claim=true registration returned no wait_session_id; refusing to arm an unmatchable claim wait\n");
+        emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        process.exit(EXIT.INTERNAL);
+      }
+    } catch (err) {
+      if (err && err.clientOutdated) {
+        process.stderr.write(`botbuddy wait: client protocol is no longer supported — upgrade with: ${err.upgradeCommand}\n`);
+        emitReceipt({
+          schema_version: 1,
+          outcome: "error",
+          error: err.errorCode,
+          detail: String(err.message),
+          minimum_wait_protocol: err.minimumProtocol,
+          upgrade_command: err.upgradeCommand,
+        });
+        process.exit(EXIT.INVALID);
+      }
+      if (err && err.auth) {
+        const error = typedProfileError(err.errorCode);
+        process.stderr.write(`botbuddy wait: profile authentication failed (${error}); run '${profileRecovery(opts.agentProfile)}'\n`);
+        emitReceipt(profileErrorReceipt(opts.agentProfile, error));
+        process.exit(EXIT.AUTH);
+      }
+      if (err && err.cap) {
+        process.stderr.write(`bb-wait: too many active waits for this agent — ${err.message}\n`);
+        emitReceipt({
+          schema_version: 1,
+          outcome: "error",
+          error: err.errorCode || "wait_session_cap_exceeded",
+          detail: String(err.message),
+        });
+        process.exit(EXIT.INVALID);
+      }
+      if (err && err.invalidCondition) {
+        // A rejected condition set is a configuration error, not a wait — fail closed
+        // rather than arming an untracked wait that skips the server's initial
+        // evaluation (BOT-1066 no_signal_source, BOT-1247 unblocked_cross_tenant, …).
+        process.stderr.write(`bb-wait: invalid condition (${err.errorCode}) — ${err.message}\n`);
+        emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.message) });
+        process.exit(EXIT.INVALID);
+      }
+      if (err && err.initialEval) {
+        process.stderr.write(`bb-wait: initial wait evaluation failed (${err.errorCode}) — ${err.detail}\n`);
+        emitReceipt({ schema_version: 1, outcome: "error", error: err.errorCode, detail: String(err.detail) });
+        process.exit(EXIT.INTERNAL);
+      }
+      if (hasClaim) {
+        process.stderr.write(`bb-wait: claim=true wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
+        emitReceipt({ schema_version: 1, outcome: "error", error: "claim_registration_failed" });
+        process.exit(EXIT.INTERNAL);
+      }
+      // BOT-1338: every non-timer wait is now a tenant-bound machine profile. If
+      // registration did not succeed, neither the server nor this client has verified
+      // that profile's tenant, so there is no safe untracked fallback for ANY condition.
+      process.stderr.write(`bb-wait: profiled wait-session registration failed (failing closed, not arming untracked): ${err && err.message || err}\n`);
+      emitReceipt(withPrincipalReceipt(
+        { schema_version: 1, outcome: "error", error: "register_failed", detail: String(err && err.message || err) },
+        opts.agentProfile,
+        { sessionTenant: opts.agentProfile.tenant, agentId: null },
+      ));
+      process.exit(EXIT.INTERNAL);
+    }
+  }
+
+  const connect = needsRelay ? makeConnect(opts) : async () => offlineStream();
+  // BOT-1147 AC-3: wire the feed-freshness probe only when a linear condition is
+  // armed against the relay (runWaitLoop no-ops the probe for other wait types).
+  const feedLagProbe = needsRelay && conditions.some((c) => c.type === "linear")
+    ? makeFeedLagProbe(opts)
+    : null;
+
+  try {
+    const { receipt, exitCode } = await runWaitLoop({
+      waitSessionId,
+      conditions,
+      deadlineMs,
+      since: effectiveSince,
+      connect,
+      feedLagProbe,
+      receiptMaxBytes: opts.receiptMaxBytes,
+      // BOT-1259: fail-closed tenant scope for the central guard, plus a debug sink
+      // (opt-in via BB_WAIT_DEBUG) that surfaces each fail-closed drop without turning
+      // it into an error.
+      sessionTenant,
+      debug: process.env.BB_WAIT_DEBUG ? (msg) => process.stderr.write(`${msg}\n`) : null,
+    });
+    // Emit the wake receipt FIRST — it is the terminal result the harness reads.
+    // Finalization is best-effort telemetry and must never gate or delay it.
+    const terminalReceipt = truncateReceipt(
+      withClientIdentity(withPrincipalReceipt(receipt, opts.agentProfile, {
+        sessionTenant,
+        agentId: registeredAgentId,
+      })),
+      opts.receiptMaxBytes,
+    );
+    emitReceipt(terminalReceipt, { versioned: true });
+    // BOT-1228: a `superseded` outcome means an external actor already terminalized
+    // this wait_session server-side (reconcile_waits_to_canonical → abandoned, with
+    // ended_at/updated_at stamped). Skip the client finalize: the row is already
+    // terminal (finalize_wait_session only transitions from active, so it'd be a
+    // no-op) and `superseded` isn't a wait_session_status enum value anyway.
+    if (waitSessionId && receipt.outcome !== "superseded") await finalizeWait(opts, waitSessionId, terminalReceipt);
+    process.exit(exitCode);
+  } catch (err) {
+    process.stderr.write(`bb-wait: ${err && err.stack || err}\n`);
+    emitReceipt({ schema_version: 1, outcome: "error", error: "internal" });
+    process.exit(EXIT.INTERNAL);
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runWait(process.argv.slice(2));
+}