fix: block tasks on failing verify gate

Author: lee-to

.ai-factory/patches/2026-06-30-11.27.md

@@ -0,0 +1,34 @@
+# Blocking verify gate retried indefinitely
+
+**Date:** 2026-06-30 11:27
+**Files:** packages/agent/src/stageErrorHandler.ts, packages/agent/src/subagents/verifier.ts, packages/agent/src/__tests__/stageErrorHandler.test.ts, packages/agent/src/__tests__/coordinator.test.ts
+**Severity:** medium
+
+## Problem
+
+When `aif-verify` emitted a blocking `aif-gate-result`, `runVerifier` threw a plain `Error`.
+The coordinator classified plain stage errors as `revert`, which left the task in `verify`.
+The next poll selected the same task again, creating an implicit retry loop.
+
+## Root Cause
+
+The verifier needed to distinguish a deliberate gate block from an unexpected runtime failure.
+Without a structured error type, the coordinator had no safe signal to move the task to
+`blocked_external` and avoid retrying every poll cycle.
+
+## Solution
+
+Added `StageManualBlockError` with a structured `blockedReason` field and taught
+`classifyStageError` to map it to `blocked_external` with `retryAfter=null`. The verifier now
+throws this error for blocking gate results after persisting the verification output. Regression
+tests cover both the classifier and the coordinator behavior across a second poll.
+
+## Prevention
+
+- Use structured error classes or fields for intentional stage-control outcomes.
+- Do not rely on generic `Error` when a coordinator needs different recovery behavior.
+- Add coordinator-level regression tests for any stage error that must not be retried.
+
+## Tags
+
+`#coordinator` `#verify` `#structured-errors` `#retry-loop` `#typescript`

packages/agent/src/__tests__/coordinator.test.ts

@@ -94,6 +94,7 @@ const { runImplementer } = await import("../subagents/implementer.js");
 const { runReviewer } = await import("../subagents/reviewer.js");
 const { runVerifier } = await import("../subagents/verifier.js");
 const { handleAutoReviewGate } = await import("../autoReviewHandler.js");
+const { StageManualBlockError } = await import("../stageErrorHandler.js");
 
 describe("coordinator", () => {
   beforeEach(() => {
@@ -310,6 +311,43 @@ describe("coordinator", () => {
     expect(task!.status).toBe("done");
   });
 
+  it("should block verify tasks instead of retrying when verify gate blocks", async () => {
+    const db = testDb.current;
+    db.insert(tasks)
+      .values({
+        id: "task-blocking-verify",
+        projectId: "test-project",
+        title: "Blocking verify",
+        status: "verify",
+        useSubagents: false,
+        runPostVerify: true,
+      })
+      .run();
+
+    vi.mocked(runVerifier).mockRejectedValueOnce(
+      new StageManualBlockError(
+        "Verify stage returned a blocking gate result. Review the Verification section for details.",
+      ),
+    );
+
+    await pollAndProcess();
+
+    expect(runVerifier).toHaveBeenCalledTimes(1);
+    expect(runReviewer).not.toHaveBeenCalled();
+
+    const task = db.select().from(tasks).where(eq(tasks.id, "task-blocking-verify")).get();
+    expect(task!.status).toBe("blocked_external");
+    expect(task!.blockedFromStatus).toBe("verify");
+    expect(task!.blockedReason).toBe(
+      "Verify stage returned a blocking gate result. Review the Verification section for details.",
+    );
+    expect(task!.retryAfter).toBeNull();
+
+    await pollAndProcess();
+
+    expect(runVerifier).toHaveBeenCalledTimes(1);
+  });
+
   it("should not auto-implement plan_ready tasks when autoMode=false", async () => {
     const db = testDb.current;
     db.insert(tasks)

packages/agent/src/__tests__/stageErrorHandler.test.ts

@@ -34,7 +34,7 @@ vi.mock("@aif/shared", async (importOriginal) => {
   };
 });
 
-const { classifyStageError } = await import("../stageErrorHandler.js");
+const { classifyStageError, StageManualBlockError } = await import("../stageErrorHandler.js");
 import { appendTaskActivityLog } from "@aif/data";
 
 function makeInput(overrides: Record<string, unknown> = {}) {
@@ -92,6 +92,26 @@ describe("classifyStageError", () => {
     expect(result.kind).toBe("blocked_external");
   });
 
+  it("returns manual blocked_external for explicit stage gate blocks", () => {
+    const result = classifyStageError(
+      makeInput({
+        stageLabel: "verifier",
+        sourceStatus: "verify",
+        retryCount: 2,
+        err: new StageManualBlockError("Verify gate blocked this task."),
+      }),
+    );
+
+    expect(result).toEqual({
+      kind: "blocked_external",
+      blockedReason: "Verify gate blocked this task.",
+      retryAfter: null,
+      retryAfterSource: "none",
+      retryCount: 2,
+      limitSnapshot: null,
+    });
+  });
+
   it("includes retryAfter ISO string for external failures", () => {
     const before = Date.now();
     const result = classifyStageError(

packages/agent/src/stageErrorHandler.ts

@@ -32,6 +32,16 @@ const NON_RETRYABLE_RUNTIME_CATEGORIES = new Set([
   "content_filter",
 ]);
 
+export class StageManualBlockError extends Error {
+  readonly blockedReason: string;
+
+  constructor(blockedReason: string, message = blockedReason) {
+    super(message);
+    this.name = "StageManualBlockError";
+    this.blockedReason = blockedReason;
+  }
+}
+
 export type ErrorRecovery =
   | { kind: "fast_retry" }
   | {
@@ -52,6 +62,14 @@ interface StageErrorInput {
   err: unknown;
 }
 
+function findStageManualBlockError(err: unknown): StageManualBlockError | null {
+  if (err instanceof StageManualBlockError) return err;
+  if (err instanceof Error && "cause" in err && err.cause) {
+    return findStageManualBlockError(err.cause);
+  }
+  return null;
+}
+
 function buildUserSafeExternalReason(err: unknown): string {
   const runtimeError = findRuntimeExecutionError(err);
   if (!runtimeError) {
@@ -130,6 +148,33 @@ function resolveRetryAfter(err: unknown): {
 export function classifyStageError(input: StageErrorInput): ErrorRecovery {
   const { taskId, stageLabel, sourceStatus, err } = input;
 
+  const manualBlockErr = findStageManualBlockError(err);
+  if (manualBlockErr) {
+    logActivity(
+      taskId,
+      "Agent",
+      `coordinator moved to blocked_external from ${sourceStatus} at ${stageLabel}; retryAfter=manual; source=none; reason=${truncateReason(manualBlockErr.blockedReason)}`,
+    );
+
+    log.warn(
+      {
+        taskId,
+        stage: stageLabel,
+        errorName: manualBlockErr.name,
+      },
+      "Subagent stage requested manual block",
+    );
+
+    return {
+      kind: "blocked_external",
+      blockedReason: manualBlockErr.blockedReason,
+      retryAfter: null,
+      retryAfterSource: "none",
+      retryCount: input.retryCount ?? 0,
+      limitSnapshot: null,
+    };
+  }
+
   // Branch / worktree isolation failures must NEVER fall into the generic
   // revert path — generic revert triggers unbounded re-planning on a
   // corrupted work tree. Pin the task to blocked_external with no retry so

packages/agent/src/subagents/verifier.ts

@@ -3,6 +3,7 @@ import { createRuntimeWorkflowSpec } from "@aif/runtime";
 import { logger } from "@aif/shared";
 import { assertCurrentBranch, restorePersistedBranch } from "../gitBranch.js";
 import { logActivity } from "../hooks.js";
+import { StageManualBlockError } from "../stageErrorHandler.js";
 import { executeSubagentQuery } from "../subagentQuery.js";
 
 const log = logger("verifier");
@@ -110,7 +111,10 @@ Task description: ${task.description}`;
   const gate = extractVerifyGateResult(resultText);
   if (gate?.status === "fail" || gate?.blocking === true) {
     log.warn({ taskId, blockers: gate.blockers ?? [] }, "Verify stage returned blocking result");
-    throw new Error("Verify stage returned a blocking gate result");
+    throw new StageManualBlockError(
+      "Verify stage returned a blocking gate result. Review the Verification section for details.",
+      "Verify stage returned a blocking gate result",
+    );
   }
 
   logActivity(taskId, "Agent", "verify stage complete (aif-verify)");