@botbuddy/cli 1.34.4 → 1.36.0

package/src/pw/telemetry.mjs

@@ -1,14 +1,115 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { homedir } from "node:os";
+// BOT-1318 — production wiring for bb pw browser-acceptance telemetry.
+//
+// Replaces the pre-BOT-1318 lane-number spool + close-only record_lane_event
+// rollup. A repository opts in by committing `.botbuddy/config.json` (BOT-1316);
+// once opted in every rule fails closed: the checked-in repository must match
+// origin, the local credential binding must belong to the expected tenant, and
+// that credential is attested once against the server (cached by fingerprint).
+// A repository without the checked-in config stays untracked, exactly as before.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { deriveSession } from "./readiness.mjs";
-const spoolDir = (env) => env.BB_PW_SPOOL_DIR || join(homedir(), ".botbuddy", "pw-spool");
-export function makeTelemetry({ env = process.env } = {}) {
-  const path = (lane) => join(spoolDir(env), `lane-${lane}.jsonl`);
-  const readEvents = (lane) => existsSync(path(lane)) ? readFileSync(path(lane), "utf8").split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } }) : [];
+import { fileURLToPath } from "node:url";
+import { VERSION } from "../version.mjs";
+import { createTelemetryOutbox } from "../telemetry-outbox.mjs";
+import { deliverExecutionEvent } from "../telemetry-delivery.mjs";
+import { attestTelemetryCredential, loadTelemetryIdentity, loadTelemetryLocation } from "../telemetry-config.mjs";
+import { defaultGitInfo, findGitRoot } from "../test-lane.mjs";
+import { createBrowserTelemetryResolver } from "./session.mjs";
+import { resolveAgentSessionCredential } from "../agent-session.mjs";
+import { homedir } from "node:os";
+
+const HEARTBEAT_ENTRY = fileURLToPath(new URL("./heartbeat.mjs", import.meta.url));
+
+export function telemetryRoot(env = process.env) {
+  return env.BB_PW_TELEMETRY_ROOT || join(homedir(), ".botbuddy");
+}
+
+// Ticket/PR/branch attribution reuses the `botbuddy test` helper (BOT-1510):
+// explicit BB_PW_TICKET_ID / BB_PW_PR_ID win, else the branch's `bot-<n>` segment
+// and `gh pr view`; anything unresolved stays null — never a guess.
+export function gitInfoFor({ cwd, env }) {
+  let cached = null;
+  return () => {
+    if (!cached) {
+      const prOverride = env.BB_PW_PR_ID ? Number.parseInt(env.BB_PW_PR_ID, 10) : null;
+      cached = defaultGitInfo({ cwd, ticket: env.BB_PW_TICKET_ID || null, pr: Number.isInteger(prOverride) ? prOverride : null });
+    }
+    return cached;
+  };
+}
+
+// The session credential the foreground authenticated with (e.g. an explicit
+// --agent-session-token that is neither exported nor cached) is handed to the
+// detached heartbeat through its environment — readable only by the same user,
+// never on the command line — so the heartbeat re-resolves the same principal.
+export function spawnHeartbeatProcess({ cwd, env, sessionCredential = null, spawnImpl = spawn }) {
+  return (info) => {
+    const childEnv = { ...env, BB_PW_TELEMETRY_ROOT: info.root, ...(sessionCredential ? { BOTBUDDY_AGENT_SESSION_TOKEN: sessionCredential } : {}) };
+    const child = spawnImpl(process.execPath, [HEARTBEAT_ENTRY, JSON.stringify({ ...info, cwd })], {
+      cwd, detached: true, stdio: "ignore", env: childEnv,
+    });
+    child.on("error", () => {});
+    child.unref();
+    return child.pid ?? null;
+  };
+}
+
+// The worktree's already-resolved session credential (exported or the fresh `bb setup`
+// cache). Never self-heals: the detached heartbeat must not mint a session.
+async function cachedSessionCredential({ env, cwd }) {
+  try {
+    const credential = await resolveAgentSessionCredential({ argv: [], env, cwd, sessionId: null, flagToken: null, selfHeal: async () => null, warn: () => {} });
+    return credential?.token ?? null;
+  } catch { return null; }
+}
+
+/**
+ * Resolve the verified telemetry identity for this worktree and return a
+ * lane-tracker resolver, `{ tracked:false }` when the repository has not opted
+ * in, or `{ error }` (fail closed) when the opted-in identity is invalid. The
+ * durable mcp_env key is preferred; without one, the session credential the lane
+ * gate authenticated with (`sessionCredential`), else the cached session, is used.
+ */
+export async function resolveBrowserTelemetry({
+  env = process.env, cwd = process.cwd(), sessionCredential = null,
+  identityOptions = {}, resolveSession = cachedSessionCredential, attest = attestTelemetryCredential,
+} = {}) {
+  const gitRoot = findGitRoot(cwd);
+  if (!gitRoot || !existsSync(join(gitRoot, ".botbuddy", "config.json"))) return { tracked: false };
+  let identity;
+  try {
+    await loadTelemetryLocation(cwd, identityOptions);
+    identity = await loadTelemetryIdentity(cwd, { ...identityOptions, fallbackCredential: async () => sessionCredential || (await resolveSession({ env, cwd })) });
+  } catch (error) {
+    return { error: `bb-pw: browser telemetry identity rejected (${error?.message ?? "invalid"}); nothing was run. Fix .botbuddy/config.json or the worktree credential binding.` };
+  }
+  const root = telemetryRoot(env);
+  try {
+    const outbox = await createTelemetryOutbox({ root: join(root, "telemetry"), tenant: identity.tenant, repository: identity.repository, producerVersion: VERSION });
+    await attest(identity, outbox);
+  } catch (error) {
+    return { error: `bb-pw: browser telemetry credential rejected (${error?.message ?? "unattested"}); nothing was run.` };
+  }
+  return {
+    tracked: true,
+    resolver: createBrowserTelemetryResolver({
+      root, tenant: identity.tenant, repository: identity.repository, producerVersion: VERSION,
+      deliver: (event) => deliverExecutionEvent(event, { credential: identity.credential }),
+      gitInfo: gitInfoFor({ cwd, env }),
+      spawnHeartbeat: spawnHeartbeatProcess({ cwd, env, sessionCredential }),
+    }),
+  };
+}
+
+/** The runPw `deps.telemetry` default: `{ resolve({host, lane}) }`. */
+export function makeTelemetry({ env = process.env, cwd = process.cwd(), sessionCredential = null } = {}) {
+  let resolved = null;
   return {
-    append(lane, event) { mkdirSync(spoolDir(env), { recursive: true }); appendFileSync(path(lane), JSON.stringify({ ts: event.ts, method: event.method, url: event.url ?? null }) + "\n"); },
-    count(lane) { return readEvents(lane).length; },
-    async rollup({ lane, coordinator, host }) { const events = readEvents(lane); if (!events.length) return { emitted: false, count: 0 }; const session = deriveSession(events, { meta: { host, slot: String(lane), ticket_id: env.BB_PW_TICKET_ID, ticket_url: env.BB_PW_TICKET_URL, pr_id: env.BB_PW_PR_ID, pr_url: env.BB_PW_PR_URL, branch: env.BB_PW_BRANCH, commit_sha: env.BB_PW_COMMIT, environment: env.BB_PW_ENV } }); const event = { ...session, started_at: new Date(session.started_at).toISOString(), ended_at: new Date(session.ended_at).toISOString(), ended_reason: "close" }; try { if (!coordinator?.emit) return { emitted: false, count: events.length, session: event }; await coordinator.emit(event); rmSync(path(lane), { force: true }); return { emitted: true, count: events.length, session: event }; } catch { return { emitted: false, count: events.length, session: event }; } },
+    async resolve({ host, lane }) {
+      resolved ??= await resolveBrowserTelemetry({ env, cwd, sessionCredential });
+      if (!resolved.tracked) return resolved;
+      return resolved.resolver.resolve({ host, lane });
+    },
   };
 }

package/src/telemetry-config.mjs

@@ -36,18 +36,23 @@ export async function repositoryFromRemote(cwd = process.cwd()) {
 
 export async function verifyTelemetryIdentity(config, {
   cwd = process.cwd(), repositoryFromRemote: remote = repositoryFromRemote, resolveBinding = resolveAgentBinding, call = callToolJson, verifyCredential = false,
+  // BOT-1318: a `bb setup`-only worktree holds no mcp_env key, only its cached
+  // session token. The durable key still wins; the fallback is used only without it,
+  // and is attested against the expected tenant like any other credential.
+  fallbackCredential = async () => null,
 } = {}) {
   const repository = await remote(cwd);
   if (repository.toLowerCase() !== config.repository.toLowerCase()) throw new Error("telemetry repository mismatch with origin remote");
   const binding = await resolveBinding({ cwd });
-  if (!binding?.token) throw new Error("telemetry requires a locally stored tenant-bound credential");
-  if (binding.tenant !== config.expectedTenant) throw new Error("telemetry tenant mismatch with checked-in config");
+  if (binding?.tenant !== config.expectedTenant) throw new Error("telemetry tenant mismatch with checked-in config");
+  const credential = binding.token || (await fallbackCredential()) || null;
+  if (!credential) throw new Error("telemetry requires a locally stored tenant-bound credential");
   // A binding file names the intended tenant; it is not proof that a rotated
   // environment credential still belongs there. Ask the server's read-only
   // identity endpoint before allowing a foreground child to run.
   if (verifyCredential) {
     const verified = await call("whoami", {}, {
-      auth: { "x-agent-api-key": binding.token },
+      auth: { "x-agent-api-key": credential },
       tenant: config.expectedTenant,
       signal: AbortSignal.timeout(2_000),
     });
@@ -55,7 +60,7 @@ export async function verifyTelemetryIdentity(config, {
       throw new Error("telemetry credential is not attested to the expected tenant");
     }
   }
-  return { repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile, credential: binding.token };
+  return { repository: config.repository, tenant: config.expectedTenant, appSlug: config.appSlug, profile: config.profile, credential };
 }
 
 export async function loadTelemetryLocation(cwd = process.cwd(), {

package/src/telemetry-delivery.mjs

@@ -21,11 +21,29 @@ export async function deliverExecutionEvent(event, {
     });
     let body = {};
     try { body = await response.json(); } catch { /* typed HTTP status still controls retry */ }
-    if (response.status === 200 || response.status === 202) return { accepted: true, receipt: body.receipt ?? "accepted" };
+    // BOT-1318 (Codex R1 P2): carry the canonical execution UUID from the real
+    // execution-ingest receipt so producers can report it (never source_run_id).
+    if (response.status === 200 || response.status === 202) {
+      return {
+        accepted: true, receipt: body.receipt ?? "accepted",
+        ...(typeof body.execution_id === "string" && body.execution_id ? { execution_id: body.execution_id } : {}),
+        // BOT-1318 (Codex R13): a terminal outcome on a non-terminal event means the
+        // server already ended the run (e.g. reaped as abandoned) — producers reconcile.
+        ...(typeof body.outcome === "string" && body.outcome ? { outcome: body.outcome } : {}),
+      };
+    }
     // A reaper may have terminalized a run after a successful upload whose
     // response was lost. BOT-1317 correctly refuses a contradictory terminal;
     // retaining that record would otherwise block every later local event.
-    if (response.status === 409 && body.error === "terminal_conflict") return { accepted: true, receipt: "terminal_conflict_retired" };
+    // The 409 carries the canonical outcome and execution id; keep them so the producer
+    // reconciles its local terminal to the server's (Codex R27).
+    if (response.status === 409 && body.error === "terminal_conflict") {
+      return {
+        accepted: true, receipt: "terminal_conflict_retired",
+        ...(typeof body.outcome === "string" && body.outcome ? { outcome: body.outcome } : {}),
+        ...(typeof body.execution_id === "string" && body.execution_id ? { execution_id: body.execution_id } : {}),
+      };
+    }
     // The queue cannot repair an event rejected by the server's contract.
     // Quarantine these client errors so one malformed historical line does not
     // starve later valid lifecycle events. Authentication is deliberately left

package/src/telemetry-outbox.mjs

@@ -3,7 +3,7 @@
 // append a small, allowlisted lifecycle event before spawning a child; delivery
 // is a separate, idempotent step against execution-ingest.
 
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { chmod, link, mkdir, open, readFile, readdir, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -24,10 +24,26 @@ const CORRELATION_KEYS = new Set([
 ]);
 const PROGRESS_KEYS = new Set(["completed", "total", "phase", "current_item", "worker", "shard"]);
 const DIAGNOSTIC_KEYS = new Set(["code", "message", "category", "signal", "retryable"]);
+// BOT-1318: the optional, bounded browser-acceptance object. Mirrors the
+// execution-ingest contract; anything else (typed values, raw output, invented
+// metrics) is stripped here rather than shipped for the server to reject.
+const BROWSER_KEYS = new Set(["lane", "host", "action", "summary"]);
+const BROWSER_ACTION_KEYS = new Set(["action_id", "verb", "category", "phase", "started_at", "finished_at", "command_ms", "result", "error_class", "route"]);
+const BROWSER_SUMMARY_KEYS = new Set([
+  "actions_total", "actions_succeeded", "actions_failed", "actions_interrupted", "command_ms", "active_ms", "action_span_ms",
+  "first_action_at", "last_action_at", "navigations", "screenshots", "snapshots", "interactions", "distinct_routes", "acceptance_verdict",
+]);
+const pick = (value, keys) => Object.fromEntries(Object.entries(value).filter(([key]) => keys.has(key)));
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const hash = (value) => createHash("sha256").update(value).digest("hex");
 
+/** True when a string carries a credential the outbox would redact. */
+export function containsSensitive(value) {
+  SENSITIVE.lastIndex = 0;
+  return typeof value === "string" && SENSITIVE.test(value);
+}
+
 function redactString(value) {
   SENSITIVE.lastIndex = 0;
   return value.replace(SENSITIVE, "[REDACTED]");
@@ -55,7 +71,7 @@ function eventPayload(event) {
   if (!clean || typeof clean !== "object" || Array.isArray(clean)) throw new Error("telemetry event must be an object");
   // execution-ingest is intentionally strict. Keep this client-side allowlist so
   // a reporter cannot accidentally turn arbitrary process state into telemetry.
-  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs"]);
+  const allowed = new Set(["schema_version", "action", "producer_kind", "source_run_id", "attempt", "producer_event_id", "producer_sequence", "occurred_at", "context", "progress", "outcome", "diagnostic", "evidence_refs", "browser"]);
   for (const key of Object.keys(clean)) if (!allowed.has(key)) delete clean[key];
   // Mirror the server contract at the producer boundary. A malformed reporter
   // must not create a permanently retrying record merely because it included
@@ -69,6 +85,11 @@ function eventPayload(event) {
   if (clean.progress && typeof clean.progress === "object" && !Array.isArray(clean.progress)) {
     clean.progress = Object.fromEntries(Object.entries(clean.progress).filter(([key]) => PROGRESS_KEYS.has(key)));
   }
+  if (clean.browser && typeof clean.browser === "object" && !Array.isArray(clean.browser)) {
+    clean.browser = pick(clean.browser, BROWSER_KEYS);
+    if (clean.browser.action && typeof clean.browser.action === "object" && !Array.isArray(clean.browser.action)) clean.browser.action = pick(clean.browser.action, BROWSER_ACTION_KEYS);
+    if (clean.browser.summary && typeof clean.browser.summary === "object" && !Array.isArray(clean.browser.summary)) clean.browser.summary = pick(clean.browser.summary, BROWSER_SUMMARY_KEYS);
+  }
   if (clean.diagnostic && typeof clean.diagnostic === "object" && !Array.isArray(clean.diagnostic)) {
     clean.diagnostic = Object.fromEntries(Object.entries(clean.diagnostic).filter(([key]) => DIAGNOSTIC_KEYS.has(key)));
   }
@@ -88,7 +109,7 @@ async function durableWrite(path, value, { append = false } = {}) {
 }
 
 async function atomicJson(path, value) {
-  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
   await durableWrite(temp, `${JSON.stringify(value)}\n`);
   await rename(temp, path);
   // Persist the directory entry, not just the file data, before reporting the
@@ -137,7 +158,7 @@ export async function createTelemetryOutbox({
         // Write a complete, fsynced owner record first, then atomically publish
         // it with link(2). A crash can leave an unreferenced temp file but can
         // never strand the shared lock name with missing PID metadata.
-        const candidate = `${lockPath}.${process.pid}.${Date.now()}.tmp`;
+        const candidate = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
         await durableWrite(candidate, JSON.stringify({ pid: process.pid, created_at: now().toISOString() }));
         try { await link(candidate, lockPath); } finally { await unlink(candidate).catch(() => {}); }
         return async () => { try { await unlink(lockPath); } catch { /* a process may have cleaned its own stale lock */ } };
@@ -257,7 +278,7 @@ export async function createTelemetryOutbox({
         }
         offset += Buffer.byteLength(line) + 1;
       }
-      const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+      const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
       await durableWrite(tmp, remaining.map((record) => `${JSON.stringify(record)}\n`).join(""));
       await rename(tmp, path);
       let dir;
@@ -266,20 +287,25 @@ export async function createTelemetryOutbox({
     } finally { await release(); }
   }
 
-  async function status() {
+  /** `ownerOf(event)` (optional) also counts the queue per owner key, e.g. a browser lane. */
+  async function status({ ownerOf = null } = {}) {
     const lines = await readLines();
     let oldest = null;
     let queued = 0;
+    const byOwner = {};
     for (const line of lines) {
       try {
         const record = parseRecord(line);
         queued += 1;
+        const owner = ownerOf ? ownerOf(record.event) : null;
+        if (owner) byOwner[owner] = (byOwner[owner] ?? 0) + 1;
         if (!oldest || record.created_at < oldest) oldest = record.created_at;
       } catch { queued += 1; }
     }
     const persisted = await readStatus();
     return {
       queued_count: queued,
+      ...(ownerOf ? { queued_by_owner: byOwner } : {}),
       oldest_queued_at: oldest,
       last_successful_delivery_at: persisted.last_successful_delivery_at ?? null,
       last_error_class: persisted.last_error_class ?? null,

package/src/wait-core.mjs

@@ -132,8 +132,8 @@ const VALIDATORS = {
       claim,
     };
   },
-  "pr-state": (p) => parsePrTarget(p, "pr-state"),
-  "pr-review": (p) => parsePrTarget(p, "pr-review"),
+  "pr-state": (p) => parsePrCondition(p, "pr-state"),
+  "pr-review": (p) => parsePrCondition(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.
@@ -354,6 +354,46 @@ function parsePrTarget(p, label) {
   return { repo, number: number != null && number !== "" ? number : null };
 }
 
+// BOT-1975 / BOT-1972 — the pr-state / pr-review key allowlist. Before this an
+// unknown key (a typo'd `shaa=`, or `sha=` / `reviewer=` on a client that did not
+// implement them) was silently discarded and the wait armed WIDER than asked —
+// it then woke on another head's or another reviewer's signal. Now an unknown key
+// refuses at arm (invalid_conditions, exit 4). `reviewer=` is pr-review only.
+const PR_CONDITION_KEYS = Object.freeze({
+  "pr-state": Object.freeze(["repo", "pr", "number", "sha"]),
+  "pr-review": Object.freeze(["repo", "pr", "number", "sha", "reviewer"]),
+});
+
+// A GitHub login compared case-insensitively, with the App suffix `[bot]` stripped
+// (the webhook reports `chatgpt-codex-connector[bot]`; humans type it either way).
+function normalizeReviewerLogin(login) {
+  return String(login).trim().toLowerCase().replace(/\[bot\]$/, "");
+}
+
+function parsePrCondition(p, label) {
+  const allowed = PR_CONDITION_KEYS[label];
+  const unknown = Object.keys(p).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`${label} unknown key '${unknown[0]}' (allowed: ${allowed.join(", ")})`);
+  }
+  const out = parsePrTarget(p, label);
+  // Optional keys are added ONLY when given, so a plain wait's params (sent to the
+  // relay and saved in the local checkpoint) are byte-identical to before.
+  if (p.sha !== undefined) {
+    const sha = typeof p.sha === "string" ? p.sha.trim().toLowerCase() : "";
+    if (!/^[0-9a-f]{7,40}$/.test(sha)) {
+      throw new Error(`${label} sha= must be 7–40 hex characters (a commit SHA or its prefix)`);
+    }
+    out.sha = sha;
+  }
+  if (p.reviewer !== undefined) {
+    const reviewer = typeof p.reviewer === "string" ? normalizeReviewerLogin(p.reviewer) : "";
+    if (reviewer === "") throw new Error(`${label} reviewer= must be a GitHub login`);
+    out.reviewer = reviewer;
+  }
+  return out;
+}
+
 // Does a spine subject_key (`owner/repo#number`) satisfy a pr target?
 function prSubjectMatches(subjectKey, params) {
   if (typeof subjectKey !== "string") return false;
@@ -361,6 +401,35 @@ function prSubjectMatches(subjectKey, params) {
   return subjectKey.startsWith(`${params.repo}#`);
 }
 
+// Does a commit field on a signal payload start with the condition's sha prefix?
+// A missing / non-string field never matches a sha-scoped condition.
+function shaPrefixMatches(value, sha) {
+  return typeof value === "string" && value.trim().toLowerCase().startsWith(sha);
+}
+
+// BOT-1975: optional head scoping for pr-state. pr_state signals carry the PR
+// head as payload.head_ref_oid; a signal for a previous head does not wake.
+function prStateFiltersMatch(signal, params) {
+  if (params.sha == null) return true;
+  return shaPrefixMatches(signal.payload?.head_ref_oid, params.sha);
+}
+
+// BOT-1975 / BOT-1972: optional commit + reviewer scoping for pr-review. A
+// `review_unavailable` signal (the Codex usage-limit decline) names no commit, so
+// it always passes the sha filter — the waiter must learn no review is coming.
+function prReviewFiltersMatch(signal, params) {
+  const payload = signal.payload ?? {};
+  if (params.sha != null && payload.transition !== "review_unavailable" &&
+      !shaPrefixMatches(payload.commit_sha, params.sha)) {
+    return false;
+  }
+  if (params.reviewer != null) {
+    if (typeof payload.reviewer_login !== "string") return false;
+    if (normalizeReviewerLogin(payload.reviewer_login) !== params.reviewer) return false;
+  }
+  return true;
+}
+
 /**
  * Parse and strictly validate a list of `TYPE:params` condition specs.
  *
@@ -777,9 +846,11 @@ function conditionMatchesSignal(condition, signal, waitSessionId) {
       return signal.subject_key.startsWith(`${params.subtype}:${params.host}:`);
     }
     case "pr-state":
-      return signal.signal_type === "pr_state" && prSubjectMatches(signal.subject_key, params);
+      return signal.signal_type === "pr_state" && prSubjectMatches(signal.subject_key, params) &&
+        prStateFiltersMatch(signal, params);
     case "pr-review":
-      return signal.signal_type === "pr_review" && prSubjectMatches(signal.subject_key, params);
+      return signal.signal_type === "pr_review" && prSubjectMatches(signal.subject_key, params) &&
+        prReviewFiltersMatch(signal, params);
     case "test-run":
       return signal.signal_type === "test_run" && signal.subject_key === `run:${params.runId}`;
     case "guidance":

package/src/wait.mjs

@@ -71,19 +71,35 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       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).
+  pr-state:repo=<owner/repo>[,pr=<n>][,sha=<head>]
+                                      a PR lifecycle or mergeable flip (draft<->ready, merged,
+                                      closed, conflict/clean flip) plus check-rollup, review-
+                                      decision and unresolved-thread-count changes, as projected
+                                      by the PR read model. 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. The
+                                      payload carries head_ref_oid; sha=<head> (7-40 hex, a
+                                      prefix is fine) wakes only on signals for that head, so a
+                                      previous head's check result can't wake you. A push alone
+                                      emits nothing — the head rides on the next transition.
+  pr-review:repo=<owner/repo>[,pr=<n>][,reviewer=<login>][,sha=<commit>]
+                                      a submitted review, a new review comment, a thread
+                                      resolved/re-opened (payload carries the unresolved-thread
+                                      count), a Codex clean pass (payload.transition=clean_pass)
+                                      or the Codex usage-limit decline (transition=
+                                      review_unavailable — no review is coming).
                                       Edge-triggered: it wakes only on review activity AFTER
-                                      arm. If the PR ALREADY has an outstanding review at arm,
-                                      bb-wait prints a one-line stderr notice (unresolved count,
-                                      review_decision, age) so a silent park isn't mistaken for
-                                      "no review yet" — the existing review will not re-wake it.
+                                      arm, so arm BEFORE requesting the review. If the PR ALREADY
+                                      has an outstanding review at arm, bb-wait prints a one-line
+                                      stderr notice (unresolved count, review_decision, age) so a
+                                      silent park isn't mistaken for "no review yet" — the
+                                      existing review will not re-wake it.
+                                      reviewer=<login> wakes only on that reviewer (case-
+                                      insensitive; a trailing [bot] is ignored). sha=<commit>
+                                      wakes only on verdicts for that commit (submitted reviews
+                                      and clean passes carry commit_sha; thread comments do not,
+                                      so they never match sha=); the usage-limit decline always
+                                      passes sha=. Any other key is refused (exit 4).
   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
@@ -113,7 +129,8 @@ CONDITIONS  (TYPE:key=val,key=val — repeat for several; --any wakes on the fir
                                       the ranking (first-come). Needs cli >= 1.20.0.
   ci:repo=<owner/repo>,{scope=latest,pr=<n> | run_id=<id> | sha=<sha>
                         | scope=next[,sha=<sha>][,branch=<name>][,workflow=<name>]}
-                                      a PR's CI reaching a terminal conclusion (owner-scoped);
+                                      a run's terminal conclusion (owner-scoped) — not a
+                                      PR state or review change (use pr-state / pr-review);
                                       GitHub Actions or an external check_suite provider.
                                       A repo with no CI feed is rejected (no_signal_source).
                                       scope=next is LIVE-ONLY: it wakes on the first terminal
@@ -154,7 +171,9 @@ AUTH
 
 OUTPUT
   Exactly one JSON receipt line on stdout at exit, with client semver and
-  protocol identity. Diagnostics go to stderr.
+  protocol identity. Diagnostics go to stderr — including the arm-time notices
+  (outstanding review, latest CI run). Do not pipe bb wait through tail: the
+  notice is on stderr and you will not see it until the wait exits.
   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