agentic-orchestrator 0.1.27 → 0.2.0

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

@@ -2,8 +2,9 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
+import * as CoreFs from '../src/core/fs.js';
 import { ERROR_CODES } from '../src/core/error-codes.js';
-import { STATUS, TOOLS } from '../src/core/constants.js';
+import { GATE_RESULT, STATUS, TOOLS } from '../src/core/constants.js';
 import { SupervisorRuntime } from '../src/index.js';
 
 function makeRuntime(options: Record<string, unknown> = {}) {
@@ -12,7 +13,7 @@ function makeRuntime(options: Record<string, unknown> = {}) {
     agentsConfig: { roles: {}, missing_prompt_behavior: 'ignore' },
   };
 
-  const kernel = {
+  const kernel: any = {
     getRepoRoot: vi.fn(() => kernelState.repoRoot),
     getAgentsConfig: vi.fn(() => kernelState.agentsConfig),
     getPolicySnapshot: vi.fn(
@@ -26,11 +27,15 @@ function makeRuntime(options: Record<string, unknown> = {}) {
     getRuntimeSessions: vi.fn(async () => ({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'unknown',
+      reconciler_session_id: 'unknown',
       orchestrator_epoch: 0,
       feature_sessions: {},
     })),
     updateOrchestratorSession: vi.fn(async () => ({ data: {} })),
+    updateReconcilerSession: vi.fn(async () => ({ data: {} })),
+    updateOrganizerSession: vi.fn(async () => ({ data: {} })),
     updateFeatureSessionAssignment: vi.fn(async () => ({ data: { updated: true } })),
     pruneFeatureSessionAssignments: vi.fn(async () => ({ data: { removed: [] } })),
     ensureLoaded: vi.fn(async () => undefined),
@@ -39,9 +44,14 @@ function makeRuntime(options: Record<string, unknown> = {}) {
     renewLeases: vi.fn(async () => undefined),
     renewRunLease: vi.fn(async () => undefined),
     repoDiff: vi.fn(async () => ({ data: { diff: '' } })),
+    readState: vi.fn(async () => ({ frontMatter: {} })),
+    updateState: vi.fn(async () => ({ data: { updated: true } })),
+    featurePath: vi.fn((featureId: string) => `/tmp/.aop/features/${featureId}`),
+    worktreePath: vi.fn((featureId: string) => `/tmp/.aop/worktrees/${featureId}`),
+    validatePatchDiff: vi.fn(async () => ({ data: { valid: true } })),
   };
 
-  const provider = {
+  const provider: any = {
     selection: {
       provider: 'custom',
       model: 'model-x',
@@ -54,11 +64,11 @@ function makeRuntime(options: Record<string, unknown> = {}) {
     closeSession: vi.fn(async () => ({ closed: true })),
   };
 
-  const toolClient = {
+  const toolClient: any = {
     call: vi.fn(async (): Promise<any> => ({ ok: true, data: {} })),
   };
 
-  const runtime = new SupervisorRuntime(kernel as any, provider as any, toolClient as any, {
+  const runtime = new SupervisorRuntime(kernel, provider, toolClient, {
     run_id: 'run:test',
     owner_instance_id: 'owner:test',
     max_iterations_per_phase: 0,
@@ -81,7 +91,7 @@ describe('SupervisorRuntime unit behavior', () => {
       },
     });
 
-    const runtime = new SupervisorRuntime(kernel as any, provider as any, toolClient as any, {
+    const runtime = new SupervisorRuntime(kernel, provider, toolClient, {
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
     });
@@ -89,28 +99,90 @@ describe('SupervisorRuntime unit behavior', () => {
     expect(runtime.maxIterationsPerPhase).toBe(4);
   });
 
+  it('GIVEN_cli_execution_mode_override_WHEN_resolving_execution_mode_THEN_returns_cli_mode', async () => {
+    const { runtime, kernel } = makeRuntime({ execution_mode: 'interactive' });
+
+    await expect(runtime.resolveExecutionMode('feature_a')).resolves.toBe('interactive');
+    expect(kernel.readState).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_state_execution_mode_WHEN_resolving_execution_mode_THEN_prefers_state_value', async () => {
+    const { runtime, kernel } = makeRuntime();
+    kernel.readState.mockResolvedValue({
+      frontMatter: { execution_mode: 'interactive' },
+    });
+
+    await expect(runtime.resolveExecutionMode('feature_a')).resolves.toBe('interactive');
+  });
+
+  it('GIVEN_state_read_failure_WHEN_runtime_default_exists_THEN_uses_runtime_execution_mode', async () => {
+    const { runtime, kernel } = makeRuntime();
+    kernel.readState.mockRejectedValue(new Error('state unavailable'));
+    kernel.getAgentsConfig.mockReturnValue({
+      roles: {},
+      missing_prompt_behavior: 'ignore',
+      runtime: { execution_mode: 'interactive' },
+    });
+
+    await expect(runtime.resolveExecutionMode('feature_a')).resolves.toBe('interactive');
+  });
+
+  it('GIVEN_invalid_state_and_runtime_execution_modes_WHEN_resolving_execution_mode_THEN_defaults_to_deterministic', async () => {
+    const { runtime, kernel } = makeRuntime();
+    kernel.readState.mockResolvedValue({
+      frontMatter: { execution_mode: 'sometimes' },
+    });
+    kernel.getAgentsConfig.mockReturnValue({
+      roles: {},
+      missing_prompt_behavior: 'ignore',
+      runtime: { execution_mode: 'sometimes' },
+    });
+
+    await expect(runtime.resolveExecutionMode('feature_a')).resolves.toBe('deterministic');
+  });
+
   it('GIVEN_matching_runtime_session_WHEN_ensuring_orchestrator_session_THEN_reuses_existing_session', async () => {
     const { runtime, kernel, provider } = makeRuntime();
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch-existing',
+      reconciler_session_id: 'reconciler-existing',
+      organizer_session_id: 'organizer-existing',
       orchestrator_epoch: 0,
       feature_sessions: {},
     });
-    provider.reattachSession.mockResolvedValue({
-      session_id: 'orch-existing',
-      role: 'orchestrator',
-      feature_id: 'global',
-      system_prompt_loaded: false,
-    });
+    provider.reattachSession
+      .mockResolvedValueOnce({
+        session_id: 'orch-existing',
+        role: 'orchestrator',
+        feature_id: 'global',
+        system_prompt_loaded: false,
+      })
+      .mockResolvedValueOnce({
+        session_id: 'reconciler-existing',
+        role: 'reconciler',
+        feature_id: 'global',
+        system_prompt_loaded: false,
+      })
+      .mockResolvedValueOnce({
+        session_id: 'organizer-existing',
+        role: 'organizer',
+        feature_id: 'global',
+        system_prompt_loaded: false,
+      });
 
     await runtime.ensureGlobalOrchestratorSession();
 
     expect(runtime.orchestratorSessionId).toBe('orch-existing');
+    expect(runtime.reconcilerSessionId).toBe('reconciler-existing');
     expect(runtime.runMetadata.orchestrator_reattached).toBe(true);
+    expect(runtime.runMetadata.reconciler_reattached).toBe(true);
     expect(provider.createSession).not.toHaveBeenCalled();
     expect(kernel.updateOrchestratorSession).not.toHaveBeenCalled();
+    expect(kernel.updateReconcilerSession).not.toHaveBeenCalled();
+    expect(kernel.updateOrganizerSession).not.toHaveBeenCalled();
   });
 
   it('GIVEN_no_reusable_orchestrator_session_WHEN_ensuring_THEN_creates_and_persists_new_session', async () => {
@@ -118,6 +190,7 @@ describe('SupervisorRuntime unit behavior', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'other-run',
       owner_instance_id: 'other-owner',
+      provider: 'custom',
       orchestrator_session_id: 'unknown',
       orchestrator_epoch: 0,
       feature_sessions: {},
@@ -127,7 +200,9 @@ describe('SupervisorRuntime unit behavior', () => {
     await runtime.ensureGlobalOrchestratorSession();
 
     expect(runtime.orchestratorSessionId).toBe('orch-new');
+    expect(runtime.reconcilerSessionId).toBe('orch-new');
     expect(runtime.runMetadata.orchestrator_reattached).toBe(false);
+    expect(runtime.runMetadata.reconciler_reattached).toBe(false);
     expect(kernel.updateOrchestratorSession).toHaveBeenCalledWith(
       expect.objectContaining({
         run_id: 'run:test',
@@ -136,6 +211,40 @@ describe('SupervisorRuntime unit behavior', () => {
         increment_epoch: false,
       }),
     );
+    expect(kernel.updateReconcilerSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        reconciler_session_id: 'orch-new',
+      }),
+    );
+  });
+
+  it('GIVEN_provider_mismatch_WHEN_ensuring_orchestrator_session_THEN_discards_old_session_and_creates_new', async () => {
+    const { runtime, kernel, provider } = makeRuntime();
+    kernel.getRuntimeSessions.mockResolvedValue({
+      run_id: 'run:test',
+      owner_instance_id: 'owner:test',
+      provider: 'codex',
+      orchestrator_session_id: 'builder-some-feature-385de175-ded8-45cf-aa53-1c49d4860f45',
+      orchestrator_epoch: 2,
+      feature_sessions: {},
+    });
+    provider.createSession.mockResolvedValue({ session_id: 'orch-new-copilot' });
+
+    await runtime.ensureGlobalOrchestratorSession();
+
+    expect(runtime.orchestratorSessionId).toBe('orch-new-copilot');
+    expect(runtime.reconcilerSessionId).toBe('orch-new-copilot');
+    expect(runtime.runMetadata.orchestrator_reattached).toBe(false);
+    expect(provider.reattachSession).not.toHaveBeenCalled();
+    expect(kernel.updateOrchestratorSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        run_id: 'run:test',
+        owner_instance_id: 'owner:test',
+        orchestrator_session_id: 'orch-new-copilot',
+      }),
+    );
   });
 
   it('GIVEN_reattach_timeout_on_reusable_session_WHEN_ensuring_THEN_recreates_orchestrator_and_marks_epoch_orphan', async () => {
@@ -149,6 +258,7 @@ describe('SupervisorRuntime unit behavior', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch-old',
       orchestrator_epoch: 4,
       feature_sessions: {},
@@ -165,6 +275,7 @@ describe('SupervisorRuntime unit behavior', () => {
     await runtime.ensureGlobalOrchestratorSession();
 
     expect(runtime.orchestratorSessionId).toBe('orch-new');
+    expect(runtime.reconcilerSessionId).toBe('orch-new');
     expect(runtime.runMetadata.orchestrator_reattached).toBe(false);
     expect(runtime.runMetadata.orchestrator_epoch_incremented).toBe(true);
     expect(kernel.updateOrchestratorSession).toHaveBeenCalledWith(
@@ -190,6 +301,7 @@ describe('SupervisorRuntime unit behavior', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch',
       orchestrator_epoch: 0,
       feature_sessions: {
@@ -220,6 +332,7 @@ describe('SupervisorRuntime unit behavior', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch',
       orchestrator_epoch: 1,
       feature_sessions: {
@@ -287,6 +400,8 @@ describe('SupervisorRuntime unit behavior', () => {
       planner: 'planner prompt',
       builder: null,
       qa: null,
+      reconciler: null,
+      organizer: null,
     });
     expect(second).toEqual(first);
     await fs.rm(repoRoot, { recursive: true, force: true });
@@ -356,6 +471,69 @@ describe('SupervisorRuntime unit behavior', () => {
     expect(gateCalls[0][2]).toMatchObject({ feature_id: 'feature_a', mode: 'fast' });
   });
 
+  it('GIVEN_interactive_resume_gate_refresh_WHEN_running_build_wave_THEN_reruns_fast_gate_without_worker_turn', async () => {
+    const { runtime, provider } = makeRuntime({ max_parallel_gate_runs: 1 });
+    const callTool = vi.spyOn(runtime, 'callTool');
+
+    callTool.mockImplementation(async (_role, toolName, _args) => {
+      if (toolName === TOOLS.FEATURE_STATE_GET) {
+        return {
+          ok: true,
+          data: {
+            front_matter: {
+              status: STATUS.BUILDING,
+              status_reason: 'recovered_from_blocked:gate_refresh:fast',
+              gate_retry_count: 0,
+              version: 3,
+              checkpoints: [
+                {
+                  checkpoint_id: 'checkpoint-new',
+                  timestamp: '2026-03-12T16:00:00.000Z',
+                  files_changed: ['apps/control-plane/src/supervisor/build-wave-executor.ts'],
+                  validation_status: 'valid',
+                  diff_snapshot: '.aop/features/feature_a/checkpoints/checkpoint-new.diff',
+                  diff_hash: 'diff-new',
+                },
+              ],
+            },
+          },
+        };
+      }
+      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.GATES_RUN) {
+        return { ok: true, data: { overall: GATE_RESULT.PASS } };
+      }
+      return { ok: true, data: {} };
+    });
+
+    await runtime.runBuildWave(['feature_a']);
+
+    expect(callTool).toHaveBeenCalledWith(
+      'builder',
+      TOOLS.GATES_RUN,
+      expect.objectContaining({ feature_id: 'feature_a', mode: 'fast' }),
+    );
+    expect(provider.createSession).not.toHaveBeenCalled();
+  });
+
   it('GIVEN_qa_features_WHEN_running_qa_wave_THEN_rotates_qa_session_and_updates_assignments', async () => {
     const { runtime, kernel, provider } = makeRuntime({ max_parallel_gate_runs: 1 });
     runtime.orchestratorSessionId = 'orch-main';
@@ -460,6 +638,136 @@ describe('SupervisorRuntime unit behavior', () => {
     });
   });
 
+  it('GIVEN_prior_active_run_history_WHEN_marking_run_started_THEN_interrupts_previous_run_and_reuses_existing_start_time', async () => {
+    const { runtime, kernel } = makeRuntime();
+    const nowSpy = vi.spyOn(CoreFs, 'nowIso').mockReturnValue('2026-03-14T12:00:00.000Z');
+    kernel.readState.mockResolvedValue({
+      frontMatter: {
+        version: 7,
+        run_history: [
+          {
+            run_id: 'older-run',
+            started_at: '2026-03-14T09:00:00.000Z',
+            ended_at: null,
+            status: 'active',
+          },
+          {
+            run_id: 'run:test',
+            started_at: '2026-03-14T08:00:00.000Z',
+            ended_at: '2026-03-14T08:30:00.000Z',
+            status: 'failed',
+          },
+        ],
+      },
+    });
+    kernel.updateState.mockImplementation(async (_featureId, _expectedVersion, updater) => ({
+      data: await updater({ version: 7 }, 'body'),
+    }));
+
+    await (runtime as any).markRunHistoryStarted('feature_a');
+
+    expect(kernel.updateState).toHaveBeenCalledWith('feature_a', 7, expect.any(Function));
+    const call = kernel.updateState.mock.calls[0];
+    const updated = await call[2]({ version: 7 }, 'body');
+    expect(updated.frontMatter.run_history).toEqual([
+      {
+        run_id: 'older-run',
+        started_at: '2026-03-14T09:00:00.000Z',
+        ended_at: '2026-03-14T12:00:00.000Z',
+        status: 'interrupted',
+      },
+      {
+        run_id: 'run:test',
+        started_at: '2026-03-14T08:00:00.000Z',
+        ended_at: null,
+        status: 'active',
+      },
+    ]);
+    nowSpy.mockRestore();
+  });
+
+  it('GIVEN_missing_current_run_history_WHEN_marking_run_ended_THEN_inserts_terminal_entry_using_phase_entered_at_and_timeout_status', async () => {
+    const { runtime, kernel } = makeRuntime();
+    const nowSpy = vi.spyOn(CoreFs, 'nowIso').mockReturnValue('2026-03-14T14:00:00.000Z');
+    kernel.readState.mockResolvedValue({
+      frontMatter: {
+        version: 4,
+        status: STATUS.BLOCKED,
+        status_reason: 'timeout while waiting for checkpoint freshness',
+        phase_entered_at: '2026-03-14T13:30:00.000Z',
+        run_history: [],
+      },
+    });
+    kernel.updateState.mockImplementation(async (_featureId, _expectedVersion, updater) => ({
+      data: await updater({ version: 4 }, 'body'),
+    }));
+
+    await (runtime as any).markRunHistoryEnded('feature_a');
+
+    const updated = await kernel.updateState.mock.calls[0][2]({ version: 4 }, 'body');
+    expect(updated.frontMatter.run_history).toEqual([
+      {
+        run_id: 'run:test',
+        started_at: '2026-03-14T13:30:00.000Z',
+        ended_at: '2026-03-14T14:00:00.000Z',
+        status: 'timeout',
+      },
+    ]);
+    nowSpy.mockRestore();
+  });
+
+  it('GIVEN_existing_current_run_WHEN_marking_run_ended_THEN_updates_entry_to_completed', async () => {
+    const { runtime, kernel } = makeRuntime();
+    const nowSpy = vi.spyOn(CoreFs, 'nowIso').mockReturnValue('2026-03-14T16:00:00.000Z');
+    kernel.readState.mockResolvedValue({
+      frontMatter: {
+        version: 9,
+        status: STATUS.MERGED,
+        run_history: [
+          {
+            run_id: 'run:test',
+            started_at: '2026-03-14T15:00:00.000Z',
+            ended_at: null,
+            status: 'active',
+          },
+        ],
+      },
+    });
+    kernel.updateState.mockImplementation(async (_featureId, _expectedVersion, updater) => ({
+      data: await updater({ version: 9 }, 'body'),
+    }));
+
+    await (runtime as any).markRunHistoryEnded('feature_a');
+
+    const updated = await kernel.updateState.mock.calls[0][2]({ version: 9 }, 'body');
+    expect(updated.frontMatter.run_history).toEqual([
+      {
+        run_id: 'run:test',
+        started_at: '2026-03-14T15:00:00.000Z',
+        ended_at: '2026-03-14T16:00:00.000Z',
+        status: 'completed',
+      },
+    ]);
+    nowSpy.mockRestore();
+  });
+
+  it('GIVEN_version_conflict_or_unexpected_write_failures_WHEN_marking_run_history_THEN_they_are_swallowed_best_effort', async () => {
+    const { runtime, kernel } = makeRuntime();
+    kernel.readState.mockResolvedValue({
+      frontMatter: {
+        version: 1,
+        run_history: [],
+      },
+    });
+    kernel.updateState.mockRejectedValueOnce({
+      normalizedResponse: { error: { code: 'version_conflict' } },
+    });
+    kernel.updateState.mockRejectedValueOnce(new Error('disk full'));
+
+    await expect((runtime as any).markRunHistoryStarted('feature_a')).resolves.toBeUndefined();
+    await expect((runtime as any).markRunHistoryEnded('feature_a')).resolves.toBeUndefined();
+  });
+
   it('GIVEN_active_sessions_WHEN_renewing_heartbeats_THEN_renews_lock_and_run_leases', async () => {
     const { runtime, kernel } = makeRuntime();
     runtime.sessionsByFeature.set('feature_a', {
@@ -539,9 +847,7 @@ describe('SupervisorRuntime delegation methods', () => {
       supervisor: { agent_idle_threshold_ms: 60000 },
     });
 
-    expect(
-      () => new SupervisorRuntime(kernel as any, provider as any, toolClient as any),
-    ).not.toThrow();
+    expect(() => new SupervisorRuntime(kernel, provider, toolClient)).not.toThrow();
   });
 
   it('GIVEN_planner_role_with_sessions_WHEN_calling_tool_THEN_uses_planner_session', async () => {
@@ -685,6 +991,7 @@ describe('SupervisorRuntime delegation methods', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch-old',
       orchestrator_epoch: 4,
       feature_sessions: {},
@@ -709,11 +1016,13 @@ describe('SupervisorRuntime delegation methods', () => {
   it('GIVEN_feature_id_WHEN_initializeFeatureCluster_called_THEN_delegates_to_session_orchestrator', async () => {
     const { runtime, provider, toolClient } = makeRuntime();
     runtime.orchestratorSessionId = 'orch-main';
+    runtime.reconcilerSessionId = 'reconciler-main';
     provider.createSession.mockResolvedValue({ session_id: 'created-session' });
     vi.spyOn(runtime, 'loadRolePrompts').mockResolvedValue({
       planner: { system: 'planner-prompt', tools: [], model_hint: null },
       builder: { system: 'builder-prompt', tools: [], model_hint: null },
       qa: { system: 'qa-prompt', tools: [], model_hint: null },
+      reconciler: { system: 'reconciler-prompt', tools: [], model_hint: null },
     } as never);
     toolClient.call.mockResolvedValue({
       ok: true,
@@ -722,7 +1031,7 @@ describe('SupervisorRuntime delegation methods', () => {
 
     await runtime.initializeFeatureCluster('feature_init');
 
-    // createSession should have been called for planner, builder, qa roles
+    // createSession should have been called for planner, builder, and qa roles only.
     expect(provider.createSession).toHaveBeenCalledTimes(3);
   });
 
@@ -751,7 +1060,9 @@ describe('SupervisorRuntime delegation methods', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'none',
       owner_instance_id: 'none',
+      provider: 'custom',
       orchestrator_session_id: null,
+      reconciler_session_id: 'unknown',
       orchestrator_epoch: 0,
       feature_sessions: {},
     });
@@ -763,7 +1074,7 @@ describe('SupervisorRuntime delegation methods', () => {
     } as any);
 
     await runtime.ensureGlobalOrchestratorSession();
-    expect(provider.createSession).toHaveBeenCalled();
+    expect(provider.createSession).toHaveBeenCalledTimes(3);
   });
 
   it('GIVEN_active_feature_ids_WHEN_cleanupOrphanWorkerSessions_called_THEN_delegates_to_session_orchestrator', async () => {
@@ -771,6 +1082,7 @@ describe('SupervisorRuntime delegation methods', () => {
     kernel.getRuntimeSessions.mockResolvedValue({
       run_id: 'run:test',
       owner_instance_id: 'owner:test',
+      provider: 'custom',
       orchestrator_session_id: 'orch-session',
       orchestrator_epoch: 1,
       feature_sessions: {},
@@ -878,7 +1190,7 @@ describe('SupervisorRuntime delegation methods', () => {
       supervisor: { max_iterations_per_phase: 10, max_parallel_gate_runs: 2 },
     });
     const runtime2 = new SupervisorRuntime(
-      kernel as any,
+      kernel,
       {
         selection: { provider: 'custom', model: 'm', provider_config_ref: null },
         createSession: vi.fn(),
@@ -942,6 +1254,61 @@ describe('BuildWaveExecutor branches', () => {
     const gateRuns = toolCaller.callTool.mock.calls.filter((c) => c[1] === TOOLS.GATES_RUN);
     expect(gateRuns).toHaveLength(1);
   });
+
+  it('GIVEN_failed_fast_gate_context_WHEN_build_wave_runs_THEN_initial_builder_uses_base_instructions', async () => {
+    const { BuildWaveExecutor } = await import('../src/supervisor/build-wave-executor.js');
+
+    const workerDecisionRunner = {
+      execute: vi.fn(async () => ({
+        planSubmission: false,
+        patchApplied: false,
+        noteLogged: false,
+        requestHandled: false,
+        priorityOrder: [] as string[],
+        toolResults: [],
+      })),
+    };
+    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: {
+              state: { front_matter: { gates: { fast: GATE_RESULT.FAIL } } },
+              latest_evidence: {
+                mode: 'fast',
+                overall: 'fail',
+                coverage_status: 'fail',
+                step_results: [{ name: 'test', exit_code: 1, log_path: '/nonexistent.log' }],
+              },
+            },
+          };
+        }
+        if (toolName === TOOLS.GATES_RUN) {
+          return { ok: true, data: { overall: 'pass', evidence_path: 'evidence.json' } };
+        }
+        return { ok: true, data: {} };
+      }),
+    };
+    const executor = new BuildWaveExecutor({
+      toolCaller: toolCaller as never,
+      workerDecisionRunner: workerDecisionRunner as never,
+    });
+
+    await executor.run(['feature_a'], 1);
+
+    const firstCallArgs = workerDecisionRunner.execute.mock.calls.at(0) as unknown as
+      | [{ instructions: string }]
+      | undefined;
+    // Initial builder run uses base instructions; failure analysis is injected in the repair loop
+    expect(firstCallArgs?.[0]?.instructions).toContain('Emit PATCH outputs');
+  });
 });
 
 describe('QaWaveExecutor gate run throws exception', () => {