fix(agent-actions): wake sibling PRs a prior delivery missed over the cap (#2479)

Gate finding on this PR: contributorCapMatch was computed only from
otherOpenPullRequests, so webhook delivery order (not guaranteed to match
PR creation order) could let a sibling's own webhook process before this
PR existed in the DB — that sibling would wrongly conclude it's within
the cap, and since nothing else ever re-evaluates it, the cap would be
permanently bypassed for that PR.

Once a delivery has the complete picture, it now wakes any other still-
open sibling that's also in the over-cap set via the existing
agent-regate-pr sweep-unit job — the same "wake and fully re-evaluate"
entry point the linked-issue-wake feature (#2259) uses for an identical
class of problem, so the sibling gets its own live-head/CI-freshness
re-check rather than acting on a shortcut. Coalesced per sibling PR to
avoid an O(N^2) job storm from a burst of over-cap siblings.

Author: JSONbored

src/queue/processors.ts

@@ -1738,7 +1738,7 @@ async function runAgentMaintenancePlanAndExecute(
     liveFacts: LiveGithubFacts;
   },
 ): Promise<void> {
-  const { installationId, repoFullName, pr, settings, otherOpenPullRequests, gate } = args;
+  const { installationId, repoFullName, pr, settings, otherOpenPullRequests, deliveryId, gate } = args;
 
   // Convergence safety: feed the planner the PR's changed paths + the repo's hard-guardrail globs so guarded
   // paths force manual review, and flag owner-authored PRs so they are never auto-closed (standing rule).
@@ -1882,6 +1882,17 @@ async function runAgentMaintenancePlanAndExecute(
     if (overCapNumbers.has(pr.number)) {
       contributorCapMatch = { matched: true, authorLogin: pr.authorLogin, openCount: authorOpenPrNumbers.length, cap: contributorOpenPrCap };
     }
+    // Webhook-delivery-order guard (#2479 gate finding): delivery order is not guaranteed to match PR creation
+    // order, so a sibling PR's own webhook can process before THIS PR exists in the DB and wrongly conclude the
+    // author is within the cap — nothing else would ever re-evaluate it, permanently bypassing the cap for that
+    // sibling. Now that THIS delivery has the complete picture, wake any OTHER still-open sibling that's also
+    // in the over-cap set so its own next pass re-evaluates against the complete set and self-corrects.
+    const otherOverCapSiblingNumbers = otherOpenPullRequests
+      .filter((other) => (other.authorLogin ?? "").toLowerCase() === authorLoginLower && overCapNumbers.has(other.number))
+      .map((other) => other.number);
+    if (otherOverCapSiblingNumbers.length > 0) {
+      await wakeOverCapSiblingPullRequests(env, deliveryId, installationId, repoFullName, otherOverCapSiblingNumbers);
+    }
   }
 
   const planned = planAgentMaintenanceActions({
@@ -2515,6 +2526,51 @@ async function scheduleTrailingIssueLinkedReReview(
   await putTransientKey(env, key, "1", CI_COALESCE_WINDOW_SECONDS);
 }
 
+/** Best-effort wake for sibling PRs discovered to be over the per-contributor cap by a LATER delivery (#2270,
+ *  #2479 gate finding): webhook delivery order isn't guaranteed to match PR creation order, so a sibling's own
+ *  webhook can fire before this one exists in the DB and wrongly conclude the author is within the cap — with
+ *  nothing else to ever re-evaluate it, that verdict would otherwise stand forever. Reuses the existing
+ *  agent-regate-pr sweep-unit job (already rate-limit-aware and retried) — the SAME "wake and fully
+ *  re-evaluate" entry point the linked-issue-wake feature (#2259) uses for an identical class of problem, so
+ *  the sibling gets its own live-head/CI-freshness re-check before anything acts on it, not a shortcut based
+ *  on this delivery's now-possibly-stale snapshot. Coalesced per sibling PR (mirrors
+ *  scheduleTrailingIssueLinkedReReview's check-then-claim-after-success shape) so a burst of N over-cap
+ *  siblings each discovering the same others doesn't fan out into an O(N^2) job storm. */
+async function wakeOverCapSiblingPullRequests(
+  env: Env,
+  deliveryId: string,
+  installationId: number,
+  repoFullName: string,
+  siblingPrNumbers: number[],
+): Promise<void> {
+  await Promise.all(
+    siblingPrNumbers.map(async (prNumber) => {
+      const key = `contributor-cap-wake:${repoFullName.toLowerCase()}#${prNumber}`;
+      if (await getTransientKey(env, key)) return;
+      try {
+        await env.JOBS.send({
+          type: "agent-regate-pr",
+          deliveryId,
+          repoFullName,
+          prNumber,
+          installationId,
+        });
+      } catch (error) {
+        console.log(
+          JSON.stringify({
+            ev: "contributor_cap_wake_enqueue_failed",
+            repoFullName,
+            pull: prNumber,
+            message: errorMessage(error).slice(0, 120),
+          }),
+        );
+        return; // do NOT claim — a later discovery should retry the enqueue
+      }
+      await putTransientKey(env, key, "1", CI_COALESCE_WINDOW_SECONDS);
+    }),
+  );
+}
+
 async function ciHeadShaResolutionCoalesced(
   env: Env,
   repoFullName: string,

test/unit/queue.test.ts

@@ -5773,6 +5773,208 @@ describe("queue processors", () => {
     expect(seen.closed).toBe(false);
   });
 
+  it("contributor open-PR cap (#2270): an author-less (ghost) open PR among the repo's others is excluded from the count and the sibling-wake scan, not crashed on", async () => {
+    const env = createTestEnv({ GITHUB_APP_PRIVATE_KEY: await generatePrivateKeyPem() });
+    await upsertInstallation(env, {
+      installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" }, target_type: "User", repository_selection: "all", permissions: { metadata: "read", pull_requests: "write", issues: "write" }, events: ["pull_request"] },
+      repositories: [{ name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } }],
+    });
+    // A ghost PR with no `user` at all (authorLogin ends up null) — must not match farmer99's count, and must
+    // not crash the sibling-wake scan, which runs the identical (authorLogin ?? "") fallback.
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 50, title: "Ghost PR", state: "open", head: { sha: "ghost50" }, labels: [], body: "z" });
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 53, title: "Farmer PR one", state: "open", user: { login: "farmer99" }, head: { sha: "f53" }, labels: [], body: "x" });
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 54, title: "Farmer PR two", state: "open", user: { login: "farmer99" }, head: { sha: "f54" }, labels: [], body: "y" });
+    await upsertRepositorySettings(env, {
+      repoFullName: "JSONbored/gittensory",
+      commentMode: "all_prs",
+      publicSurface: "comment_only",
+      checkRunMode: "off",
+      gateCheckMode: "enabled",
+      aiReviewMode: "advisory",
+      autonomy: { close: "auto", label: "auto" },
+      contributorOpenPrCap: 2,
+    });
+    const seen = { closed: false };
+    vi.stubGlobal("fetch", async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = input.toString();
+      const method = init?.method ?? "GET";
+      if (url === "https://api.gittensor.io/miners") return Response.json([]);
+      if (url.includes("/access_tokens")) return Response.json({ token: "installation-token" });
+      if (url.includes("/pulls/55/files")) return Response.json([{ filename: "src/a.ts", status: "modified", additions: 1, deletions: 0, changes: 1, patch: "@@\n+const ok = true;" }]);
+      if (url.includes("/pulls/55/reviews")) return Response.json([]);
+      if (url.includes("/pulls/55/commits")) return Response.json([]);
+      if (url.endsWith("/pulls/55") && method === "PATCH") { seen.closed = JSON.parse(String(init?.body ?? "{}")).state === "closed"; return Response.json({ number: 55, state: "closed" }); }
+      if (url.endsWith("/pulls/55")) return Response.json({ number: 55, state: "open", user: { login: "farmer99" }, head: { sha: "f55" }, mergeable_state: "clean" });
+      if (url.includes("/commits/f55/check-runs")) return Response.json({ total_count: 0, check_runs: [] });
+      if (url.includes("/commits/f55/status")) return Response.json({ state: "success", statuses: [] });
+      if (url.includes("/issues/55/labels") && method === "GET") return Response.json([]);
+      if (url.includes("/issues/55/labels") && method === "POST") return Response.json([]);
+      if (url.includes("/issues/55/comments") && method === "POST") return Response.json({ id: 1 }, { status: 201 });
+      if (url.includes("/issues/55/comments")) return Response.json([]);
+      return Response.json({});
+    });
+
+    await processJob(env, {
+      type: "github-webhook",
+      deliveryId: "contributor-cap-ghost-author",
+      eventName: "pull_request",
+      payload: {
+        action: "opened",
+        installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" } },
+        repository: { name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } },
+        pull_request: { number: 55, title: "Farmer's 3rd PR", state: "open", user: { login: "farmer99" }, head: { sha: "f55" }, labels: [], body: "x", mergeable_state: "clean", reviewDecision: "APPROVED" },
+      },
+    });
+
+    // Ghost PR's null authorLogin never matches "farmer99" — the count is still exactly 3 (farmer99's own).
+    expect(seen.closed).toBe(true);
+  });
+
+  it("contributor open-PR cap (#2270): out-of-order webhook delivery wakes and self-corrects the missed sibling (regression, gate finding on #2479)", async () => {
+    // PR56 (the NEWER PR) is delivered BEFORE PR55 exists in the DB — a real possibility under concurrent/
+    // retried webhook delivery. At that moment PR56 only sees {54, 56} (2 total, AT the cap of 2, not over),
+    // so it correctly stays open — but a naive "only ever check myself" implementation would leave it open
+    // FOREVER, since nothing else ever re-evaluates PR56 again. This pins the fix: once PR55's delivery later
+    // sees the COMPLETE set {54, 55, 56}, it must wake PR56 (not just decide for itself) so PR56 gets a fresh,
+    // fully-gated re-evaluation and self-corrects.
+    const env = createTestEnv({ GITHUB_APP_PRIVATE_KEY: await generatePrivateKeyPem() });
+    await upsertInstallation(env, {
+      installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" }, target_type: "User", repository_selection: "all", permissions: { metadata: "read", pull_requests: "write", issues: "write" }, events: ["pull_request"] },
+      repositories: [{ name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } }],
+    });
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 54, title: "Farmer PR zero", state: "open", user: { login: "farmer99" }, head: { sha: "f54" }, labels: [], body: "w" });
+    await upsertRepositorySettings(env, {
+      repoFullName: "JSONbored/gittensory",
+      commentMode: "all_prs",
+      publicSurface: "comment_only",
+      checkRunMode: "off",
+      gateCheckMode: "enabled",
+      aiReviewMode: "advisory",
+      autonomy: { close: "auto", label: "auto" },
+      contributorOpenPrCap: 2,
+    });
+    const closedNumbers = new Set<number>();
+    const fanned: import("../../src/types").JobMessage[] = [];
+    const realSend = env.JOBS.send.bind(env.JOBS);
+    env.JOBS.send = (async (message: import("../../src/types").JobMessage, options?: QueueSendOptions) => {
+      if (message.type === "agent-regate-pr") fanned.push(message);
+      return realSend(message, options);
+    }) as typeof env.JOBS.send;
+    vi.stubGlobal("fetch", async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = input.toString();
+      const method = init?.method ?? "GET";
+      if (url === "https://api.gittensor.io/miners") return Response.json([]);
+      if (url.includes("/access_tokens")) return Response.json({ token: "installation-token" });
+      for (const [n, sha] of [[55, "f55"], [56, "f56"]] as const) {
+        if (url.includes(`/pulls/${n}/files`)) return Response.json([{ filename: "src/a.ts", status: "modified", additions: 1, deletions: 0, changes: 1, patch: "@@\n+const ok = true;" }]);
+        if (url.includes(`/pulls/${n}/reviews`)) return Response.json([]);
+        if (url.includes(`/pulls/${n}/commits`)) return Response.json([]);
+        if (url.endsWith(`/pulls/${n}`) && method === "PATCH") { closedNumbers.add(n); return Response.json({ number: n, state: "closed" }); }
+        if (url.endsWith(`/pulls/${n}`)) return Response.json({ number: n, state: closedNumbers.has(n) ? "closed" : "open", user: { login: "farmer99" }, head: { sha }, mergeable_state: "clean" });
+        if (url.includes(`/commits/${sha}/check-runs`)) return Response.json({ total_count: 0, check_runs: [] });
+        if (url.includes(`/commits/${sha}/status`)) return Response.json({ state: "success", statuses: [] });
+        if (url.includes(`/issues/${n}/labels`) && method === "GET") return Response.json([]);
+        if (url.includes(`/issues/${n}/labels`) && method === "POST") return Response.json([]);
+        if (url.includes(`/issues/${n}/comments`) && method === "POST") return Response.json({ id: 1 }, { status: 201 });
+        if (url.includes(`/issues/${n}/comments`)) return Response.json([]);
+      }
+      return Response.json({});
+    });
+
+    // PR56 arrives FIRST — PR55 does not exist yet, so PR56 sees only {54, 56}: at the cap, not over.
+    await processJob(env, {
+      type: "github-webhook",
+      deliveryId: "burst-pr56-first",
+      eventName: "pull_request",
+      payload: {
+        action: "opened",
+        installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" } },
+        repository: { name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } },
+        pull_request: { number: 56, title: "Farmer PR two (out of order)", state: "open", user: { login: "farmer99" }, head: { sha: "f56" }, labels: [], body: "y", mergeable_state: "clean", reviewDecision: "APPROVED" },
+      },
+    });
+    expect(closedNumbers.has(56)).toBe(false); // correctly not closed YET — the set looked complete at the time
+
+    // PR55 arrives SECOND — now the complete set {54, 55, 56} is visible. PR55 itself ranks within the cap
+    // (oldest 2 of 3), so it stays open — but PR56 is now discoverably over-cap and must be woken.
+    await processJob(env, {
+      type: "github-webhook",
+      deliveryId: "burst-pr55-second",
+      eventName: "pull_request",
+      payload: {
+        action: "opened",
+        installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" } },
+        repository: { name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } },
+        pull_request: { number: 55, title: "Farmer PR one", state: "open", user: { login: "farmer99" }, head: { sha: "f55" }, labels: [], body: "x", mergeable_state: "clean", reviewDecision: "APPROVED" },
+      },
+    });
+    expect(closedNumbers.has(55)).toBe(false); // PR55 itself is within the cap
+    expect(fanned.some((job) => job.type === "agent-regate-pr" && job.prNumber === 56)).toBe(true); // sibling woken
+
+    // Drain the woken job — PR56's OWN fresh re-evaluation now sees the complete set and self-corrects.
+    env.JOBS.send = realSend;
+    for (const job of fanned) await processJob(env, job);
+    expect(closedNumbers.has(56)).toBe(true);
+  });
+
+  it("contributor open-PR cap (#2270): a re-delivered sibling-wake is coalesced — the second discovery does not re-enqueue", async () => {
+    const env = createTestEnv({ GITHUB_APP_PRIVATE_KEY: await generatePrivateKeyPem() });
+    await upsertInstallation(env, {
+      installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" }, target_type: "User", repository_selection: "all", permissions: { metadata: "read", pull_requests: "write", issues: "write" }, events: ["pull_request"] },
+      repositories: [{ name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } }],
+    });
+    // Pre-seed the coalescing key for PR56 exactly as wakeOverCapSiblingPullRequests itself would after a
+    // first, already-successful enqueue — proving the SECOND discovery within the window skips re-enqueueing.
+    await env.SELFHOST_TRANSIENT_CACHE?.set("contributor-cap-wake:jsonbored/gittensory#56", "1", 60);
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 54, title: "Farmer PR zero", state: "open", user: { login: "farmer99" }, head: { sha: "f54" }, labels: [], body: "w" });
+    await upsertPullRequestFromGitHub(env, "JSONbored/gittensory", { number: 56, title: "Farmer PR two (already over cap)", state: "open", user: { login: "farmer99" }, head: { sha: "f56" }, labels: [], body: "y" });
+    await upsertRepositorySettings(env, {
+      repoFullName: "JSONbored/gittensory",
+      commentMode: "all_prs",
+      publicSurface: "comment_only",
+      checkRunMode: "off",
+      gateCheckMode: "enabled",
+      aiReviewMode: "advisory",
+      autonomy: { close: "auto", label: "auto" },
+      contributorOpenPrCap: 2,
+    });
+    const fanned: import("../../src/types").JobMessage[] = [];
+    const realSend = env.JOBS.send.bind(env.JOBS);
+    env.JOBS.send = (async (message: import("../../src/types").JobMessage, options?: QueueSendOptions) => {
+      if (message.type === "agent-regate-pr") fanned.push(message);
+      return realSend(message, options);
+    }) as typeof env.JOBS.send;
+    vi.stubGlobal("fetch", async (input: RequestInfo | URL) => {
+      const url = input.toString();
+      if (url === "https://api.gittensor.io/miners") return Response.json([]);
+      if (url.includes("/access_tokens")) return Response.json({ token: "installation-token" });
+      if (url.includes("/pulls/55/files")) return Response.json([{ filename: "src/a.ts", status: "modified", additions: 1, deletions: 0, changes: 1, patch: "@@\n+const ok = true;" }]);
+      if (url.includes("/pulls/55/reviews")) return Response.json([]);
+      if (url.includes("/pulls/55/commits")) return Response.json([]);
+      if (url.endsWith("/pulls/55")) return Response.json({ number: 55, state: "open", user: { login: "farmer99" }, head: { sha: "f55" }, mergeable_state: "clean" });
+      if (url.includes("/commits/f55/check-runs")) return Response.json({ total_count: 0, check_runs: [] });
+      if (url.includes("/commits/f55/status")) return Response.json({ state: "success", statuses: [] });
+      if (url.includes("/issues/55/labels")) return Response.json([]);
+      if (url.includes("/issues/55/comments")) return Response.json([]);
+      return Response.json({});
+    });
+
+    // PR55 arrives and independently discovers PR56 is over cap — but the wake was already claimed.
+    await processJob(env, {
+      type: "github-webhook",
+      deliveryId: "wake-coalesce-second",
+      eventName: "pull_request",
+      payload: {
+        action: "opened",
+        installation: { id: 123, account: { login: "JSONbored", id: 1, type: "User" } },
+        repository: { name: "gittensory", full_name: "JSONbored/gittensory", private: false, owner: { login: "JSONbored" } },
+        pull_request: { number: 55, title: "Farmer PR one", state: "open", user: { login: "farmer99" }, head: { sha: "f55" }, labels: [], body: "x", mergeable_state: "clean", reviewDecision: "APPROVED" },
+      },
+    });
+
+    expect(fanned).toEqual([]); // coalesced — no duplicate wake enqueued
+  });
+
   // #1092: prReadyForReview rebases a BEHIND-base PR through the agent executor (gated by update_branch autonomy
   // + pull_requests:write) before reviewing, then defers — the synchronize on the new head re-runs review.
   async function seedBehindRepo(env: Env, over: { autonomy?: Record<string, string>; agentPaused?: boolean; perms?: Record<string, string>; noInstall?: boolean } = {}) {