fix(heartbeat): board user wakeups bypass gate block backoff (paperclipai#221)

Board user comments are explicit instructions that should always reach
the agent. The gate_block_backoff was unconditionally skipping wakeups
after 3+ consecutive gate blocks, silently dropping board user comments.

Now requestedByActorType=user bypasses the backoff and resets the
gateBlockCount so the agent gets a fresh slate.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nydamon

server/src/__tests__/gate-block-backoff.test.ts

@@ -249,6 +249,49 @@ describe("gate-block backoff", () => {
     expect(updated.status).toBe("in_review");
   });
 
+  it("board user wakeup bypasses gate block backoff", async () => {
+    const { agentId, issueId } = await seedIssueWithGateBlocks({ gateBlockCount: 5 });
+
+    const heartbeat = heartbeatService(db);
+    const result = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "test",
+      reason: "assignment",
+      contextSnapshot: { issueId },
+      requestedByActorType: "user",
+      requestedByActorId: randomUUID(),
+    });
+
+    // Board user wakeup should NOT be skipped despite high gate block count
+    expect(result).not.toBeNull();
+
+    // Gate block counter should be reset to 0
+    const [updated] = await db.select().from(issues).where(eq(issues.id, issueId));
+    expect(updated.gateBlockCount).toBe(0);
+  });
+
+  it("agent wakeup is still skipped by gate block backoff", async () => {
+    const { agentId, issueId } = await seedIssueWithGateBlocks({ gateBlockCount: 5 });
+
+    const heartbeat = heartbeatService(db);
+    const result = await heartbeat.wakeup(agentId, {
+      source: "automation",
+      triggerDetail: "test",
+      reason: "assignment",
+      contextSnapshot: { issueId },
+      requestedByActorType: "agent",
+      requestedByActorId: randomUUID(),
+    });
+
+    // Agent-originated wakeup should still be skipped
+    expect(result).toBeNull();
+
+    const wakeups = await db.select().from(agentWakeupRequests);
+    const skipped = wakeups.find((w) => w.reason?.startsWith("gate_block_backoff"));
+    expect(skipped).toBeTruthy();
+    expect(skipped!.status).toBe("skipped");
+  });
+
   it("timer wakes bypass the issue-specific gate check (no issueId)", async () => {
     // Timer wakes go through the non-issue pathway in enqueueWakeup.
     // Even if the agent has issues with high gateBlockCount, timer wakes

server/src/services/heartbeat.ts

@@ -3613,8 +3613,11 @@ export function heartbeatService(db: Db) {
         // Gate-block backoff: skip dispatch to issues that keep hitting gate blocks.
         // Counter is incremented by the PATCH /issues/:id gate handlers and resets
         // on status or assignee changes.
+        // Board user wakeups bypass backoff — a human comment is an explicit instruction
+        // that should always reach the agent regardless of prior gate failures.
         const GATE_BLOCK_THRESHOLD = 3;
-        if (issue.gateBlockCount >= GATE_BLOCK_THRESHOLD) {
+        const isBoardUserWake = opts.requestedByActorType === "user";
+        if (issue.gateBlockCount >= GATE_BLOCK_THRESHOLD && !isBoardUserWake) {
           await tx.insert(agentWakeupRequests).values({
             companyId: agent.companyId,
             agentId,
@@ -3631,6 +3634,14 @@ export function heartbeatService(db: Db) {
           return { kind: "skipped" as const };
         }
 
+        // Board user wakeup resets gate block counter so the agent gets a fresh slate
+        if (isBoardUserWake && issue.gateBlockCount > 0) {
+          await tx
+            .update(issues)
+            .set({ gateBlockCount: 0, updatedAt: new Date() })
+            .where(eq(issues.id, issueId));
+        }
+
         let activeExecutionRun = issue.executionRunId
           ? await tx
             .select()