@botbuddy/cli 1.67.0 → 1.68.1

package/src/status-band-read.mjs

@@ -0,0 +1,552 @@
+// BOT-2644 / BOT-3152. Read-only host adapter (`bb status-band read`), run from the
+// installed CLI. Credentials stay in this process, never in the mod.
+import { open, readFile, realpath } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+const UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TICKET = /^BOT-[1-9]\d*$/;
+// The repo's committed binding picks the tenant; each tenant owns one key prefix.
+const TENANTS = { botbuddy: "BOT", "supply-guard": "ENT" };
+const MCP = "https://api.bot-buddy.ai/functions/v1/mcp-server/tools/";
+const UUID_LOWER = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const LINEAR_PROJECT_URL = /^https:\/\/linear\.app\/[a-z0-9-]{1,64}\/project\/[a-z0-9-]{1,200}$/;
+const PROJECT_IDENTIFIER = /^P-[A-Z][A-Z0-9]{1,9}-[1-9]\d{0,5}$/;
+const PROJECT_STATES = ["backlog", "planned", "started", "paused", "completed", "canceled"];
+const REPO = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}$/;
+// Linear state type or BB work-item stage → the band's status word.
+const STATUS = {
+  started: "In Progress",
+  working: "In Progress",
+  review: "In Review",
+  completed: "Done",
+  complete: "Done",
+  canceled: "Canceled",
+  unstarted: "Todo",
+  backlog: "Backlog",
+  planned: "Todo",
+  triage: "Triage",
+};
+const QUERY = `query BbClaudeStatus($id: String!) {
+ organization { urlKey }
+ issue(id: $id) {
+  id identifier title url team { key } state { name type }
+  inverseRelations(first: 100) {
+   nodes { type issue { identifier title url team { key } state { name type } } }
+   pageInfo { hasNextPage endCursor }
+  }
+ }
+}`;
+// A review-round count from BB, or null when BB has none for the PR.
+function reviewCount(v) {
+  return Number.isSafeInteger(v) && v >= 0 && v <= 999 ? v : null;
+}
+// BOT-3152 AC-2: the web top bar's Staging chip (top_bar_signals): red while the
+// tenant has an open staging incident; null when BB did not say (never green).
+function stagingOf(own) {
+  const st = own?.staging;
+  if (!st || typeof st !== "object" || typeof st.configured !== "boolean") return null;
+  const since = typeof st.open_since === "string" && Number.isFinite(Date.parse(st.open_since)) ? new Date(st.open_since).toISOString() : null;
+  return { configured: st.configured, red: st.configured && since !== null, since: st.configured ? since : null };
+}
+function refuse(code) {
+  throw new Error(code);
+}
+function label(value, max = 240) {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    value.length > max ||
+    /[\u0000-\u001f\u007f\u202a-\u202e\u2066-\u2069]/u.test(value)
+  )
+    refuse("invalid_response");
+  return value.trim();
+}
+function issueLink(value, key) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    refuse("unsafe_link");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.hostname !== "linear.app" ||
+    url.port ||
+    url.username ||
+    url.password ||
+    !new RegExp(`^/botbuddy/issue/${key}(?:/|$)`).test(url.pathname) ||
+    url.search ||
+    url.hash
+  )
+    refuse("unsafe_link");
+  return url.href;
+}
+// A display string from BB, or null: never throws, so one odd title cannot
+// sink the snapshot the way a bad identity or link must.
+function safeText(value, max = 240) {
+  if (typeof value !== "string") return null;
+  const t = value.trim();
+  if (!t || /[\u0000-\u001f\u007f\u202a-\u202e\u2066-\u2069]/u.test(t)) return null;
+  return t.length > max ? t.slice(0, max - 1) + "…" : t;
+}
+async function jsonRequest(url, init, fetchImpl, timeoutMs = 8000) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      ...init,
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    refuse("source_unreachable");
+  }
+  if (!response.ok)
+    refuse(
+      response.status === 401 || response.status === 403
+        ? "source_unauthorized"
+        : "source_unavailable",
+    );
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    refuse("invalid_response");
+  }
+  if (body?.errors || body?.error || body?.isError) refuse("source_rejected");
+  return body;
+}
+async function readSession(cwd) {
+  const handle = await open(join(cwd, ".botbuddy/agent-state.json"), "r").catch(
+    () => refuse("session_missing"),
+  );
+  try {
+    const info = await handle.stat();
+    if ((info.mode & 0o077) !== 0 || info.size > 65536)
+      refuse("session_file_unsafe");
+    try {
+      return JSON.parse(await handle.readFile("utf8"));
+    } catch {
+      refuse("session_invalid");
+    }
+  } finally {
+    await handle.close();
+  }
+}
+export async function readStatus({
+  cwd,
+  harnessSessionId,
+  ticketId,
+  linearKey,
+  // BOT-3135: a relay wake skips the slow epic read; the mod keeps the last epic.
+  skipEpic = false,
+  now = () => Date.now(),
+  fetchImpl = fetch,
+  branchReader = async (path) =>
+    (
+      await execFileAsync("git", ["branch", "--show-current"], { cwd: path })
+    ).stdout.trim(),
+}) {
+  if (!UUID.test(harnessSessionId)) refuse("harness_session_missing");
+  const root = await realpath(cwd);
+  let binding;
+  try {
+    binding = JSON.parse(
+      await readFile(join(root, ".botbuddy-agent.json"), "utf8"),
+    );
+  } catch {
+    refuse("repo_binding_missing");
+  }
+  if (binding.schema_version !== 1 || !Object.hasOwn(TENANTS, binding.tenant))
+    refuse("tenant_mismatch");
+  const tenant = binding.tenant;
+  const prefix = TENANTS[tenant];
+  // Linear is read for the BotBuddy workspace only (exact state + blockers);
+  // SupplyGuard status comes from BB's own synced copy of its tickets.
+  const useLinear = tenant === "botbuddy";
+  if (useLinear && (typeof linearKey !== "string" || !linearKey.trim()))
+    refuse("linear_key_missing");
+  const state = await readSession(root);
+  if (
+    state.schema_version !== 1 ||
+    state.harness_session_id?.toLowerCase() !== harnessSessionId.toLowerCase()
+  )
+    refuse("session_mismatch");
+  if (
+    state.tenant !== tenant ||
+    !UUID.test(state.agent_id) ||
+    !UUID.test(state.session_id)
+  )
+    refuse("session_invalid");
+  if (state.worktree !== root) refuse("worktree_mismatch");
+  if (!(Date.parse(state.expires_at) > now())) refuse("session_expired");
+  if (
+    typeof state.agent_session_token !== "string" ||
+    !/^bb_(?:agent|sess)_[0-9a-f]{64}$/.test(state.agent_session_token)
+  )
+    refuse("session_invalid");
+  const branch = label(await branchReader(root));
+  const keyPattern = new RegExp(`^${prefix}-[1-9]\\d*$`);
+  const branchTicket = branch.match(
+    new RegExp(`(?:^|/)${prefix.toLowerCase()}-([1-9]\\d*)(?:-|$)`, "i"),
+  );
+  const branchKeys = branchTicket ? [`${prefix}-${branchTicket[1]}`] : [];
+  // `/bb-status live KEY…` picks the tickets explicitly.
+  const selected = ticketId === undefined ? null : [...new Set(String(ticketId).split(","))];
+  if (selected && (!selected.length || selected.length > 5 || !selected.every((k) => keyPattern.test(k))))
+    refuse("ticket_missing");
+  const identity = await jsonRequest(
+    "https://api.bot-buddy.ai/functions/v1/mcp-server/tools/whoami",
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-agent-api-key": state.agent_session_token,
+      },
+      body: "{}",
+    },
+    fetchImpl,
+  );
+  if (identity.tenant_id !== tenant) refuse("tenant_mismatch");
+  if (
+    identity.agent?.id !== state.agent_id ||
+    identity.credential_kind !== "agent_session"
+  )
+    refuse("agent_mismatch");
+  const bb = (name, args, timeoutMs) =>
+    jsonRequest(
+      MCP + name,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-agent-api-key": state.agent_session_token,
+        },
+        body: JSON.stringify(args),
+      },
+      fetchImpl,
+      timeoutMs,
+    ).catch(() => null);
+  // BOT-3136: what this session registered with BB comes first. A reply for
+  // another session or tenant is ignored, and an empty one falls back to the
+  // branch key, which the snapshot labels as a guess.
+  // BOT-3152 (review on #1616): read even with an explicit selection, because the
+  // tenant's staging state comes from it whatever supplies the tickets.
+  const own = await bb("get_session_status", {});
+  const ownOk =
+    own?.session_id === state.session_id && own?.tenant_id === tenant && Array.isArray(own?.tickets);
+  const sessionKeys = ownOk && !selected
+    ? [...new Set(own.tickets.map((x) => String(x?.key || "").toUpperCase()).filter((k) => keyPattern.test(k)))].slice(0, 5)
+    : [];
+  const bindingKind = selected ? "selected" : sessionKeys.length ? "session" : "branch";
+  const keys = selected ?? (sessionKeys.length ? sessionKeys : branchKeys);
+  if (!keys.length) refuse("ticket_missing");
+  const key = keys[0];
+  const useSession = bindingKind === "session";
+  // The Linear ticket read and the BB reads are independent, so they run
+  // together; a refused BB read blanks only its line. The epic read is the slow
+  // one (~7 s live), so it gets a longer budget, and a relay wake skips it.
+  const linearGraph = useLinear
+    ? jsonRequest(
+        "https://api.linear.app/graphql",
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: linearKey },
+          body: JSON.stringify({ query: QUERY, variables: { id: key } }),
+        },
+        fetchImpl,
+      )
+    : null;
+  linearGraph?.catch(() => {});
+  // A session-bound band needs none of the broad reads (BOT-3136 AC-2).
+  const [work, prState, epicHealth] = useSession
+    ? [null, null, null]
+    : await Promise.all([
+        bb("list_work_items", { entity: "ticket", limit: 200 }),
+        bb("get_pr_state", { include_closed: true }),
+        skipEpic ? null : bb("get_epic_health", { team_key: prefix }, 15000),
+      ]);
+  let linearTicket = null;
+  const blockers = [];
+  if (useLinear) {
+  const graph = await linearGraph;
+  const issue = graph?.data?.issue;
+  if (
+    graph?.data?.organization?.urlKey !== "botbuddy" ||
+    issue?.team?.key !== "BOT" ||
+    issue?.identifier !== key
+  )
+    refuse("ticket_scope_mismatch");
+  const relations = issue.inverseRelations;
+  if (
+    relations?.pageInfo?.hasNextPage !== false ||
+    !Array.isArray(relations.nodes)
+  )
+    refuse("blockers_incomplete");
+  for (const relation of relations.nodes) {
+    if (relation.type !== "blocks") continue;
+    const blocker = relation.issue;
+    if (
+      !blocker ||
+      !TICKET.test(blocker.identifier) ||
+      blocker.team?.key !== "BOT" ||
+      !blocker.state?.type
+    )
+      refuse("blockers_incomplete");
+    if (["completed", "canceled"].includes(blocker.state.type)) continue;
+    blockers.push({
+      key: blocker.identifier,
+      title: label(blocker.title),
+      status: label(blocker.state.name),
+      url: issueLink(blocker.url, blocker.identifier),
+    });
+  }
+  linearTicket = {
+    key,
+    title: label(issue.title),
+    status: label(issue.state?.name),
+    url: issueLink(issue.url, key),
+  };
+  }
+  const epics = Array.isArray(epicHealth?.epics) ? epicHealth.epics : [];
+  const workItems = Array.isArray(work?.items) ? work.items : [];
+  const fromBb = (k) => {
+    if (useSession) {
+      const t = own.tickets.find((x) => String(x?.key || "").toUpperCase() === k);
+      return t ? { title: t.title, status: STATUS[t.state_type] || (typeof t.state === "string" ? t.state : null) } : null;
+    }
+    const item = workItems.find((w) => w?.kind === "ticket" && w.ticket === k);
+    if (item) return { title: item.title, status: STATUS[item.stage] };
+    for (const e of epics) {
+      const c = (e?.children || []).find((x) => x?.external_id === k);
+      if (c) return { title: c.title, status: STATUS[c.state_type] };
+    }
+    return null;
+  };
+  const tickets = keys.map((k) => {
+    if (linearTicket && k === key)
+      return { key: k, title: linearTicket.title, status: linearTicket.status };
+    const found = fromBb(k);
+    return {
+      key: k,
+      title: found ? safeText(found.title) || "Not in BB yet" : "Not in BB yet",
+      status: found?.status || "Unknown",
+    };
+  });
+  // PRs whose head is this worktree's branch, or whose title or branch names
+  // one of the session's tickets as a whole key (BOT-77, never BOT-770).
+  const keyRes = keys.map((k) => new RegExp(`(?:^|[^A-Za-z0-9])${k}(?![0-9])`, "i"));
+  const mentions = (p) =>
+    keyRes.some((re) => re.test(String(p?.title || "")) || re.test(String(p?.headRefName || "")));
+  // Newest first as BB returns them.
+  const prs = useSession
+    ? (Array.isArray(own.prs) ? own.prs : [])
+        .filter((p) => REPO.test(p?.repo) && Number.isSafeInteger(p?.number) && p.number > 0)
+        .slice(0, 5)
+        .map((p) => ({
+          repo: p.repo,
+          number: p.number,
+          title: safeText(p.title) || "Untitled PR",
+          state: p.state === "draft" || (p.is_draft && p.state === "open") ? "draft" : ["open", "merged", "closed"].includes(p.state) ? p.state : "open",
+          conflict: false,
+          // BOT-3152 AC-3: pr_state.review_rounds, the column get_pr_state returns as reviewRounds.
+          reviews: reviewCount(p.review_rounds),
+        }))
+    : Array.isArray(prState?.prs)
+    ? prState.prs
+        .filter((p) => (p?.headRefName === branch || mentions(p)) && REPO.test(p.slug) && Number.isSafeInteger(p.number) && p.number > 0)
+        .slice(0, 5)
+        .map((p) => ({
+          repo: p.slug,
+          number: p.number,
+          title: safeText(p.title) || "Untitled PR",
+          // BB reports a draft either as state "draft" or as an open PR flagged isDraft.
+          state: p.state === "draft" || (p.isDraft && p.state === "open") ? "draft" : ["open", "merged", "closed"].includes(p.state) ? p.state : "open",
+          conflict: p.mergeable === "CONFLICTING",
+          reviews: reviewCount(p.reviewRounds),
+        }))
+    : null;
+  // Always one epic: the project of the first ticket, in session order, that
+  // belongs to one.
+  const epicOf = (k) =>
+    epics.find(
+      (e) => UUID_LOWER.test(e?.epic_project_id) && (e.children || []).some((c) => c?.external_id === k),
+    );
+  const owner = useSession ? null : keys.map(epicOf).find(Boolean);
+  let epic = null;
+  const se = useSession ? own.epic : null;
+  if (se && UUID_LOWER.test(se.linear_project_id)) {
+    // As the branch path and v_epics.progress_pct do: canceled children don't count.
+    const total = Math.max(0, (se.children_total ?? 0) - (se.children_canceled ?? 0));
+    const done = Math.min(total, Math.max(0, se.children_completed ?? 0));
+    const slug = String(se.url || "").match(/-([0-9a-f]{8,16})$/);
+    epic = {
+      id: se.linear_project_id,
+      short_id: slug ? slug[1] : se.linear_project_id.slice(0, 8),
+      name: safeText(se.name) || "Untitled epic",
+      state: PROJECT_STATES.includes(se.state) ? se.state : "planned",
+      url: LINEAR_PROJECT_URL.test(se.url || "") ? se.url : null,
+      identifier: PROJECT_IDENTIFIER.test(se.identifier || "") ? se.identifier : null,
+      done,
+      total,
+      percent: Number.isFinite(se.progress_pct) ? Math.max(0, Math.min(100, Math.round(se.progress_pct))) : total ? Math.round((100 * done) / total) : 0,
+    };
+  }
+  if (owner) {
+    const total = Math.max(0, (owner.children_total ?? 0) - (owner.children_canceled ?? 0));
+    const done = Math.min(total, Math.max(0, owner.children_completed ?? 0));
+    const slug = String(owner.epic_url || "").match(/-([0-9a-f]{8,16})$/);
+    epic = {
+      id: owner.epic_project_id,
+      short_id: slug ? slug[1] : owner.epic_project_id.slice(0, 8),
+      name: safeText(owner.epic_name) || "Untitled epic",
+      // Linear's project state drives its icon; percent only fills the wedge.
+      state: PROJECT_STATES.includes(owner.project_state) ? owner.project_state : "planned",
+      // The project's own Linear page, for the band's direct ↗ link.
+      url: LINEAR_PROJECT_URL.test(owner.epic_url || "") ? owner.epic_url : null,
+      identifier: null,
+      done,
+      total,
+      percent: total ? Math.round((100 * done) / total) : 0,
+    };
+  }
+  // A bootstrap/session switch during either network request invalidates this snapshot.
+  const latest = await readSession(root);
+  if (
+    latest.agent_id !== state.agent_id ||
+    latest.session_id !== state.session_id ||
+    latest.harness_session_id !== state.harness_session_id ||
+    latest.session_token_generation !== state.session_token_generation ||
+    latest.agent_session_token !== state.agent_session_token ||
+    latest.tenant !== state.tenant ||
+    latest.worktree !== state.worktree ||
+    !(Date.parse(latest.expires_at) > now()) ||
+    (await branchReader(root)) !== branch
+  )
+    refuse("session_changed");
+  // Linear's project identifier (e.g. P-BOT-39): read directly for BotBuddy,
+  // whose Linear key this adapter holds; Supply Guard waits for BB to sync it.
+  if (epic && !epic.identifier && useLinear) {
+    const found = await jsonRequest(
+      "https://api.linear.app/graphql",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: linearKey },
+        body: JSON.stringify({
+          query: "query BbProjectIdentifier($id: String!) { project(id: $id) { identifier } }",
+          variables: { id: epic.id },
+        }),
+      },
+      fetchImpl,
+    ).catch(() => null);
+    const id = found?.data?.project?.identifier;
+    epic.identifier = PROJECT_IDENTIFIER.test(id || "") ? id : null;
+  }
+  return {
+    schema_version: 2,
+    tenant,
+    harness_session_id: harnessSessionId.toLowerCase(),
+    session_id: state.session_id,
+    observed_at: new Date(now()).toISOString(),
+    branch,
+    agent: {
+      id: state.agent_id,
+      name: label(identity.agent.display_name, 100),
+    },
+    ticket: linearTicket || { ...tickets[0], url: null },
+    tickets,
+    prs,
+    epic,
+    ...(skipEpic && !useSession ? { epic_skipped: true } : {}),
+    // BOT-3152 AC-1: the epic source failed, so "no epic" would be a guess.
+    epic_unreadable: useSession ? false : !skipEpic && !Array.isArray(epicHealth?.epics),
+    staging: ownOk ? stagingOf(own) : null,
+    // BOT-3136: where the tickets came from — the registered session, an explicit
+    // pick, or (only when the session registered none) a guess from the branch.
+    binding: bindingKind,
+    blockers: useLinear
+      ? [...new Map(blockers.map((b) => [b.key, b])).values()].sort((a, b) =>
+          a.key.localeCompare(b.key),
+        )
+      : null,
+  };
+}
+// BOT-3152 AC-5: a repo with no SessionStart bootstrap hook (Supply Guard) leaves
+// the worktree cache missing, unbound (no harness id) or expired, so the band
+// binds this session itself, once per read, through the same bootstrap
+// `bb bootstrap` runs. A cache another harness session holds is never
+// bootstrapped over: that session owns the worktree's identity.
+const BINDABLE = new Set(["session_missing", "session_mismatch", "session_expired"]);
+async function bindable(cwd, harnessSessionId, now) {
+  let state;
+  try {
+    state = JSON.parse(await readFile(join(await realpath(cwd), ".botbuddy/agent-state.json"), "utf8"));
+  } catch (error) {
+    return error?.code === "ENOENT";
+  }
+  const holder = typeof state?.harness_session_id === "string" ? state.harness_session_id.toLowerCase() : "";
+  if (!holder || holder === harnessSessionId.toLowerCase()) return true;
+  return !(Date.parse(state.expires_at) > now());
+}
+async function bootstrapBand({ cwd, harnessSessionId, branch }) {
+  const [{ bootstrapHarnessSession }, { getConfig }, { hostname }] = await Promise.all([
+    import("./session-bootstrap.mjs"),
+    import("./config.mjs"),
+    import("node:os"),
+  ]);
+  await bootstrapHarnessSession({
+    name: `${getConfig()?.agent_name || `botbuddy-${hostname()}`}-${harnessSessionId.slice(0, 8)}`,
+    type: "claude",
+    harnessSessionId,
+    cwd,
+    branch,
+    noTicketReason: "bb-status band bound a Claude Code session its repo did not bootstrap",
+    harness: "botbuddy-claude-band",
+  });
+}
+
+export async function main(args, {
+  out = process.stdout,
+  cwd = process.cwd(),
+  env = process.env,
+  read = readStatus,
+  bootstrap = bootstrapBand,
+  now = () => Date.now(),
+} = {}) {
+  try {
+    args = [...args];
+    const skipEpic = args.at(-1) === "--skip-epic";
+    if (skipEpic) args.pop();
+    if (args.length !== 2 && args.length !== 4) refuse("invalid_arguments");
+    if (
+      args[0] !== "--harness-session-id" ||
+      (args.length === 4 && args[2] !== "--ticket-id")
+    )
+      refuse("invalid_arguments");
+    const request = { cwd, harnessSessionId: args[1], ticketId: args[3], linearKey: env.LINEAR_BB_API_KEY, skipEpic };
+    let snapshot;
+    try {
+      snapshot = await read(request);
+    } catch (error) {
+      if (!BINDABLE.has(error?.message) || !UUID.test(args[1]) || !(await bindable(cwd, args[1], now))) throw error;
+      let branch = null;
+      try {
+        branch = (await execFileAsync("git", ["branch", "--show-current"], { cwd })).stdout.trim() || null;
+      } catch { /* detached or not a repo: bootstrap without a branch */ }
+      try {
+        await bootstrap({ cwd, harnessSessionId: args[1].toLowerCase(), branch });
+      } catch {
+        throw error;
+      }
+      snapshot = await read(request);
+    }
+    out.write(JSON.stringify(snapshot) + "\n");
+    return 0;
+  } catch (error) {
+    const known = /^[a-z_]+$/.test(error?.message ?? "") ? error.message : "status_unavailable";
+    out.write(JSON.stringify({ error: known }) + "\n");
+    return 1;
+  }
+}

package/src/status-band-relay.mjs

@@ -0,0 +1,104 @@
+// BOT-3135 / BOT-3152. The band's relay child (`bb status-band relay`): arms ONE
+// `bb wait` on the band's own subjects and reports how it ended. It runs this
+// installed package's own `wait` through the node that runs it — no PATH lookup,
+// no shell, no repo checkout — and never reads BB itself.
+import { execFile as nodeExecFile } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+// Under the 10-minute ceiling a mod gives a one-shot child, so a stuck
+// relay can never outlive one arm; the mod re-arms from the cursor.
+export const WAIT_TIMEOUT_SECONDS = 570;
+const SHORT_TIMEOUT_REASON =
+  "bb-status band relay: re-armed from its cursor every 570 s by the mod";
+const KEY = "(?:BOT|ENT)-[1-9]\\d{0,5}";
+const REPO = "[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}";
+// BOT-3136: the epic row wakes on its Linear project.
+const PROJECT = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+// BOT-3152 AC-2: any staging incident of the session's tenant opening or closing.
+const STAGING = "event:type=staging_incident";
+const CONDITION = new RegExp(
+  `^(?:linear:issue=${KEY}|unblocked:${KEY}|pr-(?:state|review):repo=${REPO},pr=[1-9]\\d{0,6}|event:type=linear_project,subject=${PROJECT}|${STAGING})$`,
+);
+const CURSOR = /^\d{1,16}$/;
+// The band's largest list: 5 tickets, 5 PRs (state + review), blockers, epic, staging.
+const MAX_CONDITIONS = 18;
+export const CLI_ENTRY = join(resolve(dirname(fileURLToPath(import.meta.url)), ".."), "bin", "botbuddy.mjs");
+
+function invalid() {
+  throw new Error("invalid_arguments");
+}
+
+export function relayArgs(argv) {
+  const conditions = [];
+  let since = null;
+  for (let i = 0; i < argv.length; i += 2) {
+    const [flag, value] = [argv[i], argv[i + 1]];
+    if (typeof value !== "string") invalid();
+    if (flag === "--cond" && CONDITION.test(value) && !value.includes("..") && !conditions.includes(value)) conditions.push(value);
+    else if (flag === "--since" && since === null && CURSOR.test(value)) since = value;
+    else invalid();
+  }
+  if (conditions.length < 1 || conditions.length > MAX_CONDITIONS) invalid();
+  return { conditions, since };
+}
+
+// The receipt is bb's last JSON line; only the fields the mod needs leave here.
+export function summarize(exit, stdout) {
+  let receipt = null;
+  for (const line of String(stdout).trim().split("\n").reverse()) {
+    try {
+      receipt = JSON.parse(line);
+      break;
+    } catch {
+      /* banner or log line */
+    }
+  }
+  const cursor = receipt?.next_cursor == null ? null : String(receipt.next_cursor);
+  const id = receipt?.wait_session_id;
+  return {
+    exit,
+    outcome: typeof receipt?.outcome === "string" && /^[a-z_]{1,40}$/.test(receipt.outcome) ? receipt.outcome : "error",
+    wait_id: typeof id === "string" && /^[0-9a-z-]{1,64}$/i.test(id) ? id : null,
+    next_cursor: cursor && CURSOR.test(cursor) ? cursor : null,
+  };
+}
+
+export async function runRelay(
+  argv,
+  { execPath = process.execPath, cliEntry = CLI_ENTRY, execFile = promisify(nodeExecFile), cwd } = {},
+) {
+  const { conditions, since } = relayArgs(argv);
+  const args = [
+    cliEntry,
+    "wait",
+    ...conditions,
+    "--timeout",
+    String(WAIT_TIMEOUT_SECONDS),
+    "--allow-short-timeout",
+    SHORT_TIMEOUT_REASON,
+    ...(since ? ["--since", since] : []),
+  ];
+  try {
+    const { stdout } = await execFile(execPath, args, {
+      cwd,
+      maxBuffer: 4 * 1024 * 1024,
+      timeout: (WAIT_TIMEOUT_SECONDS + 25) * 1000,
+    });
+    return summarize(0, stdout);
+  } catch (error) {
+    return summarize(typeof error?.code === "number" ? error.code : 7, error?.stdout ?? "");
+  }
+}
+
+export async function main(argv, { out = process.stdout, cwd = process.cwd() } = {}) {
+  let res;
+  try {
+    res = await runRelay(argv, { cwd });
+  } catch {
+    res = { exit: 4, outcome: "error", error: "invalid_arguments", wait_id: null, next_cursor: null };
+  }
+  out.write(JSON.stringify(res) + "\n");
+  return 0;
+}