agentic-orchestrator 0.1.2 → 0.1.4

package/apps/control-plane/test/supervisor-collaborators.spec.ts

@@ -1,5 +1,9 @@
-import { describe, expect, it, vi } from 'vitest';
-import { STATUS, TOOLS } from '../src/core/constants.js';
+import fs from 'node:fs/promises';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { GATE_RESULT, STATUS, TOOLS } from '../src/core/constants.js';
+import { ERROR_CODES } from '../src/core/error-codes.js';
+import { BuildWaveExecutor } from '../src/supervisor/build-wave-executor.js';
+import { PromptBundleLoader } from '../src/supervisor/prompt-bundle-loader.js';
 import { QaWaveExecutor } from '../src/supervisor/qa-wave-executor.js';
 import { SessionOrchestrator } from '../src/supervisor/session-orchestrator.js';
 import { UNASSIGNED_SESSION_ID } from '../src/supervisor/types.js';
@@ -61,6 +65,213 @@ describe('QaWaveExecutor collaborator branches', () => {
       qa_session_id: 'qa-new'
     });
   });
+
+  describe('QaWaveExecutor catch and reactions branches', () => {
+    beforeEach(() => { vi.clearAllMocks(); });
+
+    function makeBaseDeps() {
+      const state = {
+        runId: 'run-qa',
+        ownerInstanceId: 'owner-qa',
+        orchestratorSessionId: 'orch-qa',
+        sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>([
+          ['feature_x', { planner: 'p-1', builder: 'b-1', qa: 'q-old' }]
+        ])
+      };
+      const provider = {
+        closeSession: vi.fn(async () => ({ closed: true })),
+        createSession: vi.fn(async () => ({ session_id: 'qa-new' }))
+      };
+      const kernel = {
+        updateFeatureSessionAssignment: vi.fn(async () => ({ data: {} }))
+      };
+      const promptProvider = {
+        loadRolePrompts: vi.fn(async () => ({ planner: null, builder: null, qa: 'qa-prompt' }))
+      };
+      const featureClusterPatcher = {
+        patchFeatureCluster: vi.fn(async () => undefined)
+      };
+      return { state, provider, kernel, promptProvider, featureClusterPatcher };
+    }
+
+    it('GIVEN_gates_run_throws_WHEN_qa_wave_runs_THEN_sets_gate_overall_to_fail_and_continues', async () => {
+      const { state, provider, kernel, promptProvider, featureClusterPatcher } = makeBaseDeps();
+      const toolCaller = {
+        callTool: vi.fn(async (_role: string, toolName: string) => {
+          if (toolName === TOOLS.FEATURE_STATE_GET) {
+            return { ok: true, data: { front_matter: { status: STATUS.QA, gate_retry_count: 0 } } };
+          }
+          if (toolName === TOOLS.GATES_RUN) {
+            throw new Error('gates failed unexpectedly');
+          }
+          return { ok: true, data: {} };
+        })
+      };
+
+      const executor = new QaWaveExecutor({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        promptProvider: promptProvider as never,
+        featureClusterPatcher: featureClusterPatcher as never,
+        state: state as never
+      });
+
+      await executor.run(['feature_x'], 1);
+
+      expect(provider.createSession).toHaveBeenCalledWith('qa', 'feature_x', 'qa-prompt');
+    });
+
+    it('GIVEN_reactions_service_with_retries_WHEN_gate_fails_initially_THEN_retries_until_pass', async () => {
+      const { state, provider, kernel, promptProvider, featureClusterPatcher } = makeBaseDeps();
+      let gateCallCount = 0;
+      const toolCaller = {
+        callTool: vi.fn(async (_role: string, toolName: string) => {
+          if (toolName === TOOLS.FEATURE_STATE_GET) {
+            return { ok: true, data: { front_matter: { status: STATUS.QA, gate_retry_count: 0 } } };
+          }
+          if (toolName === TOOLS.GATES_RUN) {
+            gateCallCount += 1;
+            return { ok: true, data: { overall: gateCallCount === 1 ? GATE_RESULT.FAIL : GATE_RESULT.PASS } };
+          }
+          return { ok: true, data: {} };
+        })
+      };
+      const reactionsService = {
+        retryDelayMs: vi.fn(() => 5),
+        shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+        buildRepairPrompt: vi.fn(() => 'repair prompt'),
+        recordRetry: vi.fn(async () => undefined),
+        shouldEscalate: vi.fn(() => false),
+        notifyEscalation: vi.fn(async () => undefined)
+      };
+
+      const executor = new QaWaveExecutor({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        promptProvider: promptProvider as never,
+        featureClusterPatcher: featureClusterPatcher as never,
+        state: state as never,
+        reactionsService: reactionsService as never
+      });
+
+      await executor.run(['feature_x'], 1);
+
+      expect(reactionsService.recordRetry).toHaveBeenCalledWith('feature_x', 1);
+      expect(reactionsService.notifyEscalation).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_reactions_service_retry_exhausted_WHEN_gate_still_fails_THEN_calls_shouldEscalate_and_notifyEscalation', async () => {
+      const { state, provider, kernel, promptProvider, featureClusterPatcher } = makeBaseDeps();
+      const toolCaller = {
+        callTool: vi.fn(async (_role: string, toolName: string) => {
+          if (toolName === TOOLS.FEATURE_STATE_GET) {
+            return { ok: true, data: { front_matter: { status: STATUS.QA, gate_retry_count: 0 } } };
+          }
+          if (toolName === TOOLS.GATES_RUN) {
+            return { ok: true, data: { overall: GATE_RESULT.FAIL } };
+          }
+          return { ok: true, data: {} };
+        })
+      };
+      const reactionsService = {
+        retryDelayMs: vi.fn(() => 5),
+        shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+        buildRepairPrompt: vi.fn(() => 'repair prompt'),
+        recordRetry: vi.fn(async () => undefined),
+        shouldEscalate: vi.fn(() => true),
+        notifyEscalation: vi.fn(async () => undefined)
+      };
+
+      const executor = new QaWaveExecutor({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        promptProvider: promptProvider as never,
+        featureClusterPatcher: featureClusterPatcher as never,
+        state: state as never,
+        reactionsService: reactionsService as never
+      });
+
+      await executor.run(['feature_x'], 1);
+
+      expect(reactionsService.notifyEscalation).toHaveBeenCalledWith(
+        'feature_x',
+        expect.objectContaining({ featureId: 'feature_x', gateName: 'full' })
+      );
+    });
+
+    it('GIVEN_reactions_service_WHEN_gate_passes_on_first_try_THEN_no_retry_attempted', async () => {
+      const { state, provider, kernel, promptProvider, featureClusterPatcher } = makeBaseDeps();
+      const toolCaller = {
+        callTool: vi.fn(async (_role: string, toolName: string) => {
+          if (toolName === TOOLS.FEATURE_STATE_GET) {
+            return { ok: true, data: { front_matter: { status: STATUS.QA, gate_retry_count: 0 } } };
+          }
+          if (toolName === TOOLS.GATES_RUN) {
+            return { ok: true, data: { overall: GATE_RESULT.PASS } };
+          }
+          return { ok: true, data: {} };
+        })
+      };
+      const reactionsService = {
+        retryDelayMs: vi.fn(() => 5),
+        shouldRetry: vi.fn(),
+        buildRepairPrompt: vi.fn(() => 'repair prompt'),
+        recordRetry: vi.fn(async () => undefined),
+        shouldEscalate: vi.fn(() => false),
+        notifyEscalation: vi.fn(async () => undefined)
+      };
+
+      const executor = new QaWaveExecutor({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        promptProvider: promptProvider as never,
+        featureClusterPatcher: featureClusterPatcher as never,
+        state: state as never,
+        reactionsService: reactionsService as never
+      });
+
+      await executor.run(['feature_x'], 1);
+
+      expect(reactionsService.shouldRetry).not.toHaveBeenCalled();
+    });
+
+    it('GIVEN_feature_not_in_qa_status_WHEN_run_called_THEN_feature_skipped_entirely', async () => {
+      const { state, provider, kernel, promptProvider, featureClusterPatcher } = makeBaseDeps();
+      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 workerDecisionRunner = {
+        execute: vi.fn(async () => ({
+          planSubmission: false, patchApplied: false, noteLogged: false,
+          requestHandled: false, priorityOrder: [] as string[], toolResults: []
+        }))
+      };
+
+      const executor = new QaWaveExecutor({
+        kernel: kernel as never,
+        provider: provider as never,
+        toolCaller: toolCaller as never,
+        promptProvider: promptProvider as never,
+        featureClusterPatcher: featureClusterPatcher as never,
+        state: state as never,
+        workerDecisionRunner: workerDecisionRunner as never
+      });
+
+      await executor.run(['feature_x'], 1);
+
+      expect(workerDecisionRunner.execute).not.toHaveBeenCalled();
+      expect(provider.createSession).not.toHaveBeenCalled();
+    });
+  });
 });
 
 describe('SessionOrchestrator collaborator branches', () => {
@@ -198,4 +409,490 @@ describe('SessionOrchestrator collaborator branches', () => {
       })
     );
   });
+
+  it('GIVEN_existing_sessions_with_unassigned_WHEN_closing_feature_cluster_THEN_closes_assigned_sessions_only', async () => {
+    const { orchestrator, provider, state } = createOrchestrator();
+    state.sessionsByFeature.set('feature_close', {
+      planner: 'planner-c',
+      builder: UNASSIGNED_SESSION_ID,
+      qa: 'qa-c'
+    });
+
+    await orchestrator.closeFeatureCluster('feature_close');
+
+    expect(provider.closeSession).toHaveBeenCalledWith('planner-c');
+    expect(provider.closeSession).toHaveBeenCalledWith('qa-c');
+    expect(provider.closeSession).not.toHaveBeenCalledWith(UNASSIGNED_SESSION_ID);
+    expect(state.sessionsByFeature.has('feature_close')).toBe(false);
+  });
+
+  it('GIVEN_no_sessions_in_map_WHEN_closing_feature_cluster_THEN_is_noop', async () => {
+    const { orchestrator, provider } = createOrchestrator();
+
+    await orchestrator.closeFeatureCluster('feature_nonexistent');
+
+    expect(provider.closeSession).not.toHaveBeenCalled();
+  });
+});
+
+describe('BuildWaveExecutor catch and reactions branches', () => {
+  function makeBaseBuildDeps() {
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    return { workerDecisionRunner };
+  }
+
+  it('GIVEN_reactions_service_retry_catch_throws_WHEN_build_wave_THEN_sets_gate_fail_and_checks_escalation', async () => {
+    const { workerDecisionRunner } = makeBaseBuildDeps();
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount += 1;
+          if (gatesCallCount === 1) {
+            return { ok: true, data: { overall: GATE_RESULT.FAIL } };
+          }
+          throw new Error('retry gate exploded');
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 5),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      buildRepairPrompt: vi.fn(() => 'repair prompt'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+
+    await executor.run(['feature_build'], 1);
+
+    expect(reactionsService.recordRetry).toHaveBeenCalledWith('feature_build', 1);
+    expect(reactionsService.shouldEscalate).toHaveBeenCalled();
+  });
+
+  it('GIVEN_reactions_service_retry_succeeds_WHEN_build_wave_THEN_breaks_and_skips_escalation', async () => {
+    const { workerDecisionRunner } = makeBaseBuildDeps();
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount += 1;
+          return { ok: true, data: { overall: gatesCallCount === 1 ? GATE_RESULT.FAIL : GATE_RESULT.PASS } };
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 5),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      buildRepairPrompt: vi.fn(() => 'repair prompt'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+
+    await executor.run(['feature_build'], 1);
+
+    expect(reactionsService.recordRetry).toHaveBeenCalledWith('feature_build', 1);
+    // Gate passed in retry → break taken → shouldEscalate NOT called (gateOverall=PASS short-circuits)
+    expect(reactionsService.shouldEscalate).not.toHaveBeenCalled();
+    expect(reactionsService.notifyEscalation).not.toHaveBeenCalled();
+  });
+});
+
+describe('PromptBundleLoader behavior', () => {
+  it('GIVEN_missing_prompt_behavior_error_WHEN_file_not_found_THEN_throws_missing_role_prompt', async () => {
+    const readFileSpy = vi.spyOn(fs, 'readFile').mockRejectedValue(new Error('ENOENT: no such file') as never);
+    const runtimeStateReader = {
+      getRepoRoot: vi.fn(() => '/fake/repo'),
+      getAgentsConfig: vi.fn(() => ({
+        roles: { planner: { system_prompt_path: 'prompts/planner.md' } },
+        missing_prompt_behavior: 'error'
+      }))
+    };
+    const loader = new PromptBundleLoader(runtimeStateReader as never);
+
+    await expect(loader.loadRolePrompts()).rejects.toMatchObject({
+      code: ERROR_CODES.MISSING_ROLE_PROMPT
+    });
+
+    readFileSpy.mockRestore();
+  });
+
+  it('GIVEN_cache_set_WHEN_peek_cache_called_THEN_returns_cached_value', () => {
+    const runtimeStateReader = {
+      getRepoRoot: vi.fn(() => '/fake/repo'),
+      getAgentsConfig: vi.fn(() => ({ roles: {}, missing_prompt_behavior: 'ignore' }))
+    };
+    const loader = new PromptBundleLoader(runtimeStateReader as never);
+    const bundle = { planner: 'planner prompt', builder: null, qa: 'qa prompt' };
+
+    loader.setCache(bundle);
+
+    expect(loader.peekCache()).toEqual(bundle);
+  });
+
+  it('GIVEN_cache_set_to_null_WHEN_peek_cache_called_THEN_returns_null', () => {
+    const runtimeStateReader = {
+      getRepoRoot: vi.fn(() => '/fake/repo'),
+      getAgentsConfig: vi.fn(() => ({ roles: {}, missing_prompt_behavior: 'ignore' }))
+    };
+    const loader = new PromptBundleLoader(runtimeStateReader as never);
+
+    loader.setCache(null);
+
+    expect(loader.peekCache()).toBeNull();
+  });
+
+  it('GIVEN_agentsConfig_without_roles_or_behavior_WHEN_loadRolePrompts_THEN_uses_defaults', async () => {
+    const runtimeStateReader = {
+      getRepoRoot: vi.fn(() => '/fake/repo'),
+      getAgentsConfig: vi.fn(() => ({}))
+    };
+    const loader = new PromptBundleLoader(runtimeStateReader as never);
+    const bundle = await loader.loadRolePrompts();
+    expect(bundle.planner).toBeNull();
+    expect(bundle.builder).toBeNull();
+    expect(bundle.qa).toBeNull();
+  });
+});
+
+describe('BuildWaveExecutor waitBeforeRetry branch', () => {
+  function makeBaseDeps() {
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    return { workerDecisionRunner };
+  }
+
+  it('GIVEN_reactionsService_with_waitBeforeRetry_function_WHEN_gate_fails_THEN_calls_waitBeforeRetry', async () => {
+    const { workerDecisionRunner } = makeBaseDeps();
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount += 1;
+          return { ok: true, data: { overall: gatesCallCount === 1 ? GATE_RESULT.FAIL : GATE_RESULT.PASS } };
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const waitBeforeRetry = vi.fn(async () => undefined);
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      waitBeforeRetry,
+      buildRepairPrompt: vi.fn(() => 'repair prompt'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+
+    await executor.run(['feature_wait'], 1);
+
+    expect(waitBeforeRetry).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('QaWaveExecutor waitBeforeRetry branch', () => {
+  it('GIVEN_reactionsService_with_waitBeforeRetry_WHEN_gate_fails_then_passes_THEN_calls_waitBeforeRetry', async () => {
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    const state = {
+      runId: 'run-qa-retry',
+      ownerInstanceId: 'owner-qa-retry',
+      orchestratorSessionId: null,
+      sessionsByFeature: new Map<string, { planner: string; builder: string; qa: string }>()
+    };
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.QA, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount += 1;
+          return { ok: true, data: { overall: gatesCallCount === 1 ? GATE_RESULT.FAIL : GATE_RESULT.PASS } };
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const waitBeforeRetry = vi.fn(async () => undefined);
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      waitBeforeRetry,
+      buildRepairPrompt: vi.fn(() => 'repair prompt'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+    const provider = {
+      closeSession: vi.fn(async () => ({ closed: true })),
+      createSession: vi.fn(async () => ({ session_id: 'qa-retry-session' }))
+    };
+    const kernel = {
+      updateFeatureSessionAssignment: vi.fn(async () => ({ data: { updated: true } }))
+    };
+    const promptProvider = {
+      loadRolePrompts: vi.fn(async () => ({ planner: null, builder: null, qa: null }))
+    };
+    const featureClusterPatcher = {
+      patchFeatureCluster: vi.fn(async () => undefined)
+    };
+    const executor = new QaWaveExecutor({
+      kernel: kernel as never,
+      provider: provider as never,
+      toolCaller: toolCaller as never,
+      promptProvider: promptProvider as never,
+      featureClusterPatcher: featureClusterPatcher as never,
+      state: state as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+
+    await executor.run(['feature_qa_wait'], 1);
+
+    expect(waitBeforeRetry).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('BuildWaveExecutor error message fallback', () => {
+  it('GIVEN_gates_throw_without_message_WHEN_run_THEN_gateLogs_empty_string', async () => {
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          throw {}; // no message property → typed.message ?? '' = ''
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn(() => false),
+      buildRepairPrompt: vi.fn(() => 'prompt'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+    await executor.run(['feature_x'], 1);
+  });
+
+  it('GIVEN_retry_gates_return_no_overall_WHEN_run_THEN_defaults_to_PASS', async () => {
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount++;
+          if (gatesCallCount === 1) {return { ok: true, data: { overall: GATE_RESULT.FAIL } };}
+          return { ok: true, data: {} };
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      buildRepairPrompt: vi.fn(() => 'repair'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+    await executor.run(['feature_x'], 1);
+    // retry returned no overall → defaults to PASS → gateOverall = PASS → shouldEscalate not called
+    expect(reactionsService.shouldEscalate).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_retry_gates_still_fail_WHEN_run_THEN_gateExitCode_is_1', async () => {
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          return { ok: true, data: { overall: GATE_RESULT.FAIL } };
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      buildRepairPrompt: vi.fn(() => 'repair'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+    await executor.run(['feature_x'], 1);
+    // retry still fails (FAIL) → shouldEscalate should be checked
+    expect(reactionsService.shouldEscalate).toHaveBeenCalled();
+  });
+
+  it('GIVEN_retry_gates_throw_without_message_WHEN_run_THEN_handled', async () => {
+    let gatesCallCount = 0;
+    const toolCaller = {
+      callTool: vi.fn(async (_role: string, toolName: string) => {
+        if (toolName === TOOLS.FEATURE_STATE_GET) {
+          return { ok: true, data: { front_matter: { status: STATUS.BUILDING, gate_retry_count: 0 } } };
+        }
+        if (toolName === TOOLS.FEATURE_GET_CONTEXT) {
+          return { ok: true, data: {} };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          gatesCallCount++;
+          if (gatesCallCount === 1) {return { ok: true, data: { overall: GATE_RESULT.FAIL } };}
+          throw {}; // retry throws without message → typed.message ?? '' = ''
+        }
+        return { ok: true, data: {} };
+      })
+    };
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: []
+      }))
+    };
+    const reactionsService = {
+      retryDelayMs: vi.fn(() => 0),
+      shouldRetry: vi.fn().mockReturnValueOnce(true).mockReturnValue(false),
+      buildRepairPrompt: vi.fn(() => 'repair'),
+      recordRetry: vi.fn(async () => undefined),
+      shouldEscalate: vi.fn(() => false),
+      notifyEscalation: vi.fn(async () => undefined)
+    };
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+      reactionsService: reactionsService as never
+    });
+    await executor.run(['feature_x'], 1);
+  });
 });