agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/test/run-coordinator.spec.ts

@@ -3,6 +3,148 @@ import { STATUS, TOOLS } from '../src/core/constants.js';
 import { RunCoordinator } from '../src/supervisor/run-coordinator.js';
 
 describe('RunCoordinator iteration behavior', () => {
+  it('waits on awaiting_input features and resumes waves after the answer restores a runnable status', async () => {
+    vi.useFakeTimers();
+    try {
+      let status: string = STATUS.AWAITING_INPUT;
+      const kernel = {
+        ensureLoaded: vi.fn(async () => undefined),
+        recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
+        acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+        releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
+        pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+        getRuntimeSessions: vi.fn(async () => ({
+          run_id: 'run:test',
+          owner_instance_id: 'owner:test',
+          orchestrator_session_id: 'orch:test',
+          feature_sessions: {},
+        })),
+        getPolicySnapshot: vi.fn(() => ({
+          reactions: {
+            gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+          },
+        })),
+        updateState: vi.fn(async () => ({})),
+        checkBudget: vi.fn(async () => ({
+          over_budget: false,
+          alert_threshold_reached: false,
+          current_cost_usd: 0,
+          limit_usd: -1,
+          alert_threshold: 0.8,
+        })),
+        drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+        markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+      };
+
+      const provider = {
+        selection: {
+          provider: 'custom',
+          model: 'model-test',
+        },
+      };
+
+      const toolCaller = {
+        callTool: vi.fn(async (_role: string, toolName: string) => {
+          if (toolName === TOOLS.REPORT_DASHBOARD) {
+            return { ok: true, data: { features: [] } };
+          }
+          if (toolName === TOOLS.FEATURE_STATE_GET) {
+            return { ok: true, data: { front_matter: { status } } };
+          }
+          return { ok: true, data: {} };
+        }),
+      };
+
+      const state = {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      };
+
+      const sessionOrchestrator = {
+        ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+        cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+        initializeFeatureCluster: vi.fn(async (featureId: string) => {
+          state.sessionsByFeature.set(featureId, {
+            planner: `${featureId}:planner`,
+            builder: `${featureId}:builder`,
+            qa: `${featureId}:qa`,
+          });
+        }),
+        closeFeatureCluster: vi.fn(async () => undefined),
+        reconcileQueuedFeatures: vi.fn(async () => undefined),
+        enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+      };
+
+      const planningWaveExecutor = {
+        run: vi.fn(async () => {
+          status = STATUS.MERGED;
+        }),
+        runPostQaReconciliation: vi.fn(async () => undefined),
+        clearFeatureTracking: vi.fn(),
+      };
+
+      const buildWaveExecutor = {
+        run: vi.fn(async () => undefined),
+        clearFeatureTracking: vi.fn(),
+      };
+
+      const qaWaveExecutor = {
+        run: vi.fn(async () => undefined),
+        clearFeatureTracking: vi.fn(),
+      };
+
+      const leaseHeartbeatService = {
+        renew: vi.fn(async () => undefined),
+      };
+
+      const executionEnrollmentService = {
+        start: vi.fn(async () => undefined),
+        stop: vi.fn(async () => undefined),
+        notifyNewRequestHint: vi.fn(async () => undefined),
+        noteSafeCheckpoint: vi.fn(async () => undefined),
+        hasPendingWork: vi.fn(() => false),
+        drainReadyDecisions: vi.fn(async () => []),
+      };
+
+      const coordinator = new RunCoordinator({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        state: state as never,
+        sessionOrchestrator: sessionOrchestrator as never,
+        planningWaveExecutor: planningWaveExecutor as never,
+        buildWaveExecutor: buildWaveExecutor as never,
+        qaWaveExecutor: qaWaveExecutor as never,
+        leaseHeartbeatService: leaseHeartbeatService as never,
+        maxActiveFeatures: 1,
+        maxParallelGateRuns: 2,
+        maxIterationsPerPhase: 1,
+        takeoverStaleRun: false,
+        providerConfigRefHash: () => 'hash',
+        executionEnrollmentService: executionEnrollmentService as never,
+      });
+
+      const startPromise = coordinator.start([{ feature_id: 'feature_waiting' }]);
+
+      await vi.advanceTimersByTimeAsync(500);
+      expect(planningWaveExecutor.run).not.toHaveBeenCalled();
+      expect(executionEnrollmentService.noteSafeCheckpoint).toHaveBeenCalled();
+
+      status = STATUS.PLANNING;
+      await vi.advanceTimersByTimeAsync(1_500);
+      await startPromise;
+
+      expect(planningWaveExecutor.run).toHaveBeenCalledWith(['feature_waiting']);
+      expect(leaseHeartbeatService.renew).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('GIVEN_long_running_wave_WHEN_iteration_exceeds_lease_interval_THEN_background_renew_keeps_run_lease_fresh', async () => {
     vi.useFakeTimers();
     try {
@@ -10,6 +152,7 @@ describe('RunCoordinator iteration behavior', () => {
         ensureLoaded: vi.fn(async () => undefined),
         recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
         acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+        releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
         pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
         getRuntimeSessions: vi.fn(async () => ({
           run_id: 'run:test',
@@ -17,6 +160,11 @@ describe('RunCoordinator iteration behavior', () => {
           orchestrator_session_id: 'orch:test',
           feature_sessions: {},
         })),
+        getPolicySnapshot: vi.fn(() => ({
+          reactions: {
+            gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+          },
+        })),
         updateState: vi.fn(async () => ({})),
         checkBudget: vi.fn(async () => ({
           over_budget: false,
@@ -25,6 +173,8 @@ describe('RunCoordinator iteration behavior', () => {
           limit_usd: -1,
           alert_threshold: 0.8,
         })),
+        drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+        markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
       };
 
       const provider = {
@@ -127,6 +277,7 @@ describe('RunCoordinator iteration behavior', () => {
       ensureLoaded: vi.fn(async () => undefined),
       recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
       acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
       pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
       getRuntimeSessions: vi.fn(async () => ({
         run_id: 'run:test',
@@ -134,7 +285,23 @@ describe('RunCoordinator iteration behavior', () => {
         orchestrator_session_id: 'orch:test',
         feature_sessions: {},
       })),
-      updateState: vi.fn(async () => ({})),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
+      updateState: vi.fn(
+        async (
+          _featureId: string,
+          _scope: unknown,
+          updater?: (frontMatter: Record<string, unknown>) => Promise<unknown>,
+        ) => {
+          if (typeof updater === 'function') {
+            await updater({});
+          }
+          return {};
+        },
+      ),
       checkBudget: vi.fn(async () => ({
         over_budget: false,
         alert_threshold_reached: false,
@@ -142,6 +309,8 @@ describe('RunCoordinator iteration behavior', () => {
         limit_usd: -1,
         alert_threshold: 0.8,
       })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
     };
 
     const provider = {
@@ -153,6 +322,9 @@ describe('RunCoordinator iteration behavior', () => {
 
     const toolCaller = {
       callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
+        }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
         }
@@ -243,11 +415,13 @@ describe('RunCoordinator iteration behavior', () => {
     );
   });
 
-  it('GIVEN_terminal_active_feature_WHEN_slots_free_up_THEN_promotes_next_queued_feature_deterministically', async () => {
+  it('GIVEN_phase_reconciliation_enabled_WHEN_running_iteration_THEN_reconciles_mainline_before_planning_build_and_qa', async () => {
+    let featureStatus: string = STATUS.PLANNING;
     const kernel = {
       ensureLoaded: vi.fn(async () => undefined),
       recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
       acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
       pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
       getRuntimeSessions: vi.fn(async () => ({
         run_id: 'run:test',
@@ -255,6 +429,16 @@ describe('RunCoordinator iteration behavior', () => {
         orchestrator_session_id: 'orch:test',
         feature_sessions: {},
       })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+        reconciliation: {
+          enabled: true,
+          check_before_phases: ['planning', 'building', 'qa'],
+          auto_merge_non_conflicting: true,
+        },
+      })),
       updateState: vi.fn(async () => ({})),
       checkBudget: vi.fn(async () => ({
         over_budget: false,
@@ -263,35 +447,17 @@ describe('RunCoordinator iteration behavior', () => {
         limit_usd: -1,
         alert_threshold: 0.8,
       })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
     };
 
-    const provider = {
-      selection: {
-        provider: 'custom',
-        model: 'model-test',
-      },
-    };
-
-    const statusReads = new Map<string, string[]>([
-      ['feature_a', ['planning', 'merged']],
-      ['feature_b', ['planning']],
-    ]);
-
     const toolCaller = {
-      callTool: vi.fn(async (_role: string, toolName: string, args: Record<string, unknown>) => {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          const featureId = String(args.feature_id);
-          const states = statusReads.get(featureId) ?? ['planning'];
-          const status = states.shift() ?? states.at(-1) ?? 'planning';
-          statusReads.set(featureId, states.length === 0 ? [status] : states);
-          return {
-            ok: true,
-            data: {
-              front_matter: {
-                status,
-              },
-            },
-          };
+          return { ok: true, data: { front_matter: { status: featureStatus } } };
+        }
+        if (toolName === TOOLS.REPO_RECONCILE_MAINLINE) {
+          return { ok: true, data: { status: 'up_to_date' } };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
@@ -300,6 +466,13 @@ describe('RunCoordinator iteration behavior', () => {
       }),
     };
 
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+      },
+    };
+
     const state = {
       runId: 'run:test',
       ownerInstanceId: 'owner:test',
@@ -312,33 +485,30 @@ describe('RunCoordinator iteration behavior', () => {
     const sessionOrchestrator = {
       ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
       cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
-      initializeFeatureCluster: vi.fn(async (featureId: string) => {
-        state.sessionsByFeature.set(featureId, {
-          planner: `${featureId}:planner`,
-          builder: `${featureId}:builder`,
-          qa: `${featureId}:qa`,
-        });
-      }),
-      closeFeatureCluster: vi.fn(async (featureId: string) => {
-        state.sessionsByFeature.delete(featureId);
-      }),
+      initializeFeatureCluster: vi.fn(async () => undefined),
       reconcileQueuedFeatures: vi.fn(async () => undefined),
       enforceActiveFeatureInvariant: vi.fn(async () => undefined),
     };
 
     const planningWaveExecutor = {
-      run: vi.fn(async () => undefined),
+      run: vi.fn(async () => {
+        featureStatus = STATUS.BUILDING;
+      }),
       runPostQaReconciliation: vi.fn(async () => undefined),
       clearFeatureTracking: vi.fn(),
     };
 
     const buildWaveExecutor = {
-      run: vi.fn(async () => undefined),
+      run: vi.fn(async () => {
+        featureStatus = STATUS.QA;
+      }),
       clearFeatureTracking: vi.fn(),
     };
 
     const qaWaveExecutor = {
-      run: vi.fn(async () => undefined),
+      run: vi.fn(async () => {
+        featureStatus = STATUS.READY_TO_MERGE;
+      }),
       clearFeatureTracking: vi.fn(),
     };
 
@@ -358,32 +528,43 @@ describe('RunCoordinator iteration behavior', () => {
       leaseHeartbeatService: leaseHeartbeatService as never,
       maxActiveFeatures: 1,
       maxParallelGateRuns: 2,
-      maxIterationsPerPhase: 2,
+      maxIterationsPerPhase: 1,
       takeoverStaleRun: false,
       providerConfigRefHash: () => 'hash',
     });
 
-    const result = await coordinator.start([
-      { feature_id: 'feature_a' },
-      { feature_id: 'feature_b' },
-    ]);
+    await coordinator.start([{ feature_id: 'feature_a' }]);
 
-    expect(result.queue_depth).toBe(0);
-    expect(sessionOrchestrator.initializeFeatureCluster).toHaveBeenNthCalledWith(1, 'feature_a');
-    expect(sessionOrchestrator.closeFeatureCluster).toHaveBeenCalledWith('feature_a');
-    expect(planningWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
-    expect(buildWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
-    expect(qaWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
-    expect(sessionOrchestrator.initializeFeatureCluster).toHaveBeenNthCalledWith(2, 'feature_b');
-    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(1, ['feature_a']);
-    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(2, ['feature_b']);
+    const reconcileCalls = toolCaller.callTool.mock.calls.filter(
+      ([, toolName]) => toolName === TOOLS.REPO_RECONCILE_MAINLINE,
+    );
+    expect(reconcileCalls).toHaveLength(3);
+    expect(reconcileCalls.map((call) => (call as unknown[])[2])).toEqual([
+      {
+        feature_id: 'feature_a',
+        auto_merge_non_conflicting: true,
+        commit_message: 'chore: checkpoint feature_a before planning reconciliation',
+      },
+      {
+        feature_id: 'feature_a',
+        auto_merge_non_conflicting: true,
+        commit_message: 'chore: checkpoint feature_a before building reconciliation',
+      },
+      {
+        feature_id: 'feature_a',
+        auto_merge_non_conflicting: true,
+        commit_message: 'chore: checkpoint feature_a before qa reconciliation',
+      },
+    ]);
   });
 
-  it('GIVEN_orchestrator_priority_request_WHEN_running_iteration_THEN_reorders_active_feature_execution', async () => {
+  it('GIVEN_phase_reconciliation_detects_mainline_conflict_WHEN_planning_starts_THEN_feature_is_skipped_for_that_phase', async () => {
+    let featureStatus: string = STATUS.PLANNING;
     const kernel = {
       ensureLoaded: vi.fn(async () => undefined),
       recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
       acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
       pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
       getRuntimeSessions: vi.fn(async () => ({
         run_id: 'run:test',
@@ -391,6 +572,16 @@ describe('RunCoordinator iteration behavior', () => {
         orchestrator_session_id: 'orch:test',
         feature_sessions: {},
       })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+        reconciliation: {
+          enabled: true,
+          check_before_phases: ['planning'],
+          auto_merge_non_conflicting: true,
+        },
+      })),
       updateState: vi.fn(async () => ({})),
       checkBudget: vi.fn(async () => ({
         over_budget: false,
@@ -399,26 +590,18 @@ describe('RunCoordinator iteration behavior', () => {
         limit_usd: -1,
         alert_threshold: 0.8,
       })),
-    };
-
-    const provider = {
-      selection: {
-        provider: 'custom',
-        model: 'model-test',
-      },
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
     };
 
     const toolCaller = {
-      callTool: vi.fn(async (_role: string, toolName: string, _args: Record<string, unknown>) => {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          return {
-            ok: true,
-            data: {
-              front_matter: {
-                status: 'planning',
-              },
-            },
-          };
+          return { ok: true, data: { front_matter: { status: featureStatus } } };
+        }
+        if (toolName === TOOLS.REPO_RECONCILE_MAINLINE) {
+          featureStatus = STATUS.BLOCKED;
+          return { ok: true, data: { status: 'conflict_detected' } };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
@@ -427,6 +610,13 @@ describe('RunCoordinator iteration behavior', () => {
       }),
     };
 
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+      },
+    };
+
     const state = {
       runId: 'run:test',
       ownerInstanceId: 'owner:test',
@@ -439,14 +629,7 @@ describe('RunCoordinator iteration behavior', () => {
     const sessionOrchestrator = {
       ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
       cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
-      initializeFeatureCluster: vi.fn(async (featureId: string) => {
-        state.sessionsByFeature.set(featureId, {
-          planner: `${featureId}:planner`,
-          builder: `${featureId}:builder`,
-          qa: `${featureId}:qa`,
-        });
-      }),
-      closeFeatureCluster: vi.fn(async (_featureId: string) => undefined),
+      initializeFeatureCluster: vi.fn(async () => undefined),
       reconcileQueuedFeatures: vi.fn(async () => undefined),
       enforceActiveFeatureInvariant: vi.fn(async () => undefined),
     };
@@ -454,31 +637,23 @@ describe('RunCoordinator iteration behavior', () => {
     const planningWaveExecutor = {
       run: vi.fn(async () => undefined),
       runPostQaReconciliation: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
     };
 
     const buildWaveExecutor = {
       run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
     };
 
     const qaWaveExecutor = {
       run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
     };
 
     const leaseHeartbeatService = {
       renew: vi.fn(async () => undefined),
     };
 
-    const workerDecisionRunner = {
-      execute: vi.fn(async () => ({
-        planSubmission: false,
-        patchApplied: false,
-        noteLogged: false,
-        requestHandled: true,
-        priorityOrder: ['feature_b'],
-        toolResults: [],
-      })),
-    };
-
     const coordinator = new RunCoordinator({
       kernel: kernel as never,
       provider: provider as never,
@@ -489,50 +664,32 @@ describe('RunCoordinator iteration behavior', () => {
       buildWaveExecutor: buildWaveExecutor as never,
       qaWaveExecutor: qaWaveExecutor as never,
       leaseHeartbeatService: leaseHeartbeatService as never,
-      maxActiveFeatures: 2,
+      maxActiveFeatures: 1,
       maxParallelGateRuns: 2,
       maxIterationsPerPhase: 1,
       takeoverStaleRun: false,
       providerConfigRefHash: () => 'hash',
-      workerDecisionRunner: workerDecisionRunner as never,
     });
 
-    await coordinator.start([{ feature_id: 'feature_a' }, { feature_id: 'feature_b' }]);
+    await coordinator.start([{ feature_id: 'feature_a' }]);
 
-    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(1, ['feature_b', 'feature_a']);
+    const reconcileCall = toolCaller.callTool.mock.calls.find(
+      ([, toolName]) => toolName === TOOLS.REPO_RECONCILE_MAINLINE,
+    );
+    expect((reconcileCall as unknown[] | undefined)?.[2]).toEqual({
+      feature_id: 'feature_a',
+      auto_merge_non_conflicting: true,
+      commit_message: 'chore: checkpoint feature_a before planning reconciliation',
+    });
+    expect(planningWaveExecutor.run).toHaveBeenCalledWith([]);
   });
-});
 
-describe('RunCoordinator notification and budget branches', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  function makeCoordinatorDeps(
-    opts: {
-      checkBudgetImpl?: () => Promise<{
-        over_budget: boolean;
-        alert_threshold_reached: boolean;
-        current_cost_usd: number;
-        limit_usd: number;
-        alert_threshold: number;
-      }>;
-      toolCallerImpl?: (role: string, toolName: string) => Promise<{ ok: boolean; data: unknown }>;
-      notifier?: { notify: ReturnType<typeof vi.fn> };
-      prMonitor?: { checkAndUpdate: ReturnType<typeof vi.fn> };
-      issueTracker?: {
-        getIssue: ReturnType<typeof vi.fn>;
-        addComment: ReturnType<typeof vi.fn>;
-        updateIssueStatus: ReturnType<typeof vi.fn>;
-      };
-      maxIterationsPerPhase?: number;
-      maxActiveFeatures?: number;
-    } = {},
-  ) {
+  it('GIVEN_terminal_active_feature_WHEN_slots_free_up_THEN_promotes_next_queued_feature_deterministically', async () => {
     const kernel = {
       ensureLoaded: vi.fn(async () => undefined),
       recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
       acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
       pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
       getRuntimeSessions: vi.fn(async () => ({
         run_id: 'run:test',
@@ -540,16 +697,56 @@ describe('RunCoordinator notification and budget branches', () => {
         orchestrator_session_id: 'orch:test',
         feature_sessions: {},
       })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
       updateState: vi.fn(async () => ({})),
-      checkBudget: opts.checkBudgetImpl
-        ? vi.fn(opts.checkBudgetImpl)
-        : vi.fn(async () => ({
-            over_budget: false,
-            alert_threshold_reached: false,
-            current_cost_usd: 0,
-            limit_usd: -1,
-            alert_threshold: 0.8,
-          })),
+      checkBudget: vi.fn(async () => ({
+        over_budget: false,
+        alert_threshold_reached: false,
+        current_cost_usd: 0,
+        limit_usd: -1,
+        alert_threshold: 0.8,
+      })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
+
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+      },
+    };
+
+    const statusReads = new Map<string, string[]>([
+      ['feature_a', ['planning', 'merged']],
+      ['feature_b', ['planning']],
+    ]);
+
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string, args: Record<string, unknown>) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          const featureId = String(args.feature_id);
+          const states = statusReads.get(featureId) ?? ['planning'];
+          const status = states.shift() ?? states.at(-1) ?? 'planning';
+          statusReads.set(featureId, states.length === 0 ? [status] : states);
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      }),
     };
 
     const state = {
@@ -561,22 +758,19 @@ describe('RunCoordinator notification and budget branches', () => {
       runMetadata: {},
     };
 
-    const defaultToolCallerImpl = async (_role: string, toolName: string) => {
-      if (toolName === TOOLS.REPORT_DASHBOARD) {
-        return { ok: true, data: { features: [] } };
-      }
-      return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
-    };
-
-    const toolCaller = {
-      callTool: opts.toolCallerImpl ? vi.fn(opts.toolCallerImpl) : vi.fn(defaultToolCallerImpl),
-    };
-
     const sessionOrchestrator = {
       ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
       cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
-      initializeFeatureCluster: vi.fn(async () => undefined),
-      closeFeatureCluster: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async (featureId: string) => {
+        state.sessionsByFeature.set(featureId, {
+          planner: `${featureId}:planner`,
+          builder: `${featureId}:builder`,
+          qa: `${featureId}:qa`,
+        });
+      }),
+      closeFeatureCluster: vi.fn(async (featureId: string) => {
+        state.sessionsByFeature.delete(featureId);
+      }),
       reconcileQueuedFeatures: vi.fn(async () => undefined),
       enforceActiveFeatureInvariant: vi.fn(async () => undefined),
     };
@@ -584,11 +778,22 @@ describe('RunCoordinator notification and budget branches', () => {
     const planningWaveExecutor = {
       run: vi.fn(async () => undefined),
       runPostQaReconciliation: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+
+    const buildWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+
+    const qaWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+
+    const leaseHeartbeatService = {
+      renew: vi.fn(async () => undefined),
     };
-    const buildWaveExecutor = { run: vi.fn(async () => undefined) };
-    const qaWaveExecutor = { run: vi.fn(async () => undefined) };
-    const leaseHeartbeatService = { renew: vi.fn(async () => undefined) };
-    const provider = { selection: { provider: 'test', model: 'test-model' } };
 
     const coordinator = new RunCoordinator({
       kernel: kernel as never,
@@ -600,110 +805,1145 @@ describe('RunCoordinator notification and budget branches', () => {
       buildWaveExecutor: buildWaveExecutor as never,
       qaWaveExecutor: qaWaveExecutor as never,
       leaseHeartbeatService: leaseHeartbeatService as never,
-      maxActiveFeatures: opts.maxActiveFeatures ?? 5,
+      maxActiveFeatures: 1,
       maxParallelGateRuns: 2,
-      maxIterationsPerPhase: opts.maxIterationsPerPhase ?? 1,
+      maxIterationsPerPhase: 2,
       takeoverStaleRun: false,
       providerConfigRefHash: () => 'hash',
-      notifier: opts.notifier as never,
-      prMonitor: opts.prMonitor as never,
-      issueTracker: opts.issueTracker as never,
-    });
-
-    return { coordinator, kernel, toolCaller, sessionOrchestrator };
-  }
-
-  it('GIVEN_over_budget_feature_WHEN_pauseOverBudgetFeatures_runs_THEN_feature_removed_and_state_updated', async () => {
-    const { coordinator, kernel, sessionOrchestrator } = makeCoordinatorDeps({
-      checkBudgetImpl: async () => ({
-        over_budget: true,
-        alert_threshold_reached: false,
-        current_cost_usd: 5.5,
-        limit_usd: 5.0,
-        alert_threshold: 0.8,
-      }),
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    const result = await coordinator.start([
+      { feature_id: 'feature_a' },
+      { feature_id: 'feature_b' },
+    ]);
 
-    expect(kernel.updateState).toHaveBeenCalledWith('feature_x', null, expect.any(Function));
-    const updateStateCall = kernel.updateState.mock.calls[0] as unknown[] | undefined;
-    expect(updateStateCall).toBeDefined();
-    const callbackArg = updateStateCall?.[2] as
-      | ((fm: object) => Promise<{ frontMatter: { status: string } }>)
-      | undefined;
-    expect(callbackArg).toBeDefined();
-    if (callbackArg == null) {
-      throw new Error('missing updateState callback');
-    }
-    const result = await callbackArg({});
-    expect(result.frontMatter.status).toBe(STATUS.PAUSED_BUDGET);
-    expect(sessionOrchestrator.closeFeatureCluster).toHaveBeenCalledWith('feature_x');
+    expect(result.queue_depth).toBe(0);
+    expect(sessionOrchestrator.initializeFeatureCluster).toHaveBeenNthCalledWith(1, 'feature_a');
+    expect(sessionOrchestrator.closeFeatureCluster).toHaveBeenCalledWith('feature_a');
+    expect(planningWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
+    expect(buildWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
+    expect(qaWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feature_a');
+    expect(sessionOrchestrator.initializeFeatureCluster).toHaveBeenNthCalledWith(2, 'feature_b');
+    expect(planningWaveExecutor.run).toHaveBeenCalledTimes(2);
+    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(1, ['feature_b']);
+    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(2, ['feature_b']);
   });
 
-  it('GIVEN_over_budget_feature_with_notifier_WHEN_pauseOverBudgetFeatures_runs_THEN_notifies_budget_exceeded', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    const { coordinator } = makeCoordinatorDeps({
-      checkBudgetImpl: async () => ({
-        over_budget: true,
+  it('GIVEN_orchestrator_priority_request_WHEN_running_iteration_THEN_reorders_active_feature_execution', async () => {
+    const kernel = {
+      ensureLoaded: vi.fn(async () => undefined),
+      recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
+      acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        orchestrator_session_id: 'orch:test',
+        feature_sessions: {},
+      })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
+      updateState: vi.fn(async () => ({})),
+      checkBudget: vi.fn(async () => ({
+        over_budget: false,
         alert_threshold_reached: false,
-        current_cost_usd: 5.5,
-        limit_usd: 5.0,
+        current_cost_usd: 0,
+        limit_usd: -1,
         alert_threshold: 0.8,
-      }),
-      notifier,
-    });
-
-    await coordinator.start([{ feature_id: 'feature_x' }]);
-
-    expect(notifier.notify).toHaveBeenCalledWith(
-      'budget_exceeded',
-      expect.objectContaining({ feature_id: 'feature_x' }),
-    );
-  });
-
-  it('GIVEN_alert_threshold_reached_WHEN_pauseOverBudgetFeatures_runs_THEN_notifies_budget_alert', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    const { coordinator } = makeCoordinatorDeps({
-      checkBudgetImpl: async () => ({
-        over_budget: false,
-        alert_threshold_reached: true,
-        current_cost_usd: 4.5,
-        limit_usd: 5.0,
-        alert_threshold: 0.9,
-      }),
-      notifier,
-    });
-
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+      })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
 
-    expect(notifier.notify).toHaveBeenCalledWith(
-      'budget_alert',
-      expect.objectContaining({ feature_id: 'feature_x' }),
-    );
-  });
+    const provider = {
+      selection: {
+        provider: 'custom',
+        model: 'model-test',
+      },
+    };
 
-  it('GIVEN_feature_transitions_to_BLOCKED_from_PLANNING_WHEN_notifyStatusTransitions_THEN_notifies_collision_detected', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    let callCount = 0;
-    const { coordinator } = makeCoordinatorDeps({
-      // calls: 1=init_rebalance, 2=iter1_notify, 3=iter1_rebalance, 4=iter2_notify, 5=iter2_rebalance
-      toolCallerImpl: async (_role, toolName) => {
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string, _args: Record<string, unknown>) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          callCount += 1;
-          const status = callCount <= 3 ? STATUS.PLANNING : STATUS.BLOCKED;
-          return { ok: true, data: { front_matter: { status } } };
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: 'planning',
+              },
+            },
+          };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
         }
         return { ok: true, data: {} };
-      },
-      notifier,
-      maxIterationsPerPhase: 2,
-    });
-
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+      }),
+    };
+
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+
+    const sessionOrchestrator = {
+      ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+      cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async (featureId: string) => {
+        state.sessionsByFeature.set(featureId, {
+          planner: `${featureId}:planner`,
+          builder: `${featureId}:builder`,
+          qa: `${featureId}:qa`,
+        });
+      }),
+      closeFeatureCluster: vi.fn(async (_featureId: string) => undefined),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+    };
+
+    const planningWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      runPostQaReconciliation: vi.fn(async () => undefined),
+    };
+
+    const buildWaveExecutor = {
+      run: vi.fn(async () => undefined),
+    };
+
+    const qaWaveExecutor = {
+      run: vi.fn(async () => undefined),
+    };
+
+    const leaseHeartbeatService = {
+      renew: vi.fn(async () => undefined),
+    };
+
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: true,
+        priorityOrder: ['feature_b'],
+        toolResults: [],
+      })),
+    };
+
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: provider as never,
+      toolCaller: toolCaller as never,
+      state: state as never,
+      sessionOrchestrator: sessionOrchestrator as never,
+      planningWaveExecutor: planningWaveExecutor as never,
+      buildWaveExecutor: buildWaveExecutor as never,
+      qaWaveExecutor: qaWaveExecutor as never,
+      leaseHeartbeatService: leaseHeartbeatService as never,
+      maxActiveFeatures: 2,
+      maxParallelGateRuns: 2,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      workerDecisionRunner: workerDecisionRunner as never,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_a' }, { feature_id: 'feature_b' }]);
+
+    expect(planningWaveExecutor.run).toHaveBeenNthCalledWith(1, ['feature_b', 'feature_a']);
+  });
+});
+
+describe('RunCoordinator enrollment checkpoints', () => {
+  it('runs a planning mini-pass when planning work is admitted during the build cursor', async () => {
+    const kernel = {
+      getRuntimeSessions: vi.fn(async () => ({
+        feature_sessions: {},
+      })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+      updateExecutionRequestProgress: vi.fn(async () => ({
+        data: { updated: true, progress: null },
+      })),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+    };
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>([
+        ['feature_build', { planner: 'planner:build', builder: 'builder:build', qa: 'qa:build' }],
+      ]),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const planningWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      runPostQaReconciliation: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+    const buildWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+    const qaWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      clearFeatureTracking: vi.fn(),
+    };
+    const sessionOrchestrator = {
+      closeFeatureCluster: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async (featureId: string) => {
+        state.sessionsByFeature.set(featureId, {
+          planner: `${featureId}:planner`,
+          builder: `${featureId}:builder`,
+          qa: `${featureId}:qa`,
+        });
+      }),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+    };
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string, args?: { feature_id?: string }) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          const featureId = args?.feature_id;
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: featureId === 'feature_planning' ? STATUS.PLANNING : STATUS.BUILDING,
+                version: 1,
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      }),
+    };
+    const executionEnrollmentService = {
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(async () => undefined),
+      notifyNewRequestHint: vi.fn(async () => undefined),
+      noteSafeCheckpoint: vi.fn(async () => undefined),
+      hasPendingWork: vi.fn(() => true),
+      drainReadyDecisions: vi
+        .fn()
+        .mockResolvedValueOnce([
+          {
+            request: {
+              request_id: 'exec_req_001',
+              request_type: 'add_features',
+              status: 'pending',
+              requested_at: new Date(0).toISOString(),
+              processed_at: null,
+              requested_by: 'cli:add',
+              operation_id: 'op:add:feature_planning',
+              features: [
+                {
+                  feature_id: 'feature_planning',
+                  spec_path: '.aop/features/feature_planning/spec.md',
+                },
+              ],
+              progress: {
+                detected_at: new Date(0).toISOString(),
+                last_evaluated_at: new Date(0).toISOString(),
+                queued: [],
+                skipped: [],
+                deferred: [],
+              },
+              outcome: null,
+            },
+            decisions: [
+              {
+                request_id: 'exec_req_001',
+                feature_id: 'feature_planning',
+                disposition: 'queue_now',
+                reason: 'capacity_available',
+              },
+            ],
+            progress: {
+              detected_at: new Date(0).toISOString(),
+              last_evaluated_at: new Date(0).toISOString(),
+              queued: [],
+              skipped: [],
+              deferred: [],
+            },
+          },
+        ])
+        .mockResolvedValue([]),
+    };
+
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: { selection: { provider: 'custom', model: 'test-model' } } as never,
+      toolCaller: toolCaller as never,
+      state: state as never,
+      sessionOrchestrator: sessionOrchestrator as never,
+      planningWaveExecutor: planningWaveExecutor as never,
+      buildWaveExecutor: buildWaveExecutor as never,
+      qaWaveExecutor: qaWaveExecutor as never,
+      leaseHeartbeatService: { renew: vi.fn(async () => undefined) } as never,
+      maxActiveFeatures: 2,
+      maxParallelGateRuns: 1,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      executionEnrollmentService: executionEnrollmentService as never,
+    });
+
+    (
+      coordinator as unknown as {
+        currentActiveFeatureIds: string[];
+        currentPhaseCursor: 'building';
+      }
+    ).currentActiveFeatureIds = ['feature_build'];
+    (
+      coordinator as unknown as {
+        currentActiveFeatureIds: string[];
+        currentPhaseCursor: 'building';
+      }
+    ).currentPhaseCursor = 'building';
+
+    await coordinator.handleSafeCheckpoint();
+
+    expect(sessionOrchestrator.initializeFeatureCluster).toHaveBeenCalledWith('feature_planning');
+    expect(planningWaveExecutor.run).toHaveBeenCalledWith(['feature_build', 'feature_planning']);
+    expect(buildWaveExecutor.run).not.toHaveBeenCalled();
+    expect(qaWaveExecutor.run).not.toHaveBeenCalled();
+    expect(kernel.markExecutionRequestProcessed).toHaveBeenCalledWith(
+      'run:test',
+      'owner:test',
+      'exec_req_001',
+      'applied',
+      {
+        queued: ['feature_planning'],
+        skipped: [],
+      },
+    );
+  });
+
+  it('skips safe checkpoints when enrollment has no pending work', async () => {
+    const executionEnrollmentService = {
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(async () => undefined),
+      notifyNewRequestHint: vi.fn(async () => undefined),
+      noteSafeCheckpoint: vi.fn(async () => undefined),
+      hasPendingWork: vi.fn(() => false),
+      drainReadyDecisions: vi.fn(async () => []),
+    };
+
+    const coordinator = new RunCoordinator({
+      kernel: {
+        getRuntimeSessions: vi.fn(async () => ({ feature_sessions: {} })),
+        pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+      } as never,
+      provider: { selection: { provider: 'custom', model: 'test-model' } } as never,
+      toolCaller: { callTool: vi.fn(async () => ({ ok: true, data: {} })) } as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      } as never,
+      sessionOrchestrator: {
+        reconcileQueuedFeatures: vi.fn(async () => undefined),
+        enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+      } as never,
+      planningWaveExecutor: { run: vi.fn(async () => undefined) } as never,
+      buildWaveExecutor: { run: vi.fn(async () => undefined) } as never,
+      qaWaveExecutor: { run: vi.fn(async () => undefined) } as never,
+      leaseHeartbeatService: { renew: vi.fn(async () => undefined) } as never,
+      maxActiveFeatures: 1,
+      maxParallelGateRuns: 1,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      executionEnrollmentService: executionEnrollmentService as never,
+    });
+
+    await coordinator.handleSafeCheckpoint();
+
+    expect(executionEnrollmentService.noteSafeCheckpoint).not.toHaveBeenCalled();
+    expect(executionEnrollmentService.drainReadyDecisions).not.toHaveBeenCalled();
+  });
+});
+
+describe('RunCoordinator helpers', () => {
+  const baseDeps = () => {
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
+        }
+        return { ok: true, data: {} };
+      }),
+    };
+
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+
+    const sessionOrchestrator = {
+      closeFeatureCluster: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async () => undefined),
+    };
+
+    const kernel = {
+      ensureLoaded: vi.fn(async () => undefined),
+      recoverFromState: vi.fn(async () => undefined),
+      acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({})),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({})),
+      getRuntimeSessions: vi.fn(async () => ({})),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
+      checkBudget: vi.fn(async () => ({
+        over_budget: false,
+        alert_threshold_reached: false,
+        current_cost_usd: 1,
+        limit_usd: 10,
+        alert_threshold: 0.8,
+      })),
+      updateState: vi.fn(async () => ({})),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
+
+    const noopWave = { run: vi.fn(async () => undefined), clearFeatureTracking: vi.fn() };
+    const planningWaveExecutor = {
+      ...noopWave,
+      runPostQaReconciliation: vi.fn(async () => undefined),
+    };
+    const buildWaveExecutor = { ...noopWave };
+    const qaWaveExecutor = { ...noopWave };
+    const leaseHeartbeatService = { renew: vi.fn(async () => undefined) };
+
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: { selection: { provider: 'p', model: 'm' } } as never,
+      toolCaller: toolCaller as never,
+      state: state as never,
+      sessionOrchestrator: sessionOrchestrator as never,
+      planningWaveExecutor: planningWaveExecutor as never,
+      buildWaveExecutor: buildWaveExecutor as never,
+      qaWaveExecutor: qaWaveExecutor as never,
+      leaseHeartbeatService: leaseHeartbeatService as never,
+      maxActiveFeatures: 2,
+      maxParallelGateRuns: 1,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      notifier: { notify: vi.fn(async () => undefined) } as never,
+      prMonitor: {
+        checkAndUpdate: vi.fn(async () => undefined),
+      } as never,
+      issueTracker: {
+        addComment: vi.fn(async () => undefined),
+        updateIssueStatus: vi.fn(async () => undefined),
+        getIssue: vi.fn(async () => ({
+          id: '123',
+          title: 'title',
+          body: '',
+          status: 'open',
+          url: 'u',
+        })),
+      } as never,
+      workerDecisionRunner: {
+        execute: vi.fn(async () => ({ priorityOrder: ['b', 'a'] })),
+      } as never,
+    });
+
+    return {
+      coordinator,
+      kernel,
+      toolCaller,
+      sessionOrchestrator,
+      state,
+      planningWaveExecutor,
+      buildWaveExecutor,
+      qaWaveExecutor,
+    } as const;
+  };
+
+  it('GIVEN_over_budget_and_alert_features_WHEN_pausing_THEN_notifies_and_removes_over_budget', async () => {
+    const { coordinator, kernel, sessionOrchestrator } = baseDeps();
+    vi.mocked(kernel.checkBudget).mockResolvedValueOnce({
+      over_budget: true,
+      alert_threshold_reached: false,
+      current_cost_usd: 11,
+      limit_usd: 10,
+      alert_threshold: 0.8,
+    } as any);
+    vi.mocked(kernel.checkBudget).mockResolvedValueOnce({
+      over_budget: false,
+      alert_threshold_reached: true,
+      current_cost_usd: 8,
+      limit_usd: 10,
+      alert_threshold: 0.8,
+    } as any);
+
+    const remaining = await (coordinator as any).pauseOverBudgetFeatures(['over', 'warn']);
+
+    expect(remaining).toEqual(['warn']);
+    expect(sessionOrchestrator.closeFeatureCluster).toHaveBeenCalledWith('over');
+    expect(kernel.updateState).toHaveBeenCalledWith('over', null, expect.any(Function));
+  });
+
+  it('GIVEN_worker_priority_order_WHEN_apply_prioritization_THEN_reorders_active_features', async () => {
+    const { coordinator } = baseDeps();
+
+    const reordered = await (coordinator as any).applyOrchestratorPrioritization(
+      ['a', 'b', 'c'],
+      1,
+    );
+
+    expect(reordered).toEqual(['b', 'a', 'c']);
+  });
+
+  it('GIVEN_status_changes_WHEN_notifyStatusTransitions_THEN_triggers_notifier_and_issue_tracker', async () => {
+    const { coordinator, toolCaller } = baseDeps();
+    vi.mocked(toolCaller.callTool).mockImplementation(async (_role: string, toolName: string) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return {
+          ok: true,
+          data: {
+            front_matter: {
+              status: STATUS.READY_TO_MERGE,
+              gates: { fast: 'pass', full: 'pass' },
+              version: 3,
+              worktree_branch: 'feat/123',
+              pr: {},
+            },
+          },
+        } as any;
+      }
+      return { ok: true, data: {} } as any;
+    });
+
+    await (coordinator as any).notifyStatusTransitions(['feature_notify']);
+
+    const prMonitor = (coordinator as any).prMonitor;
+    const notifier = (coordinator as any).notifier;
+    const issueTracker = (coordinator as any).issueTracker;
+
+    expect(notifier.notify).toHaveBeenCalledWith('ready_to_merge', expect.any(Object));
+    expect(prMonitor.checkAndUpdate).toHaveBeenCalledWith('feature_notify', 'feat/123');
+    expect(issueTracker.addComment).toHaveBeenCalled();
+    expect(issueTracker.updateIssueStatus).toHaveBeenCalledWith('notify', STATUS.READY_TO_MERGE);
+  });
+
+  it('GIVEN_feature_tracking_WHEN_clearWaveTracking_called_THEN_invokes_executor_clear_methods', () => {
+    const { coordinator, planningWaveExecutor, buildWaveExecutor, qaWaveExecutor } = baseDeps();
+
+    (coordinator as any).clearWaveTracking('feat_clear');
+
+    expect(planningWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feat_clear');
+    expect(buildWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feat_clear');
+    expect(qaWaveExecutor.clearFeatureTracking).toHaveBeenCalledWith('feat_clear');
+  });
+
+  it('GIVEN_tool_call_failure_WHEN_readFeatureStateSnapshot_runs_THEN_returns_null_status', async () => {
+    const { coordinator } = baseDeps();
+    vi.spyOn(coordinator as any, 'toolCaller', 'get').mockReturnValue({
+      callTool: vi.fn(async () => {
+        throw new Error('fail');
+      }),
+    });
+
+    const snapshot = await (coordinator as any).readFeatureStateSnapshot('feat_missing');
+    expect(snapshot).toEqual({
+      status: null,
+      statusReason: null,
+      branch: 'feat_missing',
+      hasPr: false,
+    });
+  });
+
+  it('GIVEN_multiple_scoped_features_WHEN_rebalanceActiveFeatures_runs_THEN_sorts_with_comparator', async () => {
+    const { coordinator, state, kernel, sessionOrchestrator } = baseDeps();
+    state.queue = [{ feature_id: 'b' }, { feature_id: 'a' }];
+    vi.mocked(kernel.checkBudget).mockResolvedValue({
+      over_budget: false,
+      alert_threshold_reached: false,
+      current_cost_usd: 1,
+      limit_usd: 10,
+      alert_threshold: 0.8,
+    } as any);
+    vi.mocked(sessionOrchestrator.initializeFeatureCluster).mockResolvedValue();
+
+    const result = await (coordinator as any).rebalanceActiveFeatures([]);
+    expect(result).toEqual(['a', 'b']);
+  });
+
+  it('GIVEN_background_renewal_WHEN_error_occurs_THEN_throwIfBackgroundLeaseRenewalFailed_throws', async () => {
+    vi.useFakeTimers();
+    const { coordinator } = baseDeps();
+    (coordinator as any).leaseHeartbeatService.renew = vi.fn(async () => {
+      throw new Error('lease-fail');
+    });
+
+    const originalInterval = (RunCoordinator as any).BACKGROUND_LEASE_RENEW_INTERVAL_MS;
+    (RunCoordinator as any).BACKGROUND_LEASE_RENEW_INTERVAL_MS = 1;
+
+    const background = (coordinator as any).startBackgroundLeaseRenewal();
+    await vi.advanceTimersByTimeAsync(2);
+    expect(background.error()).toBeInstanceOf(Error);
+    await background.stop();
+    expect(() =>
+      (coordinator as any).throwIfBackgroundLeaseRenewalFailed(background.error()),
+    ).toThrow('lease-fail');
+    (RunCoordinator as any).BACKGROUND_LEASE_RENEW_INTERVAL_MS = originalInterval;
+    vi.useRealTimers();
+  });
+
+  it('GIVEN_static_asRecord_WHEN_non_object_passed_THEN_returns_empty_object', () => {
+    const result = (RunCoordinator as any).asRecord(null);
+    expect(result).toEqual({});
+  });
+
+  it('GIVEN_feature_status_lookup_WHEN_readFeatureStatus_called_THEN_returns_status_or_null', async () => {
+    const { coordinator, toolCaller } = baseDeps();
+    vi.mocked(toolCaller.callTool).mockRejectedValueOnce(new Error('fail'));
+    const nullStatus = await (coordinator as any).readFeatureStatus('missing');
+    expect(nullStatus).toBeNull();
+
+    vi.mocked(toolCaller.callTool).mockResolvedValue({
+      ok: true,
+      data: { front_matter: { status: STATUS.BUILDING } },
+    } as any);
+    const status = await (coordinator as any).readFeatureStatus('feat');
+    expect(status).toBe(STATUS.BUILDING);
+  });
+
+  it('GIVEN_issue_tracker_errors_WHEN_syncIssueTrackerStatus_runs_THEN_catches_failures', async () => {
+    const { coordinator } = baseDeps();
+    (coordinator as any).issueTracker = {
+      getIssue: vi.fn(async () => {
+        throw new Error('fail');
+      }),
+      addComment: vi.fn(async () => {
+        throw new Error('comment-fail');
+      }),
+      updateIssueStatus: vi.fn(async () => {
+        throw new Error('status-fail');
+      }),
+    };
+
+    await (coordinator as any).syncIssueTrackerStatus('feature_issue', STATUS.PLANNING, undefined);
+    expect((coordinator as any).issueTracker.getIssue).toHaveBeenCalled();
+    expect((coordinator as any).issueTracker.addComment).toHaveBeenCalled();
+    expect((coordinator as any).issueTracker.updateIssueStatus).toHaveBeenCalled();
+  });
+
+  it('GIVEN_queue_entries_WHEN_applyOrchestratorPrioritization_runs_THEN_maps_queue_and_sorts_remaining', async () => {
+    const { coordinator, state } = baseDeps();
+    state.queue = [{ feature_id: 'z' }, { feature_id: 'y' }];
+    const result = await (coordinator as any).applyOrchestratorPrioritization(['x', 'y', 'z'], 2);
+    expect(result.slice(-2)).toEqual(['y', 'z']);
+  });
+
+  it('GIVEN_enrollment_batch_with_races_and_deferred_work_WHEN_applying_THEN_updates_progress_instead_of_marking_processed', async () => {
+    const { coordinator, kernel, state } = baseDeps();
+    (kernel as any).updateExecutionRequestProgress = vi.fn(async () => ({
+      data: { updated: true },
+    }));
+    state.sessionsByFeature.set('feature_active', {
+      planner: 'planner:active',
+      builder: 'builder:active',
+      qa: 'qa:active',
+    });
+    state.queue = [{ feature_id: 'feature_queued' }];
+    vi.mocked(kernel.getRuntimeSessions).mockResolvedValue({
+      feature_sessions: {
+        feature_assigned: {
+          planner_session_id: 'planner:assigned',
+          builder_session_id: 'builder:assigned',
+          qa_session_id: 'qa:assigned',
+        },
+      },
+    } as any);
+    const readFeatureStatusMock = (featureId: string): Promise<string> =>
+      Promise.resolve(featureId === 'feature_terminal' ? STATUS.MERGED : STATUS.PLANNING);
+    (coordinator as any).readFeatureStatus = readFeatureStatusMock;
+
+    const queued = await (coordinator as any).applyEnrollmentDecisionBatch({
+      request: {
+        request_id: 'exec_req_002',
+        request_type: 'add_features',
+        status: 'pending',
+        requested_at: new Date(0).toISOString(),
+        processed_at: null,
+        requested_by: 'cli:add',
+        operation_id: 'op:add:mixed',
+        features: [
+          { feature_id: 'feature_active', spec_path: '.aop/features/feature_active/spec.md' },
+          { feature_id: 'feature_queued', spec_path: '.aop/features/feature_queued/spec.md' },
+          { feature_id: 'feature_assigned', spec_path: '.aop/features/feature_assigned/spec.md' },
+          { feature_id: 'feature_terminal', spec_path: '.aop/features/feature_terminal/spec.md' },
+        ],
+        progress: null,
+        outcome: null,
+      },
+      decisions: [
+        {
+          request_id: 'exec_req_002',
+          feature_id: 'feature_active',
+          disposition: 'queue_now',
+          reason: 'capacity_available',
+        },
+        {
+          request_id: 'exec_req_002',
+          feature_id: 'feature_queued',
+          disposition: 'queue_now',
+          reason: 'capacity_available',
+        },
+        {
+          request_id: 'exec_req_002',
+          feature_id: 'feature_assigned',
+          disposition: 'queue_now',
+          reason: 'capacity_available',
+        },
+        {
+          request_id: 'exec_req_002',
+          feature_id: 'feature_terminal',
+          disposition: 'queue_now',
+          reason: 'capacity_available',
+        },
+      ],
+      progress: {
+        detected_at: '2026-03-16T00:00:00.000Z',
+        last_evaluated_at: '2026-03-16T00:00:01.000Z',
+        queued: [],
+        skipped: [],
+        deferred: [{ feature_id: 'feature_waiting', reason: 'capacity_full' }],
+      },
+    });
+
+    expect(queued).toEqual([]);
+    expect((kernel as any).updateExecutionRequestProgress).toHaveBeenCalledWith(
+      'run:test',
+      'owner:test',
+      'exec_req_002',
+      expect.objectContaining({
+        skipped: [
+          { feature_id: 'feature_active', reason: 'already_active' },
+          { feature_id: 'feature_assigned', reason: 'already_assigned_cluster' },
+          { feature_id: 'feature_queued', reason: 'already_queued' },
+          { feature_id: 'feature_terminal', reason: 'terminal_status' },
+        ],
+        deferred: [{ feature_id: 'feature_waiting', reason: 'capacity_full' }],
+      }),
+    );
+    expect(kernel.markExecutionRequestProcessed).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_forced_build_and_qa_phases_WHEN_running_checkpoint_mini_pass_THEN_dispatches_the_matching_wave', async () => {
+    const planningRun = vi.fn(async () => undefined);
+    const buildRun = vi.fn(async () => undefined);
+    const qaRun = vi.fn(async () => undefined);
+    const coordinator = new RunCoordinator({
+      kernel: {
+        ensureLoaded: vi.fn(async () => undefined),
+        recoverFromState: vi.fn(async () => undefined),
+        acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+        releaseRunLease: vi.fn(async () => ({})),
+        pruneFeatureSessionAssignments: vi.fn(async () => ({})),
+        getRuntimeSessions: vi.fn(async () => ({})),
+        getPolicySnapshot: vi.fn(() => ({
+          reactions: {
+            gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+          },
+        })),
+        checkBudget: vi.fn(async () => ({
+          over_budget: false,
+          alert_threshold_reached: false,
+          current_cost_usd: 0,
+          limit_usd: -1,
+          alert_threshold: 0.8,
+        })),
+        updateState: vi.fn(async () => ({})),
+        drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+        markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+      } as never,
+      provider: { selection: { provider: 'p', model: 'm' } } as never,
+      toolCaller: { callTool: vi.fn(async () => ({ ok: true, data: {} })) } as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+        queue: [] as Array<{ feature_id: string }>,
+        runMetadata: {},
+      } as never,
+      sessionOrchestrator: {
+        closeFeatureCluster: vi.fn(async () => undefined),
+        enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+        reconcileQueuedFeatures: vi.fn(async () => undefined),
+        initializeFeatureCluster: vi.fn(async () => undefined),
+      } as never,
+      planningWaveExecutor: {
+        run: planningRun,
+        runPostQaReconciliation: vi.fn(async () => undefined),
+        clearFeatureTracking: vi.fn(),
+      } as never,
+      buildWaveExecutor: { run: buildRun, clearFeatureTracking: vi.fn() } as never,
+      qaWaveExecutor: { run: qaRun, clearFeatureTracking: vi.fn() } as never,
+      leaseHeartbeatService: { renew: vi.fn(async () => undefined) } as never,
+      maxActiveFeatures: 2,
+      maxParallelGateRuns: 1,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+    });
+    (coordinator as any).currentActiveFeatureIds = ['feature_a', 'feature_b'];
+
+    vi.spyOn(coordinator as any, 'resolveCheckpointMiniPassPhase').mockResolvedValueOnce(
+      'building',
+    );
+    await (coordinator as any).runCheckpointMiniPass(['feature_a']);
+
+    vi.spyOn(coordinator as any, 'resolveCheckpointMiniPassPhase').mockResolvedValueOnce('qa');
+    await (coordinator as any).runCheckpointMiniPass(['feature_b']);
+
+    vi.spyOn(coordinator as any, 'resolveCheckpointMiniPassPhase').mockResolvedValueOnce(null);
+    await (coordinator as any).runCheckpointMiniPass(['feature_c']);
+
+    expect(planningRun).not.toHaveBeenCalled();
+    expect(buildRun).toHaveBeenCalledWith(['feature_a', 'feature_b'], 1);
+    expect(qaRun).toHaveBeenCalledWith(['feature_a', 'feature_b'], 1);
+  });
+});
+
+describe('RunCoordinator notification and budget branches', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function makeCoordinatorDeps(
+    opts: {
+      checkBudgetImpl?: () => Promise<{
+        over_budget: boolean;
+        alert_threshold_reached: boolean;
+        current_cost_usd: number;
+        limit_usd: number;
+        alert_threshold: number;
+      }>;
+      toolCallerImpl?: (
+        role: string,
+        toolName: string,
+        args?: Record<string, unknown>,
+      ) => Promise<{ ok: boolean; data: unknown }>;
+      notifier?: { notify: ReturnType<typeof vi.fn> };
+      prMonitor?: { checkAndUpdate: ReturnType<typeof vi.fn> };
+      issueTracker?: {
+        getIssue: ReturnType<typeof vi.fn>;
+        addComment: ReturnType<typeof vi.fn>;
+        updateIssueStatus: ReturnType<typeof vi.fn>;
+      };
+      policySnapshot?: Record<string, unknown>;
+      maxIterationsPerPhase?: number;
+      maxActiveFeatures?: number;
+      executionEnrollmentService?: {
+        start: ReturnType<typeof vi.fn>;
+        stop: ReturnType<typeof vi.fn>;
+        notifyNewRequestHint: ReturnType<typeof vi.fn>;
+        noteSafeCheckpoint: ReturnType<typeof vi.fn>;
+        hasPendingWork: ReturnType<typeof vi.fn>;
+        drainReadyDecisions: ReturnType<typeof vi.fn>;
+      };
+    } = {},
+  ) {
+    const kernel = {
+      ensureLoaded: vi.fn(async () => undefined),
+      recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
+      acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        orchestrator_session_id: 'orch:test',
+        feature_sessions: {},
+      })),
+      getPolicySnapshot: vi.fn(
+        () =>
+          opts.policySnapshot ?? {
+            reactions: {
+              gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+            },
+          },
+      ),
+      updateState: vi.fn(async () => ({})),
+      checkBudget: opts.checkBudgetImpl
+        ? vi.fn(opts.checkBudgetImpl)
+        : vi.fn(async () => ({
+            over_budget: false,
+            alert_threshold_reached: false,
+            current_cost_usd: 0,
+            limit_usd: -1,
+            alert_threshold: 0.8,
+          })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
+
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+
+    const defaultToolCallerImpl = async (
+      _role: string,
+      toolName: string,
+      _args?: Record<string, unknown>,
+    ) => {
+      if (toolName === TOOLS.REPORT_DASHBOARD) {
+        return { ok: true, data: { features: [] } };
+      }
+      return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
+    };
+
+    const toolCaller = {
+      callTool: opts.toolCallerImpl ? vi.fn(opts.toolCallerImpl) : vi.fn(defaultToolCallerImpl),
+    };
+
+    const sessionOrchestrator = {
+      ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+      cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async () => undefined),
+      closeFeatureCluster: vi.fn(async () => undefined),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+    };
+
+    const planningWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      runPostQaReconciliation: vi.fn(async () => undefined),
+    };
+    const buildWaveExecutor = { run: vi.fn(async () => undefined) };
+    const qaWaveExecutor = { run: vi.fn(async () => undefined) };
+    const leaseHeartbeatService = { renew: vi.fn(async () => undefined) };
+    const provider = { selection: { provider: 'test', model: 'test-model' } };
+
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: provider as never,
+      toolCaller: toolCaller as never,
+      state: state as never,
+      sessionOrchestrator: sessionOrchestrator as never,
+      planningWaveExecutor: planningWaveExecutor as never,
+      buildWaveExecutor: buildWaveExecutor as never,
+      qaWaveExecutor: qaWaveExecutor as never,
+      leaseHeartbeatService: leaseHeartbeatService as never,
+      maxActiveFeatures: opts.maxActiveFeatures ?? 5,
+      maxParallelGateRuns: 2,
+      maxIterationsPerPhase: opts.maxIterationsPerPhase ?? 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      notifier: opts.notifier as never,
+      prMonitor: opts.prMonitor as never,
+      issueTracker: opts.issueTracker as never,
+      executionEnrollmentService: opts.executionEnrollmentService as never,
+    });
+
+    return {
+      coordinator,
+      kernel,
+      toolCaller,
+      sessionOrchestrator,
+      planningWaveExecutor,
+      buildWaveExecutor,
+      qaWaveExecutor,
+    };
+  }
+
+  it('GIVEN_over_budget_feature_WHEN_pauseOverBudgetFeatures_runs_THEN_feature_removed_and_state_updated', async () => {
+    const { coordinator, kernel, sessionOrchestrator } = makeCoordinatorDeps({
+      checkBudgetImpl: async () => ({
+        over_budget: true,
+        alert_threshold_reached: false,
+        current_cost_usd: 5.5,
+        limit_usd: 5.0,
+        alert_threshold: 0.8,
+      }),
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(kernel.updateState).toHaveBeenCalledWith('feature_x', null, expect.any(Function));
+    const updateStateCall = kernel.updateState.mock.calls[0] as unknown[] | undefined;
+    expect(updateStateCall).toBeDefined();
+    const callbackArg = updateStateCall?.[2] as
+      | ((fm: object) => Promise<{ frontMatter: { status: string } }>)
+      | undefined;
+    expect(callbackArg).toBeDefined();
+    if (callbackArg == null) {
+      throw new Error('missing updateState callback');
+    }
+    const result = await callbackArg({});
+    expect(result.frontMatter.status).toBe(STATUS.PAUSED_BUDGET);
+    expect(sessionOrchestrator.closeFeatureCluster).toHaveBeenCalledWith('feature_x');
+  });
+
+  it('GIVEN_over_budget_feature_with_notifier_WHEN_pauseOverBudgetFeatures_runs_THEN_notifies_budget_exceeded', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    const { coordinator } = makeCoordinatorDeps({
+      checkBudgetImpl: async () => ({
+        over_budget: true,
+        alert_threshold_reached: false,
+        current_cost_usd: 5.5,
+        limit_usd: 5.0,
+        alert_threshold: 0.8,
+      }),
+      notifier,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'budget_exceeded',
+      expect.objectContaining({ feature_id: 'feature_x' }),
+    );
+  });
+
+  it('GIVEN_alert_threshold_reached_WHEN_pauseOverBudgetFeatures_runs_THEN_notifies_budget_alert', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    const { coordinator } = makeCoordinatorDeps({
+      checkBudgetImpl: async () => ({
+        over_budget: false,
+        alert_threshold_reached: true,
+        current_cost_usd: 4.5,
+        limit_usd: 5.0,
+        alert_threshold: 0.9,
+      }),
+      notifier,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'budget_alert',
+      expect.objectContaining({ feature_id: 'feature_x' }),
+    );
+  });
+
+  it('GIVEN_feature_transitions_to_BLOCKED_from_PLANNING_WHEN_notifyStatusTransitions_THEN_notifies_collision_detected', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    let featureStatus: string = STATUS.PLANNING;
+    let reconciliationCount = 0;
+    const kernel = {
+      ensureLoaded: vi.fn(async () => undefined),
+      recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
+      acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        orchestrator_session_id: 'orch:test',
+        feature_sessions: {},
+      })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
+      updateState: vi.fn(async () => ({})),
+      checkBudget: vi.fn(async () => ({
+        over_budget: false,
+        alert_threshold_reached: false,
+        current_cost_usd: 0,
+        limit_usd: -1,
+        alert_threshold: 0.8,
+      })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
+
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: featureStatus } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      }),
+    };
+
+    const state = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+
+    const sessionOrchestrator = {
+      ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+      cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async () => undefined),
+      closeFeatureCluster: vi.fn(async () => undefined),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+    };
+
+    const planningWaveExecutor = {
+      run: vi.fn(async () => undefined),
+      runPostQaReconciliation: vi.fn(async () => {
+        reconciliationCount += 1;
+        if (reconciliationCount === 2) {
+          featureStatus = STATUS.BLOCKED;
+        }
+      }),
+    };
+    const buildWaveExecutor = { run: vi.fn(async () => undefined) };
+    const qaWaveExecutor = { run: vi.fn(async () => undefined) };
+    const leaseHeartbeatService = { renew: vi.fn(async () => undefined) };
+    const provider = { selection: { provider: 'test', model: 'test-model' } };
+
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: provider as never,
+      toolCaller: toolCaller as never,
+      state: state as never,
+      sessionOrchestrator: sessionOrchestrator as never,
+      planningWaveExecutor: planningWaveExecutor as never,
+      buildWaveExecutor: buildWaveExecutor as never,
+      qaWaveExecutor: qaWaveExecutor as never,
+      leaseHeartbeatService: leaseHeartbeatService as never,
+      maxActiveFeatures: 5,
+      maxParallelGateRuns: 2,
+      maxIterationsPerPhase: 2,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      notifier: notifier as never,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
 
     expect(notifier.notify).toHaveBeenCalledWith(
       'collision_detected',
@@ -711,72 +1951,867 @@ describe('RunCoordinator notification and budget branches', () => {
     );
   });
 
-  it('GIVEN_feature_transitions_to_BLOCKED_from_non_PLANNING_WHEN_notifyStatusTransitions_THEN_notifies_gate_failed', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    let callCount = 0;
-    const { coordinator } = makeCoordinatorDeps({
+  it('GIVEN_feature_transitions_to_BLOCKED_from_non_PLANNING_WHEN_notifyStatusTransitions_THEN_notifies_gate_failed', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    let callCount = 0;
+    const { coordinator } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          callCount += 1;
+          const status = callCount === 1 ? STATUS.BUILDING : STATUS.BLOCKED;
+          return { ok: true, data: { front_matter: { status } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+      notifier,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'gate_failed',
+      expect.objectContaining({ feature_id: 'feature_x' }),
+    );
+  });
+
+  it('GIVEN_feature_transitions_to_READY_TO_MERGE_WHEN_notifyStatusTransitions_THEN_notifies_and_calls_prMonitor', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    const prMonitor = { checkAndUpdate: vi.fn(async () => null) };
+    let callCount = 0;
+    const { coordinator } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          callCount += 1;
+          const status = callCount === 1 ? STATUS.PLANNING : STATUS.READY_TO_MERGE;
+          return { ok: true, data: { front_matter: { status } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+      notifier,
+      prMonitor,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'ready_to_merge',
+      expect.objectContaining({ feature_id: 'feature_x' }),
+    );
+    expect(prMonitor.checkAndUpdate).toHaveBeenCalledWith('feature_x', 'feature_x');
+  });
+
+  it('GIVEN_feature_has_existing_pr_WHEN_status_is_unchanged_THEN_pr_monitor_polls_continuously', async () => {
+    const prMonitor = { checkAndUpdate: vi.fn(async () => null) };
+    const { coordinator } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.QA,
+                pr: { number: 77, url: 'https://example.com/pr/77' },
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+      prMonitor,
+      maxIterationsPerPhase: 2,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(prMonitor.checkAndUpdate).toHaveBeenCalledWith('feature_x', 'feature_x');
+  });
+
+  it('GIVEN_feature_transitions_to_MERGED_WHEN_notifyStatusTransitions_THEN_notifies_feature_merged', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    let callCount = 0;
+    const { coordinator } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          callCount += 1;
+          const status = callCount <= 2 ? STATUS.PLANNING : STATUS.MERGED;
+          return { ok: true, data: { front_matter: { status } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+      notifier,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(notifier.notify).toHaveBeenCalledWith(
+      'feature_merged',
+      expect.objectContaining({ feature_id: 'feature_x' }),
+    );
+  });
+
+  it('GIVEN_feature_transitions_to_terminal_status_WHEN_notifyStatusTransitions_runs_THEN_calls_notifyNewRequestHint', async () => {
+    const executionEnrollmentService = {
+      start: vi.fn(async () => undefined),
+      stop: vi.fn(async () => undefined),
+      notifyNewRequestHint: vi.fn(async () => undefined),
+      noteSafeCheckpoint: vi.fn(async () => undefined),
+      hasPendingWork: vi.fn(() => false),
+      drainReadyDecisions: vi.fn(async () => []),
+    };
+    let callCount = 0;
+    const { coordinator } = makeCoordinatorDeps({
+      executionEnrollmentService,
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          callCount += 1;
+          const status = callCount <= 2 ? STATUS.PLANNING : STATUS.MERGED;
+          return { ok: true, data: { front_matter: { status } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'feature_terminal' }]);
+
+    // notifyNewRequestHint is called once at startup and once when the feature reaches MERGED
+    expect(executionEnrollmentService.notifyNewRequestHint).toHaveBeenCalledTimes(2);
+  });
+
+  it('GIVEN_issue_tracker_WHEN_feature_first_enters_PLANNING_THEN_fetches_issue_and_stores_in_frontmatter', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator, kernel } = makeCoordinatorDeps({ issueTracker });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(issueTracker.getIssue).toHaveBeenCalledWith('x');
+    expect(kernel.updateState).toHaveBeenCalledWith('feature_x', null, expect.any(Function));
+  });
+
+  it('GIVEN_issue_tracker_WHEN_status_transitions_THEN_adds_comment', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator } = makeCoordinatorDeps({ issueTracker });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(issueTracker.addComment).toHaveBeenCalledWith('x', expect.stringContaining('planning'));
+  });
+
+  it('GIVEN_issue_tracker_WHEN_status_transitions_THEN_syncs_tracker_status_for_non_terminal_states', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator } = makeCoordinatorDeps({ issueTracker });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(issueTracker.updateIssueStatus).toHaveBeenCalledWith('x', STATUS.PLANNING);
+  });
+
+  it('GIVEN_issue_tracker_WHEN_status_is_MERGED_THEN_updates_issue_status_to_closed', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    let callCount = 0;
+    const { coordinator } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          callCount += 1;
+          const status = callCount <= 2 ? STATUS.PLANNING : STATUS.MERGED;
+          return { ok: true, data: { front_matter: { status } } };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+      issueTracker,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(issueTracker.updateIssueStatus).toHaveBeenCalledWith('x', STATUS.MERGED);
+  });
+
+  it('GIVEN_same_status_seen_twice_WHEN_notifyStatusTransitions_THEN_skips_duplicate_notification', async () => {
+    const notifier = { notify: vi.fn(async () => undefined) };
+    const { coordinator } = makeCoordinatorDeps({
+      // always returns PLANNING — second iteration sees same status, should not re-notify
+      notifier,
+      maxIterationsPerPhase: 2,
+    });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    // notify called once only — second iteration sees same status, skipped
+    const planningNotifies = notifier.notify.mock.calls.filter(
+      (c: unknown[]) => c[0] !== 'budget_alert' && c[0] !== 'budget_exceeded',
+    );
+    expect(planningNotifies.length).toBe(0); // PLANNING has no notifier branch, just confirm no error
+  });
+
+  it('GIVEN_issue_tracker_returns_issue_without_title_WHEN_first_planning_transition_THEN_skips_updateState', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({ id: '123', title: '', url: 'http://test' })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator, kernel } = makeCoordinatorDeps({ issueTracker });
+
+    await coordinator.start([{ feature_id: 'feature_x' }]);
+
+    expect(issueTracker.getIssue).toHaveBeenCalledWith('x');
+    // updateState should NOT be called since issue has no title
+    const stateUpdateForIssue = kernel.updateState.mock.calls.filter(
+      (c: unknown[]) => c[0] === 'feature_x',
+    );
+    expect(stateUpdateForIssue.length).toBe(0);
+  });
+
+  it('GIVEN_priority_order_with_unknown_feature_WHEN_applyOrchestratorPrioritization_runs_THEN_skips_unknown_and_appends_rest', async () => {
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: true,
+        priorityOrder: ['unknown_feature', 'feature_b'],
+        toolResults: [],
+      })),
+    };
+
+    const { ...rest } = makeCoordinatorDeps({ maxActiveFeatures: 2, maxIterationsPerPhase: 1 });
+    // Rebuild coordinator with workerDecisionRunner
+    const kernel2 = {
+      ensureLoaded: vi.fn(async () => undefined),
+      recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
+      acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
+      pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
+      getRuntimeSessions: vi.fn(async () => ({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        orchestrator_session_id: 'orch:test',
+        feature_sessions: {},
+      })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
+      updateState: vi.fn(async () => ({})),
+      checkBudget: vi.fn(async () => ({
+        over_budget: false,
+        alert_threshold_reached: false,
+        current_cost_usd: 0,
+        limit_usd: -1,
+        alert_threshold: 0.8,
+      })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
+    };
+    const state2 = {
+      runId: 'run:test',
+      ownerInstanceId: 'owner:test',
+      orchestratorSessionId: 'orch:test',
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
+      queue: [] as Array<{ feature_id: string }>,
+      runMetadata: {},
+    };
+    const toolCaller2 = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === 'report.dashboard') {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
+      }),
+    };
+    const sessionOrchestrator2 = {
+      ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+      cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+      initializeFeatureCluster: vi.fn(async () => undefined),
+      closeFeatureCluster: vi.fn(async () => undefined),
+      reconcileQueuedFeatures: vi.fn(async () => undefined),
+      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+    };
+    const coord2 = new RunCoordinator({
+      kernel: kernel2 as never,
+      provider: { selection: { provider: 'test', model: 'test' } } as never,
+      toolCaller: toolCaller2 as never,
+      state: state2 as never,
+      sessionOrchestrator: sessionOrchestrator2 as never,
+      planningWaveExecutor: {
+        run: vi.fn(async () => undefined),
+        runPostQaReconciliation: vi.fn(async () => undefined),
+      } as never,
+      buildWaveExecutor: { run: vi.fn(async () => undefined) } as never,
+      qaWaveExecutor: { run: vi.fn(async () => undefined) } as never,
+      leaseHeartbeatService: { renew: vi.fn(async () => undefined) } as never,
+      maxActiveFeatures: 2,
+      maxParallelGateRuns: 2,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      workerDecisionRunner: workerDecisionRunner as never,
+    });
+
+    void rest; // suppress unused warning
+    await coord2.start([{ feature_id: 'feature_a' }, { feature_id: 'feature_b' }]);
+    // Should complete without error; unknown_feature was skipped in prioritization
+    expect(workerDecisionRunner.execute).toHaveBeenCalled();
+  });
+
+  it('GIVEN_blocked_feature_with_passing_fast_gate_evidence_WHEN_iteration_runs_THEN_advances_to_QA', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 3,
+                gates: { fast: 'pass', full: 'na' },
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_fast_pass' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const recoveryCall = patchCalls.find((c) => {
+      const callArgs = c as unknown[];
+      const args = callArgs[2] as { patch?: { front_matter?: { status?: string } } } | undefined;
+      return args?.patch?.front_matter?.status === STATUS.QA;
+    });
+    expect(recoveryCall).toBeDefined();
+  });
+
+  it('GIVEN_blocked_feature_with_passing_full_gate_evidence_WHEN_iteration_runs_THEN_advances_to_READY_TO_MERGE', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 7,
+                gates: { fast: 'pass', full: 'pass' },
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_full_pass' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const recoveryCall = patchCalls.find((c) => {
+      const callArgs = c as unknown[];
+      const args = callArgs[2] as { patch?: { front_matter?: { status?: string } } } | undefined;
+      return args?.patch?.front_matter?.status === STATUS.READY_TO_MERGE;
+    });
+    expect(recoveryCall).toBeDefined();
+  });
+
+  it('GIVEN_blocked_feature_with_failed_fast_gate_and_retry_policy_WHEN_iteration_runs_THEN_returns_to_BUILDING', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 2,
+                gates: { fast: 'fail', full: 'na' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_fast_fail' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const recoveryCall = patchCalls.find((c) => {
+      const callArgs = c as unknown[];
+      const args = callArgs[2] as
+        | { patch?: { front_matter?: { status?: string; status_reason?: string } } }
+        | undefined;
+      return args?.patch?.front_matter?.status === STATUS.BUILDING;
+    });
+    expect(recoveryCall).toBeDefined();
+    if (recoveryCall) {
+      const callArgs = recoveryCall as unknown[];
+      const args = callArgs[2] as
+        | { patch?: { front_matter?: { status_reason?: string } } }
+        | undefined;
+      expect(args?.patch?.front_matter?.status_reason).toBe(
+        'recovered_from_blocked:gate_retry:fast',
+      );
+    }
+  });
+
+  it('GIVEN_blocked_feature_with_failed_full_gate_and_retry_policy_WHEN_iteration_runs_THEN_returns_to_QA', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 4,
+                gates: { fast: 'pass', full: 'fail' },
+                evidence: { last_gate_mode: 'full' },
+                gate_retry_count: 1,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_full_fail' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const recoveryCall = patchCalls.find((c) => {
+      const callArgs = c as unknown[];
+      const args = callArgs[2] as { patch?: { front_matter?: { status?: string } } } | undefined;
+      return args?.patch?.front_matter?.status === STATUS.QA;
+    });
+    expect(recoveryCall).toBeDefined();
+  });
+
+  it('GIVEN_blocked_feature_with_failed_gate_and_retry_limit_reached_WHEN_iteration_runs_THEN_does_not_requeue', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      policySnapshot: {
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 1 },
+        },
+      },
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 5,
+                gates: { fast: 'fail', full: 'na' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 1,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_fast_fail_maxed' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    expect(patchCalls).toHaveLength(0);
+  });
+
+  it('GIVEN_blocked_feature_with_duplicate_checkpoint_WHEN_iteration_runs_THEN_keeps_feature_blocked_until_new_work_exists', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'Gate mode fast failed',
+                gates: { fast: 'fail', full: 'na' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-stale',
+                    timestamp: new Date().toISOString(),
+                    files_changed: ['src/stale.ts'],
+                    validation_status: 'skipped',
+                    diff_snapshot: '.aop/features/blocked_stale/checkpoints/checkpoint-stale.diff',
+                    net_new_worktree_change: false,
+                    duplicate_of_checkpoint_id: 'checkpoint-prev',
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_stale_retry' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const staleBlockCall = patchCalls.find((c) => {
+      const args = c[2] as
+        | { patch?: { front_matter?: { status?: string; status_reason?: string } } }
+        | undefined;
+      return (
+        args?.patch?.front_matter?.status === STATUS.BLOCKED &&
+        args.patch.front_matter.status_reason === 'blocked:gate_retry_waiting_for_new_work:fast'
+      );
+    });
+    expect(staleBlockCall).toBeDefined();
+    expect(
+      patchCalls.some((c) => {
+        const args = c[2] as { patch?: { front_matter?: { status?: string } } } | undefined;
+        return args?.patch?.front_matter?.status === STATUS.BUILDING;
+      }),
+    ).toBe(false);
+  });
+
+  it('GIVEN_blocked_feature_with_stale_fast_evidence_and_valid_checkpoint_WHEN_iteration_runs_THEN_recovers_into_gate_refresh', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'Gate mode fast failed',
+                gates: { fast: 'fail', full: 'na' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-new',
+                    timestamp: new Date().toISOString(),
+                    files_changed: ['src/new.ts'],
+                    validation_status: 'valid',
+                    diff_snapshot: '.aop/features/blocked_refresh/checkpoints/checkpoint-new.diff',
+                    diff_hash: 'diff-new',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return {
+            ok: true,
+            data: {
+              latest_evidence: {
+                mode: 'fast',
+                overall: 'fail',
+                input_diff_hash: 'diff-old',
+              },
+              gate_evidence_by_mode: {
+                fast: {
+                  mode: 'fast',
+                  overall: 'fail',
+                  input_diff_hash: 'diff-old',
+                },
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await coordinator.start([{ feature_id: 'blocked_refresh' }]);
+
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    const recoveryCall = patchCalls.find((c) => {
+      const args = c[2] as
+        | { patch?: { front_matter?: { status?: string; status_reason?: string } } }
+        | undefined;
+      return (
+        args?.patch?.front_matter?.status === STATUS.BUILDING &&
+        args.patch.front_matter.status_reason === 'recovered_from_blocked:gate_refresh:fast'
+      );
+    });
+    expect(recoveryCall).toBeDefined();
+  });
+
+  it('GIVEN_blocked_feature_with_stale_full_evidence_and_valid_checkpoint_WHEN_iteration_runs_THEN_recovers_into_gate_refresh', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
       toolCallerImpl: async (_role, toolName) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          callCount += 1;
-          const status = callCount === 1 ? STATUS.BUILDING : STATUS.BLOCKED;
-          return { ok: true, data: { front_matter: { status } } };
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'Gate mode full failed',
+                gates: { fast: 'fail', full: 'fail' },
+                evidence: { last_gate_mode: 'full' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-new',
+                    timestamp: new Date().toISOString(),
+                    files_changed: ['src/new.ts'],
+                    validation_status: 'valid',
+                    diff_snapshot:
+                      '.aop/features/blocked_refresh_full/checkpoints/checkpoint-new.diff',
+                    diff_hash: 'diff-new',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return {
+            ok: true,
+            data: {
+              latest_evidence: {
+                mode: 'full',
+                overall: 'fail',
+                input_diff_hash: 'diff-old',
+              },
+              gate_evidence_by_mode: {
+                full: {
+                  mode: 'full',
+                  overall: 'fail',
+                  input_diff_hash: 'diff-old',
+                },
+              },
+            },
+          };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
         }
         return { ok: true, data: {} };
       },
-      notifier,
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await coordinator.start([{ feature_id: 'blocked_refresh_full' }]);
 
-    expect(notifier.notify).toHaveBeenCalledWith(
-      'gate_failed',
-      expect.objectContaining({ feature_id: 'feature_x' }),
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
     );
+    const recoveryCall = patchCalls.find((c) => {
+      const args = c[2] as
+        | { patch?: { front_matter?: { status?: string; status_reason?: string } } }
+        | undefined;
+      return (
+        args?.patch?.front_matter?.status === STATUS.QA &&
+        args.patch.front_matter.status_reason === 'recovered_from_blocked:gate_refresh:full'
+      );
+    });
+    expect(recoveryCall).toBeDefined();
   });
 
-  it('GIVEN_feature_transitions_to_READY_TO_MERGE_WHEN_notifyStatusTransitions_THEN_notifies_and_calls_prMonitor', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    const prMonitor = { checkAndUpdate: vi.fn(async () => null) };
-    let callCount = 0;
-    const { coordinator } = makeCoordinatorDeps({
+  it('GIVEN_blocked_feature_with_stale_fast_evidence_and_latest_skipped_duplicate_checkpoint_WHEN_iteration_runs_THEN_recovers_into_gate_refresh', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
       toolCallerImpl: async (_role, toolName) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          callCount += 1;
-          const status = callCount === 1 ? STATUS.PLANNING : STATUS.READY_TO_MERGE;
-          return { ok: true, data: { front_matter: { status } } };
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'blocked:gate_retry_waiting_for_new_work:fast',
+                gates: { fast: 'fail', full: 'na' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-valid',
+                    timestamp: new Date().toISOString(),
+                    files_changed: ['src/new.ts'],
+                    validation_status: 'valid',
+                    diff_snapshot:
+                      '.aop/features/blocked_refresh_duplicate/checkpoints/checkpoint-valid.diff',
+                    diff_hash: 'diff-new',
+                    net_new_worktree_change: true,
+                  },
+                  {
+                    checkpoint_id: 'checkpoint-skipped',
+                    timestamp: new Date().toISOString(),
+                    files_changed: [],
+                    validation_status: 'skipped',
+                    diff_snapshot:
+                      '.aop/features/blocked_refresh_duplicate/checkpoints/checkpoint-skipped.diff',
+                    diff_hash: 'diff-new',
+                    duplicate_of_checkpoint_id: 'checkpoint-valid',
+                    net_new_worktree_change: false,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return {
+            ok: true,
+            data: {
+              latest_evidence: {
+                mode: 'fast',
+                overall: 'fail',
+                input_diff_hash: 'diff-old',
+              },
+              gate_evidence_by_mode: {
+                fast: {
+                  mode: 'fast',
+                  overall: 'fail',
+                  input_diff_hash: 'diff-old',
+                },
+              },
+            },
+          };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
         }
         return { ok: true, data: {} };
       },
-      notifier,
-      prMonitor,
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await coordinator.start([{ feature_id: 'blocked_refresh_duplicate' }]);
 
-    expect(notifier.notify).toHaveBeenCalledWith(
-      'ready_to_merge',
-      expect.objectContaining({ feature_id: 'feature_x' }),
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
     );
-    expect(prMonitor.checkAndUpdate).toHaveBeenCalledWith('feature_x', 'feature_x');
+    const recoveryCall = patchCalls.find((c) => {
+      const args = c[2] as
+        | { patch?: { front_matter?: { status?: string; status_reason?: string } } }
+        | undefined;
+      return (
+        args?.patch?.front_matter?.status === STATUS.BUILDING &&
+        args.patch.front_matter.status_reason === 'recovered_from_blocked:gate_refresh:fast'
+      );
+    });
+    expect(recoveryCall).toBeDefined();
   });
 
-  it('GIVEN_feature_has_existing_pr_WHEN_status_is_unchanged_THEN_pr_monitor_polls_continuously', async () => {
-    const prMonitor = { checkAndUpdate: vi.fn(async () => null) };
-    const { coordinator } = makeCoordinatorDeps({
+  it('GIVEN_blocked_feature_with_stale_merge_evidence_and_valid_checkpoint_WHEN_iteration_runs_THEN_leaves_merge_repair_blocked_until_operator_reroutes', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
       toolCallerImpl: async (_role, toolName) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
           return {
             ok: true,
             data: {
               front_matter: {
-                status: STATUS.QA,
-                pr: { number: 77, url: 'https://example.com/pr/77' },
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'Gate mode merge failed',
+                gates: { fast: 'pass', full: 'pass', merge: 'fail' },
+                evidence: { last_gate_mode: 'merge' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-merge-new',
+                    timestamp: new Date().toISOString(),
+                    files_changed: ['src/new.ts'],
+                    validation_status: 'valid',
+                    diff_snapshot:
+                      '.aop/features/blocked_refresh_merge/checkpoints/checkpoint-merge-new.diff',
+                    diff_hash: 'diff-merge-new',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return {
+            ok: true,
+            data: {
+              latest_evidence: {
+                mode: 'merge',
+                overall: 'fail',
+                input_diff_hash: 'diff-merge-old',
+              },
+              gate_evidence_by_mode: {
+                merge: {
+                  mode: 'merge',
+                  overall: 'fail',
+                  input_diff_hash: 'diff-merge-old',
+                },
               },
             },
           };
@@ -786,161 +2821,547 @@ describe('RunCoordinator notification and budget branches', () => {
         }
         return { ok: true, data: {} };
       },
-      prMonitor,
-      maxIterationsPerPhase: 2,
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await coordinator.start([{ feature_id: 'blocked_refresh_merge' }]);
 
-    expect(prMonitor.checkAndUpdate).toHaveBeenCalledWith('feature_x', 'feature_x');
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('orchestrator', TOOLS.GATES_RUN, {
+      feature_id: 'blocked_refresh_merge',
+      mode: 'merge',
+    });
+    const patchCalls = toolCaller.callTool.mock.calls.filter(
+      (c) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    expect(
+      patchCalls.some((c) => {
+        const args = c[2] as { patch?: { front_matter?: { status_reason?: string } } } | undefined;
+        return (
+          args?.patch?.front_matter?.status_reason === 'recovered_from_blocked:gate_refresh:merge'
+        );
+      }),
+    ).toBe(false);
   });
 
-  it('GIVEN_feature_transitions_to_MERGED_WHEN_notifyStatusTransitions_THEN_notifies_feature_merged', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    let callCount = 0;
-    const { coordinator } = makeCoordinatorDeps({
+  it('GIVEN_blocked_feature_with_stale_merge_evidence_WHEN_recoverBlockedFeatures_runs_THEN_keeps_waiting_for_operator_reroute', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
       toolCallerImpl: async (_role, toolName) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          callCount += 1;
-          const status = callCount === 1 ? STATUS.PLANNING : STATUS.MERGED;
-          return { ok: true, data: { front_matter: { status } } };
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                version: 6,
+                status_reason: 'Gate mode merge failed',
+                gates: { fast: 'pass', full: 'pass', merge: 'fail' },
+                evidence: { last_gate_mode: 'merge' },
+                gate_retry_count: 0,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'checkpoint-merge-new',
+                    validation_status: 'valid',
+                    diff_hash: 'diff-merge-new',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return {
+            ok: true,
+            data: {
+              latest_evidence: {
+                mode: 'merge',
+                overall: 'fail',
+                input_diff_hash: 'diff-merge-old',
+              },
+              gate_evidence_by_mode: {
+                merge: {
+                  mode: 'merge',
+                  overall: 'fail',
+                  input_diff_hash: 'diff-merge-old',
+                },
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await (coordinator as any).recoverBlockedFeatures(['blocked_refresh_merge']);
+
+    expect(toolCaller.callTool).not.toHaveBeenCalledWith('orchestrator', TOOLS.GATES_RUN, {
+      feature_id: 'blocked_refresh_merge',
+      mode: 'merge',
+    });
+  });
+
+  it('GIVEN_blocked_merge_failed_feature_in_active_run_WHEN_other_feature_is_resumed_THEN_planning_wave_excludes_merge_blocked_feature', async () => {
+    const { coordinator, planningWaveExecutor } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role, toolName, args) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          if (args?.feature_id === 'feature_merge_blocked') {
+            return {
+              ok: true,
+              data: {
+                front_matter: {
+                  status: STATUS.BLOCKED,
+                  version: 11,
+                  gates: { plan: 'pass', fast: 'pass', full: 'pass', merge: 'fail' },
+                  evidence: { last_gate_mode: 'merge' },
+                  merge_repair: {
+                    attempts: 1,
+                    max_attempts: 5,
+                    active: true,
+                    requested_at: null,
+                    last_failed_at: null,
+                    last_gate_evidence_path: null,
+                    last_failure_summary: null,
+                    reviewer_message: null,
+                    exhausted_at: null,
+                  },
+                  status_reason: 'blocked:gate_retry_waiting_for_new_work:merge',
+                },
+              },
+            };
+          }
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.PLANNING,
+                version: 4,
+                gates: { plan: 'na', fast: 'na', full: 'na', merge: 'na' },
+              },
+            },
+          };
         }
         if (toolName === TOOLS.REPORT_DASHBOARD) {
           return { ok: true, data: { features: [] } };
         }
         return { ok: true, data: {} };
       },
-      notifier,
+      maxActiveFeatures: 2,
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await coordinator.start([
+      { feature_id: 'feature_merge_blocked' },
+      { feature_id: 'feature_resumed' },
+    ]);
 
-    expect(notifier.notify).toHaveBeenCalledWith(
-      'feature_merged',
-      expect.objectContaining({ feature_id: 'feature_x' }),
-    );
+    expect(planningWaveExecutor.run).toHaveBeenCalledWith(['feature_resumed']);
   });
 
-  it('GIVEN_issue_tracker_WHEN_feature_first_enters_PLANNING_THEN_fetches_issue_and_stores_in_frontmatter', async () => {
-    const issueTracker = {
-      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
-      addComment: vi.fn(async () => undefined),
-      updateIssueStatus: vi.fn(async () => undefined),
-    };
-    const { coordinator, kernel } = makeCoordinatorDeps({ issueTracker });
+  it('GIVEN_blocked_feature_with_passing_full_gate_WHEN_recoverBlockedFeatures_runs_THEN_marks_ready_to_merge', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                gates: { full: 'pass' },
+                evidence: {},
+                version: 4,
+                recovery: {
+                  state: 'retrying',
+                  cause: 'provider_output_invalid',
+                  role: 'planner',
+                },
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await (coordinator as any).recoverBlockedFeatures(['feature_blocked']);
 
-    expect(issueTracker.getIssue).toHaveBeenCalledWith('x');
-    expect(kernel.updateState).toHaveBeenCalledWith('feature_x', null, expect.any(Function));
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_blocked',
+      expected_version: 4,
+      patch: {
+        front_matter: {
+          status: STATUS.READY_TO_MERGE,
+          status_reason: 'recovered_from_blocked:passing_gate_evidence',
+          recovery: null,
+        },
+      },
+    });
   });
 
-  it('GIVEN_issue_tracker_WHEN_status_transitions_THEN_adds_comment', async () => {
-    const issueTracker = {
-      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
-      addComment: vi.fn(async () => undefined),
-      updateIssueStatus: vi.fn(async () => undefined),
-    };
-    const { coordinator } = makeCoordinatorDeps({ issueTracker });
+  it('GIVEN_blocked_feature_with_passing_full_gate_and_empty_checkpoint_diff_WHEN_recoverBlockedFeatures_runs_THEN_does_not_mark_ready_to_merge', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                gates: { full: 'pass' },
+                evidence: {},
+                version: 4,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'cp-empty',
+                    validation_status: 'valid',
+                    diff_hash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+                    net_new_worktree_change: false,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await (coordinator as any).recoverBlockedFeatures(['feature_blocked']);
 
-    expect(issueTracker.addComment).toHaveBeenCalledWith('x', expect.stringContaining('planning'));
+    expect(
+      toolCaller.callTool.mock.calls.some(
+        (call) =>
+          call[1] === TOOLS.FEATURE_STATE_PATCH &&
+          (call[2] as { patch?: { front_matter?: { status?: string } } }).patch?.front_matter
+            ?.status === STATUS.READY_TO_MERGE,
+      ),
+    ).toBe(false);
   });
 
-  it('GIVEN_issue_tracker_WHEN_status_transitions_THEN_syncs_tracker_status_for_non_terminal_states', async () => {
-    const issueTracker = {
-      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
-      addComment: vi.fn(async () => undefined),
-      updateIssueStatus: vi.fn(async () => undefined),
-    };
-    const { coordinator } = makeCoordinatorDeps({ issueTracker });
+  it('GIVEN_blocked_feature_with_stale_fast_gate_evidence_WHEN_recoverBlockedFeatures_runs_THEN_refreshes_from_building', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                gates: { fast: 'fail' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+                version: 6,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'cp-1',
+                    validation_status: 'valid',
+                    diff_hash: 'diff-1',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: { gate_evidence_by_mode: {}, latest_evidence: null } };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await (coordinator as any).recoverBlockedFeatures(['feature_refresh']);
+
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_refresh',
+      expected_version: 6,
+      patch: {
+        front_matter: {
+          status: STATUS.BUILDING,
+          status_reason: 'recovered_from_blocked:gate_refresh:fast',
+        },
+      },
+    });
+  });
+
+  it('GIVEN_blocked_feature_without_new_work_WHEN_recoverBlockedFeatures_runs_THEN_records_waiting_reason', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                gates: { fast: 'fail' },
+                evidence: { last_gate_mode: 'fast' },
+                gate_retry_count: 0,
+                status_reason: 'blocked:legacy',
+                version: 2,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'cp-2',
+                    validation_status: 'valid',
+                    net_new_worktree_change: false,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await (coordinator as any).recoverBlockedFeatures(['feature_waiting']);
+
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_waiting',
+      expected_version: 2,
+      patch: {
+        front_matter: {
+          status: STATUS.BLOCKED,
+          status_reason: 'blocked:gate_retry_waiting_for_new_work:fast',
+        },
+      },
+    });
+  });
+
+  it('GIVEN_blocked_feature_with_checkpoint_invalid_and_net_new_work_WHEN_recoverBlockedFeatures_runs_THEN_returns_to_building', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                version: 11,
+                status: STATUS.BLOCKED,
+                status_reason:
+                  'interactive_checkpoint_invalid: Builder checkpoint invalid: lint error',
+                gates: { plan: 'pass', fast: 'na', full: 'na' },
+                evidence: {},
+                checkpoints: [{ checkpoint_id: 'cp-1', net_new_worktree_change: true }],
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await (coordinator as any).recoverBlockedFeatures(['feature_cp_invalid']);
+
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_cp_invalid',
+      expected_version: 11,
+      patch: {
+        front_matter: {
+          status: STATUS.BUILDING,
+          status_reason: 'recovered_from_blocked:worker_retry:interactive_checkpoint_invalid',
+        },
+      },
+    });
+  });
+
+  it('GIVEN_blocked_feature_with_checkpoint_invalid_and_no_new_work_WHEN_recoverBlockedFeatures_runs_THEN_stays_blocked', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                version: 12,
+                status: STATUS.BLOCKED,
+                status_reason:
+                  'interactive_checkpoint_invalid: Builder checkpoint invalid: lint error',
+                gates: { plan: 'pass', fast: 'na', full: 'na' },
+                evidence: {},
+                checkpoints: [
+                  {
+                    checkpoint_id: 'cp-1',
+                    net_new_worktree_change: false,
+                  },
+                ],
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
+
+    await (coordinator as any).recoverBlockedFeatures(['feature_cp_no_new']);
+
+    const statePatches = toolCaller.callTool.mock.calls.filter(
+      (call: unknown[]) => call[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    expect(statePatches).toHaveLength(0);
+  });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+  it('GIVEN_blocked_feature_with_provider_output_invalid_and_net_new_work_WHEN_recoverBlockedFeatures_runs_THEN_returns_to_building', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                version: 13,
+                status: STATUS.BLOCKED,
+                status_reason: 'provider_output_invalid: Builder emitted malformed worker outputs',
+                gates: { plan: 'pass', fast: 'na', full: 'na' },
+                evidence: {},
+                checkpoints: [{ checkpoint_id: 'cp-2', net_new_worktree_change: true }],
+              },
+            },
+          };
+        }
+        return { ok: true, data: {} };
+      },
+    });
 
-    expect(issueTracker.updateIssueStatus).toHaveBeenCalledWith('x', STATUS.PLANNING);
+    await (coordinator as any).recoverBlockedFeatures(['feature_output_invalid']);
+
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_output_invalid',
+      expected_version: 13,
+      patch: {
+        front_matter: {
+          status: STATUS.BUILDING,
+          status_reason: 'recovered_from_blocked:worker_retry:provider_output_invalid',
+        },
+      },
+    });
   });
 
-  it('GIVEN_issue_tracker_WHEN_status_is_MERGED_THEN_updates_issue_status_to_closed', async () => {
-    const issueTracker = {
-      getIssue: vi.fn(async () => ({ id: '123', title: 'Test Issue', url: 'http://test' })),
-      addComment: vi.fn(async () => undefined),
-      updateIssueStatus: vi.fn(async () => undefined),
-    };
-    let callCount = 0;
-    const { coordinator } = makeCoordinatorDeps({
-      toolCallerImpl: async (_role, toolName) => {
+  it('GIVEN_blocked_feature_with_retryable_full_failure_WHEN_recoverBlockedFeatures_runs_THEN_returns_to_qa', async () => {
+    const { coordinator, toolCaller } = makeCoordinatorDeps({
+      toolCallerImpl: async (_role: string, toolName: string) => {
         if (toolName === TOOLS.FEATURE_STATE_GET) {
-          callCount += 1;
-          const status = callCount === 1 ? STATUS.PLANNING : STATUS.MERGED;
-          return { ok: true, data: { front_matter: { status } } };
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: STATUS.BLOCKED,
+                gates: { full: 'fail' },
+                evidence: { last_gate_mode: 'full' },
+                gate_retry_count: 0,
+                version: 9,
+                checkpoints: [
+                  {
+                    checkpoint_id: 'cp-3',
+                    validation_status: 'valid',
+                    net_new_worktree_change: true,
+                  },
+                ],
+              },
+            },
+          };
         }
-        if (toolName === TOOLS.REPORT_DASHBOARD) {
-          return { ok: true, data: { features: [] } };
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
         }
         return { ok: true, data: {} };
       },
-      issueTracker,
     });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+    await (coordinator as any).recoverBlockedFeatures(['feature_retry']);
 
-    expect(issueTracker.updateIssueStatus).toHaveBeenCalledWith('x', STATUS.MERGED);
+    expect(toolCaller.callTool).toHaveBeenCalledWith('orchestrator', TOOLS.FEATURE_STATE_PATCH, {
+      feature_id: 'feature_retry',
+      expected_version: 9,
+      patch: {
+        front_matter: {
+          status: STATUS.QA,
+          status_reason: 'recovered_from_blocked:gate_retry:full',
+        },
+      },
+    });
   });
+});
 
-  it('GIVEN_same_status_seen_twice_WHEN_notifyStatusTransitions_THEN_skips_duplicate_notification', async () => {
-    const notifier = { notify: vi.fn(async () => undefined) };
-    const { coordinator } = makeCoordinatorDeps({
-      // always returns PLANNING — second iteration sees same status, should not re-notify
-      notifier,
-      maxIterationsPerPhase: 2,
-    });
+describe('RunCoordinator checkpoint freshness helpers', () => {
+  const hasNetNewCheckpointWork = (frontMatter: Record<string, unknown>): boolean =>
+    (
+      RunCoordinator as unknown as {
+        hasNetNewCheckpointWork: (frontMatter: Record<string, unknown>) => boolean;
+      }
+    ).hasNetNewCheckpointWork(frontMatter);
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+  it('treats missing checkpoints as net-new work to avoid false negatives', () => {
+    expect(hasNetNewCheckpointWork({})).toBe(true);
+  });
 
-    // notify called once only — second iteration sees same status, skipped
-    const planningNotifies = notifier.notify.mock.calls.filter(
-      (c: unknown[]) => c[0] !== 'budget_alert' && c[0] !== 'budget_exceeded',
-    );
-    expect(planningNotifies.length).toBe(0); // PLANNING has no notifier branch, just confirm no error
+  it('treats malformed latest checkpoints as net-new work to avoid blocking retries', () => {
+    expect(hasNetNewCheckpointWork({ checkpoints: ['invalid-checkpoint'] })).toBe(true);
   });
 
-  it('GIVEN_issue_tracker_returns_issue_without_title_WHEN_first_planning_transition_THEN_skips_updateState', async () => {
-    const issueTracker = {
-      getIssue: vi.fn(async () => ({ id: '123', title: '', url: 'http://test' })),
-      addComment: vi.fn(async () => undefined),
-      updateIssueStatus: vi.fn(async () => undefined),
-    };
-    const { coordinator, kernel } = makeCoordinatorDeps({ issueTracker });
+  it('treats duplicate checkpoints as not net-new work', () => {
+    expect(
+      hasNetNewCheckpointWork({
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-2',
+            duplicate_of_checkpoint_id: 'checkpoint-1',
+          },
+        ],
+      }),
+    ).toBe(false);
+  });
 
-    await coordinator.start([{ feature_id: 'feature_x' }]);
+  it('treats explicit no-new-work checkpoints as not net-new work', () => {
+    expect(
+      hasNetNewCheckpointWork({
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-2',
+            net_new_worktree_change: false,
+          },
+        ],
+      }),
+    ).toBe(false);
+  });
 
-    expect(issueTracker.getIssue).toHaveBeenCalledWith('x');
-    // updateState should NOT be called since issue has no title
-    const stateUpdateForIssue = kernel.updateState.mock.calls.filter(
-      (c: unknown[]) => c[0] === 'feature_x',
-    );
-    expect(stateUpdateForIssue.length).toBe(0);
+  it('treats checkpoints with positive net-new work as retry-eligible', () => {
+    expect(
+      hasNetNewCheckpointWork({
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-3',
+            net_new_worktree_change: true,
+          },
+        ],
+      }),
+    ).toBe(true);
   });
 
-  it('GIVEN_priority_order_with_unknown_feature_WHEN_applyOrchestratorPrioritization_runs_THEN_skips_unknown_and_appends_rest', async () => {
-    const workerDecisionRunner = {
-      execute: vi.fn(async () => ({
-        planSubmission: false,
-        patchApplied: false,
-        noteLogged: false,
-        requestHandled: true,
-        priorityOrder: ['unknown_feature', 'feature_b'],
-        toolResults: [],
-      })),
-    };
+  it('ignores blank duplicate checkpoint ids when determining net-new work', () => {
+    expect(
+      hasNetNewCheckpointWork({
+        checkpoints: [
+          {
+            checkpoint_id: 'checkpoint-4',
+            duplicate_of_checkpoint_id: '   ',
+          },
+        ],
+      }),
+    ).toBe(true);
+  });
+});
 
-    const { ...rest } = makeCoordinatorDeps({ maxActiveFeatures: 2, maxIterationsPerPhase: 1 });
-    // Rebuild coordinator with workerDecisionRunner
-    const kernel2 = {
+describe('RunCoordinator issue tracker helpers', () => {
+  function makeIssueCoordinator(issueTracker?: {
+    getIssue: ReturnType<typeof vi.fn>;
+    addComment: ReturnType<typeof vi.fn>;
+    updateIssueStatus: ReturnType<typeof vi.fn>;
+  }) {
+    const kernel = {
       ensureLoaded: vi.fn(async () => undefined),
       recoverFromState: vi.fn(async () => ({ data: { recovered: true } })),
       acquireRunLease: vi.fn(async () => ({ data: { took_over_stale: false } })),
+      releaseRunLease: vi.fn(async () => ({ data: { released: true } })),
       pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] as string[] } })),
       getRuntimeSessions: vi.fn(async () => ({
         run_id: 'run:test',
@@ -948,6 +3369,11 @@ describe('RunCoordinator notification and budget branches', () => {
         orchestrator_session_id: 'orch:test',
         feature_sessions: {},
       })),
+      getPolicySnapshot: vi.fn(() => ({
+        reactions: {
+          gate_failed: { enabled: true, action: 'retry_with_agent_repair', max_retries: 2 },
+        },
+      })),
       updateState: vi.fn(async () => ({})),
       checkBudget: vi.fn(async () => ({
         over_budget: false,
@@ -956,37 +3382,29 @@ describe('RunCoordinator notification and budget branches', () => {
         limit_usd: -1,
         alert_threshold: 0.8,
       })),
+      drainPendingExecutionRequests: vi.fn(async () => ({ data: { items: [] } })),
+      markExecutionRequestProcessed: vi.fn(async () => ({ data: { updated: true } })),
     };
-    const state2 = {
-      runId: 'run:test',
-      ownerInstanceId: 'owner:test',
-      orchestratorSessionId: 'orch:test',
-      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>(),
-      queue: [] as Array<{ feature_id: string }>,
-      runMetadata: {},
-    };
-    const toolCaller2 = {
-      callTool: vi.fn(async (_role: string, toolName: string) => {
-        if (toolName === 'report.dashboard') {
-          return { ok: true, data: { features: [] } };
-        }
-        return { ok: true, data: { front_matter: { status: STATUS.PLANNING } } };
-      }),
-    };
-    const sessionOrchestrator2 = {
-      ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
-      cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
-      initializeFeatureCluster: vi.fn(async () => undefined),
-      closeFeatureCluster: vi.fn(async () => undefined),
-      reconcileQueuedFeatures: vi.fn(async () => undefined),
-      enforceActiveFeatureInvariant: vi.fn(async () => undefined),
-    };
-    const coord2 = new RunCoordinator({
-      kernel: kernel2 as never,
-      provider: { selection: { provider: 'test', model: 'test' } } as never,
-      toolCaller: toolCaller2 as never,
-      state: state2 as never,
-      sessionOrchestrator: sessionOrchestrator2 as never,
+    const coordinator = new RunCoordinator({
+      kernel: kernel as never,
+      provider: { selection: { provider: 'test', model: 'test-model' } } as never,
+      toolCaller: { callTool: vi.fn(async () => ({ ok: true, data: {} })) } as never,
+      state: {
+        runId: 'run:test',
+        ownerInstanceId: 'owner:test',
+        orchestratorSessionId: 'orch:test',
+        sessionsByFeature: new Map(),
+        queue: [],
+        runMetadata: {},
+      } as never,
+      sessionOrchestrator: {
+        ensureGlobalOrchestratorSession: vi.fn(async () => undefined),
+        cleanupOrphanWorkerSessions: vi.fn(async () => undefined),
+        initializeFeatureCluster: vi.fn(async () => undefined),
+        closeFeatureCluster: vi.fn(async () => undefined),
+        reconcileQueuedFeatures: vi.fn(async () => undefined),
+        enforceActiveFeatureInvariant: vi.fn(async () => undefined),
+      } as never,
       planningWaveExecutor: {
         run: vi.fn(async () => undefined),
         runPostQaReconciliation: vi.fn(async () => undefined),
@@ -994,17 +3412,257 @@ describe('RunCoordinator notification and budget branches', () => {
       buildWaveExecutor: { run: vi.fn(async () => undefined) } as never,
       qaWaveExecutor: { run: vi.fn(async () => undefined) } as never,
       leaseHeartbeatService: { renew: vi.fn(async () => undefined) } as never,
-      maxActiveFeatures: 2,
+      maxActiveFeatures: 1,
+      maxParallelGateRuns: 1,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      issueTracker: issueTracker as never,
+    });
+
+    return { coordinator, kernel };
+  }
+
+  it('returns early when issue tracking is not configured', async () => {
+    const { coordinator, kernel } = makeIssueCoordinator();
+    await (
+      coordinator as unknown as {
+        syncIssueTrackerStatus: (
+          featureId: string,
+          status: string,
+          prevStatus: string | undefined,
+        ) => Promise<void>;
+      }
+    ).syncIssueTrackerStatus('feature_no_issue_tracker', STATUS.BLOCKED, STATUS.PLANNING);
+
+    expect(kernel.updateState).not.toHaveBeenCalled();
+  });
+
+  it('stores fetched issue context when planning starts with a titled issue', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({
+        id: 'ISSUE-1',
+        title: 'Investigate resume loop',
+        body: 'Details',
+        status: 'open',
+        url: 'https://example.test/issues/1',
+      })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator, kernel } = makeIssueCoordinator(issueTracker);
+
+    await (
+      coordinator as unknown as {
+        syncIssueTrackerStatus: (
+          featureId: string,
+          status: string,
+          prevStatus: string | undefined,
+        ) => Promise<void>;
+      }
+    ).syncIssueTrackerStatus('feature_resume_loop', STATUS.PLANNING, undefined);
+
+    expect(kernel.updateState).toHaveBeenCalledTimes(1);
+    expect(issueTracker.addComment).toHaveBeenCalledWith(
+      'resume_loop',
+      'AOP: feature status changed to `planning`',
+    );
+  });
+
+  it('skips issue-context persistence when the fetched issue has no title', async () => {
+    const issueTracker = {
+      getIssue: vi.fn(async () => ({
+        id: 'ISSUE-2',
+        title: '',
+        body: 'Details',
+        status: 'open',
+        url: 'https://example.test/issues/2',
+      })),
+      addComment: vi.fn(async () => undefined),
+      updateIssueStatus: vi.fn(async () => undefined),
+    };
+    const { coordinator, kernel } = makeIssueCoordinator(issueTracker);
+
+    await (
+      coordinator as unknown as {
+        syncIssueTrackerStatus: (
+          featureId: string,
+          status: string,
+          prevStatus: string | undefined,
+        ) => Promise<void>;
+      }
+    ).syncIssueTrackerStatus('feature_missing_title', STATUS.PLANNING, undefined);
+
+    expect(kernel.updateState).not.toHaveBeenCalled();
+    expect(issueTracker.addComment).toHaveBeenCalledWith(
+      'missing_title',
+      'AOP: feature status changed to `planning`',
+    );
+  });
+});
+
+describe('prepareFeaturesForPhase divergence handling', () => {
+  it('GIVEN_reconcile_throws_remote_local_divergence_WHEN_prepare_phase_THEN_patches_to_blocked_and_notifies', async () => {
+    const notifySpy = vi.fn();
+
+    const callToolMock = vi.fn(
+      async (_role: string, toolName: string, _args?: Record<string, unknown>) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: 'building',
+                version: 1,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPO_RECONCILE_MAINLINE) {
+          const err = new Error('Local main differs from origin/main') as Error & {
+            code?: string;
+          };
+          err.code = 'remote_local_divergence';
+          throw err;
+        }
+        if (toolName === TOOLS.FEATURE_STATE_PATCH) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    );
+
+    const coordinator = new RunCoordinator({
+      kernel: {
+        getPolicySnapshot: () => ({
+          reconciliation: {
+            enabled: true,
+            check_before_phases: ['building'],
+            auto_merge_non_conflicting: true,
+          },
+        }),
+      } as never,
+      provider: { selection: { provider: 'test', model: 'test' } } as never,
+      toolCaller: { callTool: callToolMock } as never,
+      state: { runId: 'run:test', ownerInstanceId: 'owner:test' } as never,
+      sessionOrchestrator: {} as never,
+      planningWaveExecutor: {} as never,
+      buildWaveExecutor: {} as never,
+      qaWaveExecutor: {} as never,
+      leaseHeartbeatService: {} as never,
+      maxActiveFeatures: 1,
       maxParallelGateRuns: 2,
       maxIterationsPerPhase: 1,
       takeoverStaleRun: false,
       providerConfigRefHash: () => 'hash',
-      workerDecisionRunner: workerDecisionRunner as never,
+      notifier: { notify: notifySpy } as never,
     });
 
-    void rest; // suppress unused warning
-    await coord2.start([{ feature_id: 'feature_a' }, { feature_id: 'feature_b' }]);
-    // Should complete without error; unknown_feature was skipped in prioritization
-    expect(workerDecisionRunner.execute).toHaveBeenCalled();
+    const eligible = await (
+      coordinator as unknown as {
+        prepareFeaturesForPhase: (ids: string[], phase: string) => Promise<string[]>;
+      }
+    ).prepareFeaturesForPhase(['feat_diverged'], 'building');
+
+    expect(eligible).toEqual([]);
+
+    // Verify FEATURE_STATE_PATCH was called to set BLOCKED
+    const patchCall = callToolMock.mock.calls.find(
+      (c: unknown[]) => c[1] === TOOLS.FEATURE_STATE_PATCH,
+    );
+    expect(patchCall).toBeDefined();
+    const patchArgs = patchCall?.[2];
+    expect(patchArgs).toMatchObject({
+      feature_id: 'feat_diverged',
+      patch: {
+        front_matter: {
+          status: 'blocked',
+          status_reason: 'remote_local_divergence',
+        },
+      },
+    });
+
+    // Verify notification was emitted
+    expect(notifySpy).toHaveBeenCalledWith(
+      'remote_local_divergence',
+      expect.objectContaining({
+        feature_id: 'feat_diverged',
+      }),
+    );
+  });
+
+  it('GIVEN_first_feature_throws_divergence_WHEN_prepare_phase_THEN_second_feature_still_evaluated', async () => {
+    const notifySpy = vi.fn();
+
+    let reconcileCallCount = 0;
+    const callToolMock = vi.fn(
+      async (_role: string, toolName: string, _args?: Record<string, unknown>) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return {
+            ok: true,
+            data: {
+              front_matter: {
+                status: 'building',
+                version: 1,
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.REPO_RECONCILE_MAINLINE) {
+          reconcileCallCount++;
+          if (reconcileCallCount === 1) {
+            const err = new Error('diverged') as Error & { code?: string };
+            err.code = 'remote_local_divergence';
+            throw err;
+          }
+          return { ok: true, data: { status: 'up_to_date' } };
+        }
+        if (toolName === TOOLS.FEATURE_STATE_PATCH) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.REPORT_DASHBOARD) {
+          return { ok: true, data: { features: [] } };
+        }
+        return { ok: true, data: {} };
+      },
+    );
+
+    const coordinator = new RunCoordinator({
+      kernel: {
+        getPolicySnapshot: () => ({
+          reconciliation: {
+            enabled: true,
+            check_before_phases: ['building'],
+            auto_merge_non_conflicting: true,
+          },
+        }),
+      } as never,
+      provider: { selection: { provider: 'test', model: 'test' } } as never,
+      toolCaller: { callTool: callToolMock } as never,
+      state: { runId: 'run:test', ownerInstanceId: 'owner:test' } as never,
+      sessionOrchestrator: {} as never,
+      planningWaveExecutor: {} as never,
+      buildWaveExecutor: {} as never,
+      qaWaveExecutor: {} as never,
+      leaseHeartbeatService: {} as never,
+      maxActiveFeatures: 1,
+      maxParallelGateRuns: 2,
+      maxIterationsPerPhase: 1,
+      takeoverStaleRun: false,
+      providerConfigRefHash: () => 'hash',
+      notifier: { notify: notifySpy } as never,
+    });
+
+    const eligible = await (
+      coordinator as unknown as {
+        prepareFeaturesForPhase: (ids: string[], phase: string) => Promise<string[]>;
+      }
+    ).prepareFeaturesForPhase(['feat_bad', 'feat_good'], 'building');
+
+    expect(eligible).toEqual(['feat_good']);
+    expect(reconcileCallCount).toBe(2);
   });
 });