agentic-orchestrator 0.1.28 → 0.2.1

package/apps/control-plane/src/providers/cli-worker-provider.ts

@@ -1,5 +1,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { ERROR_CODES } from '../core/error-codes.js';
 import {
@@ -10,11 +11,13 @@ import {
   type ProviderSelection,
   type WorkerProviderCapabilities,
   type WorkerRunInput,
+  type WorkerRunOutput,
   type WorkerCapabilities,
   type WorkerHandle,
   type WorkerProvider,
   type WorkerSession,
 } from './providers.js';
+import { unavailableUsage } from '../application/usage-types.js';
 import { PROVIDER_CLI_DEFAULTS, type ProviderCommandTemplate } from './provider-defaults.js';
 import type { ProviderOutputParser } from './output-parsers/types.js';
 import { WorkerWatchdog, type WatchdogOutcome } from './worker-watchdog.js';
@@ -30,6 +33,7 @@ interface CliWorkerProviderOptions {
   workerIdleTimeoutMs?: number;
   workerWatchdogPollIntervalMs?: number;
   workerKillGracePeriodMs?: number;
+  overlayDir?: string;
 }
 
 interface CommandTemplateValues {
@@ -38,6 +42,13 @@ interface CommandTemplateValues {
   featureId: string;
   role: string;
   message?: string;
+  model?: string;
+  outputLastMessagePath?: string;
+}
+
+interface LiveAgentConsoleCapture {
+  appendChunk: (chunk: string) => void;
+  finalize: (status: 'completed' | 'failed', fallbackContent?: string) => Promise<void>;
 }
 
 const CLAUDE_MIN_EFFECTIVE_TIMEOUT_MS = 300_000;
@@ -55,7 +66,7 @@ const CLI_PROVIDER_CAPABILITIES: WorkerProviderCapabilities = {
   supportsAcknowledgment: false,
 };
 
-function buildStructuredWorkerPrompt(
+function buildDeterministicWorkerPrompt(
   payload: Record<string, unknown>,
   systemPrompt: string | null,
 ): string {
@@ -67,8 +78,8 @@ function buildStructuredWorkerPrompt(
   lines.push(
     'Return exactly one JSON object and nothing else.',
     'Allowed output object forms:',
-    '{"type":"PLAN_SUBMISSION|PATCH|NOTE|REQUEST", ...}',
-    '{"outputs":[{"type":"PLAN_SUBMISSION|PATCH|NOTE|REQUEST", ...}], ...}',
+    '{"type":"PLAN_SUBMISSION|INTAKE_SUBMISSION|PATCH|NOTE|REQUEST", ...}',
+    '{"outputs":[{"type":"PLAN_SUBMISSION|INTAKE_SUBMISSION|PATCH|NOTE|REQUEST", ...}], ...}',
     'Do not wrap JSON in markdown code fences.',
     'Worker input payload:',
     JSON.stringify(payload),
@@ -76,6 +87,234 @@ function buildStructuredWorkerPrompt(
   return lines.join('\n');
 }
 
+function buildInteractiveWorkerPrompt(
+  payload: Record<string, unknown>,
+  systemPrompt: string | null,
+): string {
+  const lines: string[] = [];
+  if (systemPrompt) {
+    lines.push(systemPrompt);
+    lines.push('---');
+  }
+
+  const featureId = typeof payload['feature_id'] === 'string' ? payload['feature_id'] : '';
+  const repoRoot = typeof payload['repo_root'] === 'string' ? payload['repo_root'] : null;
+  const role = typeof payload['role'] === 'string' ? payload['role'] : '';
+  const workingDir =
+    typeof payload['working_directory'] === 'string' ? payload['working_directory'] : null;
+  const instructions =
+    typeof payload['instructions'] === 'string' ? payload['instructions'].trim() : '';
+  const lastToolResults = Array.isArray(payload['last_tool_results'])
+    ? payload['last_tool_results']
+    : [];
+  const projectedContext = projectInteractiveContext(payload['context_bundle']);
+  const stateStatus =
+    typeof projectedContext?.state === 'object' &&
+    projectedContext.state &&
+    typeof (projectedContext.state as Record<string, unknown>).status === 'string'
+      ? ((projectedContext.state as Record<string, unknown>).status as string)
+      : null;
+  const plannerPhase =
+    typeof payload['planner_phase'] === 'string'
+      ? payload['planner_phase']
+      : stateStatus === 'intake'
+        ? 'intake'
+        : 'planning';
+
+  lines.push(`You are the ${role} agent running in interactive mode.`);
+  lines.push(`Feature: ${featureId}`);
+  if (workingDir) {
+    lines.push(`Working directory (edit files here): ${workingDir}`);
+  }
+
+  if (repoRoot) {
+    const featureDir = `${repoRoot}/.aop/features/${featureId}`;
+    if (role === 'planner') {
+      if (plannerPhase === 'intake') {
+        lines.push(
+          '',
+          'Intake artifacts are on disk — use these files as the requirements workspace:',
+          `  ${featureDir}/spec.md                     — feature specification`,
+          `  ${featureDir}/spec.manifest.bootstrap.json — bootstrap requirements proposal`,
+          `  ${featureDir}/spec.manifest.verified.json  — current verified requirements contract`,
+          `  ${featureDir}/intake.review.json           — intake review and ambiguity status`,
+          `  ${featureDir}/questions.json               — persisted intake clarification questions and answers`,
+          `  ${featureDir}/state.md                     — current status and front matter`,
+          `  ${featureDir}/decisions.md                 — decision history`,
+        );
+      } else {
+        lines.push(
+          '',
+          'Planning artifacts are on disk — use these files as the execution-planning baseline:',
+          `  ${featureDir}/spec.md                    — feature specification`,
+          `  ${featureDir}/spec.manifest.verified.json — verified requirements contract`,
+          `  ${featureDir}/state.md                  — current status and front matter`,
+          `  ${featureDir}/plan.md                   — canonical step-by-step planning artifact`,
+          `  ${featureDir}/plan.json                 — schema-valid planning definition`,
+          `  ${featureDir}/qa_test_index.json        — QA coverage and pending items`,
+          `  ${featureDir}/evidence/                 — gate run results`,
+          `  ${featureDir}/decisions.md              — decision history`,
+        );
+      }
+    } else if (role === 'builder') {
+      if (workingDir) {
+        const contextDir = `${workingDir}/.aop/context`;
+        lines.push(
+          '',
+          'Staged artifacts (read these first for context):',
+          `  ${contextDir}/spec.md             — original feature specification`,
+          `  ${contextDir}/plan.md             — human-readable implementation plan`,
+          `  ${contextDir}/plan.json           — structured plan with tasks and acceptance criteria`,
+          `  ${contextDir}/qa_test_index.json  — test expectations (if available)`,
+        );
+      }
+      lines.push(
+        '',
+        'Runtime artifacts:',
+        `  ${featureDir}/state.md           — current status and front matter`,
+        `  ${featureDir}/evidence/          — gate run results`,
+        `  ${featureDir}/decisions.md       — decision history`,
+      );
+    } else if (role === 'qa') {
+      lines.push(
+        '',
+        'QA artifacts are on disk — use these files as the verification baseline:',
+        `  ${featureDir}/state.md              — current status and front matter`,
+        `  ${featureDir}/plan.md               — accepted planning baseline`,
+        `  ${featureDir}/plan.json             — machine-readable plan`,
+        `  ${featureDir}/qa_test_index.json    — QA coverage and pending items`,
+        `  ${featureDir}/evidence/             — latest gate evidence`,
+        `  ${featureDir}/decisions.md          — decision history`,
+      );
+    } else if (role === 'reconciler') {
+      lines.push(
+        '',
+        'Reconciliation artifacts are on disk — use these files as the merge-resolution baseline:',
+        `  ${featureDir}/state.md           — conflict status and front matter`,
+        `  ${featureDir}/spec.md            — feature intent`,
+        `  ${featureDir}/plan.md            — accepted planning baseline`,
+        `  ${featureDir}/plan.json          — machine-readable plan`,
+        `  ${featureDir}/decisions.md       — decision history`,
+        `  ${featureDir}/evidence/          — latest gate evidence`,
+      );
+    }
+  }
+
+  if (instructions.length > 0) {
+    lines.push('', 'Instructions:', instructions);
+  }
+
+  if (projectedContext) {
+    lines.push('', 'Execution context summary:', JSON.stringify(projectedContext, null, 2));
+  }
+
+  if (lastToolResults.length > 0) {
+    lines.push('', 'Recent tool results:', JSON.stringify(lastToolResults));
+  }
+
+  if (role === 'planner') {
+    const featureDir = repoRoot ? `${repoRoot}/.aop/features/${featureId}` : null;
+    if (plannerPhase === 'intake') {
+      lines.push(
+        '',
+        'Update the intake artifacts directly in the working directory.',
+        'Return exactly one JSON object and nothing else:',
+        '{"type":"INTAKE_SUBMISSION","intake_submission":{"verified_manifest":{...},"open_ambiguities":[...],"resolved_ambiguities":[...],"requires_user_input":false}}',
+        'or {"type":"REQUEST","request":{"action":"ask_user_input","question_type":"clarification","prompt":"<blocking intake question>","details":{"ambiguity_id":"AMB-001","obligation_ids":["OBL-001"]},"expected_answer":{"kind":"free_text"},"blocking":true}}',
+        'or {"type":"NOTE","content":"<why intake remains unchanged and what intake state was observed>"}',
+        'Do not emit PLAN_SUBMISSION while operating in the intake planner phase.',
+        'If you emit REQUEST.action=ask_user_input, stop there for the turn. Do not also emit INTAKE_SUBMISSION or resolve the ambiguity yourself.',
+        'Do not claim verification_basis=human_review_confirmed unless the context already contains an answered manifest-review confirmation question.',
+        'Do not wrap JSON in markdown code fences.',
+      );
+    } else {
+      lines.push(
+        '',
+        'Update the planning artifacts directly in the working directory.',
+        featureDir
+          ? `Keep ${featureDir}/plan.md aligned with the planning state and any plan_json you return.`
+          : 'Keep plan.md aligned with the planning state and any plan_json you return.',
+        'Return exactly one JSON object and nothing else:',
+        '{"type":"PLAN_SUBMISSION","plan_json":{...}}',
+        'or {"type":"REQUEST","request":{"action":"amend_plan","plan_json":{...},"expected_plan_version":<n>}}',
+        'or {"type":"NOTE","content":"<why the accepted plan remains unchanged and what state was observed>"}',
+        'Do not emit INTAKE_SUBMISSION while operating in the execution-planning phase.',
+        'Do not wrap JSON in markdown code fences.',
+      );
+    }
+  } else if (role === 'builder') {
+    lines.push(
+      '',
+      'Edit files directly in the working directory. Do not emit PATCH/unified diff output.',
+      'Use the accepted plan as your execution contract and keep changes inside planned paths.',
+      'Return NOTE only after making planned file changes.',
+      'Return REQUEST.action=more_context when the safe fix surface exceeds the accepted plan or the context is stale.',
+      'Return REQUEST.action=ask_user_input only for genuine human decisions, approvals, or policy exceptions you cannot resolve from the plan and repo.',
+      'After completing your edits, return exactly one JSON object:',
+      '{"type":"NOTE","content":"<summary of completed edits, tests updated, and remaining risks>"}',
+      'or {"type":"REQUEST","request":{"action":"more_context"}}',
+      'or {"type":"REQUEST","request":{"action":"ask_user_input","question_type":"clarification","prompt":"<question>","details":{},"expected_answer":{"kind":"free_text"},"blocking":true}}',
+      'Do not wrap JSON in markdown code fences.',
+    );
+  } else if (role === 'qa') {
+    lines.push(
+      '',
+      'Edit files directly in the working directory. Do not emit PATCH/unified diff output.',
+      'Use plan.json, qa_test_index.json, and the latest evidence as your verification contract.',
+      'Return NOTE only after making file changes that address a reproduced failure or verification gap.',
+      'Return REQUEST.action=more_context when evidence is stale or the accepted plan does not authorize the safe fix surface.',
+      'Return REQUEST.action=ask_user_input only for genuine operator decisions, approvals, or risk acknowledgements.',
+      'After completing your edits, return exactly one JSON object:',
+      '{"type":"NOTE","content":"<summary of reproduced failures, fixes applied, tests run, and remaining risks>"}',
+      'or {"type":"REQUEST","request":{"action":"more_context"}}',
+      'or {"type":"REQUEST","request":{"action":"ask_user_input","question_type":"risk_ack","prompt":"<question>","details":{},"expected_answer":{"kind":"free_text"},"blocking":true}}',
+      'Do not wrap JSON in markdown code fences.',
+    );
+  } else {
+    lines.push(
+      '',
+      'Edit files directly in the conflicted worktree. Do not emit PATCH/unified diff output.',
+      'Use spec.md, state.md, plan.json, and approved collision context as your reconciliation contract.',
+      'Return NOTE only after resolving conflicted files and performing proportionate verification.',
+      'Return REQUEST.action=more_context when the conflict snapshot or surrounding repo state is stale.',
+      'Return REQUEST.action=ask_user_input only when preserving mainline semantics and feature intent requires an operator choice.',
+      'After completing your edits, return exactly one JSON object:',
+      '{"type":"NOTE","content":"<summary of conflicts resolved, verification run, plan impacts, and residual risks>"}',
+      'or {"type":"REQUEST","request":{"action":"more_context"}}',
+      'or {"type":"REQUEST","request":{"action":"ask_user_input","question_type":"clarification","prompt":"<question>","details":{},"expected_answer":{"kind":"free_text"},"blocking":true}}',
+      'Do not wrap JSON in markdown code fences.',
+    );
+  }
+
+  return lines.join('\n');
+}
+
+function buildWorkerPrompt(
+  payload: Record<string, unknown>,
+  systemPrompt: string | null,
+  executionMode: 'deterministic' | 'interactive',
+): string {
+  if (executionMode === 'interactive') {
+    return buildInteractiveWorkerPrompt(payload, systemPrompt);
+  }
+  return buildDeterministicWorkerPrompt(payload, systemPrompt);
+}
+
+export async function resolvePromptOverlay(
+  overlayDir: string,
+  role: string,
+  provider: string,
+): Promise<string | null> {
+  const filename = `${role}.${provider}.md`;
+  const overlayPath = path.join(overlayDir, filename);
+  try {
+    const content = await fs.readFile(overlayPath, 'utf8');
+    return content.trim().length > 0 ? content : null;
+  } catch {
+    return null;
+  }
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -96,9 +335,109 @@ function asNonEmptyString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function projectInteractiveContext(contextBundle: unknown): Record<string, unknown> | null {
+  if (!isRecord(contextBundle)) {
+    return null;
+  }
+
+  const projected: Record<string, unknown> = {};
+  const state = isRecord(contextBundle['state']) ? contextBundle['state'] : null;
+  const frontMatter = isRecord(state?.['front_matter']) ? state['front_matter'] : null;
+  if (frontMatter) {
+    projected['state'] = {
+      status: frontMatter['status'] ?? null,
+      status_reason: frontMatter['status_reason'] ?? null,
+      gate_profile: frontMatter['gate_profile'] ?? null,
+      gates: isRecord(frontMatter['gates']) ? frontMatter['gates'] : null,
+    };
+  }
+
+  const plan = isRecord(contextBundle['plan']) ? contextBundle['plan'] : null;
+  if (plan) {
+    projected['accepted_plan'] = {
+      summary: plan['summary'] ?? null,
+      allowed_areas: Array.isArray(plan['allowed_areas']) ? plan['allowed_areas'] : [],
+      forbidden_areas: Array.isArray(plan['forbidden_areas']) ? plan['forbidden_areas'] : [],
+      files: isRecord(plan['files']) ? plan['files'] : null,
+      acceptance_criteria: Array.isArray(plan['acceptance_criteria'])
+        ? plan['acceptance_criteria']
+        : [],
+    };
+  }
+
+  const latestEvidence = isRecord(contextBundle['latest_evidence'])
+    ? contextBundle['latest_evidence']
+    : null;
+  if (latestEvidence) {
+    projected['latest_evidence'] = {
+      overall: latestEvidence['overall'] ?? null,
+      mode: latestEvidence['mode'] ?? null,
+      status_reason: latestEvidence['status_reason'] ?? null,
+      failed_steps: Array.isArray(latestEvidence['failed_steps'])
+        ? latestEvidence['failed_steps']
+        : [],
+    };
+  }
+
+  const qaIndex = isRecord(contextBundle['qa_test_index']) ? contextBundle['qa_test_index'] : null;
+  if (qaIndex) {
+    projected['qa_test_index'] = qaIndex;
+  }
+
+  const intake = isRecord(contextBundle['intake']) ? contextBundle['intake'] : null;
+  if (intake) {
+    const review = isRecord(intake['review']) ? intake['review'] : null;
+    const openAmbiguities = Array.isArray(review?.['ambiguities'])
+      ? review?.['ambiguities']
+          .map((item) => (isRecord(item) ? item : null))
+          .filter(
+            (item): item is Record<string, unknown> =>
+              item !== null && asNonEmptyString(item['status']) === 'open',
+          )
+          .map((item) => ({
+            id: item['id'] ?? null,
+            summary: item['summary'] ?? null,
+            obligation_ids: Array.isArray(item['obligation_ids']) ? item['obligation_ids'] : [],
+          }))
+      : [];
+    const clarificationAnswers = Array.isArray(review?.['clarification_answers'])
+      ? review?.['clarification_answers']
+          .map((item) => (isRecord(item) ? item : null))
+          .filter((item): item is Record<string, unknown> => item !== null)
+          .map((item) => ({
+            question_id: item['question_id'] ?? null,
+            ambiguity_ids: Array.isArray(item['ambiguity_ids']) ? item['ambiguity_ids'] : [],
+            answer: item['answer'] ?? null,
+            answered_at: item['answered_at'] ?? null,
+            resolution_status: item['resolution_status'] ?? null,
+          }))
+      : [];
+    projected['intake'] = {
+      summary: isRecord(intake['summary']) ? intake['summary'] : null,
+      bootstrap_manifest_version: isRecord(intake['bootstrap_manifest'])
+        ? (intake['bootstrap_manifest']['manifest_version'] ?? null)
+        : null,
+      verified_manifest_version: isRecord(intake['verified_manifest'])
+        ? (intake['verified_manifest']['manifest_version'] ?? null)
+        : null,
+      review: review
+        ? {
+            status: review['status'] ?? null,
+            questions_open: review['questions_open'] ?? null,
+            questions_resolved: review['questions_resolved'] ?? null,
+            open_ambiguities: openAmbiguities,
+            clarification_answers: clarificationAnswers,
+          }
+        : null,
+    };
+  }
+
+  return Object.keys(projected).length > 0 ? projected : null;
+}
+
 function templateFromConfig(
   config: Record<string, unknown> | null | undefined,
-  kind: 'run' | 'attach' | 'send',
+  kind: 'run' | 'run_resume' | 'attach' | 'send',
   fallback: ProviderCommandTemplate | undefined,
 ): ProviderCommandTemplate | undefined {
   const nested = isRecord(config?.[kind]) ? config?.[kind] : null;
@@ -117,33 +456,51 @@ function templateFromConfig(
   return { command, args };
 }
 
-function resolveRunTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+function appendExtraArgs(
+  template: ProviderCommandTemplate | undefined,
+  extraArgs: string[] | undefined,
+): ProviderCommandTemplate | undefined {
+  if (!template || !extraArgs?.length) {
+    return template;
+  }
+  return { command: template.command, args: [...template.args, ...extraArgs] };
+}
+
+function resolveRunTemplate(
+  selection: ProviderSelection,
+  resumeSession: boolean,
+): ProviderCommandTemplate | undefined {
   const topLevelCommand = asNonEmptyString(selection.agent_config?.command);
   const topLevelArgs = readStringArray(selection.agent_config?.args);
   const topLevelTemplate =
     topLevelCommand && topLevelArgs ? { command: topLevelCommand, args: topLevelArgs } : undefined;
+  const defaults = PROVIDER_CLI_DEFAULTS[selection.provider];
+  const kind = resumeSession ? 'run_resume' : 'run';
 
-  return templateFromConfig(
+  const template = templateFromConfig(
     selection.agent_config,
-    'run',
-    topLevelTemplate ?? PROVIDER_CLI_DEFAULTS[selection.provider]?.run,
+    kind,
+    topLevelTemplate ?? (resumeSession ? defaults?.run_resume : undefined) ?? defaults?.run,
   );
+  return appendExtraArgs(template, selection.cli_extra_args);
 }
 
 function resolveAttachTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
-  return templateFromConfig(
+  const template = templateFromConfig(
     selection.agent_config,
     'attach',
     PROVIDER_CLI_DEFAULTS[selection.provider]?.attach,
   );
+  return appendExtraArgs(template, selection.cli_extra_args);
 }
 
 function resolveSendTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
-  return templateFromConfig(
+  const template = templateFromConfig(
     selection.agent_config,
     'send',
     PROVIDER_CLI_DEFAULTS[selection.provider]?.send,
   );
+  return appendExtraArgs(template, selection.cli_extra_args);
 }
 
 function applyTemplateArgs(args: string[], values: CommandTemplateValues): string[] {
@@ -163,6 +520,12 @@ function applyTemplateArgs(args: string[], values: CommandTemplateValues): strin
     if (arg === '{message}') {
       return values.message ?? '';
     }
+    if (arg === '{output_last_message_path}') {
+      return values.outputLastMessagePath ?? '';
+    }
+    if (arg === '{model}') {
+      return values.model ?? '';
+    }
     return arg;
   });
 }
@@ -179,6 +542,12 @@ function buildRunCommandEnv(selection: ProviderSelection): NodeJS.ProcessEnv {
   if (selection.provider_config_env && selection.provider_config_ref) {
     env[selection.provider_config_env] = selection.provider_config_ref;
   }
+  if (selection.provider === 'claude') {
+    // Claude Code refuses to spawn inside an active Claude Code session.
+    // Both CLAUDECODE and CLAUDE_CODE_ENTRYPOINT must be absent to bypass the nested-session guard.
+    delete env['CLAUDECODE'];
+    delete env['CLAUDE_CODE_ENTRYPOINT'];
+  }
   return env;
 }
 
@@ -202,6 +571,206 @@ function resolveCliWorkerCapabilities(selection: ProviderSelection): WorkerCapab
   };
 }
 
+function isRawLogRole(role: string): role is 'planner' | 'builder' | 'qa' {
+  return role === 'planner' || role === 'builder' || role === 'qa';
+}
+
+function sanitizeClaudeProjectKey(value: string): string {
+  return value.replace(/[^A-Za-z0-9]/g, '-');
+}
+
+function resolveClaudeTranscriptPath(workingDirectory: string, sessionId: string): string {
+  return path.join(
+    os.homedir(),
+    '.claude',
+    'projects',
+    sanitizeClaudeProjectKey(workingDirectory),
+    `${sessionId}.jsonl`,
+  );
+}
+
+function asNonEmptyStringOrNull(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+
+function collectClaudeTranscriptTextBlocks(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const blocks: string[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry) || entry.type !== 'text') {
+      continue;
+    }
+    const text = asNonEmptyStringOrNull(entry.text);
+    if (text) {
+      blocks.push(text);
+    }
+  }
+  return blocks;
+}
+
+function summarizeClaudeToolInput(input: Record<string, unknown>): string | null {
+  const description = asNonEmptyStringOrNull(input.description);
+  if (description) {
+    return description;
+  }
+
+  const command = asNonEmptyStringOrNull(input.command);
+  if (command) {
+    return command;
+  }
+
+  const filePath = asNonEmptyStringOrNull(input.file_path);
+  if (filePath) {
+    return filePath;
+  }
+
+  const pattern = asNonEmptyStringOrNull(input.pattern);
+  const searchPath = asNonEmptyStringOrNull(input.path);
+  if (pattern && searchPath) {
+    return `${pattern} @ ${searchPath}`;
+  }
+  if (pattern) {
+    return pattern;
+  }
+
+  const specs = input.specs;
+  if (Array.isArray(specs)) {
+    const renderedSpecs = specs.filter((value): value is string => typeof value === 'string');
+    if (renderedSpecs.length > 0) {
+      return renderedSpecs.join(', ');
+    }
+  }
+
+  return null;
+}
+
+function renderClaudeTranscriptEntry(record: Record<string, unknown>): string[] {
+  const type = asNonEmptyStringOrNull(record.type);
+  if (!type) {
+    return [];
+  }
+
+  if (type === 'progress') {
+    const data = isRecord(record.data) ? record.data : null;
+    if (data?.type === 'hook_progress') {
+      const hookEvent = asNonEmptyStringOrNull(data.hookEvent);
+      const hookName = asNonEmptyStringOrNull(data.hookName);
+      const label = [hookEvent, hookName].filter(Boolean).join(' · ');
+      return label.length > 0 ? [`[progress] ${label}`] : [];
+    }
+
+    const progressType = asNonEmptyStringOrNull(data?.type);
+    return progressType ? [`[progress] ${progressType}`] : [];
+  }
+
+  const message = isRecord(record.message) ? record.message : null;
+  if (!message) {
+    return [];
+  }
+
+  if (type === 'assistant') {
+    const content = Array.isArray(message.content) ? message.content : [];
+    const rendered: string[] = [];
+    for (const entry of content) {
+      if (!isRecord(entry)) {
+        continue;
+      }
+
+      if (entry.type === 'text') {
+        const text = asNonEmptyStringOrNull(entry.text);
+        if (text) {
+          rendered.push(text);
+        }
+        continue;
+      }
+
+      if (entry.type === 'tool_use') {
+        const name = asNonEmptyStringOrNull(entry.name) ?? 'tool';
+        const input = isRecord(entry.input) ? entry.input : {};
+        const summary = summarizeClaudeToolInput(input);
+        rendered.push(summary ? `[tool] ${name}: ${summary}` : `[tool] ${name}`);
+      }
+    }
+    return rendered;
+  }
+
+  if (type === 'user') {
+    const content = Array.isArray(message.content) ? message.content : [];
+    const rendered: string[] = [];
+    for (const entry of content) {
+      if (!isRecord(entry) || entry.type !== 'tool_result') {
+        continue;
+      }
+
+      const textBlocks = collectClaudeTranscriptTextBlocks(entry.content);
+      if (textBlocks.length > 0) {
+        rendered.push(...textBlocks);
+        continue;
+      }
+
+      const text = asNonEmptyStringOrNull(entry.content);
+      if (text) {
+        rendered.push(text);
+        continue;
+      }
+
+      if (isRecord(record.toolUseResult)) {
+        const stdout = asNonEmptyStringOrNull(record.toolUseResult.stdout);
+        const stderr = asNonEmptyStringOrNull(record.toolUseResult.stderr);
+        if (stdout) {
+          rendered.push(stdout);
+        }
+        if (stderr) {
+          rendered.push(stderr);
+        }
+      }
+    }
+    return rendered;
+  }
+
+  return [];
+}
+
+function renderClaudeTranscript(raw: string): string {
+  const rendered: string[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+
+    try {
+      const parsed = JSON.parse(trimmed) as unknown;
+      if (isRecord(parsed)) {
+        rendered.push(...renderClaudeTranscriptEntry(parsed));
+      }
+    } catch {
+      // Ignore malformed partial lines while the transcript is still being written.
+    }
+  }
+  return rendered.join('\n\n');
+}
+
+export const cliWorkerProviderTestExports = {
+  buildInteractiveWorkerPrompt,
+  projectInteractiveContext,
+  resolveRunTemplate,
+  resolveAttachTemplate,
+  resolveSendTemplate,
+  applyTemplateArgs,
+  buildRunCommandEnv,
+  resolveCliWorkerCapabilities,
+  sanitizeClaudeProjectKey,
+  resolveClaudeTranscriptPath,
+  collectClaudeTranscriptTextBlocks,
+  summarizeClaudeToolInput,
+  renderClaudeTranscriptEntry,
+  renderClaudeTranscript,
+};
+
 export class CliWorkerProvider implements WorkerProvider {
   readonly mode = 'live' as const;
   readonly selection: ProviderSelection;
@@ -217,14 +786,67 @@ export class CliWorkerProvider implements WorkerProvider {
   private readonly workerWatchdogPollIntervalMs: number;
   private readonly workerKillGracePeriodMs: number;
   private readonly repoRoot: string | null;
+  private readonly overlayDir: string | null;
   private readonly rawAgentLogsEnabled: boolean;
   private readonly rawAgentLogsRetentionDays: number;
   private readonly workerCapabilities: WorkerCapabilities;
-  private readonly runTemplate: ProviderCommandTemplate | undefined;
   private readonly attachTemplate: ProviderCommandTemplate | undefined;
   private readonly sendTemplate: ProviderCommandTemplate | undefined;
   private readonly sessionsByRoleFeature = new Map<string, string>();
   private readonly systemPromptsBySession = new Map<string, string | null>();
+  private readonly bootstrappedSessionIds = new Set<string>();
+  private readonly overlayCache = new Map<string, string | null>();
+
+  private isMissingClaudeConversation(result: ProviderCommandResult): boolean {
+    if (this.selection.provider !== 'claude') {
+      return false;
+    }
+    const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+    const stdout = typeof result.stdout === 'string' ? result.stdout : '';
+    return (
+      stderr.includes('No conversation found with session ID') ||
+      stdout.includes('No conversation found with session ID')
+    );
+  }
+
+  private buildBootstrapControlPrompt(sessionId: string, message: string): string {
+    const systemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
+    return systemPrompt ? `${systemPrompt}\n---\n${message}` : message;
+  }
+
+  private async bootstrapMissingClaudeControlSession(
+    sessionId: string,
+    message: string,
+  ): Promise<boolean> {
+    if (this.selection.provider !== 'claude' || message.trim().length === 0) {
+      return false;
+    }
+
+    const runTemplate = resolveRunTemplate(this.selection, false);
+    if (!runTemplate) {
+      return false;
+    }
+
+    const prompt = this.buildBootstrapControlPrompt(sessionId, message);
+    const args = applyTemplateArgs(runTemplate.args, {
+      sessionId,
+      prompt,
+      featureId: 'global',
+      role: 'reconciler',
+      message,
+      model: this.selection.model,
+    });
+    const result = await this.commandRunner.run(runTemplate.command, args, {
+      stdin: prompt,
+      timeoutMs: 15_000,
+      env: buildRunCommandEnv(this.selection),
+    });
+    if (result.exitCode !== 0) {
+      return false;
+    }
+    this.markSessionBootstrapped(this.selection.provider, sessionId);
+    return true;
+  }
 
   constructor(selection: ProviderSelection, options: CliWorkerProviderOptions) {
     this.selection = selection;
@@ -249,13 +871,13 @@ export class CliWorkerProvider implements WorkerProvider {
     );
     this.repoRoot =
       typeof options.repoRoot === 'string' && options.repoRoot.length > 0 ? options.repoRoot : null;
+    this.overlayDir = options.overlayDir ?? null;
     this.rawAgentLogsEnabled = options.rawAgentLogsEnabled === true;
     this.rawAgentLogsRetentionDays = asPositiveInteger(
       options.rawAgentLogsRetentionDays,
       DEFAULT_RAW_LOG_RETENTION_DAYS,
     );
     this.workerCapabilities = resolveCliWorkerCapabilities(selection);
-    this.runTemplate = resolveRunTemplate(selection);
     this.attachTemplate = resolveAttachTemplate(selection);
     this.sendTemplate = resolveSendTemplate(selection);
 
@@ -282,7 +904,7 @@ export class CliWorkerProvider implements WorkerProvider {
     featureId: string,
     systemPrompt: string | null,
   ): Promise<WorkerSession> {
-    const sessionId = `${role}-${featureId}-${crypto.randomUUID()}`;
+    const sessionId = crypto.randomUUID();
     this.sessionsByRoleFeature.set(this.sessionKey(role, featureId), sessionId);
     this.systemPromptsBySession.set(sessionId, systemPrompt);
     return Promise.resolve({
@@ -311,43 +933,89 @@ export class CliWorkerProvider implements WorkerProvider {
         this.sessionsByRoleFeature.delete(key);
       }
     }
+    this.bootstrappedSessionIds.delete(sessionId);
     this.systemPromptsBySession.delete(sessionId);
     return Promise.resolve({ closed: true });
   }
 
-  async runWorker(input: WorkerRunInput): Promise<Record<string, unknown>> {
-    if (!this.runTemplate) {
+  async runWorker(input: WorkerRunInput): Promise<WorkerRunOutput> {
+    const effectiveSelection = this.resolveEffectiveSelection(input.runtime_selection ?? null);
+    const sessionId = this.resolveOrCreateSessionId(input.role, input.feature_id);
+    const workingDirectory = input.working_directory ?? this.repoRoot ?? process.cwd();
+    const resumeSession = await this.shouldResumeSession(
+      effectiveSelection.provider,
+      sessionId,
+      workingDirectory,
+    );
+    const runTemplate = resolveRunTemplate(effectiveSelection, resumeSession);
+    if (!runTemplate) {
       throw providerError(
         ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
         'Live worker provider is missing run command configuration',
         {
-          provider: this.selection.provider,
+          provider: effectiveSelection.provider,
           reason: 'missing_run_command_template',
+          resume_session: resumeSession,
         },
       );
     }
 
-    const sessionId =
-      this.sessionsByRoleFeature.get(this.sessionKey(input.role, input.feature_id)) ??
-      `${input.role}-${input.feature_id}-unassigned`;
-
+    const executionMode = input.execution_mode ?? 'deterministic';
     const promptPayload = {
       role: input.role,
       feature_id: input.feature_id,
-      context_bundle: input.context_bundle ?? {},
+      ...(typeof input.planner_phase === 'string' ? { planner_phase: input.planner_phase } : {}),
+      ...(executionMode === 'interactive'
+        ? {
+            repo_root: this.repoRoot ?? null,
+            context_bundle: input.context_bundle ?? {},
+          }
+        : { context_bundle: input.context_bundle ?? {} }),
       instructions: input.instructions ?? '',
       last_tool_results: input.last_tool_results ?? [],
       runtime_selection: input.runtime_selection ?? null,
       session_id: sessionId,
+      execution_mode: executionMode,
+      working_directory: input.working_directory ?? null,
     };
-    const systemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
-    const prompt = buildStructuredWorkerPrompt(promptPayload, systemPrompt);
+    const baseSystemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
+    let systemPrompt = baseSystemPrompt;
+    if (baseSystemPrompt && this.overlayDir) {
+      const cacheKey = `${input.role}.${effectiveSelection.provider}`;
+      let overlay: string | null;
+      if (this.overlayCache.has(cacheKey)) {
+        overlay = this.overlayCache.get(cacheKey) ?? null;
+      } else {
+        overlay = await resolvePromptOverlay(
+          this.overlayDir,
+          input.role,
+          effectiveSelection.provider,
+        );
+        this.overlayCache.set(cacheKey, overlay);
+      }
+      if (overlay) {
+        systemPrompt = `${baseSystemPrompt}\n\n---\n\n## Provider-Specific Instructions\n\n${overlay}`;
+      }
+    }
+    const prompt = buildWorkerPrompt(promptPayload, systemPrompt, executionMode);
+    const outputCapture = await this.createOutputCapture(runTemplate.args);
 
-    const args = applyTemplateArgs(this.runTemplate.args, {
+    const args = applyTemplateArgs(runTemplate.args, {
       sessionId,
       prompt,
       featureId: input.feature_id,
       role: input.role,
+      model: effectiveSelection.model,
+      outputLastMessagePath: outputCapture.lastMessagePath ?? undefined,
+    });
+    const liveAgentConsole = await this.createLiveAgentConsoleCapture({
+      featureId: input.feature_id,
+      role: input.role,
+      sessionId,
+      provider: effectiveSelection.provider,
+      model: effectiveSelection.model,
+      executionMode,
+      workingDirectory,
     });
     const effectiveTimeoutMs = this.resolveRunTimeoutMs();
     const runnerBackstopTimeoutMs = this.resolveRunnerBackstopTimeoutMs(effectiveTimeoutMs);
@@ -374,47 +1042,76 @@ export class CliWorkerProvider implements WorkerProvider {
     };
     watchdog.start();
 
-    let runResult: ProviderCommandResult;
     try {
-      runResult = await this.commandRunner.run(this.runTemplate.command, args, {
-        stdin: prompt,
-        cwd: input.working_directory,
-        timeoutMs: runnerBackstopTimeoutMs,
-        env: buildRunCommandEnv(this.selection),
-        onLifecycleEvent: (event) => {
-          workerHandle.onLifecycleEvent?.(event);
-        },
-        registerKill: (kill) => {
-          killRunner = kill;
-        },
+      let runResult: ProviderCommandResult;
+      try {
+        runResult = await this.commandRunner.run(runTemplate.command, args, {
+          stdin: prompt,
+          cwd: input.working_directory,
+          timeoutMs: runnerBackstopTimeoutMs,
+          env: buildRunCommandEnv(effectiveSelection),
+          onLifecycleEvent: (event) => {
+            workerHandle.onLifecycleEvent?.(event);
+          },
+          registerKill: (kill) => {
+            killRunner = kill;
+          },
+          onOutputChunk: (chunk) => {
+            liveAgentConsole?.appendChunk(chunk.text);
+          },
+        });
+      } catch (error) {
+        watchdog.stop({
+          signal: null,
+        });
+        await liveAgentConsole?.finalize('failed');
+        throw error;
+      }
+      const watchdogOutcome = watchdog.stop({
+        signal: runResult.signal,
+        timedOut: runResult.timedOut ?? false,
       });
-    } catch (error) {
-      watchdog.stop({
-        signal: null,
+
+      if (runResult.exitCode !== 0) {
+        this.refreshSessionForRoleFeature(input.role, input.feature_id);
+      }
+
+      this.ensureRunSucceeded(
+        runResult,
+        runTemplate.command,
+        args,
+        effectiveTimeoutMs,
+        watchdogOutcome,
+      );
+      this.markSessionBootstrapped(effectiveSelection.provider, sessionId);
+      const preferredOutput = await this.resolvePreferredWorkerOutput(
+        runResult.stdout ?? '',
+        outputCapture.lastMessagePath,
+      );
+      await liveAgentConsole?.finalize('completed', preferredOutput);
+      await this.persistRawAgentOutput(input.feature_id, input.role, preferredOutput);
+
+      const parsed = this.outputParser.parse(preferredOutput, {
+        sessionId,
+        role: input.role,
+        featureId: input.feature_id,
+        provider: this.selection.provider,
+        model: this.selection.model,
+        executionMode: input.execution_mode,
       });
+      // CLI providers do not expose token usage; return unavailable status.
+      parsed.usage = unavailableUsage(
+        effectiveSelection.provider,
+        effectiveSelection.model,
+        input.role,
+      );
+      return parsed;
+    } catch (error) {
+      await liveAgentConsole?.finalize('failed');
       throw error;
+    } finally {
+      await this.cleanupOutputCapture(outputCapture.captureDir);
     }
-    const watchdogOutcome = watchdog.stop({
-      signal: runResult.signal,
-      timedOut: runResult.timedOut ?? false,
-    });
-
-    this.ensureRunSucceeded(
-      runResult,
-      this.runTemplate.command,
-      args,
-      effectiveTimeoutMs,
-      watchdogOutcome,
-    );
-    await this.persistRawAgentOutput(input.feature_id, input.role, runResult.stdout ?? '');
-
-    return this.outputParser.parse(runResult.stdout ?? '', {
-      sessionId,
-      role: input.role,
-      featureId: input.feature_id,
-      provider: this.selection.provider,
-      model: this.selection.model,
-    });
   }
 
   getCapabilities(): WorkerProviderCapabilities {
@@ -425,6 +1122,88 @@ export class CliWorkerProvider implements WorkerProvider {
     return `${role}::${featureId}`;
   }
 
+  private resolveOrCreateSessionId(role: string, featureId: string): string {
+    const key = this.sessionKey(role, featureId);
+    const existingSessionId = this.sessionsByRoleFeature.get(key);
+    if (existingSessionId) {
+      return existingSessionId;
+    }
+
+    const sessionId = crypto.randomUUID();
+    this.sessionsByRoleFeature.set(key, sessionId);
+    this.systemPromptsBySession.set(sessionId, null);
+    return sessionId;
+  }
+
+  private refreshSessionForRoleFeature(role: string, featureId: string): void {
+    const key = this.sessionKey(role, featureId);
+    const oldSessionId = this.sessionsByRoleFeature.get(key);
+    if (!oldSessionId) {
+      return;
+    }
+    const systemPrompt = this.systemPromptsBySession.get(oldSessionId) ?? null;
+    const newSessionId = crypto.randomUUID();
+    this.sessionsByRoleFeature.set(key, newSessionId);
+    this.bootstrappedSessionIds.delete(oldSessionId);
+    this.systemPromptsBySession.delete(oldSessionId);
+    this.systemPromptsBySession.set(newSessionId, systemPrompt);
+  }
+
+  private async shouldResumeSession(
+    provider: string,
+    sessionId: string,
+    workingDirectory: string,
+  ): Promise<boolean> {
+    if (provider !== 'claude') {
+      return false;
+    }
+    if (this.bootstrappedSessionIds.has(sessionId)) {
+      return true;
+    }
+    try {
+      await fs.access(resolveClaudeTranscriptPath(workingDirectory, sessionId));
+      this.bootstrappedSessionIds.add(sessionId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private markSessionBootstrapped(provider: string, sessionId: string): void {
+    if (provider === 'claude') {
+      this.bootstrappedSessionIds.add(sessionId);
+    }
+  }
+
+  private resolveEffectiveSelection(
+    runtimeSelection: WorkerRunInput['runtime_selection'] | null,
+  ): ProviderSelection {
+    if (!runtimeSelection) {
+      return this.selection;
+    }
+    if (runtimeSelection.provider !== this.selection.provider) {
+      throw providerError(
+        ERROR_CODES.INVALID_ARGUMENT,
+        'Runtime selection provider override is not supported for this worker provider',
+        {
+          provider: this.selection.provider,
+          runtime_provider: runtimeSelection.provider,
+        },
+      );
+    }
+
+    return {
+      ...this.selection,
+      provider: runtimeSelection.provider,
+      model: runtimeSelection.model,
+      provider_config_env: runtimeSelection.provider_config_env ?? null,
+      provider_config_ref: runtimeSelection.provider_config_ref,
+      agent_config: isRecord(runtimeSelection.agent_config)
+        ? runtimeSelection.agent_config
+        : this.selection.agent_config,
+    };
+  }
+
   private ensureRunSucceeded(
     result: ProviderCommandResult,
     command: string,
@@ -452,6 +1231,7 @@ export class CliWorkerProvider implements WorkerProvider {
       idle_for_ms: watchdogOutcome.idleForMs,
       elapsed_ms: watchdogOutcome.elapsedMs,
       stderr: result.stderr,
+      stdout: result.stdout ? result.stdout.slice(0, 500) : undefined,
     });
   }
 
@@ -512,6 +1292,7 @@ export class CliWorkerProvider implements WorkerProvider {
       featureId: 'global',
       role: 'orchestrator',
       message,
+      model: this.selection.model,
     });
 
     const result = await this.commandRunner.run(template.command, args, {
@@ -524,6 +1305,15 @@ export class CliWorkerProvider implements WorkerProvider {
       return;
     }
 
+    if (
+      kind === 'send' &&
+      typeof message === 'string' &&
+      this.isMissingClaudeConversation(result) &&
+      (await this.bootstrapMissingClaudeControlSession(sessionId, message))
+    ) {
+      return;
+    }
+
     throw providerError(
       result.exitCode === 127 || result.errorCode === 'ENOENT'
         ? ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER
@@ -537,10 +1327,159 @@ export class CliWorkerProvider implements WorkerProvider {
         exit_code: result.exitCode,
         signal: result.signal,
         error_code: result.errorCode,
+        timed_out: result.timedOut ?? false,
+        stdout: result.stdout,
+        stderr: result.stderr,
       },
     );
   }
 
+  private async createLiveAgentConsoleCapture(input: {
+    featureId: string;
+    role: string;
+    sessionId: string;
+    provider: string;
+    model: string | null;
+    executionMode: 'deterministic' | 'interactive';
+    workingDirectory: string;
+  }): Promise<LiveAgentConsoleCapture | null> {
+    if (!this.rawAgentLogsEnabled || !this.repoRoot || !isRawLogRole(input.role)) {
+      return null;
+    }
+
+    const liveDir = path.join(this.repoRoot, '.aop', 'features', input.featureId, 'logs', 'live');
+    const contentPath = path.join(liveDir, `${input.role}.txt`);
+    const metadataPath = path.join(liveDir, `${input.role}.json`);
+    const startedAt = new Date().toISOString();
+    let writeChain = Promise.resolve();
+    let hasLiveContent = false;
+    let finalized = false;
+    let transcriptInterval: NodeJS.Timeout | null = null;
+    let lastTranscriptMtimeMs = -1;
+    let lastRenderedTranscript = '';
+    const transcriptPath =
+      input.provider === 'claude'
+        ? resolveClaudeTranscriptPath(input.workingDirectory, input.sessionId)
+        : null;
+
+    const enqueue = (task: () => Promise<void>): void => {
+      writeChain = writeChain.then(task).catch(() => undefined);
+    };
+
+    const syncClaudeTranscript = (): void => {
+      if (!transcriptPath || finalized) {
+        return;
+      }
+
+      enqueue(async () => {
+        try {
+          const stats = await fs.stat(transcriptPath);
+          if (stats.mtimeMs <= lastTranscriptMtimeMs) {
+            return;
+          }
+
+          const raw = await fs.readFile(transcriptPath, 'utf8');
+          const rendered = renderClaudeTranscript(raw);
+          lastTranscriptMtimeMs = stats.mtimeMs;
+          if (rendered === lastRenderedTranscript) {
+            return;
+          }
+
+          lastRenderedTranscript = rendered;
+          hasLiveContent = rendered.trim().length > 0;
+          await fs.writeFile(contentPath, rendered, 'utf8');
+        } catch {
+          // Claude transcript mirroring is best-effort.
+        }
+      });
+    };
+
+    try {
+      await fs.mkdir(liveDir, { recursive: true });
+      await fs.writeFile(contentPath, '', 'utf8');
+      await fs.writeFile(
+        metadataPath,
+        JSON.stringify(
+          {
+            feature_id: input.featureId,
+            role: input.role,
+            session_id: input.sessionId,
+            provider: input.provider,
+            model: input.model,
+            execution_mode: input.executionMode,
+            status: 'running',
+            started_at: startedAt,
+            ended_at: null,
+          },
+          null,
+          2,
+        ),
+        'utf8',
+      );
+    } catch {
+      return null;
+    }
+
+    if (transcriptPath) {
+      syncClaudeTranscript();
+      transcriptInterval = setInterval(() => {
+        syncClaudeTranscript();
+      }, 500);
+    }
+
+    return {
+      appendChunk: (chunk: string) => {
+        if (finalized || chunk.length === 0 || transcriptPath) {
+          return;
+        }
+        hasLiveContent = true;
+        enqueue(async () => {
+          await fs.appendFile(contentPath, chunk, 'utf8');
+        });
+      },
+      finalize: async (status: 'completed' | 'failed', fallbackContent?: string) => {
+        if (finalized) {
+          return;
+        }
+        finalized = true;
+        if (transcriptInterval) {
+          clearInterval(transcriptInterval);
+          transcriptInterval = null;
+        }
+        if (transcriptPath) {
+          syncClaudeTranscript();
+        }
+        if (!hasLiveContent && typeof fallbackContent === 'string' && fallbackContent.length > 0) {
+          enqueue(async () => {
+            await fs.writeFile(contentPath, fallbackContent, 'utf8');
+          });
+        }
+        await writeChain;
+        await fs
+          .writeFile(
+            metadataPath,
+            JSON.stringify(
+              {
+                feature_id: input.featureId,
+                role: input.role,
+                session_id: input.sessionId,
+                provider: input.provider,
+                model: input.model,
+                execution_mode: input.executionMode,
+                status,
+                started_at: startedAt,
+                ended_at: new Date().toISOString(),
+              },
+              null,
+              2,
+            ),
+            'utf8',
+          )
+          .catch(() => undefined);
+      },
+    };
+  }
+
   private async persistRawAgentOutput(
     featureId: string,
     role: string,
@@ -552,7 +1491,7 @@ export class CliWorkerProvider implements WorkerProvider {
     if (stdout.trim().length === 0) {
       return;
     }
-    if (role !== 'planner' && role !== 'builder' && role !== 'qa') {
+    if (!isRawLogRole(role)) {
       return;
     }
 
@@ -569,6 +1508,43 @@ export class CliWorkerProvider implements WorkerProvider {
     }
   }
 
+  private async createOutputCapture(
+    args: string[],
+  ): Promise<{ captureDir: string | null; lastMessagePath: string | null }> {
+    if (!args.includes('{output_last_message_path}')) {
+      return { captureDir: null, lastMessagePath: null };
+    }
+    const captureDir = await fs.mkdtemp(path.join(os.tmpdir(), 'aop-provider-output-'));
+    return {
+      captureDir,
+      lastMessagePath: path.join(captureDir, 'last-message.txt'),
+    };
+  }
+
+  private async resolvePreferredWorkerOutput(
+    stdout: string,
+    lastMessagePath: string | null,
+  ): Promise<string> {
+    if (lastMessagePath) {
+      try {
+        const lastMessage = await fs.readFile(lastMessagePath, 'utf8');
+        if (lastMessage.trim().length > 0) {
+          return lastMessage;
+        }
+      } catch {
+        // Fall back to stdout when the provider does not materialize the capture file.
+      }
+    }
+    return stdout;
+  }
+
+  private async cleanupOutputCapture(captureDir: string | null): Promise<void> {
+    if (!captureDir) {
+      return;
+    }
+    await fs.rm(captureDir, { recursive: true, force: true }).catch(() => undefined);
+  }
+
   private async cleanupExpiredRawAgentLogs(logsDir: string): Promise<void> {
     const cutoffMs = Date.now() - this.rawAgentLogsRetentionDays * 24 * 60 * 60 * 1000;
     try {