@botbuddy/cli 1.35.0 → 1.36.0

package/package.json

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

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