agentic-orchestrator 0.1.27 → 0.2.0

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

@@ -1,5 +1,16 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { GATE_RESULT, STATUS, TOOLS } from '../core/constants.js';
+import type { ArtifactStager } from './artifact-stager.js';
 import { ERROR_CODES } from '../core/error-codes.js';
+import {
+  assessGateFreshness,
+  hasMaterialWorktreeDiffHash,
+  readGateEvidenceByMode,
+  type GateFreshnessAssessment,
+} from '../core/gate-freshness.js';
+import { extractGateLog } from '../core/gate-log-extractor.js';
+import type { GateLogExtraction } from '../core/gate-log-extractor.js';
 import type { FeatureStatePayload, SupervisorToolCaller } from './types.js';
 import {
   NOOP_WORKER_DECISION_RUNNER,
@@ -45,6 +56,8 @@ interface BuildWaveExecutorDependencies {
   runId?: string | (() => string);
   providerName?: string;
   modelName?: string;
+  safeCheckpointHook?: () => Promise<void>;
+  artifactStager?: ArtifactStager;
 }
 
 function isRetryableToolError(error: unknown): boolean {
@@ -65,6 +78,28 @@ function asVersion(value: unknown): number | null {
   return Math.floor(value);
 }
 
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function asNumber(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return null;
+  }
+  return value;
+}
+
 const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
   ERROR_CODES.PROVIDER_SPAWN_TIMEOUT,
   ERROR_CODES.PROVIDER_STALL_TIMEOUT,
@@ -75,6 +110,10 @@ const TIMEOUT_RUNTIME_ERROR_CODES = new Set<string>([
  * @fileoverview Build phase wave executor.
  */
 
+/**
+ * Executes the build phase for one supervisor iteration wave.
+ * Dispatches worker decisions, runs fast gates, and manages gate-repair retry loops.
+ */
 export class BuildWaveExecutor {
   private readonly toolCaller: SupervisorToolCaller;
   private readonly workerDecisionRunner: WorkerDecisionRunner;
@@ -94,10 +133,13 @@ export class BuildWaveExecutor {
   private readonly runId: string | (() => string) | null;
   private readonly providerName: string;
   private readonly modelName: string;
+  private readonly safeCheckpointHook: (() => Promise<void>) | undefined;
+  private readonly artifactStager: ArtifactStager | null;
   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: BuildWaveExecutorDependencies) {
     this.toolCaller = dependencies.toolCaller;
@@ -121,11 +163,20 @@ export class BuildWaveExecutor {
     this.runId = dependencies.runId ?? null;
     this.providerName = dependencies.providerName ?? 'unknown';
     this.modelName = dependencies.modelName ?? 'unknown';
+    this.safeCheckpointHook = dependencies.safeCheckpointHook;
+    this.artifactStager = dependencies.artifactStager ?? null;
   }
 
+  /**
+   * Runs a single build wave: invokes workers for each building feature, executes fast gates,
+   * and retries gate failures via the reactions service repair loop.
+   * @param featureIds Feature IDs eligible for this wave.
+   * @param maxParallelGateRuns Maximum number of features to process concurrently in one wave.
+   */
   async run(featureIds: string[], maxParallelGateRuns: number): Promise<void> {
     this.blockedForCurrentCycle.clear();
     const batch: string[] = [];
+    const directGateCandidates = new Set<string>();
     for (const featureId of featureIds) {
       const state = await this.toolCaller.callTool<FeatureStatePayload>(
         'builder',
@@ -148,200 +199,293 @@ export class BuildWaveExecutor {
 
     const selected = batch.slice(0, maxParallelGateRuns);
     for (const featureId of selected) {
-      const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
-        feature_id: featureId,
-      });
-      let decision;
       try {
-        decision = await this.workerDecisionRunner.execute({
-          role: 'builder',
-          featureId,
-          contextBundle: context.data,
-          instructions:
-            'Emit PATCH outputs for code changes, NOTE outputs for progress context, and REQUEST outputs for lock/context needs.',
+        const state = await this.toolCaller.callTool<FeatureStatePayload>(
+          'builder',
+          TOOLS.FEATURE_STATE_GET,
+          {
+            feature_id: featureId,
+          },
+        );
+        const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
+          feature_id: featureId,
         });
-      } catch (error) {
-        const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId, 'build');
-        if (handledRuntimeFailure) {
+        const gateFreshness = this.assessFastGateFreshness(
+          state.data.front_matter as unknown as Record<string, unknown>,
+          context.data,
+        );
+        if (
+          this.shouldBypassWorkerForGateRefresh(
+            state.data.front_matter.status_reason,
+            gateFreshness,
+          )
+        ) {
+          directGateCandidates.add(featureId);
           continue;
         }
-        throw error;
-      }
+        if (this.artifactStager && this.repoRoot) {
+          const worktreePath = path.join(this.repoRoot, '.worktrees', featureId);
+          try {
+            await this.artifactStager.stage(featureId, worktreePath);
+          } catch {
+            // Non-fatal: builder can still function without staged artifacts
+          }
+        }
 
-      const stalled = await this.enforceSemanticStallPolicy(featureId, decision, context.data);
-      if (stalled) {
-        continue;
-      }
+        const instructions =
+          'Emit PATCH outputs for code changes, NOTE outputs for progress context, and REQUEST outputs for lock/context needs.';
+        let decision;
+        try {
+          decision = await this.workerDecisionRunner.execute({
+            role: 'builder',
+            featureId,
+            contextBundle: context.data,
+            instructions,
+          });
+        } catch (error) {
+          const handledRuntimeFailure = await this.handleRuntimeFailure(error, featureId, 'build');
+          if (handledRuntimeFailure) {
+            continue;
+          }
+          throw error;
+        }
+
+        const stalled = await this.enforceSemanticStallPolicy(featureId, decision, context.data);
+        if (stalled) {
+          continue;
+        }
 
-      const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, decision);
-      if (!shouldSkip) {
-        this.noProgressByFeature.delete(featureId);
+        if (decision.questionRequested) {
+          this.noProgressByFeature.delete(featureId);
+          this.blockedForCurrentCycle.add(featureId);
+          continue;
+        }
+
+        const shouldSkip = await this.enforceWorkerExecutionPolicy(
+          featureId,
+          decision,
+          gateFreshness,
+        );
+        if (!shouldSkip) {
+          this.noProgressByFeature.delete(featureId);
+          directGateCandidates.add(featureId);
+        }
+      } finally {
+        if (this.safeCheckpointHook) {
+          await this.safeCheckpointHook();
+        }
       }
     }
 
     const gateCandidates = selected.filter(
-      (featureId) => !this.blockedForCurrentCycle.has(featureId),
+      (featureId) =>
+        !this.blockedForCurrentCycle.has(featureId) && directGateCandidates.has(featureId),
     );
     const executing = gateCandidates.map(async (featureId) => {
-      const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
-        'builder',
-        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>(
+        const stateForRetry = await this.toolCaller.callTool<FeatureStatePayload>(
           'builder',
-          TOOLS.GATES_RUN,
+          TOOLS.FEATURE_STATE_GET,
           {
             feature_id: featureId,
-            mode: 'fast',
           },
         );
-        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);
-      }
+        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>(
+            'builder',
+            TOOLS.GATES_RUN,
+            {
+              feature_id: featureId,
+              mode: 'fast',
+            },
+          );
+          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: 'fast',
-          exit_code: gateExitCode,
-          evidence_summary: gateEvidencePath,
-          logs_excerpt: gateLogs.slice(0, 800),
-          failed_at: new Date().toISOString(),
-          retry_delay_ms: this.reactionsService?.retryDelayMs(),
-        });
-      }
+        if (gateOverall === GATE_RESULT.FAIL) {
+          failureHistory.push({
+            attempt: initialRetryCount + 1,
+            gate_name: 'fast',
+            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) {
-        const context = await this.toolCaller.callTool('builder', TOOLS.FEATURE_GET_CONTEXT, {
-          feature_id: featureId,
-        });
-        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: 'fast',
-            exitCode: gateExitCode,
-            logs: gateLogs,
-            evidenceSummary: gateEvidencePath,
-            retryCount,
-            failureHistory,
-          };
-          const repairPrompt = this.reactionsService.buildRepairPrompt(ctx);
-          let repairDecision: WorkerDecisionResult;
-          try {
-            repairDecision = await this.workerDecisionRunner.execute({
-              role: 'builder',
+        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;
+            // Refresh context before each repair attempt so the builder sees its own recent patches
+            const repairContext = await this.toolCaller.callTool(
+              'builder',
+              TOOLS.FEATURE_GET_CONTEXT,
+              {
+                feature_id: featureId,
+              },
+            );
+            const failureAnalysis = await this.extractFailureAnalysis(
+              repairContext.data,
+              gateExitCode,
+            );
+            const ctx: GateRepairContext = {
               featureId,
-              contextBundle: context.data,
-              instructions: repairPrompt,
-            });
-          } catch (error) {
-            const handledRuntimeFailure = await this.handleRuntimeFailure(
-              error,
+              gateName: 'fast',
+              exitCode: gateExitCode,
+              logs: gateLogs,
+              evidenceSummary: gateEvidencePath,
+              retryCount,
+              failureHistory,
+              ...(failureAnalysis ? { failureAnalysis } : {}),
+            };
+            const repairPrompt = this.reactionsService.buildRepairPrompt(ctx);
+            let repairDecision: WorkerDecisionResult;
+            try {
+              repairDecision = await this.workerDecisionRunner.execute({
+                role: 'builder',
+                featureId,
+                contextBundle: repairContext.data,
+                instructions: repairPrompt,
+              });
+            } catch (error) {
+              const handledRuntimeFailure = await this.handleRuntimeFailure(
+                error,
+                featureId,
+                'build',
+              );
+              if (handledRuntimeFailure) {
+                break;
+              }
+              throw error;
+            }
+            const semanticStall = await this.enforceSemanticStallPolicy(
               featureId,
-              'build',
+              repairDecision,
+              repairContext.data,
             );
-            if (handledRuntimeFailure) {
+            if (semanticStall) {
               break;
             }
-            throw error;
-          }
-          const semanticStall = await this.enforceSemanticStallPolicy(
-            featureId,
-            repairDecision,
-            context.data,
-          );
-          if (semanticStall) {
-            break;
-          }
-          const shouldSkip = await this.enforceWorkerExecutionPolicy(featureId, repairDecision);
-          if (shouldSkip) {
-            break;
-          }
-          this.noProgressByFeature.delete(featureId);
-
-          try {
-            const retryResult = await this.toolCaller.callTool<GatesRunData>(
+            if (repairDecision.questionRequested) {
+              this.noProgressByFeature.delete(featureId);
+              this.blockedForCurrentCycle.add(featureId);
+              break;
+            }
+            const refreshedState = await this.toolCaller.callTool<FeatureStatePayload>(
               'builder',
-              TOOLS.GATES_RUN,
+              TOOLS.FEATURE_STATE_GET,
               {
                 feature_id: featureId,
-                mode: 'fast',
               },
             );
-            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(
+              'builder',
+              TOOLS.FEATURE_GET_CONTEXT,
+              {
+                feature_id: featureId,
+              },
+            );
+            const shouldSkip = await this.enforceWorkerExecutionPolicy(
+              featureId,
+              repairDecision,
+              this.assessFastGateFreshness(
+                refreshedState.data.front_matter as unknown as Record<string, unknown>,
+                refreshedContext.data,
+              ),
+            );
+            if (shouldSkip) {
+              break;
+            }
+            this.noProgressByFeature.delete(featureId);
+
+            try {
+              const retryResult = await this.toolCaller.callTool<GatesRunData>(
+                'builder',
+                TOOLS.GATES_RUN,
+                {
+                  feature_id: featureId,
+                  mode: 'fast',
+                },
+              );
+              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: 'fast',
-              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: 'fast',
+                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: 'fast',
+              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: 'fast',
-            exitCode: gateExitCode,
-            logs: gateLogs,
-            evidenceSummary: gateEvidencePath,
-            retryCount,
-            failureHistory,
-          };
-          await this.reactionsService.notifyEscalation(featureId, escalateCtx);
+      } finally {
+        if (this.safeCheckpointHook) {
+          await this.safeCheckpointHook();
         }
       }
     });
@@ -349,10 +493,6 @@ export class BuildWaveExecutor {
     await Promise.allSettled(executing);
   }
 
-  private asRecord(value: unknown): Record<string, unknown> {
-    return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
-  }
-
   private resolveRunId(): string {
     if (typeof this.runId === 'function') {
       const value = this.runId();
@@ -372,11 +512,17 @@ export class BuildWaveExecutor {
     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);
   }
@@ -428,6 +574,25 @@ export class BuildWaveExecutor {
     }
 
     const message = typed.message ?? `Builder 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)`,
+      });
+      // Don't block — let the coordinator re-enter the build wave on the next iteration
+      return false;
+    }
+
     await this.appendRuntimePolicyEvent({
       featureId,
       phase,
@@ -497,7 +662,7 @@ export class BuildWaveExecutor {
     }
 
     if (this.planConformanceScorer) {
-      const plan = this.asRecord(this.asRecord(contextData).plan);
+      const plan = asRecord(asRecord(contextData)?.plan) ?? {};
       const conformanceResult = this.planConformanceScorer.check(featureId, decision, plan);
       if (conformanceResult.skipped && conformanceResult.warning) {
         await this.logPlanConformanceWarningOnce(featureId, conformanceResult.warning);
@@ -574,25 +739,98 @@ export class BuildWaveExecutor {
     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'];
     },
+    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,
+        `Builder checkpoint invalid: ${violations}`,
+      );
+      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,
         'Builder emitted malformed worker outputs',
       );
       this.blockedForCurrentCycle.add(featureId);
       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 ?? 'builder',
+          },
+        },
+      });
+      this.lastStatusByFeature.set(featureId, STATUS.BLOCKED);
+      await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+        feature_id: featureId,
+        note: JSON.stringify({
+          phase: 'build',
+          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 ?? 'builder',
+        }),
+      });
+      this.blockedForCurrentCycle.add(featureId);
+      return true;
+    }
+
+    if (
+      decision.interactiveOutcome === 'no_new_work' &&
+      gateFreshness.shouldRerunGate &&
+      hasMaterialWorktreeDiffHash(gateFreshness.currentDiffHash)
+    ) {
+      this.noProgressByFeature.delete(featureId);
+      return false;
+    }
+
     if (!decision.noProgress) {
       this.noProgressByFeature.delete(featureId);
       return false;
@@ -609,12 +847,85 @@ export class BuildWaveExecutor {
     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,
       `Builder made no actionable progress in ${currentCount} consecutive iterations`,
     );
     return true;
   }
 
+  private assessFastGateFreshness(
+    frontMatter: Record<string, unknown>,
+    contextData: unknown,
+  ): GateFreshnessAssessment {
+    return assessGateFreshness({
+      frontMatter,
+      mode: 'fast',
+      gateEvidenceByMode: readGateEvidenceByMode(contextData),
+      latestEvidence: asRecord(contextData)?.latest_evidence,
+    });
+  }
+
+  private shouldBypassWorkerForGateRefresh(
+    statusReason: unknown,
+    gateFreshness: GateFreshnessAssessment,
+  ): boolean {
+    if (!gateFreshness.shouldRerunGate) {
+      return false;
+    }
+    return (
+      typeof statusReason === 'string' &&
+      statusReason.includes('recovered_from_blocked:gate_refresh:fast')
+    );
+  }
+
+  private async extractFailureAnalysis(
+    contextData: unknown,
+    exitCode: number,
+  ): Promise<GateLogExtraction | null> {
+    try {
+      const contextRecord = asRecord(contextData);
+      const latestEvidence = asRecord(contextRecord?.latest_evidence);
+      const stepResultsRaw = Array.isArray(latestEvidence?.step_results)
+        ? latestEvidence.step_results
+        : [];
+      const stepResults = (stepResultsRaw as unknown[])
+        .map((item) => asRecord(item))
+        .filter(
+          (item): item is Record<string, unknown> => item !== null && Object.keys(item).length > 0,
+        );
+
+      const failingStep =
+        stepResults.find((item) => (asNumber(item.exit_code) ?? 0) !== 0) ?? stepResults[0] ?? null;
+      if (!failingStep) {
+        return null;
+      }
+
+      const stepName = asString(failingStep.name) ?? 'unknown';
+      const stepCmd: string[] = Array.isArray(failingStep.cmd)
+        ? (failingStep.cmd as unknown[]).map((c) => String(c))
+        : [];
+      const rawLogPath = asString(failingStep.log_path);
+      const logPath = rawLogPath
+        ? path.isAbsolute(rawLogPath)
+          ? rawLogPath
+          : this.repoRoot
+            ? path.join(this.repoRoot, rawLogPath)
+            : rawLogPath
+        : null;
+
+      if (!logPath) {
+        return null;
+      }
+
+      const logContent = await fs.readFile(logPath, 'utf8');
+      return extractGateLog({ stepName, cmd: stepCmd, exitCode, logContent });
+    } catch {
+      return null;
+    }
+  }
+
   private async applyWorkerPolicyAction(
     featureId: string,
     action: