agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/test/worker-provider-adapters.spec.ts

@@ -4,11 +4,18 @@ import path from 'node:path';
 import { describe, expect, it, vi } from 'vitest';
 import { ERROR_CODES } from '../src/core/error-codes.js';
 import { ApiWorkerProvider } from '../src/providers/api-worker-provider.js';
-import { CliWorkerProvider } from '../src/providers/cli-worker-provider.js';
-import type { ProviderCommandResult, ProviderSelection } from '../src/providers/providers.js';
+import {
+  CliWorkerProvider,
+  cliWorkerProviderTestExports,
+} from '../src/providers/cli-worker-provider.js';
+import type {
+  ProviderCommandResult,
+  ProviderCommandRunner,
+  ProviderSelection,
+} from '../src/providers/providers.js';
 import type { ProviderOutputParser } from '../src/providers/output-parsers/types.js';
 import type { WorkerOutputEnvelope } from '../src/providers/output-parsers/types.js';
-import { GenericCliOutputParser } from '../src/providers/output-parsers/generic-output-parser.js';
+import { GenericCliOutputParser } from '../src/providers/output-parsers/index.js';
 
 const parserContext = {
   sessionId: 'session-1',
@@ -32,6 +39,584 @@ function makeSelection(
   };
 }
 
+describe('cliWorkerProviderTestExports', () => {
+  it('GIVEN_non_record_context_WHEN_projectInteractiveContext_THEN_returns_null', () => {
+    expect(cliWorkerProviderTestExports.projectInteractiveContext(null)).toBeNull();
+  });
+
+  it('GIVEN_mixed_context_shapes_WHEN_projectInteractiveContext_THEN_normalizes_fallback_fields', () => {
+    const projected = cliWorkerProviderTestExports.projectInteractiveContext({
+      state: {
+        front_matter: {
+          status: 'intake',
+          status_reason: 'awaiting_input',
+          gate_profile: 'fast',
+          gates: 'invalid-shape',
+        },
+      },
+      plan: {
+        summary: 'Ship the telemetry dashboard.',
+        allowed_areas: 'packages/web-dashboard/src',
+        forbidden_areas: ['apps/control-plane/src/providers'],
+        files: 'invalid-shape',
+        acceptance_criteria: 'missing-array',
+      },
+      latest_evidence: {
+        overall: 'pass',
+        mode: 'fast',
+        status_reason: 'clean',
+        failed_steps: 'invalid-shape',
+      },
+      qa_test_index: {
+        pending: ['qa-001'],
+      },
+      intake: {
+        summary: 'invalid-shape',
+        bootstrap_manifest: 'invalid-shape',
+        verified_manifest: { manifest_version: '2.0.0' },
+        review: {
+          status: 'awaiting_input',
+          questions_open: 1,
+          questions_resolved: 0,
+          ambiguities: [
+            {
+              id: 'AMB-001',
+              summary: 'Derived USD remains optional.',
+              status: 'open',
+              obligation_ids: 'invalid-shape',
+            },
+            {
+              id: 'AMB-002',
+              summary: 'Closed ambiguity should be filtered out.',
+              status: 'resolved',
+              obligation_ids: ['OBL-001'],
+            },
+            null,
+          ],
+          clarification_answers: [
+            {
+              question_id: 'question-1',
+              ambiguity_ids: 'invalid-shape',
+              answer: 'Use tokens as the primary metric.',
+              answered_at: '2026-03-18T18:07:02.505Z',
+              resolution_status: 'candidate',
+            },
+            null,
+          ],
+        },
+      },
+    });
+
+    expect(projected).toEqual({
+      state: {
+        status: 'intake',
+        status_reason: 'awaiting_input',
+        gate_profile: 'fast',
+        gates: null,
+      },
+      accepted_plan: {
+        summary: 'Ship the telemetry dashboard.',
+        allowed_areas: [],
+        forbidden_areas: ['apps/control-plane/src/providers'],
+        files: null,
+        acceptance_criteria: [],
+      },
+      latest_evidence: {
+        overall: 'pass',
+        mode: 'fast',
+        status_reason: 'clean',
+        failed_steps: [],
+      },
+      qa_test_index: {
+        pending: ['qa-001'],
+      },
+      intake: {
+        summary: null,
+        bootstrap_manifest_version: null,
+        verified_manifest_version: '2.0.0',
+        review: {
+          status: 'awaiting_input',
+          questions_open: 1,
+          questions_resolved: 0,
+          open_ambiguities: [
+            {
+              id: 'AMB-001',
+              summary: 'Derived USD remains optional.',
+              obligation_ids: [],
+            },
+          ],
+          clarification_answers: [
+            {
+              question_id: 'question-1',
+              ambiguity_ids: [],
+              answer: 'Use tokens as the primary metric.',
+              answered_at: '2026-03-18T18:07:02.505Z',
+              resolution_status: 'candidate',
+            },
+          ],
+        },
+      },
+    });
+
+    expect(
+      cliWorkerProviderTestExports.projectInteractiveContext({
+        intake: {
+          summary: {},
+        },
+      }),
+    ).toEqual({
+      intake: {
+        summary: {},
+        bootstrap_manifest_version: null,
+        verified_manifest_version: null,
+        review: null,
+      },
+    });
+  });
+
+  it('GIVEN_nullish_projection_fields_WHEN_projectInteractiveContext_THEN_preserves_record_shapes_with_null_defaults', () => {
+    expect(
+      cliWorkerProviderTestExports.projectInteractiveContext({
+        state: {
+          front_matter: {
+            gates: {},
+          },
+        },
+        plan: {
+          acceptance_criteria: [],
+        },
+        latest_evidence: {
+          failed_steps: [],
+        },
+        intake: {
+          bootstrap_manifest: {},
+          verified_manifest: {},
+          review: {
+            ambiguities: [
+              {
+                status: 'open',
+                obligation_ids: ['OBL-777'],
+              },
+            ],
+            clarification_answers: [
+              {
+                ambiguity_ids: ['AMB-777'],
+              },
+            ],
+          },
+        },
+      }),
+    ).toEqual({
+      state: {
+        status: null,
+        status_reason: null,
+        gate_profile: null,
+        gates: {},
+      },
+      accepted_plan: {
+        summary: null,
+        allowed_areas: [],
+        forbidden_areas: [],
+        files: null,
+        acceptance_criteria: [],
+      },
+      latest_evidence: {
+        overall: null,
+        mode: null,
+        status_reason: null,
+        failed_steps: [],
+      },
+      intake: {
+        summary: null,
+        bootstrap_manifest_version: null,
+        verified_manifest_version: null,
+        review: {
+          status: null,
+          questions_open: null,
+          questions_resolved: null,
+          open_ambiguities: [
+            {
+              id: null,
+              summary: null,
+              obligation_ids: ['OBL-777'],
+            },
+          ],
+          clarification_answers: [
+            {
+              question_id: null,
+              ambiguity_ids: ['AMB-777'],
+              answer: null,
+              answered_at: null,
+              resolution_status: null,
+            },
+          ],
+        },
+      },
+    });
+  });
+
+  it('GIVEN_intake_state_without_explicit_phase_WHEN_buildInteractiveWorkerPrompt_THEN_infers_intake_contract_and_omits_optional_sections', () => {
+    const prompt = cliWorkerProviderTestExports.buildInteractiveWorkerPrompt(
+      {
+        role: 'planner',
+        feature_id: 'feature-intake',
+        repo_root: '/tmp/repo',
+        context_bundle: {
+          state: {
+            front_matter: {
+              status: 'intake',
+            },
+          },
+        },
+        instructions: 42,
+        last_tool_results: 'invalid-shape',
+        working_directory: 99,
+      },
+      null,
+    );
+
+    expect(prompt).toContain('Feature: feature-intake');
+    expect(prompt).toContain('Intake artifacts are on disk');
+    expect(prompt).toContain('Update the intake artifacts directly in the working directory.');
+    expect(prompt).not.toContain('Working directory (edit files here):');
+    expect(prompt).not.toContain('Instructions:');
+    expect(prompt).not.toContain('Recent tool results:');
+  });
+
+  it('GIVEN_non_string_prompt_fields_WHEN_buildInteractiveWorkerPrompt_THEN_uses_safe_empty_fallbacks', () => {
+    const prompt = cliWorkerProviderTestExports.buildInteractiveWorkerPrompt(
+      {
+        role: 7,
+        feature_id: 11,
+        repo_root: '/tmp/repo',
+        context_bundle: {},
+      },
+      null,
+    );
+
+    expect(prompt).toContain('You are the  agent running in interactive mode.');
+    expect(prompt).toContain('Feature: ');
+    expect(prompt).toContain('Edit files directly in the conflicted worktree.');
+    expect(prompt).not.toContain('Planning artifacts are on disk');
+    expect(prompt).not.toContain('Implementation artifacts are on disk');
+    expect(prompt).not.toContain('QA artifacts are on disk');
+    expect(prompt).not.toContain('Reconciliation artifacts are on disk');
+  });
+
+  it('GIVEN_builder_role_without_workingDir_WHEN_buildInteractiveWorkerPrompt_THEN_omits_staged_artifacts_section', () => {
+    const prompt = cliWorkerProviderTestExports.buildInteractiveWorkerPrompt(
+      {
+        role: 'builder',
+        feature_id: 'feat-no-worktree',
+        repo_root: '/tmp/repo',
+        context_bundle: {},
+        // working_directory intentionally omitted so workingDir is null
+      },
+      null,
+    );
+
+    expect(prompt).toContain('You are the builder agent running in interactive mode.');
+    expect(prompt).toContain('Feature: feat-no-worktree');
+    expect(prompt).not.toContain('Staged artifacts');
+    expect(prompt).toContain('Runtime artifacts:');
+    expect(prompt).toContain('/tmp/repo/.aop/features/feat-no-worktree/state.md');
+  });
+
+  it('GIVEN_template_helpers_WHEN_resolving_commands_THEN_apply_defaults_placeholders_env_and_capabilities', () => {
+    const selection = makeSelection('custom', {
+      provider_config_env: 'WORKER_TOKEN',
+      provider_config_ref: 'secret-token',
+      agent_config: {
+        command: ' worker-cli ',
+        args: ['run', '{prompt}'],
+        run_resume: {
+          command: 'resume-cli',
+          args: ['resume', '{session_id}'],
+        },
+        attach_command: 'attach-cli',
+        attach_args: ['attach', '{session_id}'],
+        send: {
+          command: 'send-cli',
+          args: ['send', '{message}'],
+        },
+      },
+      cli_extra_args: ['--json'],
+    });
+
+    expect(cliWorkerProviderTestExports.resolveRunTemplate(selection, false)).toEqual({
+      command: 'worker-cli',
+      args: ['run', '{prompt}', '--json'],
+    });
+    expect(cliWorkerProviderTestExports.resolveRunTemplate(selection, true)).toEqual({
+      command: 'resume-cli',
+      args: ['resume', '{session_id}', '--json'],
+    });
+    expect(cliWorkerProviderTestExports.resolveAttachTemplate(selection)).toEqual({
+      command: 'attach-cli',
+      args: ['attach', '{session_id}', '--json'],
+    });
+    expect(cliWorkerProviderTestExports.resolveSendTemplate(selection)).toEqual({
+      command: 'send-cli',
+      args: ['send', '{message}', '--json'],
+    });
+    expect(
+      cliWorkerProviderTestExports.resolveRunTemplate(
+        makeSelection('custom', {
+          agent_config: {
+            run: {
+              command: '   ',
+              args: ['ok', 1],
+            },
+          } as unknown as Record<string, unknown>,
+        }),
+        false,
+      ),
+    ).toBeUndefined();
+
+    expect(
+      cliWorkerProviderTestExports.applyTemplateArgs(
+        [
+          '{session_id}',
+          '{prompt}',
+          '{feature_id}',
+          '{role}',
+          '{message}',
+          '{output_last_message_path}',
+          '{model}',
+          'literal',
+        ],
+        {
+          sessionId: 'session-a',
+          prompt: 'do work',
+          featureId: 'feature-a',
+          role: 'planner',
+          message: undefined,
+          outputLastMessagePath: undefined,
+          model: undefined,
+        },
+      ),
+    ).toEqual(['session-a', 'do work', 'feature-a', 'planner', '', '', '', 'literal']);
+
+    const codexEnv = cliWorkerProviderTestExports.buildRunCommandEnv(selection);
+    expect(codexEnv['WORKER_TOKEN']).toBe('secret-token');
+
+    const originalClaudeCode = process.env['CLAUDECODE'];
+    const originalEntrypoint = process.env['CLAUDE_CODE_ENTRYPOINT'];
+    process.env['CLAUDECODE'] = 'nested-session';
+    process.env['CLAUDE_CODE_ENTRYPOINT'] = 'entry';
+    try {
+      const claudeEnv = cliWorkerProviderTestExports.buildRunCommandEnv(
+        makeSelection('claude', {
+          provider_config_env: 'WORKER_TOKEN',
+          provider_config_ref: 'secret-token',
+        }),
+      );
+      expect(claudeEnv['WORKER_TOKEN']).toBe('secret-token');
+      expect(claudeEnv).not.toHaveProperty('CLAUDECODE');
+      expect(claudeEnv).not.toHaveProperty('CLAUDE_CODE_ENTRYPOINT');
+    } finally {
+      if (originalClaudeCode === undefined) {
+        delete process.env['CLAUDECODE'];
+      } else {
+        process.env['CLAUDECODE'] = originalClaudeCode;
+      }
+      if (originalEntrypoint === undefined) {
+        delete process.env['CLAUDE_CODE_ENTRYPOINT'];
+      } else {
+        process.env['CLAUDE_CODE_ENTRYPOINT'] = originalEntrypoint;
+      }
+    }
+
+    expect(
+      cliWorkerProviderTestExports.resolveCliWorkerCapabilities(makeSelection('claude')),
+    ).toEqual({
+      supportsIdleDetection: false,
+      supportsSpawnDetection: true,
+    });
+    expect(
+      cliWorkerProviderTestExports.resolveCliWorkerCapabilities(makeSelection('codex')),
+    ).toEqual({
+      supportsIdleDetection: true,
+      supportsSpawnDetection: true,
+    });
+    expect(cliWorkerProviderTestExports.sanitizeClaudeProjectKey('/tmp/work tree')).toBe(
+      '-tmp-work-tree',
+    );
+    expect(
+      cliWorkerProviderTestExports.resolveClaudeTranscriptPath('/tmp/work tree', 'session-a'),
+    ).toContain(path.join('.claude', 'projects', '-tmp-work-tree', 'session-a.jsonl'));
+  });
+
+  it('GIVEN_claude_defaults_WHEN_resolving_attach_and_send_templates_THEN_both_resume_the_target_session', () => {
+    const selection = makeSelection('claude');
+
+    expect(cliWorkerProviderTestExports.resolveAttachTemplate(selection)).toEqual({
+      command: 'claude',
+      args: ['--dangerously-skip-permissions', '--resume', '{session_id}'],
+    });
+    expect(cliWorkerProviderTestExports.resolveSendTemplate(selection)).toEqual({
+      command: 'claude',
+      args: [
+        '--dangerously-skip-permissions',
+        '--resume',
+        '{session_id}',
+        '--print',
+        '--output-format',
+        'text',
+        '{message}',
+      ],
+    });
+  });
+
+  it('GIVEN_transcript_helper_inputs_WHEN_rendering_THEN_covers_progress_tool_and_user_fallback_paths', () => {
+    expect(cliWorkerProviderTestExports.collectClaudeTranscriptTextBlocks(null)).toEqual([]);
+    expect(
+      cliWorkerProviderTestExports.collectClaudeTranscriptTextBlocks([
+        { type: 'image', text: 'ignored' },
+        { type: 'text', text: 'first block' },
+        { type: 'text', text: '   ' },
+      ]),
+    ).toEqual(['first block']);
+
+    expect(
+      cliWorkerProviderTestExports.summarizeClaudeToolInput({ description: 'describe step' }),
+    ).toBe('describe step');
+    expect(cliWorkerProviderTestExports.summarizeClaudeToolInput({ command: 'npm test' })).toBe(
+      'npm test',
+    );
+    expect(
+      cliWorkerProviderTestExports.summarizeClaudeToolInput({ file_path: '/tmp/spec.md' }),
+    ).toBe('/tmp/spec.md');
+    expect(
+      cliWorkerProviderTestExports.summarizeClaudeToolInput({
+        pattern: 'needle',
+        path: '/tmp/repo',
+      }),
+    ).toBe('needle @ /tmp/repo');
+    expect(cliWorkerProviderTestExports.summarizeClaudeToolInput({ pattern: 'needle-only' })).toBe(
+      'needle-only',
+    );
+    expect(
+      cliWorkerProviderTestExports.summarizeClaudeToolInput({ specs: ['one', 'two', 3] }),
+    ).toBe('one, two');
+    expect(cliWorkerProviderTestExports.summarizeClaudeToolInput({})).toBeNull();
+
+    expect(cliWorkerProviderTestExports.renderClaudeTranscriptEntry({})).toEqual([]);
+
+    const rendered = cliWorkerProviderTestExports.renderClaudeTranscript(
+      [
+        '',
+        'not-json',
+        JSON.stringify({ type: 'progress', data: { type: 'token_stream' } }),
+        JSON.stringify({ type: 'assistant' }),
+        JSON.stringify({
+          type: 'assistant',
+          message: {
+            content: [
+              null,
+              { type: 'text', text: '   ' },
+              { type: 'tool_use', input: {} },
+              { type: 'tool_use', name: 'Describe', input: { description: 'describe step' } },
+              { type: 'tool_use', name: 'Shell', input: { command: 'npm test' } },
+              { type: 'tool_use', name: 'Read', input: { file_path: '/tmp/spec.md' } },
+              {
+                type: 'tool_use',
+                name: 'Search',
+                input: { pattern: 'needle', path: '/tmp/repo' },
+              },
+              { type: 'tool_use', name: 'Pattern', input: { pattern: 'needle-only' } },
+              { type: 'tool_use', name: 'Batch', input: { specs: ['one', 'two', 3] } },
+            ],
+          },
+        }),
+        JSON.stringify({
+          type: 'user',
+          message: {
+            content: [{ type: 'tool_result', content: [{ type: 'text', text: 'first block' }] }],
+          },
+        }),
+        JSON.stringify({
+          type: 'user',
+          message: {
+            content: [{ type: 'tool_result', content: 'plain result' }],
+          },
+        }),
+        JSON.stringify({
+          type: 'user',
+          message: {
+            content: [{ type: 'tool_result', content: { ignored: true } }],
+          },
+          toolUseResult: {
+            stdout: 'stdout fallback',
+            stderr: 'stderr fallback',
+          },
+        }),
+      ].join('\n'),
+    );
+
+    expect(rendered).toContain('[progress] token_stream');
+    expect(rendered).toContain('[tool] tool');
+    expect(rendered).toContain('[tool] Describe: describe step');
+    expect(rendered).toContain('[tool] Shell: npm test');
+    expect(rendered).toContain('[tool] Read: /tmp/spec.md');
+    expect(rendered).toContain('[tool] Search: needle @ /tmp/repo');
+    expect(rendered).toContain('[tool] Pattern: needle-only');
+    expect(rendered).toContain('[tool] Batch: one, two');
+    expect(rendered).toContain('first block');
+    expect(rendered).toContain('plain result');
+    expect(rendered).toContain('stdout fallback');
+    expect(rendered).toContain('stderr fallback');
+  });
+
+  it('GIVEN_watchdog_failure_shapes_WHEN_classifying_provider_errors_THEN_returns_specific_error_codes', () => {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      workerResponseTimeoutMs: 1000,
+    }) as unknown as {
+      classifyRunFailureErrorCode: (
+        result: ProviderCommandResult,
+        watchdogOutcome: {
+          reason: string;
+          timedOut: boolean;
+          idleForMs: number | null;
+          elapsedMs: number;
+        },
+      ) => string;
+    };
+
+    expect(
+      provider.classifyRunFailureErrorCode(
+        { exitCode: 1, signal: null },
+        { reason: 'spawn_timeout', timedOut: true, idleForMs: null, elapsedMs: 10 },
+      ),
+    ).toBe(ERROR_CODES.PROVIDER_SPAWN_TIMEOUT);
+    expect(
+      provider.classifyRunFailureErrorCode(
+        { exitCode: 1, signal: null },
+        { reason: 'idle_timeout', timedOut: true, idleForMs: 250, elapsedMs: 10 },
+      ),
+    ).toBe(ERROR_CODES.PROVIDER_STALL_TIMEOUT);
+    expect(
+      provider.classifyRunFailureErrorCode(
+        { exitCode: 1, signal: null },
+        { reason: 'hard_timeout', timedOut: true, idleForMs: null, elapsedMs: 10 },
+      ),
+    ).toBe(ERROR_CODES.PROVIDER_HARD_TIMEOUT);
+    expect(
+      provider.classifyRunFailureErrorCode(
+        { exitCode: 1, signal: 'SIGTERM' },
+        { reason: 'clean_exit', timedOut: false, idleForMs: null, elapsedMs: 10 },
+      ),
+    ).toBe(ERROR_CODES.PROVIDER_PROCESS_KILLED);
+    expect(
+      provider.classifyRunFailureErrorCode(
+        { exitCode: 1, signal: null },
+        { reason: 'clean_exit', timedOut: false, idleForMs: null, elapsedMs: 10 },
+      ),
+    ).toBe(ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE);
+  });
+});
+
 describe('GenericCliOutputParser', () => {
   it('GIVEN_empty_output_WHEN_parse_THEN_throws_provider_output_invalid', () => {
     const parser = new GenericCliOutputParser();
@@ -43,6 +628,26 @@ describe('GenericCliOutputParser', () => {
     }
   });
 
+  it('GIVEN_interactive_empty_output_WHEN_parse_THEN_returns_note_fallback', () => {
+    const parser = new GenericCliOutputParser();
+    const parsed = parser.parse('   ', {
+      ...parserContext,
+      executionMode: 'interactive',
+    });
+
+    expect(parsed.outputs).toEqual([
+      {
+        type: 'NOTE',
+        content: 'Interactive worker exited without a textual summary.',
+      },
+    ]);
+    expect(parsed.provider_meta).toEqual({
+      provider: parserContext.provider,
+      model: parserContext.model,
+      parse_fallback_reason: 'empty_output',
+    });
+  });
+
   it('GIVEN_invalid_json_WHEN_parse_THEN_throws_provider_output_invalid', () => {
     const parser = new GenericCliOutputParser();
     try {
@@ -53,6 +658,40 @@ describe('GenericCliOutputParser', () => {
     }
   });
 
+  it('GIVEN_prefixed_json_output_WHEN_parse_THEN_extracts_first_json_object', () => {
+    const parser = new GenericCliOutputParser();
+    const parsed = parser.parse(
+      [
+        'Now I have enough context. Let me produce the full implementation in patches.',
+        '',
+        '{"outputs":[{"type":"NOTE","content":"done"}]}',
+      ].join('\n'),
+      parserContext,
+    );
+
+    expect(parsed.outputs).toEqual([{ type: 'NOTE', content: 'done' }]);
+  });
+
+  it('GIVEN_interactive_plain_text_output_WHEN_parse_THEN_returns_note_fallback', () => {
+    const parser = new GenericCliOutputParser();
+    const parsed = parser.parse('Completed edits directly in worktree', {
+      ...parserContext,
+      executionMode: 'interactive',
+    });
+
+    expect(parsed.outputs).toEqual([
+      {
+        type: 'NOTE',
+        content: 'Completed edits directly in worktree',
+      },
+    ]);
+    expect(parsed.provider_meta).toEqual({
+      provider: parserContext.provider,
+      model: parserContext.model,
+      parse_fallback_reason: 'invalid_json',
+    });
+  });
+
   it('GIVEN_object_without_outputs_or_type_WHEN_parse_THEN_throws_provider_output_invalid', () => {
     const parser = new GenericCliOutputParser();
     try {
@@ -204,6 +843,98 @@ describe('ApiWorkerProvider', () => {
     expect(await provider.reattachSession('session-2')).toMatchObject({ session_id: 'session-2' });
     expect(await provider.closeSession('session-2')).toEqual({ closed: true });
   });
+
+  it('GIVEN_runtime_selection_with_different_provider_WHEN_runWorker_THEN_throws_invalid_argument', async () => {
+    const provider = new ApiWorkerProvider(makeSelection('gemini'), {
+      outputParser: new GenericCliOutputParser(),
+      workerResponseTimeoutMs: 1000,
+    });
+
+    try {
+      await provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-a',
+        runtime_selection: {
+          provider: 'codex',
+          model: 'codex-model',
+          provider_config_env: null,
+          provider_config_ref: null,
+          agent_config: null,
+        },
+      });
+      throw new Error('expected provider mismatch to throw');
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: ERROR_CODES.INVALID_ARGUMENT,
+        details: {
+          provider: 'gemini',
+          runtime_provider: 'codex',
+        },
+      });
+    }
+  });
+
+  it('GIVEN_runtime_selection_override_WHEN_runWorker_THEN_uses_override_model_and_falls_back_to_default_mock_config', async () => {
+    const parse = vi.fn(
+      (): WorkerOutputEnvelope => ({
+        session_id: 'builder-feature-runtime-api',
+        role: 'builder',
+        feature_id: 'feature-runtime',
+        outputs: [{ type: 'NOTE', content: 'runtime' }],
+        provider_meta: { provider: 'gemini', model: 'runtime-model' },
+      }),
+    );
+    const provider = new ApiWorkerProvider(
+      makeSelection('gemini', {
+        provider_config_env: 'GEMINI_TOKEN',
+        provider_config_ref: 'default-token',
+        agent_config: {
+          mock_response: {
+            outputs: [{ type: 'NOTE', content: 'runtime' }],
+          },
+        },
+      }),
+      {
+        outputParser: { parse },
+        workerResponseTimeoutMs: 1000,
+        workerSpawnTimeoutMs: 0,
+        workerIdleTimeoutMs: -1,
+        workerWatchdogPollIntervalMs: Number.NaN,
+        workerKillGracePeriodMs: 0,
+      },
+    );
+
+    await provider.runWorker({
+      role: 'builder',
+      feature_id: 'feature-runtime',
+      execution_mode: 'interactive',
+      runtime_selection: {
+        provider: 'gemini',
+        model: 'runtime-model',
+        provider_config_env: null,
+        provider_config_ref: 'runtime-token',
+        agent_config: 'not-an-object' as never,
+      },
+    });
+
+    expect(parse).toHaveBeenCalledWith(
+      JSON.stringify({
+        outputs: [{ type: 'NOTE', content: 'runtime' }],
+      }),
+      expect.objectContaining({
+        provider: 'gemini',
+        model: 'runtime-model',
+        executionMode: 'interactive',
+      }),
+    );
+    expect(provider.getCapabilities()).toEqual({
+      supportsInteractiveMode: false,
+      supportsWorkingDirectory: false,
+      supportsPauseResume: false,
+      supportsMessagePassing: false,
+      supportsAcknowledgment: false,
+    });
+  });
 });
 
 describe('CliWorkerProvider', () => {
@@ -278,7 +1009,14 @@ describe('CliWorkerProvider', () => {
     const firstCall = run.mock.calls.at(0);
     expect(firstCall).toBeDefined();
     expect(firstCall?.[0]).toBe('codex');
-    expect(firstCall?.[1]).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox']);
+    expect(firstCall?.[1]).toEqual([
+      'exec',
+      '--dangerously-bypass-approvals-and-sandbox',
+      '--output-last-message',
+      expect.stringMatching(/last-message\.txt$/),
+      '--disable',
+      'apps',
+    ]);
     const options = firstCall?.[2] as
       | { stdin?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv }
       | undefined;
@@ -288,6 +1026,59 @@ describe('CliWorkerProvider', () => {
     expect(parse).toHaveBeenCalledTimes(1);
   });
 
+  it('GIVEN_codex_output_last_message_file_WHEN_stdout_is_empty_THEN_parses_captured_last_message', async () => {
+    const parse = vi.fn(
+      (): WorkerOutputEnvelope => ({
+        session_id: 'builder-feature-last-message',
+        role: 'builder',
+        feature_id: 'feature-last-message',
+        outputs: [{ type: 'NOTE', content: 'captured from file' }],
+        provider_meta: { provider: 'codex', model: 'codex-model' },
+      }),
+    );
+    const run = vi.fn(async (_command: string, args: string[]): Promise<ProviderCommandResult> => {
+      const outputFlagIndex = args.indexOf('--output-last-message');
+      const outputPath =
+        outputFlagIndex >= 0 && typeof args[outputFlagIndex + 1] === 'string'
+          ? args[outputFlagIndex + 1]
+          : null;
+      expect(outputPath).toMatch(/last-message\.txt$/);
+      if (outputPath) {
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+        await fs.writeFile(outputPath, '{"type":"NOTE","content":"captured from file"}', 'utf8');
+      }
+      return {
+        exitCode: 0,
+        signal: null,
+        stdout: '',
+      };
+    });
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: { parse },
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('builder', 'feature-last-message', 'prompt');
+    const result = await provider.runWorker({
+      role: 'builder',
+      feature_id: 'feature-last-message',
+    });
+
+    expect(result).toMatchObject({
+      role: 'builder',
+      feature_id: 'feature-last-message',
+    });
+    expect(parse).toHaveBeenCalledWith(
+      '{"type":"NOTE","content":"captured from file"}',
+      expect.objectContaining({
+        role: 'builder',
+        featureId: 'feature-last-message',
+        provider: 'codex',
+      }),
+    );
+  });
+
   it('GIVEN_working_directory_WHEN_runWorker_THEN_command_runner_receives_cwd', async () => {
     const run = vi.fn(
       async (
@@ -305,6 +1096,7 @@ describe('CliWorkerProvider', () => {
     const provider = new CliWorkerProvider(makeSelection('codex'), {
       outputParser: new GenericCliOutputParser(),
       commandRunner: { run },
+      repoRoot: '/tmp/repo',
       workerResponseTimeoutMs: 2_000,
     });
 
@@ -316,11 +1108,17 @@ describe('CliWorkerProvider', () => {
       working_directory: '/tmp/feature-a-worktree',
     });
 
-    const options = run.mock.calls.at(0)?.[2] as { cwd?: string } | undefined;
+    const options = run.mock.calls.at(0)?.[2] as { cwd?: string; stdin?: string } | undefined;
     expect(options?.cwd).toBe('/tmp/feature-a-worktree');
+    expect(options?.stdin).toContain('interactive mode');
+    expect(options?.stdin).toContain('Edit files directly in the working directory');
+    expect(options?.stdin).toContain('/tmp/feature-a-worktree');
+    expect(options?.stdin).toContain('plan.md');
+    expect(options?.stdin).toContain('decisions.md');
+    expect(options?.stdin).not.toContain('Execution context summary:');
   });
 
-  it('GIVEN_claude_selection_WHEN_runWorker_THEN_passes_prompt_via_stdin_only', async () => {
+  it('GIVEN_interactive_builder_with_instructions_and_tool_results_WHEN_runWorker_THEN_prompt_includes_both_sections', async () => {
     const run = vi.fn(
       async (
         _command: string,
@@ -334,32 +1132,41 @@ describe('CliWorkerProvider', () => {
         }),
       }),
     );
-
-    const provider = new CliWorkerProvider(makeSelection('claude'), {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
       outputParser: new GenericCliOutputParser(),
       commandRunner: { run },
-      workerResponseTimeoutMs: 2222,
+      repoRoot: '/tmp/repo',
+      workerResponseTimeoutMs: 2_000,
     });
 
-    await provider.createSession('planner', 'feature-a', 'prompt');
+    await provider.createSession('builder', 'feature-b', null);
     await provider.runWorker({
-      role: 'planner',
-      feature_id: 'feature-a',
-      instructions: 'do work',
+      role: 'builder',
+      feature_id: 'feature-b',
+      execution_mode: 'interactive',
+      instructions: 'Apply the fix set.',
+      context_bundle: {
+        state: { front_matter: { status: 'building', gate_profile: 'default' } },
+        plan: {
+          summary: 'Ship the launch flow.',
+          allowed_areas: ['packages/web-dashboard/src/'],
+          files: { modify: ['packages/web-dashboard/src/app/page.tsx'] },
+        },
+      },
+      last_tool_results: [{ tool: 'repo.status', ok: true }] as never,
+      working_directory: '/tmp/feature-b-worktree',
     });
 
-    expect(run).toHaveBeenCalledTimes(1);
-    const firstCall = run.mock.calls.at(0);
-    expect(firstCall?.[0]).toBe('claude');
-    expect(firstCall?.[1]).toEqual(['--print', '--output-format', 'text']);
-    const options = firstCall?.[2] as
-      | { stdin?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv }
-      | undefined;
-    expect(options?.timeoutMs).toBe(4722);
-    expect(options?.stdin).toContain('"feature_id":"feature-a"');
+    const options = run.mock.calls.at(0)?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain('Instructions:');
+    expect(options?.stdin).toContain('Apply the fix set.');
+    expect(options?.stdin).toContain('Execution context summary:');
+    expect(options?.stdin).toContain('"Ship the launch flow."');
+    expect(options?.stdin).toContain('Recent tool results:');
+    expect(options?.stdin).toContain('"tool":"repo.status"');
   });
 
-  it('GIVEN_system_prompt_passed_to_createSession_WHEN_runWorker_THEN_system_prompt_prepended_to_stdin', async () => {
+  it('GIVEN_interactive_qa_run_WHEN_runWorker_THEN_prompt_uses_qa_specific_execution_contract', async () => {
     const run = vi.fn(
       async (
         _command: string,
@@ -368,7 +1175,473 @@ describe('CliWorkerProvider', () => {
       ): Promise<ProviderCommandResult> => ({
         exitCode: 0,
         signal: null,
-        stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'qa complete' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      repoRoot: '/tmp/repo',
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('qa', 'feature-qa', null);
+    await provider.runWorker({
+      role: 'qa',
+      feature_id: 'feature-qa',
+      execution_mode: 'interactive',
+      working_directory: '/tmp/feature-qa-worktree',
+    });
+
+    const options = run.mock.calls.at(0)?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain('QA artifacts are on disk');
+    expect(options?.stdin).toContain('qa_test_index.json');
+    expect(options?.stdin).toContain(
+      'Use plan.json, qa_test_index.json, and the latest evidence as your verification contract.',
+    );
+    expect(options?.stdin).toContain('question_type":"risk_ack"');
+  });
+
+  it('GIVEN_interactive_reconciler_run_WHEN_runWorker_THEN_prompt_uses_reconciler_specific_execution_contract', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'reconciled' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      repoRoot: '/tmp/repo',
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('reconciler', 'feature-reconcile', null);
+    await provider.runWorker({
+      role: 'reconciler',
+      feature_id: 'feature-reconcile',
+      execution_mode: 'interactive',
+      working_directory: '/tmp/feature-reconcile-worktree',
+    });
+
+    const options = run.mock.calls.at(0)?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain('Reconciliation artifacts are on disk');
+    expect(options?.stdin).toContain(
+      'Use spec.md, state.md, plan.json, and approved collision context as your reconciliation contract.',
+    );
+    expect(options?.stdin).toContain(
+      'Return REQUEST.action=ask_user_input only when preserving mainline semantics and feature intent requires an operator choice.',
+    );
+    expect(options?.stdin).not.toContain(
+      'Use the accepted plan as your execution contract and keep changes inside planned paths.',
+    );
+  });
+
+  it('GIVEN_planner_interactive_run_WHEN_runWorker_THEN_prompt_uses_plan_artifact_pointers', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'planning complete' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      repoRoot: '/tmp/repo',
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('planner', 'feature-a', 'You are the planner role.');
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-a',
+      execution_mode: 'interactive',
+      working_directory: '/tmp/repo/.aop/features/feature-a',
+    });
+
+    const options = run.mock.calls.at(0)?.[2] as { cwd?: string; stdin?: string } | undefined;
+    expect(options?.cwd).toBe('/tmp/repo/.aop/features/feature-a');
+    expect(options?.stdin).toContain('/tmp/repo/.aop/features/feature-a/plan.md');
+    expect(options?.stdin).toContain('/tmp/repo/.aop/features/feature-a/plan.json');
+    expect(options?.stdin).toContain('PLAN_SUBMISSION');
+    expect(options?.stdin).toContain(
+      'Update the planning artifacts directly in the working directory.',
+    );
+  });
+
+  it('GIVEN_planner_interactive_run_without_repo_root_WHEN_runWorker_THEN_prompt_uses_alignment_fallback_text', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'planning complete' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('planner', 'feature-a', 'You are the planner role.');
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-a',
+      execution_mode: 'interactive',
+      working_directory: '/tmp/repo/.aop/features/feature-a',
+    });
+
+    const options = run.mock.calls.at(0)?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain(
+      'Keep plan.md aligned with the planning state and any plan_json you return.',
+    );
+    expect(options?.stdin).not.toContain('/plan.md');
+  });
+
+  it('GIVEN_planner_intake_interactive_run_WHEN_runWorker_THEN_prompt_uses_intake_submission_contract', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'intake observed' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      repoRoot: '/tmp/repo',
+      workerResponseTimeoutMs: 2_000,
+    });
+
+    await provider.createSession('planner', 'feature-intake', 'You are the intake planner.');
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-intake',
+      execution_mode: 'interactive',
+      planner_phase: 'intake',
+      working_directory: '/tmp/repo/.aop/features/feature-intake',
+      context_bundle: {
+        intake: {
+          review: {
+            status: 'awaiting_input',
+            questions_open: 0,
+            questions_resolved: 1,
+            ambiguities: [
+              {
+                id: 'AMB-110',
+                summary: 'Derived USD remains optional and secondary.',
+                status: 'open',
+              },
+            ],
+            clarification_answers: [
+              {
+                question_id: 'q_answered',
+                ambiguity_ids: ['AMB-110'],
+                answer: 'Derived USD is optional and secondary; token metrics are primary.',
+                answered_at: '2026-03-18T18:07:02.505Z',
+                resolution_status: 'candidate',
+              },
+            ],
+          },
+        },
+      },
+    });
+
+    const options = run.mock.calls.at(0)?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain(
+      'questions.json               — persisted intake clarification questions and answers',
+    );
+    expect(options?.stdin).toContain(
+      'Update the intake artifacts directly in the working directory.',
+    );
+    expect(options?.stdin).toContain('"type":"INTAKE_SUBMISSION"');
+    expect(options?.stdin).toContain(
+      'Do not emit PLAN_SUBMISSION while operating in the intake planner phase.',
+    );
+    expect(options?.stdin).toContain('clarification_answers');
+    expect(options?.stdin).toContain(
+      'Derived USD is optional and secondary; token metrics are primary.',
+    );
+    expect(options?.stdin).not.toContain(
+      'Update the planning artifacts directly in the working directory.',
+    );
+  });
+
+  it('GIVEN_claude_selection_WHEN_runWorker_THEN_passes_prompt_via_stdin_only', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'ok' }],
+        }),
+      }),
+    );
+
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2222,
+    });
+
+    await provider.createSession('planner', 'feature-a', 'prompt');
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-a',
+      instructions: 'do work',
+    });
+
+    expect(run).toHaveBeenCalledTimes(1);
+    const firstCall = run.mock.calls.at(0);
+    expect(firstCall?.[0]).toBe('claude');
+    expect(firstCall?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--session-id',
+      expect.any(String),
+      '--print',
+      '--output-format',
+      'text',
+    ]);
+    const options = firstCall?.[2] as
+      | { stdin?: string; timeoutMs?: number; env?: NodeJS.ProcessEnv }
+      | undefined;
+    expect(options?.timeoutMs).toBe(4722);
+    expect(options?.stdin).toContain('"feature_id":"feature-a"');
+  });
+
+  it('GIVEN_claude_selection_without_precreated_session_WHEN_runWorker_THEN_allocates_uuid_session_id', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'ok' }],
+        }),
+      }),
+    );
+
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2222,
+    });
+
+    await provider.runWorker({
+      role: 'orchestrator',
+      feature_id: 'global',
+      instructions: 'do work',
+    });
+
+    const firstCall = run.mock.calls.at(0);
+    const sessionId = firstCall?.[1]?.[2];
+    expect(typeof sessionId).toBe('string');
+    expect(sessionId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+    const options = firstCall?.[2] as { stdin?: string } | undefined;
+    expect(options?.stdin).toContain(`"session_id":"${sessionId}"`);
+  });
+
+  it('GIVEN_claude_session_with_successful_prior_run_WHEN_runWorker_again_THEN_resumes_existing_session', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'ok' }],
+        }),
+      }),
+    );
+
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2222,
+    });
+
+    const session = await provider.createSession('planner', 'feature-resume', 'prompt');
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-resume',
+      instructions: 'first pass',
+    });
+    await provider.runWorker({
+      role: 'planner',
+      feature_id: 'feature-resume',
+      instructions: 'second pass',
+    });
+
+    expect(run).toHaveBeenCalledTimes(2);
+    expect(run.mock.calls.at(0)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--session-id',
+      session.session_id,
+      '--print',
+      '--output-format',
+      'text',
+    ]);
+    expect(run.mock.calls.at(1)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--resume',
+      session.session_id,
+      '--print',
+      '--output-format',
+      'text',
+    ]);
+  });
+
+  it('GIVEN_claude_session_with_persisted_transcript_WHEN_runWorker_THEN_resumes_existing_session', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-claude-resume-'));
+    const claudeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-claude-home-'));
+    const workingDirectory = path.join(repoRoot, '.aop', 'features', 'feature-claude-resume');
+    await fs.mkdir(workingDirectory, { recursive: true });
+
+    const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(claudeHome);
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({
+          outputs: [{ type: 'NOTE', content: 'ok' }],
+        }),
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 2222,
+    });
+
+    try {
+      const session = await provider.createSession('planner', 'feature-claude-resume', 'prompt');
+      const transcriptPath = path.join(
+        claudeHome,
+        '.claude',
+        'projects',
+        workingDirectory.replace(/[^A-Za-z0-9]/g, '-'),
+        `${session.session_id}.jsonl`,
+      );
+      await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+      await fs.writeFile(transcriptPath, '{"type":"assistant","message":{"content":[]}}\n', 'utf8');
+
+      await provider.runWorker({
+        role: 'planner',
+        feature_id: 'feature-claude-resume',
+        instructions: 'resume persisted session',
+        working_directory: workingDirectory,
+      });
+
+      expect(run).toHaveBeenCalledTimes(1);
+      expect(run.mock.calls.at(0)?.[1]).toEqual([
+        '--dangerously-skip-permissions',
+        '--resume',
+        session.session_id,
+        '--print',
+        '--output-format',
+        'text',
+      ]);
+    } finally {
+      homedirSpy.mockRestore();
+      await fs.rm(repoRoot, { recursive: true, force: true });
+      await fs.rm(claudeHome, { recursive: true, force: true });
+    }
+  });
+
+  it('GIVEN_claude_selection_WHEN_runWorker_THEN_CLAUDECODE_stripped_from_env', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+      }),
+    );
+
+    const originalClaudeCode = process.env['CLAUDECODE'];
+    const originalEntrypoint = process.env['CLAUDE_CODE_ENTRYPOINT'];
+    process.env['CLAUDECODE'] = 'test-session-id';
+    process.env['CLAUDE_CODE_ENTRYPOINT'] = 'cli';
+    try {
+      const provider = new CliWorkerProvider(makeSelection('claude'), {
+        outputParser: new GenericCliOutputParser(),
+        commandRunner: { run },
+        workerResponseTimeoutMs: 2000,
+      });
+      await provider.createSession('builder', 'feature-b', null);
+      await provider.runWorker({ role: 'builder', feature_id: 'feature-b', instructions: 'work' });
+    } finally {
+      if (originalClaudeCode === undefined) {
+        delete process.env['CLAUDECODE'];
+      } else {
+        process.env['CLAUDECODE'] = originalClaudeCode;
+      }
+      if (originalEntrypoint === undefined) {
+        delete process.env['CLAUDE_CODE_ENTRYPOINT'];
+      } else {
+        process.env['CLAUDE_CODE_ENTRYPOINT'] = originalEntrypoint;
+      }
+    }
+
+    const callOptions = run.mock.calls.at(0)?.[2] as { env?: NodeJS.ProcessEnv } | undefined;
+    expect(callOptions?.env).not.toHaveProperty('CLAUDECODE');
+    expect(callOptions?.env).not.toHaveProperty('CLAUDE_CODE_ENTRYPOINT');
+  });
+
+  it('GIVEN_system_prompt_passed_to_createSession_WHEN_runWorker_THEN_system_prompt_prepended_to_stdin', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
       }),
     );
     const provider = new CliWorkerProvider(makeSelection('claude'), {
@@ -445,16 +1718,155 @@ describe('CliWorkerProvider', () => {
     expect(stdin).toMatch(/^Return exactly one JSON object/);
   });
 
-  it('GIVEN_raw_logs_enabled_WHEN_runWorker_succeeds_THEN_stdout_is_persisted', async () => {
-    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-raw-logs-'));
-    const provider = new CliWorkerProvider(makeSelection('codex'), {
+  it('GIVEN_raw_logs_enabled_WHEN_runWorker_succeeds_THEN_stdout_is_persisted', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-raw-logs-'));
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(async () => ({
+          exitCode: 0,
+          signal: null,
+          stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+        })),
+      },
+      repoRoot,
+      rawAgentLogsEnabled: true,
+      rawAgentLogsRetentionDays: 60,
+      workerResponseTimeoutMs: 1000,
+    });
+
+    try {
+      await provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-raw',
+      });
+
+      const logsDir = path.join(repoRoot, '.aop', 'features', 'feature-raw', 'logs');
+      const files = await fs.readdir(logsDir);
+      expect(files.some((file) => /^builder-\d{13}\.txt$/.test(file))).toBe(true);
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('GIVEN_raw_logs_enabled_WHEN_worker_emits_chunks_THEN_live_console_artifact_is_updated', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-live-console-'));
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(async (_command, _args, options) => {
+          const typedOptions = options as {
+            onOutputChunk?: (chunk: { stream: 'stdout' | 'stderr'; text: string }) => void;
+          };
+          typedOptions.onOutputChunk?.({ stream: 'stdout', text: 'Thinking...\n' });
+          typedOptions.onOutputChunk?.({ stream: 'stdout', text: 'Done.\n' });
+          return {
+            exitCode: 0,
+            signal: null,
+            stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+          };
+        }),
+      },
+      repoRoot,
+      rawAgentLogsEnabled: true,
+      rawAgentLogsRetentionDays: 60,
+      workerResponseTimeoutMs: 1000,
+    });
+
+    try {
+      await provider.createSession('planner', 'feature-live', 'Prompt');
+      await provider.runWorker({
+        role: 'planner',
+        feature_id: 'feature-live',
+      });
+
+      const liveDir = path.join(repoRoot, '.aop', 'features', 'feature-live', 'logs', 'live');
+      const [content, metadataRaw] = await Promise.all([
+        fs.readFile(path.join(liveDir, 'planner.txt'), 'utf8'),
+        fs.readFile(path.join(liveDir, 'planner.json'), 'utf8'),
+      ]);
+      const metadata = JSON.parse(metadataRaw) as { status?: string; provider?: string };
+
+      expect(content).toContain('Thinking...');
+      expect(content).toContain('Done.');
+      expect(metadata.status).toBe('completed');
+      expect(metadata.provider).toBe('codex');
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('GIVEN_claude_raw_logs_enabled_WHEN_transcript_updates_THEN_live_console_mirrors_transcript', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-live-claude-'));
+    const claudeHome = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-claude-home-'));
+    const workingDirectory = path.join(repoRoot, '.aop', 'features', 'feature-live-claude');
+    await fs.mkdir(workingDirectory, { recursive: true });
+
+    const homedirSpy = vi.spyOn(os, 'homedir').mockReturnValue(claudeHome);
+    let sessionId = '';
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
       outputParser: new GenericCliOutputParser(),
       commandRunner: {
-        run: vi.fn(async () => ({
-          exitCode: 0,
-          signal: null,
-          stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
-        })),
+        run: vi.fn(async (_command, args) => {
+          expect(args).toEqual(
+            expect.arrayContaining([
+              '--session-id',
+              sessionId,
+              '--print',
+              '--output-format',
+              'text',
+            ]),
+          );
+
+          const transcriptPath = path.join(
+            claudeHome,
+            '.claude',
+            'projects',
+            workingDirectory.replace(/[^A-Za-z0-9]/g, '-'),
+            `${sessionId}.jsonl`,
+          );
+          await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+          await fs.writeFile(
+            transcriptPath,
+            [
+              JSON.stringify({
+                type: 'progress',
+                data: {
+                  type: 'hook_progress',
+                  hookEvent: 'SessionStart',
+                  hookName: 'SessionStart:startup',
+                },
+              }),
+              JSON.stringify({
+                type: 'assistant',
+                message: {
+                  content: [
+                    { type: 'tool_use', name: 'Read', input: { file_path: '/tmp/spec.md' } },
+                  ],
+                },
+              }),
+              JSON.stringify({
+                type: 'user',
+                message: {
+                  content: [{ type: 'tool_result', content: 'spec content' }],
+                },
+              }),
+              JSON.stringify({
+                type: 'assistant',
+                message: {
+                  content: [{ type: 'text', text: 'Done.' }],
+                },
+              }),
+            ].join('\n'),
+            'utf8',
+          );
+          await new Promise((resolve) => setTimeout(resolve, 700));
+          return {
+            exitCode: 0,
+            signal: null,
+            stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+          };
+        }),
       },
       repoRoot,
       rawAgentLogsEnabled: true,
@@ -463,16 +1875,40 @@ describe('CliWorkerProvider', () => {
     });
 
     try {
+      const session = await provider.createSession('planner', 'feature-live-claude', 'Prompt');
+      sessionId = session.session_id;
+
       await provider.runWorker({
-        role: 'builder',
-        feature_id: 'feature-raw',
+        role: 'planner',
+        feature_id: 'feature-live-claude',
+        working_directory: workingDirectory,
       });
 
-      const logsDir = path.join(repoRoot, '.aop', 'features', 'feature-raw', 'logs');
-      const files = await fs.readdir(logsDir);
-      expect(files.some((file) => /^builder-\d{13}\.txt$/.test(file))).toBe(true);
+      const liveDir = path.join(
+        repoRoot,
+        '.aop',
+        'features',
+        'feature-live-claude',
+        'logs',
+        'live',
+      );
+      const [content, metadataRaw] = await Promise.all([
+        fs.readFile(path.join(liveDir, 'planner.txt'), 'utf8'),
+        fs.readFile(path.join(liveDir, 'planner.json'), 'utf8'),
+      ]);
+      const metadata = JSON.parse(metadataRaw) as { status?: string; provider?: string };
+
+      expect(content).toContain('[progress] SessionStart');
+      expect(content).toContain('[tool] Read: /tmp/spec.md');
+      expect(content).toContain('spec content');
+      expect(content).toContain('Done.');
+      expect(content).not.toContain('"outputs"');
+      expect(metadata.status).toBe('completed');
+      expect(metadata.provider).toBe('claude');
     } finally {
+      homedirSpy.mockRestore();
       await fs.rm(repoRoot, { recursive: true, force: true });
+      await fs.rm(claudeHome, { recursive: true, force: true });
     }
   });
 
@@ -569,6 +2005,122 @@ describe('CliWorkerProvider', () => {
     });
   });
 
+  it('GIVEN_runtime_selection_override_WHEN_runWorker_THEN_applies_model_feature_role_placeholders_and_override_env', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => {
+        const typedOptions = options as {
+          onLifecycleEvent?: (event: {
+            type: 'spawned' | 'activity' | 'heartbeat' | 'terminated';
+          }) => void;
+          registerKill?: (kill: (signal: 'SIGTERM' | 'SIGKILL') => void) => void;
+        };
+        typedOptions.registerKill?.(vi.fn());
+        typedOptions.onLifecycleEvent?.({ type: 'spawned' });
+        typedOptions.onLifecycleEvent?.({ type: 'activity' });
+        return {
+          exitCode: 0,
+          signal: null,
+          stdout: JSON.stringify({
+            outputs: [{ type: 'NOTE', content: 'ok' }],
+          }),
+        };
+      },
+    );
+    const provider = new CliWorkerProvider(
+      makeSelection('custom', {
+        provider_config_env: 'DEFAULT_TOKEN_ENV',
+        provider_config_ref: 'default-token',
+        agent_config: {
+          run_command: 'worker-cli',
+          run_args: ['run', '{feature_id}', '{role}', '{model}', '{prompt}'],
+        },
+      }),
+      {
+        outputParser: new GenericCliOutputParser(),
+        commandRunner: { run },
+        workerResponseTimeoutMs: 1_000,
+      },
+    );
+
+    await provider.runWorker({
+      role: 'builder',
+      feature_id: 'feature-runtime-override',
+      instructions: 'Ship it.',
+      runtime_selection: {
+        provider: 'custom',
+        model: 'runtime-model',
+        provider_config_env: 'RUNTIME_TOKEN_ENV',
+        provider_config_ref: 'runtime-token',
+        agent_config: null,
+      },
+    });
+
+    const call = run.mock.calls.at(0);
+    expect(call?.[0]).toBe('worker-cli');
+    expect(call?.[1]).toEqual([
+      'run',
+      'feature-runtime-override',
+      'builder',
+      'runtime-model',
+      expect.stringContaining('"feature_id":"feature-runtime-override"'),
+    ]);
+    const options = call?.[2] as { env?: NodeJS.ProcessEnv } | undefined;
+    expect(options?.env?.RUNTIME_TOKEN_ENV).toBe('runtime-token');
+  });
+
+  it('GIVEN_runtime_selection_with_different_provider_WHEN_runWorker_THEN_throws_invalid_argument', async () => {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(),
+      },
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    await expect(
+      provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-mismatch',
+        runtime_selection: {
+          provider: 'claude',
+          model: 'claude-model',
+          provider_config_env: null,
+          provider_config_ref: null,
+          agent_config: null,
+        },
+      }),
+    ).rejects.toMatchObject({
+      code: ERROR_CODES.INVALID_ARGUMENT,
+      details: {
+        provider: 'codex',
+        runtime_provider: 'claude',
+      },
+    });
+  });
+
+  it('GIVEN_command_runner_rejects_WHEN_runWorker_THEN_original_error_bubbles_after_watchdog_cleanup', async () => {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(async () => {
+          throw new Error('runner exploded');
+        }),
+      },
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    await expect(
+      provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-runner-error',
+      }),
+    ).rejects.toThrow('runner exploded');
+  });
+
   it('GIVEN_attach_and_send_templates_WHEN_commands_succeed_THEN_methods_are_available', async () => {
     const run = vi.fn(
       async (
@@ -651,6 +2203,94 @@ describe('CliWorkerProvider', () => {
     });
   });
 
+  it('GIVEN_claude_control_commands_WHEN_attach_and_send_are_called_THEN_both_target_the_requested_session', async () => {
+    const run = vi.fn(
+      async (
+        _command: string,
+        _args: string[],
+        _options?: Record<string, unknown>,
+      ): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: '{}',
+      }),
+    );
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 1000,
+    });
+
+    await provider.attachToSession?.('session-a');
+    await provider.sendMessage?.('session-a', 'hello');
+
+    expect(run.mock.calls.at(0)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--resume',
+      'session-a',
+    ]);
+    expect(run.mock.calls.at(1)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--resume',
+      'session-a',
+      '--print',
+      '--output-format',
+      'text',
+      'hello',
+    ]);
+  });
+
+  it('GIVEN_missing_claude_conversation_WHEN_send_called_THEN_bootstraps_the_session_with_the_stored_prompt', async () => {
+    const run = vi
+      .fn<
+        (
+          _command: string,
+          _args: string[],
+          _options?: Record<string, unknown>,
+        ) => Promise<ProviderCommandResult>
+      >()
+      .mockResolvedValueOnce({
+        exitCode: 1,
+        signal: null,
+        stderr: 'Error: No conversation found with session ID: session-a\n',
+      })
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        stdout: '{}',
+      });
+    const provider = new CliWorkerProvider(makeSelection('claude'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: { run },
+      workerResponseTimeoutMs: 1000,
+    });
+
+    const session = await provider.createSession('reconciler', 'global', 'system prompt');
+    await provider.sendMessage?.(session.session_id, 'resolve the conflict');
+
+    expect(run).toHaveBeenCalledTimes(2);
+    expect(run.mock.calls.at(0)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--resume',
+      session.session_id,
+      '--print',
+      '--output-format',
+      'text',
+      'resolve the conflict',
+    ]);
+    expect(run.mock.calls.at(1)?.[1]).toEqual([
+      '--dangerously-skip-permissions',
+      '--session-id',
+      session.session_id,
+      '--print',
+      '--output-format',
+      'text',
+    ]);
+    expect(run.mock.calls.at(1)?.[2]).toMatchObject({
+      stdin: 'system prompt\n---\nresolve the conflict',
+    });
+  });
+
   it('GIVEN_send_command_general_failure_WHEN_send_called_THEN_throws_internal_error', async () => {
     const provider = new CliWorkerProvider(
       makeSelection('custom', {
@@ -699,4 +2339,221 @@ describe('CliWorkerProvider', () => {
     expect(await provider.reattachSession('session-b')).toMatchObject({ session_id: 'session-b' });
     expect(await provider.closeSession(created.session_id)).toEqual({ closed: true });
   });
+
+  it('GIVEN_existing_session_prompt_and_nonzero_exit_WHEN_next_run_retries_THEN_prompt_is_migrated_to_refreshed_session', async () => {
+    const parse = vi.fn(
+      (): WorkerOutputEnvelope => ({
+        session_id: 'builder-feature-refresh',
+        role: 'builder',
+        feature_id: 'feature-refresh',
+        outputs: [{ type: 'NOTE', content: 'ok' }],
+        provider_meta: { provider: 'codex', model: 'codex-model' },
+      }),
+    );
+    const run = vi
+      .fn<ProviderCommandRunner['run']>()
+      .mockResolvedValueOnce({
+        exitCode: 1,
+        signal: null,
+        stderr: 'boom',
+      })
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+      });
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: { parse },
+      commandRunner: { run },
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    await provider.createSession('builder', 'feature-refresh', 'Preserve this prompt.');
+    await expect(
+      provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-refresh',
+      }),
+    ).rejects.toMatchObject({
+      code: ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+    });
+
+    await provider.runWorker({
+      role: 'builder',
+      feature_id: 'feature-refresh',
+    });
+
+    const secondCallOptions = run.mock.calls.at(1)?.[2] as { stdin?: string } | undefined;
+    expect(secondCallOptions?.stdin).toContain('Preserve this prompt.');
+  });
+
+  it('GIVEN_process_kill_signal_WHEN_runWorker_fails_THEN_failure_is_classified_as_process_killed', async () => {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(
+          async (): Promise<ProviderCommandResult> => ({
+            exitCode: 1,
+            signal: 'SIGTERM' as NodeJS.Signals,
+            stderr: 'terminated',
+          }),
+        ),
+      },
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    await expect(
+      provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-killed',
+      }),
+    ).rejects.toMatchObject({
+      code: ERROR_CODES.PROVIDER_PROCESS_KILLED,
+    });
+  });
+
+  it('GIVEN_raw_logs_enabled_with_blank_stdout_or_non_worker_role_WHEN_runWorker_completes_THEN_no_raw_log_is_persisted', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-raw-logs-skip-'));
+    const parse = vi.fn(
+      (): WorkerOutputEnvelope => ({
+        session_id: 'session-skip',
+        role: 'reconciler',
+        feature_id: 'feature-skip',
+        outputs: [{ type: 'NOTE', content: 'skip' }],
+        provider_meta: { provider: 'codex', model: 'codex-model' },
+      }),
+    );
+    const run = vi
+      .fn<ProviderCommandRunner['run']>()
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        stdout: '   ',
+      })
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        stdout: 'reconciler summary',
+      });
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: { parse },
+      commandRunner: { run },
+      repoRoot,
+      rawAgentLogsEnabled: true,
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    try {
+      await provider.runWorker({
+        role: 'builder',
+        feature_id: 'feature-skip',
+      });
+      await provider.runWorker({
+        role: 'reconciler',
+        feature_id: 'feature-skip',
+      });
+
+      const logsDir = path.join(repoRoot, '.aop', 'features', 'feature-skip', 'logs');
+      const files = await fs.readdir(logsDir);
+      expect(files).toEqual(['live']);
+      const liveFiles = await fs.readdir(path.join(logsDir, 'live'));
+      expect(liveFiles).toContain('builder.json');
+      expect(liveFiles).toContain('builder.txt');
+      expect(liveFiles).not.toContain('reconciler.txt');
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('GIVEN_cleanup_directory_contains_nonmatching_file_WHEN_raw_log_cleanup_runs_THEN_nonmatching_file_is_ignored', async () => {
+    const repoRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-raw-logs-ignore-'));
+    const logsDir = path.join(repoRoot, '.aop', 'features', 'feature-ignore', 'logs');
+    await fs.mkdir(logsDir, { recursive: true });
+    await fs.writeFile(path.join(logsDir, 'notes.txt'), 'keep', 'utf8');
+
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(async () => ({
+          exitCode: 0,
+          signal: null,
+          stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+        })),
+      },
+      repoRoot,
+      rawAgentLogsEnabled: true,
+      rawAgentLogsRetentionDays: 1,
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    try {
+      await provider.runWorker({
+        role: 'planner',
+        feature_id: 'feature-ignore',
+      });
+
+      const files = await fs.readdir(logsDir);
+      expect(files).toContain('notes.txt');
+    } finally {
+      await fs.rm(repoRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('GIVEN_provider_capabilities_WHEN_requested_THEN_returns_cli_provider_flags', () => {
+    const provider = new CliWorkerProvider(makeSelection('codex'), {
+      outputParser: new GenericCliOutputParser(),
+      commandRunner: {
+        run: vi.fn(),
+      },
+      workerResponseTimeoutMs: 1_000,
+    });
+
+    expect(provider.getCapabilities()).toEqual({
+      supportsInteractiveMode: true,
+      supportsWorkingDirectory: true,
+      supportsPauseResume: false,
+      supportsMessagePassing: true,
+      supportsAcknowledgment: false,
+    });
+  });
+
+  it('GIVEN_selection_with_cli_extra_args_WHEN_runWorker_called_THEN_extra_args_appended_to_command', async () => {
+    const run = vi.fn(
+      async (): Promise<ProviderCommandResult> => ({
+        exitCode: 0,
+        signal: null,
+        stdout: JSON.stringify({ outputs: [{ type: 'NOTE', content: 'ok' }] }),
+        stderr: '',
+      }),
+    );
+    const parse = vi.fn(
+      (): WorkerOutputEnvelope => ({
+        session_id: 'planner-feature-b-session',
+        role: 'planner',
+        feature_id: 'feature-b',
+        outputs: [{ type: 'NOTE', content: 'ok' }],
+        provider_meta: { provider: 'codex', model: 'codex-model' },
+      }),
+    );
+    const selection = makeSelection('codex', {});
+    selection.cli_extra_args = ['-c', 'mcp_servers.context7.enabled=false'];
+
+    const provider = new CliWorkerProvider(selection, {
+      outputParser: { parse },
+      commandRunner: { run },
+      workerResponseTimeoutMs: 1800000,
+    });
+
+    await provider.createSession('planner', 'feature-b', 'prompt');
+    await provider.runWorker({ role: 'planner', feature_id: 'feature-b', instructions: 'do work' });
+
+    const firstCall = run.mock.calls[0];
+    expect(firstCall).toBeDefined();
+    if (!firstCall) {
+      throw new Error('expected command runner to be called');
+    }
+    const args = (firstCall as unknown[])[1] as string[];
+    expect(args).toContain('-c');
+    expect(args).toContain('mcp_servers.context7.enabled=false');
+  });
 });