@kbediako/codex-orchestrator 0.1.12 → 0.1.14-alpha.1

package/dist/orchestrator/src/cli/orchestrator.js

@@ -20,7 +20,7 @@ import { PipelineResolver } from './services/pipelineResolver.js';
 import { ControlPlaneService } from './services/controlPlaneService.js';
 import { ControlWatcher } from './control/controlWatcher.js';
 import { SchedulerService } from './services/schedulerService.js';
-import { applyHandlesToRunSummary, applyPrivacyToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
+import { applyHandlesToRunSummary, applyPrivacyToRunSummary, applyCloudExecutionToRunSummary, persistRunSummary } from './services/runSummaryWriter.js';
 import { prepareRun, resolvePipelineForResume, overrideTaskEnvironment } from './services/runPreparation.js';
 import { loadPackageConfig, loadUserConfig } from './config/userConfig.js';
 import { loadDelegationConfigFiles, computeEffectiveDelegationConfig, parseDelegationConfigOverride, splitDelegationConfigOverrides } from './config/delegationConfig.js';
@@ -28,8 +28,13 @@ import { ControlServer } from './control/controlServer.js';
 import { RunEventEmitter, RunEventPublisher, snapshotStages } from './events/runEvents.js';
 import { RunEventStream, attachRunEventAdapter } from './events/runEventStream.js';
 import { CLI_EXECUTION_MODE_PARSER, resolveRequiresCloudPolicy } from '../utils/executionMode.js';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+import { CodexCloudTaskExecutor } from '../cloud/CodexCloudTaskExecutor.js';
 const resolveBaseEnvironment = () => normalizeEnvironmentPaths(resolveEnvironmentPaths());
 const CONFIG_OVERRIDE_ENV_KEYS = ['CODEX_CONFIG_OVERRIDES', 'CODEX_MCP_CONFIG_OVERRIDES'];
+const DEFAULT_CLOUD_POLL_INTERVAL_SECONDS = 10;
+const DEFAULT_CLOUD_TIMEOUT_SECONDS = 1800;
+const DEFAULT_CLOUD_ATTEMPTS = 1;
 function collectDelegationEnvOverrides(env = process.env) {
     const layers = [];
     for (const key of CONFIG_OVERRIDE_ENV_KEYS) {
@@ -52,6 +57,37 @@ function collectDelegationEnvOverrides(env = process.env) {
     }
     return layers;
 }
+function readCloudString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function readCloudNumber(raw, fallback) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return parsed;
+}
+function resolveCloudEnvironmentId(task, target, envOverrides) {
+    const metadata = (target.metadata ?? {});
+    const taskMetadata = (task.metadata ?? {});
+    const taskCloud = (taskMetadata.cloud ?? null);
+    const candidates = [
+        readCloudString(metadata.cloudEnvId),
+        readCloudString(metadata.cloud_env_id),
+        readCloudString(metadata.envId),
+        readCloudString(metadata.environmentId),
+        readCloudString(taskCloud?.envId),
+        readCloudString(taskCloud?.environmentId),
+        readCloudString(taskMetadata.cloudEnvId),
+        readCloudString(taskMetadata.cloud_env_id),
+        readCloudString(envOverrides?.CODEX_CLOUD_ENV_ID),
+        readCloudString(process.env.CODEX_CLOUD_ENV_ID)
+    ];
+    return candidates.find((candidate) => candidate !== null) ?? null;
+}
 export class CodexOrchestrator {
     baseEnv;
     controlPlane = new ControlPlaneService();
@@ -136,7 +172,8 @@ export class CodexOrchestrator {
                 eventStream: stream,
                 onEventEntry,
                 persister,
-                envOverrides: preparation.envOverrides
+                envOverrides: preparation.envOverrides,
+                executionModeOverride: options.executionMode
             });
         }
         finally {
@@ -360,7 +397,7 @@ export class CodexOrchestrator {
             logPath: params.paths.logPath
         });
     }
-    createTaskManager(runId, pipeline, executePipeline, getResult, plannerInstance, env) {
+    createTaskManager(runId, pipeline, executePipeline, getResult, plannerInstance, env, modeOverride) {
         const planner = plannerInstance ?? new CommandPlanner(pipeline);
         const builder = new CommandBuilder(executePipeline);
         const tester = new CommandTester(getResult);
@@ -373,12 +410,15 @@ export class CodexOrchestrator {
             tester,
             reviewer,
             runIdFactory: () => runId,
-            modePolicy: (task, subtask) => this.determineMode(task, subtask),
+            modePolicy: (task, subtask) => this.determineMode(task, subtask, modeOverride),
             persistence: { autoStart: true, stateStore, manifestWriter }
         };
         return new TaskManager(options);
     }
-    determineMode(task, subtask) {
+    determineMode(task, subtask, overrideMode) {
+        if (overrideMode) {
+            return overrideMode;
+        }
         if (this.requiresCloudExecution(task, subtask)) {
             return 'cloud';
         }
@@ -402,6 +442,9 @@ export class CodexOrchestrator {
         return Boolean(task.metadata?.execution?.parallel);
     }
     async executePipeline(options) {
+        if (options.mode === 'cloud') {
+            return await this.executeCloudPipeline(options);
+        }
         const { env, pipeline, manifest, paths, runEvents, envOverrides } = options;
         const notes = [];
         let success = true;
@@ -513,7 +556,8 @@ export class CodexOrchestrator {
                             taskId: env.taskId,
                             pipelineId: stage.pipeline,
                             parentRunId: manifest.run_id,
-                            format: 'json'
+                            format: 'json',
+                            executionMode: options.executionModeOverride
                         });
                         entry.completed_at = isoTimestamp();
                         entry.sub_run_id = child.manifest.run_id;
@@ -607,31 +651,251 @@ export class CodexOrchestrator {
             logPath: relativeToRepo(env, paths.logPath)
         };
     }
+    async executeCloudPipeline(options) {
+        const { env, pipeline, manifest, paths, runEvents, target, task, envOverrides } = options;
+        const notes = [];
+        let success = true;
+        manifest.guardrail_status = undefined;
+        const persister = options.persister ??
+            new ManifestPersister({
+                manifest,
+                paths,
+                persistIntervalMs: Math.max(1000, manifest.heartbeat_interval_seconds * 1000)
+            });
+        const schedulePersist = (persistOptions = {}) => persister.schedule(persistOptions);
+        const pushHeartbeat = (forceManifest = false) => {
+            updateHeartbeat(manifest);
+            return schedulePersist({ manifest: forceManifest, heartbeat: true, force: forceManifest });
+        };
+        const controlWatcher = new ControlWatcher({
+            paths,
+            manifest,
+            eventStream: options.eventStream,
+            onEntry: options.onEventEntry,
+            persist: () => schedulePersist({ manifest: true, force: true })
+        });
+        manifest.status = 'in_progress';
+        updateHeartbeat(manifest);
+        await schedulePersist({ manifest: true, heartbeat: true, force: true });
+        runEvents?.runStarted(snapshotStages(manifest, pipeline), manifest.status);
+        const heartbeatInterval = setInterval(() => {
+            void pushHeartbeat(false).catch((error) => {
+                logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
+            });
+        }, manifest.heartbeat_interval_seconds * 1000);
+        const targetStageId = this.resolveTargetStageId(target, pipeline);
+        const targetStage = targetStageId
+            ? pipeline.stages.find((stage) => stage.id === targetStageId)
+            : undefined;
+        const targetEntry = targetStageId
+            ? manifest.commands.find((command) => command.id === targetStageId)
+            : undefined;
+        try {
+            await controlWatcher.sync();
+            await controlWatcher.waitForResume();
+            if (controlWatcher.isCanceled()) {
+                manifest.status_detail = 'run-canceled';
+                success = false;
+            }
+            else if (!targetStage || targetStage.kind !== 'command' || !targetEntry) {
+                success = false;
+                manifest.status_detail = 'cloud-target-missing';
+                const detail = targetStageId
+                    ? `Cloud execution target "${targetStageId}" could not be resolved to a command stage.`
+                    : `Cloud execution target "${target.id}" could not be resolved.`;
+                appendSummary(manifest, detail);
+                notes.push(detail);
+            }
+            else {
+                for (let i = 0; i < manifest.commands.length; i += 1) {
+                    const entry = manifest.commands[i];
+                    if (!entry || entry.id === targetStageId) {
+                        continue;
+                    }
+                    entry.status = 'skipped';
+                    entry.started_at = entry.started_at ?? isoTimestamp();
+                    entry.completed_at = isoTimestamp();
+                    entry.summary = `Skipped in cloud mode (target stage: ${targetStageId}).`;
+                }
+                const environmentId = resolveCloudEnvironmentId(task, target, envOverrides);
+                if (!environmentId) {
+                    success = false;
+                    manifest.status_detail = 'cloud-env-missing';
+                    const detail = 'Cloud execution requested but no environment id is configured. Set CODEX_CLOUD_ENV_ID or provide target metadata.cloudEnvId.';
+                    manifest.cloud_execution = {
+                        task_id: null,
+                        environment_id: null,
+                        status: 'failed',
+                        status_url: null,
+                        submitted_at: null,
+                        completed_at: isoTimestamp(),
+                        last_polled_at: null,
+                        poll_count: 0,
+                        poll_interval_seconds: DEFAULT_CLOUD_POLL_INTERVAL_SECONDS,
+                        timeout_seconds: DEFAULT_CLOUD_TIMEOUT_SECONDS,
+                        attempts: DEFAULT_CLOUD_ATTEMPTS,
+                        diff_path: null,
+                        diff_url: null,
+                        diff_status: 'unavailable',
+                        apply_status: 'not_requested',
+                        log_path: null,
+                        error: detail
+                    };
+                    appendSummary(manifest, detail);
+                    notes.push(detail);
+                    targetEntry.status = 'failed';
+                    targetEntry.started_at = targetEntry.started_at ?? isoTimestamp();
+                    targetEntry.completed_at = isoTimestamp();
+                    targetEntry.exit_code = 1;
+                    targetEntry.summary = detail;
+                }
+                else {
+                    targetEntry.status = 'running';
+                    targetEntry.started_at = isoTimestamp();
+                    await schedulePersist({ manifest: true, force: true });
+                    runEvents?.stageStarted({
+                        stageId: targetStage.id,
+                        stageIndex: targetEntry.index,
+                        title: targetStage.title,
+                        kind: 'command',
+                        logPath: targetEntry.log_path,
+                        status: targetEntry.status
+                    });
+                    const executor = new CodexCloudTaskExecutor();
+                    const prompt = this.buildCloudPrompt(task, target, pipeline, targetStage);
+                    const pollIntervalSeconds = readCloudNumber(envOverrides?.CODEX_CLOUD_POLL_INTERVAL_SECONDS ?? process.env.CODEX_CLOUD_POLL_INTERVAL_SECONDS, DEFAULT_CLOUD_POLL_INTERVAL_SECONDS);
+                    const timeoutSeconds = readCloudNumber(envOverrides?.CODEX_CLOUD_TIMEOUT_SECONDS ?? process.env.CODEX_CLOUD_TIMEOUT_SECONDS, DEFAULT_CLOUD_TIMEOUT_SECONDS);
+                    const attempts = readCloudNumber(envOverrides?.CODEX_CLOUD_EXEC_ATTEMPTS ?? process.env.CODEX_CLOUD_EXEC_ATTEMPTS, DEFAULT_CLOUD_ATTEMPTS);
+                    const branch = readCloudString(envOverrides?.CODEX_CLOUD_BRANCH) ??
+                        readCloudString(process.env.CODEX_CLOUD_BRANCH);
+                    const codexBin = resolveCodexCliBin({ ...process.env, ...(envOverrides ?? {}) });
+                    const cloudResult = await executor.execute({
+                        codexBin,
+                        prompt,
+                        environmentId,
+                        repoRoot: env.repoRoot,
+                        runDir: paths.runDir,
+                        pollIntervalSeconds,
+                        timeoutSeconds,
+                        attempts,
+                        branch,
+                        env: envOverrides
+                    });
+                    success = cloudResult.success;
+                    notes.push(...cloudResult.notes);
+                    manifest.cloud_execution = cloudResult.cloudExecution;
+                    targetEntry.log_path = cloudResult.cloudExecution.log_path;
+                    targetEntry.completed_at = isoTimestamp();
+                    targetEntry.exit_code = cloudResult.success ? 0 : 1;
+                    targetEntry.status = cloudResult.success ? 'succeeded' : 'failed';
+                    targetEntry.summary = cloudResult.summary;
+                    if (!cloudResult.success) {
+                        manifest.status_detail = `cloud:${targetStage.id}:failed`;
+                        appendSummary(manifest, cloudResult.summary);
+                    }
+                    await schedulePersist({ manifest: true, force: true });
+                    runEvents?.stageCompleted({
+                        stageId: targetStage.id,
+                        stageIndex: targetEntry.index,
+                        title: targetStage.title,
+                        kind: 'command',
+                        status: targetEntry.status,
+                        exitCode: targetEntry.exit_code,
+                        summary: targetEntry.summary,
+                        logPath: targetEntry.log_path
+                    });
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeatInterval);
+            await schedulePersist({ force: true });
+        }
+        await controlWatcher.sync();
+        if (controlWatcher.isCanceled()) {
+            finalizeStatus(manifest, 'cancelled', manifest.status_detail ?? 'run-canceled');
+        }
+        else if (success) {
+            finalizeStatus(manifest, 'succeeded');
+        }
+        else {
+            finalizeStatus(manifest, 'failed', manifest.status_detail ?? 'cloud-execution-failed');
+        }
+        updateHeartbeat(manifest);
+        await schedulePersist({ manifest: true, heartbeat: true, force: true }).catch((error) => {
+            logger.warn(`Heartbeat update failed for run ${manifest.run_id}: ${error?.message ?? String(error)}`);
+        });
+        await schedulePersist({ force: true });
+        await appendMetricsEntry(env, paths, manifest, persister);
+        return {
+            success,
+            notes,
+            manifest,
+            manifestPath: relativeToRepo(env, paths.manifestPath),
+            logPath: relativeToRepo(env, paths.logPath)
+        };
+    }
+    resolveTargetStageId(target, pipeline) {
+        const metadataStageId = typeof target.metadata?.stageId === 'string' ? target.metadata.stageId : null;
+        if (metadataStageId && pipeline.stages.some((stage) => stage.id === metadataStageId)) {
+            return metadataStageId;
+        }
+        if (target.id.includes(':')) {
+            const suffix = target.id.split(':').pop() ?? null;
+            if (suffix && pipeline.stages.some((stage) => stage.id === suffix)) {
+                return suffix;
+            }
+        }
+        if (pipeline.stages.some((stage) => stage.id === target.id)) {
+            return target.id;
+        }
+        return null;
+    }
+    buildCloudPrompt(task, target, pipeline, stage) {
+        const lines = [
+            `Task ID: ${task.id}`,
+            `Task title: ${task.title}`,
+            task.description ? `Task description: ${task.description}` : null,
+            `Pipeline: ${pipeline.id}`,
+            `Target stage: ${stage.id} (${target.description})`,
+            '',
+            'Apply the required repository changes for this target stage and produce a diff.'
+        ].filter((line) => Boolean(line));
+        return lines.join('\n');
+    }
     async performRunLifecycle(context) {
-        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides } = context;
-        let pipelineResult = null;
-        let executing = null;
-        const executePipeline = async () => {
-            if (!executing) {
-                executing = this.executePipeline({
-                    env,
-                    pipeline,
-                    manifest,
-                    paths,
-                    runEvents: context.runEvents,
-                    eventStream: context.eventStream,
-                    onEventEntry: context.onEventEntry,
-                    persister,
-                    envOverrides
-                }).then((result) => {
-                    pipelineResult = result;
-                    return result;
-                });
+        const { env, pipeline, manifest, paths, planner, taskContext, runId, persister, envOverrides, executionModeOverride } = context;
+        let latestPipelineResult = null;
+        const executingByKey = new Map();
+        const executePipeline = async (input) => {
+            const key = `${input.mode}:${input.target.id}`;
+            const existing = executingByKey.get(key);
+            if (existing) {
+                return existing;
             }
+            const executing = this.executePipeline({
+                env,
+                pipeline,
+                manifest,
+                paths,
+                mode: input.mode,
+                executionModeOverride,
+                target: input.target,
+                task: taskContext,
+                runEvents: context.runEvents,
+                eventStream: context.eventStream,
+                onEventEntry: context.onEventEntry,
+                persister,
+                envOverrides
+            }).then((result) => {
+                latestPipelineResult = result;
+                return result;
+            });
+            executingByKey.set(key, executing);
             return executing;
         };
-        const getResult = () => pipelineResult;
-        const manager = this.createTaskManager(runId, pipeline, executePipeline, getResult, planner, env);
+        const getResult = () => latestPipelineResult;
+        const manager = this.createTaskManager(runId, pipeline, executePipeline, getResult, planner, env, executionModeOverride);
         this.attachPlanTargetTracker(manager, manifest, paths, persister);
         getPrivacyGuard().reset();
         const controlPlaneResult = await this.controlPlane.guard({
@@ -672,6 +936,7 @@ export class CodexOrchestrator {
         this.scheduler.applySchedulerToRunSummary(runSummary, schedulerPlan);
         applyHandlesToRunSummary(runSummary, manifest);
         applyPrivacyToRunSummary(runSummary, manifest);
+        applyCloudExecutionToRunSummary(runSummary, manifest);
         this.controlPlane.applyControlPlaneToRunSummary(runSummary, controlPlaneResult);
         await persistRunSummary(env, paths, manifest, runSummary, persister);
         context.runEvents?.runCompleted({
@@ -722,7 +987,8 @@ export class CodexOrchestrator {
             log_path: manifest.log_path,
             heartbeat_at: manifest.heartbeat_at,
             commands: manifest.commands,
-            child_runs: manifest.child_runs
+            child_runs: manifest.child_runs,
+            cloud_execution: manifest.cloud_execution ?? null
         };
     }
     renderStatus(manifest) {
@@ -731,6 +997,10 @@ export class CodexOrchestrator {
         logger.info(`Started: ${manifest.started_at}`);
         logger.info(`Completed: ${manifest.completed_at ?? 'in-progress'}`);
         logger.info(`Manifest: ${manifest.artifact_root}/manifest.json`);
+        if (manifest.cloud_execution?.task_id) {
+            logger.info(`Cloud: ${manifest.cloud_execution.task_id} [${manifest.cloud_execution.status}]` +
+                (manifest.cloud_execution.status_url ? ` ${manifest.cloud_execution.status_url}` : ''));
+        }
         logger.info('Commands:');
         for (const command of manifest.commands) {
             const summary = command.summary ? ` — ${command.summary}` : '';

package/dist/orchestrator/src/cli/rlm/context.js

@@ -216,6 +216,29 @@ export class ContextStore {
     get sourceByteLength() {
         return this.context.index.source.byte_length;
     }
+    resolveChunkId(chunkId) {
+        if (this.chunkMap.has(chunkId)) {
+            return chunkId;
+        }
+        if (!/^\d+$/.test(chunkId)) {
+            return null;
+        }
+        const index = Number.parseInt(chunkId, 10);
+        if (!Number.isFinite(index)) {
+            return null;
+        }
+        const chunks = this.context.index.chunks;
+        if (index >= 0 && index < chunks.length) {
+            return chunks[index]?.id ?? null;
+        }
+        // Some upstream pointers are 1-based. Tolerate that legacy form by
+        // mapping index=N to chunks[N-1] when the 0-based lookup is out of range.
+        const fallback = index - 1;
+        if (fallback >= 0 && fallback < chunks.length) {
+            return chunks[fallback]?.id ?? null;
+        }
+        return null;
+    }
     validatePointer(pointer) {
         const parsed = parseContextPointer(pointer);
         if (!parsed) {
@@ -224,10 +247,11 @@ export class ContextStore {
         if (parsed.objectId !== this.context.index.object_id) {
             return null;
         }
-        if (!this.chunkMap.has(parsed.chunkId)) {
+        const resolvedChunkId = this.resolveChunkId(parsed.chunkId);
+        if (!resolvedChunkId) {
             return null;
         }
-        return parsed;
+        return { objectId: parsed.objectId, chunkId: resolvedChunkId };
     }
     async read(pointer, offset, bytes) {
         const parsed = parseContextPointer(pointer);
@@ -237,7 +261,11 @@ export class ContextStore {
         if (parsed.objectId !== this.context.index.object_id) {
             throw new Error('context object mismatch');
         }
-        const chunk = this.chunkMap.get(parsed.chunkId);
+        const resolvedChunkId = this.resolveChunkId(parsed.chunkId);
+        if (!resolvedChunkId) {
+            throw new Error('context chunk missing');
+        }
+        const chunk = this.chunkMap.get(resolvedChunkId);
         if (!chunk) {
             throw new Error('context chunk missing');
         }

package/dist/orchestrator/src/cli/rlm/symbolic.js

@@ -69,28 +69,153 @@ function toNumber(value) {
     }
     return null;
 }
-function extractJsonCandidate(raw) {
+function extractJsonCandidates(raw) {
     const trimmed = raw.trim();
     if (!trimmed) {
+        return [];
+    }
+    const candidates = [];
+    let start = -1;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < trimmed.length; index += 1) {
+        const char = trimmed[index];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === '{') {
+            if (depth === 0) {
+                start = index;
+            }
+            depth += 1;
+            continue;
+        }
+        if (char === '}') {
+            if (depth > 0) {
+                depth -= 1;
+                if (depth === 0 && start >= 0) {
+                    candidates.push(trimmed.slice(start, index + 1));
+                    start = -1;
+                }
+            }
+        }
+    }
+    return candidates;
+}
+function normalizePlannerPlan(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const record = value;
+    const schemaVersion = record.schema_version;
+    const normalizedSchemaVersion = typeof schemaVersion === 'string' ? Number(schemaVersion) : schemaVersion;
+    if (normalizedSchemaVersion !== 1) {
+        return null;
+    }
+    if (typeof record.intent !== 'string') {
         return null;
     }
-    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
-        return trimmed;
+    if (typeof schemaVersion === 'string' && Number.isFinite(normalizedSchemaVersion)) {
+        record.schema_version = normalizedSchemaVersion;
+    }
+    return record;
+}
+function unwrapPlannerPlan(value) {
+    const direct = normalizePlannerPlan(value);
+    if (direct) {
+        return direct;
+    }
+    if (Array.isArray(value)) {
+        for (let index = value.length - 1; index >= 0; index -= 1) {
+            const normalized = normalizePlannerPlan(value[index]);
+            if (normalized) {
+                return normalized;
+            }
+        }
     }
-    const start = trimmed.indexOf('{');
-    const end = trimmed.lastIndexOf('}');
-    if (start >= 0 && end > start) {
-        return trimmed.slice(start, end + 1);
+    if (value && typeof value === 'object') {
+        const record = value;
+        if (record.plan) {
+            const normalized = normalizePlannerPlan(record.plan);
+            if (normalized) {
+                return normalized;
+            }
+        }
+        const plans = record.plans;
+        if (Array.isArray(plans)) {
+            for (let index = plans.length - 1; index >= 0; index -= 1) {
+                const normalized = normalizePlannerPlan(plans[index]);
+                if (normalized) {
+                    return normalized;
+                }
+            }
+        }
     }
     return null;
 }
 function parsePlannerOutput(raw) {
-    const candidate = extractJsonCandidate(raw);
-    if (!candidate) {
-        throw new Error('plan_parse_error');
+    const candidates = extractJsonCandidates(raw);
+    for (let index = candidates.length - 1; index >= 0; index -= 1) {
+        const candidate = candidates[index];
+        try {
+            const parsed = JSON.parse(candidate);
+            const normalized = unwrapPlannerPlan(parsed);
+            if (normalized) {
+                return normalized;
+            }
+        }
+        catch {
+            // ignore parse errors and try earlier candidates
+        }
     }
-    const parsed = JSON.parse(candidate);
-    return parsed;
+    if (!candidates.length) {
+        try {
+            const parsed = JSON.parse(raw.trim());
+            const normalized = unwrapPlannerPlan(parsed);
+            if (normalized) {
+                return normalized;
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    throw new Error('plan_parse_error');
+}
+function buildPlannerRetryPrompt(prompt, errors) {
+    const headerLines = ['Return valid JSON only.'];
+    if (errors.includes('final_requires_subcall')) {
+        headerLines.push('Do not return intent=final until after at least one subcall.');
+    }
+    if (errors.length > 0) {
+        headerLines.push(`Previous error: ${errors.join('; ')}`);
+    }
+    return `${headerLines.join(' ')}\n\n${prompt}`;
+}
+async function recordPlannerFailure(params) {
+    const raw = params.raw ?? '';
+    const plannerDir = join(params.runDir, 'planner');
+    await mkdir(plannerDir, { recursive: true });
+    const filename = `iteration-${params.iteration}-attempt-${params.attempt + 1}.txt`;
+    const header = params.errors.length ? `# errors: ${params.errors.join('; ')}\n` : '';
+    const body = raw.length > 0 ? raw : '[empty planner output]';
+    await writeFile(join(plannerDir, filename), `${header}${body}`, 'utf8');
 }
 function normalizePurpose(raw) {
     if (typeof raw === 'string' && DEFAULT_ALLOWED_PURPOSES.has(raw)) {
@@ -366,14 +491,19 @@ export async function runSymbolicLoop(options) {
             const plannerErrors = [];
             const hasPriorSubcalls = priorSubcalls.length > 0;
             for (let attempt = 0; attempt < 2; attempt += 1) {
-                const raw = await options.runPlanner(attempt === 0
-                    ? plannerPrompt
-                    : `Return valid JSON only. Previous error: ${plannerErrors.join('; ')}\n\n${plannerPrompt}`, attempt);
+                const raw = await options.runPlanner(attempt === 0 ? plannerPrompt : buildPlannerRetryPrompt(plannerPrompt, plannerErrors), attempt);
                 try {
                     plan = parsePlannerOutput(raw);
                 }
                 catch {
                     plannerErrors.push('plan_parse_error');
+                    await recordPlannerFailure({
+                        runDir: options.runDir,
+                        iteration,
+                        attempt,
+                        errors: plannerErrors,
+                        raw
+                    });
                     if (attempt === 0) {
                         continue;
                     }
@@ -392,6 +522,13 @@ export async function runSymbolicLoop(options) {
                 }
                 if (validationError) {
                     plannerErrors.push(validationError);
+                    await recordPlannerFailure({
+                        runDir: options.runDir,
+                        iteration,
+                        attempt,
+                        errors: plannerErrors,
+                        raw
+                    });
                     if (attempt === 0) {
                         continue;
                     }