fix(github): suppress followed poll ticks during rate-limit backoff

The overlap guard keyed only on the sync cursor, which a page-1 rate limit
never persists — so recurring ticks during a (possibly hourly) backoff kept
re-hitting the limit and piling up runTask continuations. Add a followed_retry_at
backoff marker the guard honours directly, independent of the cursor and the
heartbeat staleness window.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: KrisBraun

connectors/github/src/github.test.ts

@@ -291,6 +291,9 @@ describe("pollFollowed overlap guard", () => {
       set: async (k: string, v: unknown) => {
         store[k] = v;
       },
+      clear: async (k: string) => {
+        delete store[k];
+      },
       // syncFollowedItems calls this first; returning null makes it a no-op
       // pass, so a single call is our proxy for "the drain actually ran".
       getAccountToken: async () => {
@@ -313,6 +316,26 @@ describe("pollFollowed overlap guard", () => {
     expect(calls()).toBe(0); // guarded: the drain (→ getAccountToken) never ran
   });
 
+  it("skips a recurring tick during a rate-limit backoff window (no cursor needed)", async () => {
+    const { fake, calls } = guardFake({
+      followed_retry_at: new Date(Date.now() + 10 * 60 * 1000).toISOString(),
+    });
+    await GitHub.prototype.pollFollowed.call(fake);
+    expect(calls()).toBe(0); // backoff marker suppresses the tick even with no cursor
+  });
+
+  it("clears the backoff marker after a non-rate-limited pass", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { fake } = guardFake({
+      // A leftover marker from an earlier backoff; the pass no longer rate-limits.
+      followed_retry_at: new Date(Date.now() - 60 * 1000).toISOString(),
+    });
+    // Continuation bypasses the guard; syncFollowedItems returns done (no retryAt).
+    await GitHub.prototype.pollFollowed.call(fake, true);
+    warn.mockRestore();
+    expect(await fake.get("followed_retry_at")).toBeNull(); // marker cleared
+  });
+
   it("does not skip a continuation call even with a cursor + fresh heartbeat", async () => {
     const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
     const { fake, calls } = guardFake({

connectors/github/src/github.ts

@@ -446,12 +446,20 @@ export class GitHub extends Connector<GitHub> {
    * yet) — the recurring schedule re-drives the next incremental pass.
    */
   async pollFollowed(isContinuation = false): Promise<void> {
-    // A recurring tick must not start a second drain while a runTask
-    // continuation chain of the same pass is still in flight — both would race
-    // the shared `followed_sync_state` cursor. The chain refreshes a heartbeat;
-    // if it's fresh AND a cursor exists, a drain is active, so skip. Staleness
-    // (a crashed chain) lets a later recurring tick resume the pass.
+    // A recurring tick must not start a redundant pass while one is already in
+    // progress — a continuation chain (via runTask) is scheduled to carry it
+    // forward. Two independent signals mark "in progress":
     if (!isContinuation) {
+      // 1. A rate-limit backoff: a continuation is scheduled for `retryAt`, so
+      //    skip until then. This covers a page-1 rate limit, which leaves no
+      //    cursor behind, and outlives the heartbeat window on long (hourly)
+      //    primary limits.
+      const retryAtStr = await this.get<string>("followed_retry_at");
+      if (retryAtStr && Date.now() < new Date(retryAtStr).getTime()) return;
+
+      // 2. A multi-page drain: the chain refreshes a heartbeat, so a fresh
+      //    heartbeat with a live cursor means a drain is active. Staleness (a
+      //    crashed chain) lets a later recurring tick resume the pass.
       const heartbeat = await this.get<string>("followed_poll_heartbeat");
       const cursor = await this.get<{ page: number }>("followed_sync_state");
       if (
@@ -471,12 +479,18 @@ export class GitHub extends Connector<GitHub> {
       this as unknown as import("./followed-sync").FollowedSource,
     );
     if (retryAt) {
-      // Rate-limited mid-pass: resume the same cursor after the limit resets.
+      // Rate-limited: record the backoff (the guard above honours it) and
+      // resume the same cursor after the limit resets.
+      await this.set("followed_retry_at", retryAt.toISOString());
       const followedCallback = await this.createCallback(this.pollFollowed, true);
       await this.runTask(followedCallback, { runAt: retryAt });
-    } else if (!done) {
-      const followedCallback = await this.createCallback(this.pollFollowed, true);
-      await this.runTask(followedCallback);
+    } else {
+      // Not rate-limited — clear any prior backoff marker.
+      await this.clear("followed_retry_at");
+      if (!done) {
+        const followedCallback = await this.createCallback(this.pollFollowed, true);
+        await this.runTask(followedCallback);
+      }
     }
   }