agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/supervisor/qa-wave-executor.ts

@@ -1,5 +1,11 @@
 import { GATE_RESULT, STATUS, TOOLS } from '../core/constants.js';
 import { ERROR_CODES } from '../core/error-codes.js';
+import {
+  assessGateFreshness,
+  hasMaterialWorktreeDiffHash,
+  readGateEvidenceByMode,
+  type GateFreshnessAssessment,
+} from '../core/gate-freshness.js';
 import type { WorkerProvider } from '../providers/providers.js';
 import type {
   AgentPromptProvider,
@@ -59,6 +65,7 @@ interface QaWaveExecutorDependencies {
   runId?: string | (() => string);
   providerName?: string;
   modelName?: string;
+  safeCheckpointHook?: () => Promise<void>;
 }
 
 function isRetryableToolError(error: unknown): boolean {
@@ -89,6 +96,11 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
  * @fileoverview QA phase wave executor.
  */
 
+/**
+ * Executes the QA phase for one supervisor iteration wave.
+ * Dispatches QA worker decisions, runs full gates, manages gate-repair retry loops,
+ * and rotates QA sessions after each gate evaluation.
+ */
 export class QaWaveExecutor {
   private readonly kernel: FeatureOrchestrationPort;
   private readonly provider: WorkerProvider;
@@ -113,10 +125,12 @@ export class QaWaveExecutor {
   private readonly runId: string | (() => string) | null;
   private readonly providerName: string;
   private readonly modelName: string;
+  private readonly safeCheckpointHook: (() => Promise<void>) | undefined;
   private readonly noProgressByFeature = new Map<string, number>();
   private readonly blockedForCurrentCycle = new Set<string>();
   private readonly lastStatusByFeature = new Map<string, string>();
   private readonly conformanceWarningsLogged = new Set<string>();
+  private readonly timeoutRetryUsed = new Set<string>();
 
   constructor(dependencies: QaWaveExecutorDependencies) {
     this.kernel = dependencies.kernel;
@@ -145,8 +159,15 @@ export class QaWaveExecutor {
     this.runId = dependencies.runId ?? null;
     this.providerName = dependencies.providerName ?? 'unknown';
     this.modelName = dependencies.modelName ?? 'unknown';
+    this.safeCheckpointHook = dependencies.safeCheckpointHook;
   }
 
+  /**
+   * Runs a single QA wave: invokes QA workers, executes full gates with repair retries,
+   * and rotates QA provider sessions for each processed feature.
+   * @param featureIds Feature IDs eligible for QA in this wave.
+   * @param maxParallelGateRuns Maximum number of features to process in one wave.
+   */
   async run(featureIds: string[], maxParallelGateRuns: number): Promise<void> {
     this.blockedForCurrentCycle.clear();
     const batch: string[] = [];
@@ -171,220 +192,281 @@ export class QaWaveExecutor {
     }
 
     for (const featureId of batch.slice(0, maxParallelGateRuns)) {
-      const context = await this.toolCaller.callTool('qa', TOOLS.FEATURE_GET_CONTEXT, {
-        feature_id: featureId,
-      });
-      let decision: WorkerDecisionResult;
       try {
-        decision = await this.workerDecisionRunner.execute({
-          role: 'qa',
-          featureId,
-          contextBundle: context.data,
-          instructions:
-            'Emit PATCH outputs for deterministic QA remediations, NOTE outputs for findings, and REQUEST outputs for lock/context needs.',
-        });
-      } catch (error) {
-        const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId, 'qa');
-        if (handledRuntimeFailure) {
-          continue;
-        }
-        throw error;
-      }
-
-      const semanticStall = await this.enforceSemanticStallPolicy(
-        featureId,
-        decision,
-        context.data,
-      );
-      if (semanticStall) {
-        continue;
-      }
-
-      const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision, 'qa');
-      if (shouldSkip) {
-        continue;
-      }
-      this.noProgressByFeature.delete(featureId);
-
-      const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
-        'qa',
-        TOOLS.FEATURE_STATE_GET,
-        {
-          feature_id: featureId,
-        },
-      );
-      const initialRetryCount = stateForRetry.data.front_matter.gate_retry_count ?? 0;
-
-      let gateOverall: string;
-      let gateExitCode: number;
-      let gateEvidencePath = '';
-      let gateLogs = '';
-      let gateRetryEligible: boolean;
-      const failureHistory: GateRepairContext['failureHistory'] = [];
-
-      try {
-        const gateResult = await this.toolCaller.callTool<GatesRunData>('qa', TOOLS.GATES_RUN, {
+        const state = await this.toolCaller.callTool<FeatureStatePayload>(
+          'qa',
+          TOOLS.FEATURE_STATE_GET,
+          {
+            feature_id: featureId,
+          },
+        );
+        const context = await this.toolCaller.callTool('qa', TOOLS.FEATURE_GET_CONTEXT, {
           feature_id: featureId,
-          mode: 'full',
-        });
-        gateOverall = gateResult.data.overall ?? GATE_RESULT.PASS;
-        gateExitCode = gateOverall === GATE_RESULT.FAIL ? 1 : 0;
-        gateEvidencePath = gateResult.data.evidence_path ?? '';
-        gateRetryEligible = gateOverall === GATE_RESULT.FAIL;
-      } catch (error) {
-        gateOverall = GATE_RESULT.FAIL;
-        gateExitCode = 1;
-        const typed = error as { message?: string };
-        gateLogs = typed.message ?? '';
-        gateRetryEligible = isRetryableToolError(error);
-      }
-
-      if (gateOverall === GATE_RESULT.FAIL) {
-        failureHistory.push({
-          attempt: initialRetryCount + 1,
-          gate_name: 'full',
-          exit_code: gateExitCode,
-          evidence_summary: gateEvidencePath,
-          logs_excerpt: gateLogs.slice(0, 800),
-          failed_at: new Date().toISOString(),
-          retry_delay_ms: this.reactionsService?.retryDelayMs(),
         });
-      }
-
-      if (this.reactionsService && gateOverall === GATE_RESULT.FAIL && gateRetryEligible) {
-        let retryCount = initialRetryCount;
-        const retryDelayMs = this.reactionsService.retryDelayMs();
-        while (gateRetryEligible && this.reactionsService.shouldRetry(featureId, retryCount)) {
-          if (typeof this.reactionsService.waitBeforeRetry === 'function') {
-            await this.reactionsService.waitBeforeRetry();
-          }
-          const attempt = retryCount + 2;
-          const ctx: GateRepairContext = {
-            featureId,
-            gateName: 'full',
-            exitCode: gateExitCode,
-            logs: gateLogs,
-            evidenceSummary: gateEvidencePath,
-            retryCount,
-            failureHistory,
-          };
-          const repairPrompt = this.reactionsService.buildRepairPrompt(ctx);
-          let repairDecision: WorkerDecisionResult;
+        const gateFreshness = this.assessFullGateFreshness(
+          state.data.front_matter as unknown as Record<string, unknown>,
+          context.data,
+        );
+        if (
+          !this.shouldBypassWorkerForGateRefresh(
+            state.data.front_matter.status_reason,
+            gateFreshness,
+          )
+        ) {
+          let decision: WorkerDecisionResult;
           try {
-            repairDecision = await this.workerDecisionRunner.execute({
+            decision = await this.workerDecisionRunner.execute({
               role: 'qa',
               featureId,
               contextBundle: context.data,
-              instructions: repairPrompt,
+              instructions:
+                'Emit PATCH outputs for deterministic QA remediations, NOTE outputs for findings, and REQUEST outputs for lock/context needs.',
             });
           } catch (error) {
             const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId, 'qa');
             if (handledRuntimeFailure) {
-              break;
+              continue;
             }
             throw error;
           }
-          const retrySemanticStall = await this.enforceSemanticStallPolicy(
+
+          const semanticStall = await this.enforceSemanticStallPolicy(
             featureId,
-            repairDecision,
+            decision,
             context.data,
           );
-          if (retrySemanticStall) {
-            break;
+          if (semanticStall) {
+            continue;
           }
-          const shouldSkipRepair = await this.enforceWorkerExecutionPolicy(
+
+          if (decision.questionRequested) {
+            this.noProgressByFeature.delete(featureId);
+            this.blockedForCurrentCycle.add(featureId);
+            continue;
+          }
+
+          const shouldSkip = await this.enforceWorkerExecutionPolicy(
             featureId,
-            repairDecision,
+            decision,
             'qa',
+            gateFreshness,
           );
-          if (shouldSkipRepair) {
-            break;
+          if (shouldSkip) {
+            continue;
           }
           this.noProgressByFeature.delete(featureId);
+        }
 
-          try {
-            const retryResult = await this.toolCaller.callTool<GatesRunData>(
+        const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
+          'qa',
+          TOOLS.FEATURE_STATE_GET,
+          {
+            feature_id: featureId,
+          },
+        );
+        const initialRetryCount = stateForRetry.data.front_matter.gate_retry_count ?? 0;
+
+        let gateOverall: string;
+        let gateExitCode: number;
+        let gateEvidencePath = '';
+        let gateLogs = '';
+        let gateRetryEligible: boolean;
+        const failureHistory: GateRepairContext['failureHistory'] = [];
+
+        try {
+          const gateResult = await this.toolCaller.callTool<GatesRunData>('qa', TOOLS.GATES_RUN, {
+            feature_id: featureId,
+            mode: 'full',
+          });
+          gateOverall = gateResult.data.overall ?? GATE_RESULT.PASS;
+          gateExitCode = gateOverall === GATE_RESULT.FAIL ? 1 : 0;
+          gateEvidencePath = gateResult.data.evidence_path ?? '';
+          gateRetryEligible = gateOverall === GATE_RESULT.FAIL;
+        } catch (error) {
+          gateOverall = GATE_RESULT.FAIL;
+          gateExitCode = 1;
+          const typed = error as { message?: string };
+          gateLogs = typed.message ?? '';
+          gateRetryEligible = isRetryableToolError(error);
+        }
+
+        if (gateOverall === GATE_RESULT.FAIL) {
+          failureHistory.push({
+            attempt: initialRetryCount + 1,
+            gate_name: 'full',
+            exit_code: gateExitCode,
+            evidence_summary: gateEvidencePath,
+            logs_excerpt: gateLogs.slice(0, 800),
+            failed_at: new Date().toISOString(),
+            retry_delay_ms: this.reactionsService?.retryDelayMs(),
+          });
+        }
+
+        if (this.reactionsService && gateOverall === GATE_RESULT.FAIL && gateRetryEligible) {
+          let retryCount = initialRetryCount;
+          const retryDelayMs = this.reactionsService.retryDelayMs();
+          while (gateRetryEligible && this.reactionsService.shouldRetry(featureId, retryCount)) {
+            if (typeof this.reactionsService.waitBeforeRetry === 'function') {
+              await this.reactionsService.waitBeforeRetry();
+            }
+            const attempt = retryCount + 2;
+            const ctx: GateRepairContext = {
+              featureId,
+              gateName: 'full',
+              exitCode: gateExitCode,
+              logs: gateLogs,
+              evidenceSummary: gateEvidencePath,
+              retryCount,
+              failureHistory,
+            };
+            const repairPrompt = this.reactionsService.buildRepairPrompt(ctx);
+            let repairDecision: WorkerDecisionResult;
+            try {
+              repairDecision = await this.workerDecisionRunner.execute({
+                role: 'qa',
+                featureId,
+                contextBundle: context.data,
+                instructions: repairPrompt,
+              });
+            } catch (error) {
+              const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId, 'qa');
+              if (handledRuntimeFailure) {
+                break;
+              }
+              throw error;
+            }
+            const retrySemanticStall = await this.enforceSemanticStallPolicy(
+              featureId,
+              repairDecision,
+              context.data,
+            );
+            if (retrySemanticStall) {
+              break;
+            }
+            if (repairDecision.questionRequested) {
+              this.noProgressByFeature.delete(featureId);
+              this.blockedForCurrentCycle.add(featureId);
+              break;
+            }
+            const refreshedState = await this.toolCaller.callTool<FeatureStatePayload>(
               'qa',
-              TOOLS.GATES_RUN,
+              TOOLS.FEATURE_STATE_GET,
               {
                 feature_id: featureId,
-                mode: 'full',
               },
             );
-            gateOverall = retryResult.data.overall ?? GATE_RESULT.PASS;
-            gateExitCode = gateOverall === GATE_RESULT.FAIL ? 1 : 0;
-            gateEvidencePath = retryResult.data.evidence_path ?? gateEvidencePath;
-            gateLogs = '';
-            gateRetryEligible = gateOverall === GATE_RESULT.FAIL;
-          } catch (error) {
-            gateOverall = GATE_RESULT.FAIL;
-            gateExitCode = 1;
-            const typed = error as { message?: string };
-            gateLogs = typed.message ?? '';
-            gateRetryEligible = isRetryableToolError(error);
-          }
+            const refreshedContext = await this.toolCaller.callTool(
+              'qa',
+              TOOLS.FEATURE_GET_CONTEXT,
+              {
+                feature_id: featureId,
+              },
+            );
+            const shouldSkipRepair = await this.enforceWorkerExecutionPolicy(
+              featureId,
+              repairDecision,
+              'qa',
+              this.assessFullGateFreshness(
+                refreshedState.data.front_matter as unknown as Record<string, unknown>,
+                refreshedContext.data,
+              ),
+            );
+            if (shouldSkipRepair) {
+              break;
+            }
+            this.noProgressByFeature.delete(featureId);
+
+            try {
+              const retryResult = await this.toolCaller.callTool<GatesRunData>(
+                'qa',
+                TOOLS.GATES_RUN,
+                {
+                  feature_id: featureId,
+                  mode: 'full',
+                },
+              );
+              gateOverall = retryResult.data.overall ?? GATE_RESULT.PASS;
+              gateExitCode = gateOverall === GATE_RESULT.FAIL ? 1 : 0;
+              gateEvidencePath = retryResult.data.evidence_path ?? gateEvidencePath;
+              gateLogs = '';
+              gateRetryEligible = gateOverall === GATE_RESULT.FAIL;
+            } catch (error) {
+              gateOverall = GATE_RESULT.FAIL;
+              gateExitCode = 1;
+              const typed = error as { message?: string };
+              gateLogs = typed.message ?? '';
+              gateRetryEligible = isRetryableToolError(error);
+            }
 
-          retryCount += 1;
-          await this.reactionsService.recordRetry(featureId, retryCount);
-
-          if (gateOverall === GATE_RESULT.FAIL) {
-            failureHistory.push({
-              attempt,
-              gate_name: 'full',
-              exit_code: gateExitCode,
-              evidence_summary: gateEvidencePath,
-              logs_excerpt: gateLogs.slice(0, 800),
-              failed_at: new Date().toISOString(),
-              retry_delay_ms: retryDelayMs,
-            });
-          }
+            retryCount += 1;
+            await this.reactionsService.recordRetry(featureId, retryCount);
+
+            if (gateOverall === GATE_RESULT.FAIL) {
+              failureHistory.push({
+                attempt,
+                gate_name: 'full',
+                exit_code: gateExitCode,
+                evidence_summary: gateEvidencePath,
+                logs_excerpt: gateLogs.slice(0, 800),
+                failed_at: new Date().toISOString(),
+                retry_delay_ms: retryDelayMs,
+              });
+            }
 
-          if (gateOverall === GATE_RESULT.PASS) {
-            break;
+            if (gateOverall === GATE_RESULT.PASS) {
+              break;
+            }
+            if (!gateRetryEligible) {
+              break;
+            }
           }
-          if (!gateRetryEligible) {
-            break;
+
+          if (
+            gateOverall === GATE_RESULT.FAIL &&
+            this.reactionsService.shouldEscalate(retryCount)
+          ) {
+            const escalateCtx: GateRepairContext = {
+              featureId,
+              gateName: 'full',
+              exitCode: gateExitCode,
+              logs: gateLogs,
+              evidenceSummary: gateEvidencePath,
+              retryCount,
+              failureHistory,
+            };
+            await this.reactionsService.notifyEscalation(featureId, escalateCtx);
           }
         }
 
-        if (gateOverall === GATE_RESULT.FAIL && this.reactionsService.shouldEscalate(retryCount)) {
-          const escalateCtx: GateRepairContext = {
-            featureId,
-            gateName: 'full',
-            exitCode: gateExitCode,
-            logs: gateLogs,
-            evidenceSummary: gateEvidencePath,
-            retryCount,
-            failureHistory,
-          };
-          await this.reactionsService.notifyEscalation(featureId, escalateCtx);
+        const sessions = this.state.sessionsByFeature.get(featureId);
+        if (sessions?.qa) {
+          await this.provider.closeSession(sessions.qa);
         }
-      }
 
-      const sessions = this.state.sessionsByFeature.get(featureId);
-      if (sessions?.qa) {
-        await this.provider.closeSession(sessions.qa);
-      }
-
-      const prompts = await this.promptProvider.loadRolePrompts();
-      const newQa = await this.provider.createSession('qa', featureId, prompts.qa);
-      if (sessions) {
-        sessions.qa = newQa.session_id;
-      }
+        const prompts = await this.promptProvider.loadRolePrompts();
+        const newQa = await this.provider.createSession('qa', featureId, prompts.qa);
+        if (sessions) {
+          sessions.qa = newQa.session_id;
+        }
 
-      await this.kernel.updateFeatureSessionAssignment({
-        run_id: this.state.runId,
-        owner_instance_id: this.state.ownerInstanceId,
-        feature_id: featureId,
-        planner_session_id: sessions?.planner ?? UNASSIGNED_SESSION_ID,
-        builder_session_id: sessions?.builder ?? UNASSIGNED_SESSION_ID,
-        qa_session_id: newQa.session_id,
-      });
+        await this.kernel.updateFeatureSessionAssignment({
+          run_id: this.state.runId,
+          owner_instance_id: this.state.ownerInstanceId,
+          feature_id: featureId,
+          planner_session_id: sessions?.planner ?? UNASSIGNED_SESSION_ID,
+          builder_session_id: sessions?.builder ?? UNASSIGNED_SESSION_ID,
+          qa_session_id: newQa.session_id,
+        });
 
-      await this.featureClusterPatcher.patchFeatureCluster(featureId, {
-        orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
-        qa_session_id: newQa.session_id,
-      });
+        await this.featureClusterPatcher.patchFeatureCluster(featureId, {
+          orchestrator_session_id: this.state.orchestratorSessionId ?? 'unknown',
+          qa_session_id: newQa.session_id,
+        });
+      } finally {
+        if (this.safeCheckpointHook) {
+          await this.safeCheckpointHook();
+        }
+      }
     }
   }
 
@@ -411,11 +493,17 @@ export class QaWaveExecutor {
     this.planConformanceScorer?.reset(featureId);
   }
 
+  /**
+   * Clears all per-feature tracking state (progress counters, blocked flags, loop detectors).
+   * Called when a feature is removed from the active execution set.
+   * @param featureId The feature whose tracking data should be purged.
+   */
   clearFeatureTracking(featureId: string): void {
     this.noProgressByFeature.delete(featureId);
     this.blockedForCurrentCycle.delete(featureId);
     this.lastStatusByFeature.delete(featureId);
     this.conformanceWarningsLogged.delete(featureId);
+    this.timeoutRetryUsed.delete(featureId);
     this.outputLoopDetector?.delete(featureId);
     this.planConformanceScorer?.delete(featureId);
   }
@@ -465,6 +553,24 @@ export class QaWaveExecutor {
       throw error;
     }
     const message = typed.message ?? `QA runtime failure: ${code}`;
+
+    // Allow one automatic retry at the same phase for timeout errors before blocking.
+    if (
+      TIMEOUT_RUNTIME_ERROR_CODES.has(code) &&
+      policyAction === 'block_feature' &&
+      !this.timeoutRetryUsed.has(featureId)
+    ) {
+      this.timeoutRetryUsed.add(featureId);
+      await this.appendRuntimePolicyEvent({
+        featureId,
+        phase,
+        errorCode: code,
+        policyAction: 'block_feature',
+        message: `${message} (auto-retry once at same phase)`,
+      });
+      return false;
+    }
+
     await this.appendRuntimePolicyEvent({
       featureId,
       phase,
@@ -611,20 +717,46 @@ export class QaWaveExecutor {
     featureId: string,
     decision: {
       invalidOutput: boolean;
+      errorCode?: string | null;
       noProgress: boolean;
+      questionRequested?: boolean;
+      contextStall?: boolean;
+      contextRequestCount?: number;
+      lastContextRequestAt?: string | null;
+      lastContextRequestRole?: string | null;
+      interactiveOutcome?: WorkerDecisionResult['interactiveOutcome'];
+      checkpoint?: WorkerDecisionResult['checkpoint'];
     },
     phase: 'qa',
+    gateFreshness: GateFreshnessAssessment,
   ): Promise<boolean> {
     if (this.providerMode !== 'live') {
       this.noProgressByFeature.delete(featureId);
       return false;
     }
 
+    if (decision.interactiveOutcome === 'checkpoint_invalid') {
+      const joinedViolations = decision.checkpoint?.violations?.join('; ');
+      const violations =
+        joinedViolations && joinedViolations.length > 0
+          ? joinedViolations
+          : 'checkpoint validation failed';
+      await this.applyWorkerPolicyAction(
+        featureId,
+        'block_feature',
+        ERROR_CODES.INTERACTIVE_CHECKPOINT_INVALID,
+        `QA checkpoint invalid: ${violations}`,
+        phase,
+      );
+      this.blockedForCurrentCycle.add(featureId);
+      return true;
+    }
+
     if (decision.invalidOutput) {
       await this.applyWorkerPolicyAction(
         featureId,
         this.malformedOutputAction,
-        ERROR_CODES.PROVIDER_OUTPUT_INVALID,
+        decision.errorCode ?? ERROR_CODES.PROVIDER_OUTPUT_INVALID,
         'QA emitted malformed worker outputs',
         phase,
       );
@@ -632,6 +764,54 @@ export class QaWaveExecutor {
       return true;
     }
 
+    if (decision.contextStall) {
+      const state = await this.toolCaller.callTool<FeatureStatePayload>(
+        'orchestrator',
+        TOOLS.FEATURE_STATE_GET,
+        {
+          feature_id: featureId,
+        },
+      );
+      const expectedVersion = asVersion(state.data.front_matter.version);
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+        feature_id: featureId,
+        expected_version: expectedVersion,
+        patch: {
+          front_matter: {
+            status: STATUS.BLOCKED,
+            status_reason: `${ERROR_CODES.PROVIDER_CONTEXT_STALL}: repeated context refresh with no progress`,
+            context_request_count: decision.contextRequestCount ?? 0,
+            last_context_request_at: decision.lastContextRequestAt ?? null,
+            last_context_request_role: decision.lastContextRequestRole ?? 'qa',
+          },
+        },
+      });
+      this.lastStatusByFeature.set(featureId, STATUS.BLOCKED);
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+        feature_id: featureId,
+        note: JSON.stringify({
+          phase,
+          decision: 'blocked',
+          error_code: ERROR_CODES.PROVIDER_CONTEXT_STALL,
+          reason: 'repeated context refresh with no progress',
+          context_request_count: decision.contextRequestCount ?? 0,
+          last_context_request_at: decision.lastContextRequestAt ?? null,
+          last_context_request_role: decision.lastContextRequestRole ?? 'qa',
+        }),
+      });
+      this.blockedForCurrentCycle.add(featureId);
+      return true;
+    }
+
+    if (
+      decision.noProgress &&
+      gateFreshness.shouldRerunGate &&
+      hasMaterialWorktreeDiffHash(gateFreshness.currentDiffHash)
+    ) {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
     if (!decision.noProgress) {
       this.noProgressByFeature.delete(featureId);
       return false;
@@ -647,13 +827,40 @@ export class QaWaveExecutor {
     await this.applyWorkerPolicyAction(
       featureId,
       this.noProgressAction,
-      ERROR_CODES.PROVIDER_NO_PROGRESS,
+      decision.interactiveOutcome === 'no_new_work'
+        ? ERROR_CODES.INTERACTIVE_NO_NEW_WORK
+        : ERROR_CODES.PROVIDER_NO_PROGRESS,
       `QA made no actionable progress in ${currentCount} consecutive iterations`,
       phase,
     );
     return true;
   }
 
+  private assessFullGateFreshness(
+    frontMatter: Record<string, unknown>,
+    contextData: unknown,
+  ): GateFreshnessAssessment {
+    return assessGateFreshness({
+      frontMatter,
+      mode: 'full',
+      gateEvidenceByMode: readGateEvidenceByMode(contextData),
+      latestEvidence: null,
+    });
+  }
+
+  private shouldBypassWorkerForGateRefresh(
+    statusReason: unknown,
+    gateFreshness: GateFreshnessAssessment,
+  ): boolean {
+    if (!gateFreshness.shouldRerunGate) {
+      return false;
+    }
+    return (
+      typeof statusReason === 'string' &&
+      statusReason.includes('recovered_from_blocked:gate_refresh:full')
+    );
+  }
+
   private async applyWorkerPolicyAction(
     featureId: string,
     action: