agentic-orchestrator 0.1.28 → 0.2.0

package/dist/apps/control-plane/providers/cli-worker-provider.js

@@ -1,8 +1,10 @@
 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 { NodeProviderCommandRunner, } from './providers.js';
+import { unavailableUsage } from '../application/usage-types.js';
 import { PROVIDER_CLI_DEFAULTS } from './provider-defaults.js';
 import { WorkerWatchdog } from './worker-watchdog.js';
 const CLAUDE_MIN_EFFECTIVE_TIMEOUT_MS = 300_000;
@@ -19,15 +21,117 @@ const CLI_PROVIDER_CAPABILITIES = {
     supportsMessagePassing: true,
     supportsAcknowledgment: false,
 };
-function buildStructuredWorkerPrompt(payload, systemPrompt) {
+function buildDeterministicWorkerPrompt(payload, systemPrompt) {
     const lines = [];
     if (systemPrompt) {
         lines.push(systemPrompt);
         lines.push('---');
     }
-    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", ...}], ...}', 'Do not wrap JSON in markdown code fences.', 'Worker input payload:', JSON.stringify(payload));
+    lines.push('Return exactly one JSON object and nothing else.', 'Allowed output object forms:', '{"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));
     return lines.join('\n');
 }
+function buildInteractiveWorkerPrompt(payload, systemPrompt) {
+    const lines = [];
+    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.status === 'string'
+        ? projectedContext.state.status
+        : 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, systemPrompt, executionMode) {
+    if (executionMode === 'interactive') {
+        return buildInteractiveWorkerPrompt(payload, systemPrompt);
+    }
+    return buildDeterministicWorkerPrompt(payload, systemPrompt);
+}
+export async function resolvePromptOverlay(overlayDir, role, provider) {
+    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) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -45,6 +149,96 @@ function asNonEmptyString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+function projectInteractiveContext(contextBundle) {
+    if (!isRecord(contextBundle)) {
+        return null;
+    }
+    const projected = {};
+    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 !== 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 !== 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, kind, fallback) {
     const nested = isRecord(config?.[kind]) ? config?.[kind] : null;
     const nestedCommand = asNonEmptyString(nested?.command);
@@ -58,17 +252,28 @@ function templateFromConfig(config, kind, fallback) {
     }
     return { command, args };
 }
-function resolveRunTemplate(selection) {
+function appendExtraArgs(template, extraArgs) {
+    if (!template || !extraArgs?.length) {
+        return template;
+    }
+    return { command: template.command, args: [...template.args, ...extraArgs] };
+}
+function resolveRunTemplate(selection, resumeSession) {
     const topLevelCommand = asNonEmptyString(selection.agent_config?.command);
     const topLevelArgs = readStringArray(selection.agent_config?.args);
     const topLevelTemplate = topLevelCommand && topLevelArgs ? { command: topLevelCommand, args: topLevelArgs } : undefined;
-    return templateFromConfig(selection.agent_config, 'run', topLevelTemplate ?? PROVIDER_CLI_DEFAULTS[selection.provider]?.run);
+    const defaults = PROVIDER_CLI_DEFAULTS[selection.provider];
+    const kind = resumeSession ? 'run_resume' : 'run';
+    const template = templateFromConfig(selection.agent_config, kind, topLevelTemplate ?? (resumeSession ? defaults?.run_resume : undefined) ?? defaults?.run);
+    return appendExtraArgs(template, selection.cli_extra_args);
 }
 function resolveAttachTemplate(selection) {
-    return templateFromConfig(selection.agent_config, 'attach', PROVIDER_CLI_DEFAULTS[selection.provider]?.attach);
+    const template = templateFromConfig(selection.agent_config, 'attach', PROVIDER_CLI_DEFAULTS[selection.provider]?.attach);
+    return appendExtraArgs(template, selection.cli_extra_args);
 }
 function resolveSendTemplate(selection) {
-    return templateFromConfig(selection.agent_config, 'send', PROVIDER_CLI_DEFAULTS[selection.provider]?.send);
+    const template = templateFromConfig(selection.agent_config, 'send', PROVIDER_CLI_DEFAULTS[selection.provider]?.send);
+    return appendExtraArgs(template, selection.cli_extra_args);
 }
 function applyTemplateArgs(args, values) {
     return args.map((arg) => {
@@ -87,6 +292,12 @@ function applyTemplateArgs(args, values) {
         if (arg === '{message}') {
             return values.message ?? '';
         }
+        if (arg === '{output_last_message_path}') {
+            return values.outputLastMessagePath ?? '';
+        }
+        if (arg === '{model}') {
+            return values.model ?? '';
+        }
         return arg;
     });
 }
@@ -101,6 +312,12 @@ function buildRunCommandEnv(selection) {
     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;
 }
 function asPositiveInteger(value, fallback) {
@@ -121,6 +338,174 @@ function resolveCliWorkerCapabilities(selection) {
         supportsSpawnDetection: true,
     };
 }
+function isRawLogRole(role) {
+    return role === 'planner' || role === 'builder' || role === 'qa';
+}
+function sanitizeClaudeProjectKey(value) {
+    return value.replace(/[^A-Za-z0-9]/g, '-');
+}
+function resolveClaudeTranscriptPath(workingDirectory, sessionId) {
+    return path.join(os.homedir(), '.claude', 'projects', sanitizeClaudeProjectKey(workingDirectory), `${sessionId}.jsonl`);
+}
+function asNonEmptyStringOrNull(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function collectClaudeTranscriptTextBlocks(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const blocks = [];
+    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) {
+    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) => typeof value === 'string');
+        if (renderedSpecs.length > 0) {
+            return renderedSpecs.join(', ');
+        }
+    }
+    return null;
+}
+function renderClaudeTranscriptEntry(record) {
+    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 = [];
+        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 = [];
+        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) {
+    const rendered = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            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 {
     mode = 'live';
     selection;
@@ -135,14 +520,57 @@ export class CliWorkerProvider {
     workerWatchdogPollIntervalMs;
     workerKillGracePeriodMs;
     repoRoot;
+    overlayDir;
     rawAgentLogsEnabled;
     rawAgentLogsRetentionDays;
     workerCapabilities;
-    runTemplate;
     attachTemplate;
     sendTemplate;
     sessionsByRoleFeature = new Map();
     systemPromptsBySession = new Map();
+    bootstrappedSessionIds = new Set();
+    overlayCache = new Map();
+    isMissingClaudeConversation(result) {
+        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'));
+    }
+    buildBootstrapControlPrompt(sessionId, message) {
+        const systemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
+        return systemPrompt ? `${systemPrompt}\n---\n${message}` : message;
+    }
+    async bootstrapMissingClaudeControlSession(sessionId, message) {
+        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, options) {
         this.selection = selection;
         this.outputParser = options.outputParser;
@@ -154,10 +582,10 @@ export class CliWorkerProvider {
         this.workerKillGracePeriodMs = asPositiveInteger(options.workerKillGracePeriodMs, DEFAULT_KILL_GRACE_PERIOD_MS);
         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);
         if (this.attachTemplate) {
@@ -176,7 +604,7 @@ export class CliWorkerProvider {
         }
     }
     createSession(role, featureId, systemPrompt) {
-        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({
@@ -203,34 +631,75 @@ export class CliWorkerProvider {
                 this.sessionsByRoleFeature.delete(key);
             }
         }
+        this.bootstrappedSessionIds.delete(sessionId);
         this.systemPromptsBySession.delete(sessionId);
         return Promise.resolve({ closed: true });
     }
     async runWorker(input) {
-        if (!this.runTemplate) {
+        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 args = applyTemplateArgs(this.runTemplate.args, {
+        const baseSystemPrompt = this.systemPromptsBySession.get(sessionId) ?? null;
+        let systemPrompt = baseSystemPrompt;
+        if (baseSystemPrompt && this.overlayDir) {
+            const cacheKey = `${input.role}.${effectiveSelection.provider}`;
+            let overlay;
+            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(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);
@@ -256,40 +725,63 @@ export class CliWorkerProvider {
             watchdog.recordActivity(event.type);
         };
         watchdog.start();
-        let runResult;
         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;
+            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,
+            });
+            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) {
-            watchdog.stop({
-                signal: null,
-            });
+            await liveAgentConsole?.finalize('failed');
             throw error;
         }
-        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,
-        });
+        finally {
+            await this.cleanupOutputCapture(outputCapture.captureDir);
+        }
     }
     getCapabilities() {
         return CLI_PROVIDER_CAPABILITIES;
@@ -297,6 +789,72 @@ export class CliWorkerProvider {
     sessionKey(role, featureId) {
         return `${role}::${featureId}`;
     }
+    resolveOrCreateSessionId(role, featureId) {
+        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;
+    }
+    refreshSessionForRoleFeature(role, featureId) {
+        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);
+    }
+    async shouldResumeSession(provider, sessionId, workingDirectory) {
+        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;
+        }
+    }
+    markSessionBootstrapped(provider, sessionId) {
+        if (provider === 'claude') {
+            this.bootstrappedSessionIds.add(sessionId);
+        }
+    }
+    resolveEffectiveSelection(runtimeSelection) {
+        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,
+        };
+    }
     ensureRunSucceeded(result, command, args, timeoutMs, watchdogOutcome) {
         if (result.exitCode === 0) {
             return;
@@ -317,6 +875,7 @@ export class CliWorkerProvider {
             idle_for_ms: watchdogOutcome.idleForMs,
             elapsed_ms: watchdogOutcome.elapsedMs,
             stderr: result.stderr,
+            stdout: result.stdout ? result.stdout.slice(0, 500) : undefined,
         });
     }
     classifyRunFailureErrorCode(result, watchdogOutcome) {
@@ -359,6 +918,7 @@ export class CliWorkerProvider {
             featureId: 'global',
             role: 'orchestrator',
             message,
+            model: this.selection.model,
         });
         const result = await this.commandRunner.run(template.command, args, {
             interactive: kind === 'attach',
@@ -368,6 +928,12 @@ export class CliWorkerProvider {
         if (result.exitCode === 0) {
             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
             : ERROR_CODES.INTERNAL_ERROR, `Provider ${kind} command failed`, {
@@ -378,8 +944,124 @@ export class CliWorkerProvider {
             exit_code: result.exitCode,
             signal: result.signal,
             error_code: result.errorCode,
+            timed_out: result.timedOut ?? false,
+            stdout: result.stdout,
+            stderr: result.stderr,
         });
     }
+    async createLiveAgentConsoleCapture(input) {
+        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 = null;
+        let lastTranscriptMtimeMs = -1;
+        let lastRenderedTranscript = '';
+        const transcriptPath = input.provider === 'claude'
+            ? resolveClaudeTranscriptPath(input.workingDirectory, input.sessionId)
+            : null;
+        const enqueue = (task) => {
+            writeChain = writeChain.then(task).catch(() => undefined);
+        };
+        const syncClaudeTranscript = () => {
+            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) => {
+                if (finalized || chunk.length === 0 || transcriptPath) {
+                    return;
+                }
+                hasLiveContent = true;
+                enqueue(async () => {
+                    await fs.appendFile(contentPath, chunk, 'utf8');
+                });
+            },
+            finalize: async (status, fallbackContent) => {
+                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);
+            },
+        };
+    }
     async persistRawAgentOutput(featureId, role, stdout) {
         if (!this.rawAgentLogsEnabled || !this.repoRoot) {
             return;
@@ -387,7 +1069,7 @@ export class CliWorkerProvider {
         if (stdout.trim().length === 0) {
             return;
         }
-        if (role !== 'planner' && role !== 'builder' && role !== 'qa') {
+        if (!isRawLogRole(role)) {
             return;
         }
         const logsDir = path.join(this.repoRoot, '.aop', 'features', featureId, 'logs');
@@ -402,6 +1084,36 @@ export class CliWorkerProvider {
             // Raw log persistence must not fail orchestration flow.
         }
     }
+    async createOutputCapture(args) {
+        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'),
+        };
+    }
+    async resolvePreferredWorkerOutput(stdout, lastMessagePath) {
+        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;
+    }
+    async cleanupOutputCapture(captureDir) {
+        if (!captureDir) {
+            return;
+        }
+        await fs.rm(captureDir, { recursive: true, force: true }).catch(() => undefined);
+    }
     async cleanupExpiredRawAgentLogs(logsDir) {
         const cutoffMs = Date.now() - this.rawAgentLogsRetentionDays * 24 * 60 * 60 * 1000;
         try {