@kbediako/codex-orchestrator 0.1.16 → 0.1.18

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

@@ -1,6 +1,7 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 const DEFAULT_ALLOWED_PURPOSES = new Set(['summarize', 'extract', 'classify', 'verify']);
+const SUBCALL_POINTER_PREFIX = 'subcall:';
 function byteLength(value) {
     return Buffer.byteLength(value ?? '', 'utf8');
 }
@@ -40,6 +41,44 @@ function truncateUtf8ToBytes(value, maxBytes) {
     }
     return buffer.slice(0, end).toString('utf8');
 }
+function isContextPointer(pointer) {
+    return pointer.startsWith('ctx:');
+}
+function parseSubcallPointer(pointer) {
+    if (!pointer.startsWith(SUBCALL_POINTER_PREFIX)) {
+        return null;
+    }
+    const body = pointer.slice(SUBCALL_POINTER_PREFIX.length);
+    const separatorIndex = body.indexOf(':');
+    if (separatorIndex <= 0 || separatorIndex >= body.length - 1) {
+        return null;
+    }
+    const iterationRaw = body.slice(0, separatorIndex);
+    const subcallId = body.slice(separatorIndex + 1);
+    const iteration = Number.parseInt(iterationRaw, 10);
+    if (!Number.isFinite(iteration) || iteration <= 0 || !subcallId) {
+        return null;
+    }
+    return { iteration, subcallId };
+}
+function buildSubcallPointer(iteration, subcallId) {
+    return `${SUBCALL_POINTER_PREFIX}${iteration}:${subcallId}`;
+}
+async function readSubcallPointerSnippet(pointerStore, pointer, offset, bytes) {
+    const record = pointerStore.get(pointer);
+    if (!record) {
+        throw new Error('plan_validation_error');
+    }
+    const raw = await readFile(record.outputPath, 'utf8');
+    const sourceBytes = Buffer.from(raw, 'utf8');
+    const safeOffset = Math.max(0, Math.floor(offset));
+    const safeBytes = Math.max(0, Math.floor(bytes));
+    if (safeOffset >= sourceBytes.length || safeBytes <= 0) {
+        return '';
+    }
+    const end = Math.min(sourceBytes.length, safeOffset + safeBytes);
+    return sourceBytes.subarray(safeOffset, end).toString('utf8');
+}
 async function mapWithConcurrency(items, maxConcurrency, worker) {
     if (items.length === 0) {
         return [];
@@ -203,6 +242,9 @@ function buildPlannerRetryPrompt(prompt, errors) {
     if (errors.includes('final_requires_subcall')) {
         headerLines.push('Do not return intent=final until after at least one subcall.');
     }
+    if (errors.includes('final_var_unbound')) {
+        headerLines.push('Use final_var only when it matches a previously declared subcalls[].output_var.');
+    }
     if (errors.length > 0) {
         headerLines.push(`Previous error: ${errors.join('; ')}`);
     }
@@ -230,10 +272,26 @@ function validatePlan(plan, budgets) {
     if (!['continue', 'final', 'pause', 'fail'].includes(plan.intent)) {
         throw new Error('plan_validation_error');
     }
+    const finalVarRaw = plan.final_var;
+    const finalVar = typeof finalVarRaw === 'string' && finalVarRaw.trim().length > 0
+        ? finalVarRaw.trim()
+        : undefined;
+    if (finalVarRaw !== undefined && !finalVar) {
+        throw new Error('plan_validation_error');
+    }
+    if (finalVar) {
+        plan.final_var = finalVar;
+    }
     if (plan.intent === 'final') {
-        if (typeof plan.final_answer !== 'string' || plan.final_answer.trim().length === 0) {
+        const finalAnswer = typeof plan.final_answer === 'string' && plan.final_answer.trim().length > 0
+            ? plan.final_answer.trim()
+            : null;
+        if (!finalAnswer && !finalVar) {
             throw new Error('plan_validation_error');
         }
+        if (finalAnswer) {
+            plan.final_answer = finalAnswer;
+        }
     }
     const reads = [];
     const rawReads = Array.isArray(plan.reads) ? plan.reads : [];
@@ -277,6 +335,23 @@ function validatePlan(plan, budgets) {
     const rawSubcalls = Array.isArray(plan.subcalls) ? plan.subcalls : [];
     for (const entry of rawSubcalls) {
         const purposeInfo = normalizePurpose(entry?.purpose);
+        const parentPointerRaw = entry?.parent_pointer;
+        if (parentPointerRaw !== undefined && typeof parentPointerRaw !== 'string') {
+            throw new Error('plan_validation_error');
+        }
+        const outputVarRaw = entry?.output_var;
+        if (outputVarRaw !== undefined && typeof outputVarRaw !== 'string') {
+            throw new Error('plan_validation_error');
+        }
+        const parentPointer = typeof parentPointerRaw === 'string' && parentPointerRaw.trim().length > 0
+            ? parentPointerRaw.trim()
+            : undefined;
+        const outputVar = typeof outputVarRaw === 'string' && outputVarRaw.trim().length > 0
+            ? outputVarRaw.trim()
+            : undefined;
+        if (outputVarRaw !== undefined && !outputVar) {
+            throw new Error('plan_validation_error');
+        }
         const maxInputBytes = toNumber(entry?.max_input_bytes);
         if (!maxInputBytes || maxInputBytes <= 0) {
             throw new Error('plan_validation_error');
@@ -320,6 +395,8 @@ function validatePlan(plan, budgets) {
         subcalls.push({
             id: '',
             purpose: purposeInfo.value,
+            parent_pointer: parentPointer,
+            output_var: outputVar,
             snippets,
             spans,
             max_input_bytes: Math.floor(maxInputBytes)
@@ -340,41 +417,116 @@ function validatePlan(plan, budgets) {
         }
     };
 }
-function validatePlanPointers(validation, contextStore) {
+function validatePlanPointers(validation, contextStore, subcallPointers) {
     const ensurePointer = (pointer) => {
         if (!pointer) {
             return;
         }
-        if (!contextStore.validatePointer(pointer)) {
-            throw new Error('plan_validation_error');
+        if (isContextPointer(pointer)) {
+            if (!contextStore.validatePointer(pointer)) {
+                throw new Error('plan_validation_error');
+            }
+            return;
         }
+        if (parseSubcallPointer(pointer)) {
+            if (!subcallPointers.has(pointer)) {
+                throw new Error('plan_validation_error');
+            }
+            return;
+        }
+        throw new Error('plan_validation_error');
     };
     for (const read of validation.reads) {
         ensurePointer(read.pointer);
     }
     for (const subcall of validation.subcalls) {
+        ensurePointer(subcall.parent_pointer);
         for (const snippet of subcall.snippets) {
             ensurePointer(snippet.pointer);
         }
     }
 }
+function formatSubcallSummary(entry) {
+    const preview = truncateUtf8ToBytes(entry.preview ?? '', 160).replace(/\s+/g, ' ').trim();
+    const outputVarSuffix = entry.output_var ? ` output_var=${entry.output_var}` : '';
+    if (!preview) {
+        return `${entry.id}: ${entry.pointer} (${entry.output_bytes} bytes)${outputVarSuffix}`;
+    }
+    return `${entry.id}: ${entry.pointer} (${entry.output_bytes} bytes)${outputVarSuffix} preview="${preview}"`;
+}
+function buildPointerReferenceHint() {
+    return 'ctx:<object_id>#chunk:<chunk_id> | subcall:<iteration>:<subcall_id>';
+}
+function buildSubcallHints() {
+    return '"parent_pointer": "optional pointer for recursion lineage", "output_var": "optional variable name",';
+}
+function hasSubcallPointer(pointer) {
+    return parseSubcallPointer(pointer) !== null;
+}
+async function resolveSnippetText(params) {
+    const { snippet, contextStore, subcallPointers } = params;
+    if (snippet.pointer) {
+        if (isContextPointer(snippet.pointer)) {
+            const result = await contextStore.read(snippet.pointer, snippet.offset ?? 0, snippet.bytes);
+            return result.text;
+        }
+        if (hasSubcallPointer(snippet.pointer)) {
+            return readSubcallPointerSnippet(subcallPointers, snippet.pointer, snippet.offset ?? 0, snippet.bytes);
+        }
+        throw new Error('plan_validation_error');
+    }
+    if (typeof snippet.start_byte === 'number') {
+        const result = await contextStore.readSpan(snippet.start_byte, snippet.bytes);
+        return result.text;
+    }
+    throw new Error('plan_validation_error');
+}
+async function resolveReadExcerpt(params) {
+    const { read, contextStore, subcallPointers, maxBytes } = params;
+    if (read.pointer) {
+        if (isContextPointer(read.pointer)) {
+            const result = await contextStore.read(read.pointer, read.offset ?? 0, read.bytes);
+            return {
+                pointer: read.pointer,
+                excerpt: truncateUtf8ToBytes(result.text, maxBytes)
+            };
+        }
+        if (hasSubcallPointer(read.pointer)) {
+            const text = await readSubcallPointerSnippet(subcallPointers, read.pointer, read.offset ?? 0, read.bytes);
+            return {
+                pointer: read.pointer,
+                excerpt: truncateUtf8ToBytes(text, maxBytes)
+            };
+        }
+        throw new Error('plan_validation_error');
+    }
+    if (typeof read.start_byte === 'number') {
+        const result = await contextStore.readSpan(read.start_byte, read.bytes);
+        return {
+            pointer: `start_byte=${read.start_byte} bytes=${read.bytes}`,
+            excerpt: truncateUtf8ToBytes(result.text, maxBytes)
+        };
+    }
+    return null;
+}
 function buildPlannerPrompt(params) {
-    const { goal, contextStore, budgets, priorReads, priorSearches, priorSubcalls } = params;
+    const { goal, contextStore, budgets, priorReads, priorSearches, priorSubcalls, deliberationBrief } = params;
     const baseLines = [
         'You are a symbolic RLM planner. Return JSON only (no prose).',
         `Goal: ${goal}`,
         `Context object_id: ${contextStore.objectId}`,
         `Chunk count: ${contextStore.chunkCount}`,
-        `Pointer format: ctx:<object_id>#chunk:<chunk_id>`,
+        `Pointer format: ${buildPointerReferenceHint()}`,
         '',
         'Schema (v1):',
         '{',
         '  "schema_version": 1,',
         '  "intent": "continue | final | pause | fail",',
-        '  "reads": [{ "pointer": "ctx:<object_id>#chunk:<chunk_id>", "offset": 0, "bytes": 4096, "reason": "..." }],',
+        `  "reads": [{ "pointer": "${buildPointerReferenceHint()}", "offset": 0, "bytes": 4096, "reason": "..." }],`,
         '  "searches": [{ "query": "...", "top_k": 20, "reason": "..." }],',
-        '  "subcalls": [{ "purpose": "summarize | extract | classify | verify", "snippets": [{ "pointer": "ctx:<object_id>#chunk:<chunk_id>", "offset": 0, "bytes": 2048 }], "max_input_bytes": 120000, "expected_output": "short summary" }],',
-        '  "final_answer": "required when intent=final"',
+        `  "subcalls": [{ "purpose": "summarize | extract | classify | verify", ${buildSubcallHints()} "snippets": [{ "pointer": "${buildPointerReferenceHint()}", "offset": 0, "bytes": 2048 }], "max_input_bytes": 120000, "expected_output": "short summary" }],`,
+        '  "final_answer": "required when intent=final unless final_var is set",',
+        '  "final_var": "optional variable name bound by subcalls[].output_var"',
         '}',
         '',
         'Constraints:',
@@ -382,6 +534,7 @@ function buildPlannerPrompt(params) {
         `- Max bytes per read: ${budgets.maxBytesPerChunkRead}.`,
         `- Max bytes per snippet: ${budgets.maxBytesPerSnippet}.`,
         '- Do not include full context; use pointers.',
+        '- Prefer prior subcall pointers for recursive chaining.',
         '- Request at least one subcall before intent=final.',
         ''
     ];
@@ -410,12 +563,18 @@ function buildPlannerPrompt(params) {
         sections.push({ key: 'reads_dropped', lines });
     }
     if (priorSubcalls.length > 0) {
-        const lines = ['Prior subcall outputs:'];
+        const lines = ['Prior subcall references:'];
         for (const entry of priorSubcalls) {
-            lines.push(`- ${entry.id}: ${entry.output}`);
+            lines.push(`- ${formatSubcallSummary(entry)}`);
         }
         sections.push({ key: 'subcalls_dropped', lines });
     }
+    if (typeof deliberationBrief === 'string' && deliberationBrief.trim().length > 0) {
+        sections.push({
+            key: 'deliberation_dropped',
+            lines: ['Deliberation brief:', deliberationBrief.trim()]
+        });
+    }
     let truncation = {};
     let prompt = [...baseLines];
     for (const section of sections) {
@@ -440,6 +599,176 @@ function buildPlannerPrompt(params) {
     }
     return { prompt: promptString, truncation };
 }
+function formatDeliberationReason(reason) {
+    switch (reason) {
+        case 'bootstrap':
+            return 'bootstrap';
+        case 'cadence':
+            return 'cadence';
+        case 'planner_recovery':
+            return 'planner_recovery';
+        case 'no_subcall_progress':
+            return 'no_subcall_progress';
+        default:
+            return 'cadence';
+    }
+}
+function attachDeliberationArtifactPaths(error, artifactPaths) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    if (artifactPaths) {
+        normalized.artifactPaths = artifactPaths;
+    }
+    return normalized;
+}
+function extractDeliberationArtifactPaths(error) {
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const rawPaths = error.artifactPaths;
+    if (!rawPaths || typeof rawPaths !== 'object') {
+        return undefined;
+    }
+    const typed = rawPaths;
+    if (typeof typed.prompt !== 'string' ||
+        typeof typed.output !== 'string' ||
+        typeof typed.meta !== 'string') {
+        return undefined;
+    }
+    return {
+        prompt: typed.prompt,
+        output: typed.output,
+        meta: typed.meta
+    };
+}
+function selectDeliberationReason(params) {
+    if (params.iteration === 1) {
+        return 'bootstrap';
+    }
+    if ((params.previousIteration?.planner_errors?.length ?? 0) > 0) {
+        return 'planner_recovery';
+    }
+    const noSearches = (params.previousIteration?.searches?.length ?? 0) === 0;
+    const noReads = (params.previousIteration?.reads?.length ?? 0) === 0;
+    const noSubcalls = (params.previousIteration?.subcalls?.length ?? 0) === 0;
+    if (noSearches && noReads && noSubcalls) {
+        return 'no_subcall_progress';
+    }
+    const minInterval = Math.max(1, Math.floor(params.minIntervalIterations));
+    if (params.lastDeliberationIteration <= 0 ||
+        params.iteration - params.lastDeliberationIteration >= minInterval) {
+        return 'cadence';
+    }
+    return null;
+}
+function buildDeliberationPrompt(params) {
+    const maxBytes = Math.max(256, Math.floor(params.maxSummaryBytes));
+    const lines = [
+        'You are a deliberation coordinator for an iterative symbolic planning loop.',
+        `Goal: ${params.goal}`,
+        `Iteration: ${params.iteration}`,
+        `Trigger: ${formatDeliberationReason(params.reason)}`,
+        `Context object_id: ${params.contextStore.objectId}`,
+        `Context chunks: ${params.contextStore.chunkCount}`,
+        'Respond with exactly four labeled lines:',
+        'Decision focus: <what to optimize next>',
+        'Risks: <top failure modes to avoid>',
+        'Context gaps: <missing evidence/plans>',
+        'Planner directives: <3 concise directives>',
+        `Keep total output under ${maxBytes} bytes and avoid markdown tables.`
+    ];
+    if (params.priorSearches.length > 0) {
+        const latestSearch = params.priorSearches[params.priorSearches.length - 1];
+        const hitCount = latestSearch?.results?.length ?? 0;
+        lines.push(`Latest search: query="${latestSearch?.query ?? ''}" hits=${hitCount}`);
+    }
+    if (params.priorReads.length > 0) {
+        const latestRead = params.priorReads[params.priorReads.length - 1];
+        lines.push(`Latest read pointer: ${latestRead?.pointer ?? ''}`);
+    }
+    if (params.priorSubcalls.length > 0) {
+        const latestSubcall = params.priorSubcalls[params.priorSubcalls.length - 1];
+        lines.push(`Latest subcall id: ${latestSubcall?.id ?? ''}`);
+        lines.push(`Latest subcall pointer: ${latestSubcall?.pointer ?? ''}`);
+        lines.push(`Latest subcall preview: ${truncateUtf8ToBytes(latestSubcall?.preview ?? '', 320)}`);
+    }
+    return lines.join('\n');
+}
+async function runDeliberationStep(params) {
+    const prompt = buildDeliberationPrompt({
+        goal: params.goal,
+        iteration: params.iteration,
+        reason: params.reason,
+        contextStore: params.contextStore,
+        priorReads: params.priorReads,
+        priorSearches: params.priorSearches,
+        priorSubcalls: params.priorSubcalls,
+        maxSummaryBytes: params.options.maxSummaryBytes
+    });
+    const promptBytes = byteLength(prompt);
+    const shouldLogArtifacts = params.options.logArtifacts === true;
+    let artifactPaths;
+    let outputPath = null;
+    let metaPath = null;
+    if (shouldLogArtifacts) {
+        const deliberationDir = join(params.runDir, 'deliberation');
+        await mkdir(deliberationDir, { recursive: true });
+        const baseName = `iteration-${String(params.iteration).padStart(4, '0')}`;
+        const promptPath = join(deliberationDir, `${baseName}-prompt.txt`);
+        outputPath = join(deliberationDir, `${baseName}-output.txt`);
+        metaPath = join(deliberationDir, `${baseName}-meta.json`);
+        await writeFile(promptPath, prompt, 'utf8');
+        artifactPaths = {
+            prompt: relative(params.repoRoot, promptPath),
+            output: relative(params.repoRoot, outputPath),
+            meta: relative(params.repoRoot, metaPath)
+        };
+    }
+    let output;
+    try {
+        output = await params.options.run(prompt, {
+            iteration: params.iteration,
+            reason: formatDeliberationReason(params.reason)
+        });
+    }
+    catch (error) {
+        if (shouldLogArtifacts && outputPath && metaPath) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            await writeFile(outputPath, '', 'utf8');
+            await writeFile(metaPath, JSON.stringify({
+                iteration: params.iteration,
+                reason: formatDeliberationReason(params.reason),
+                strategy: params.options.strategy,
+                prompt_bytes: promptBytes,
+                output_bytes: 0,
+                error: errorMessage
+            }, null, 2), 'utf8');
+        }
+        throw attachDeliberationArtifactPaths(error, artifactPaths);
+    }
+    const brief = truncateUtf8ToBytes(output ?? '', params.options.maxSummaryBytes);
+    const outputBytes = byteLength(brief);
+    if (shouldLogArtifacts && outputPath && metaPath) {
+        await writeFile(outputPath, brief, 'utf8');
+        await writeFile(metaPath, JSON.stringify({
+            iteration: params.iteration,
+            reason: formatDeliberationReason(params.reason),
+            strategy: params.options.strategy,
+            prompt_bytes: promptBytes,
+            output_bytes: outputBytes
+        }, null, 2), 'utf8');
+    }
+    return {
+        record: {
+            status: 'ran',
+            reason: formatDeliberationReason(params.reason),
+            strategy: params.options.strategy,
+            prompt_bytes: promptBytes,
+            output_bytes: outputBytes,
+            artifact_paths: artifactPaths
+        },
+        brief
+    };
+}
 async function writeState(path, state) {
     await writeFile(path, JSON.stringify(state, null, 2), 'utf8');
 }
@@ -466,6 +795,11 @@ export async function runSymbolicLoop(options) {
     let priorReads = [];
     let priorSearches = [];
     let priorSubcalls = [];
+    const subcallPointers = new Map();
+    const variableBindings = new Map();
+    let lastDeliberationIteration = 0;
+    let deliberationRuns = 0;
+    let latestDeliberationBrief = null;
     const finalize = async (status) => {
         state.final = status ?? { status: 'error', exitCode: 10 };
         await writeState(statePath, state);
@@ -476,13 +810,81 @@ export async function runSymbolicLoop(options) {
             if (timeExceeded()) {
                 return await finalize({ status: 'max_minutes', exitCode: 3 });
             }
+            const previousIteration = state.symbolic_iterations[state.symbolic_iterations.length - 1] ?? null;
+            let deliberation;
+            const deliberationOptions = options.deliberation;
+            if (!deliberationOptions?.enabled) {
+                if (deliberationOptions) {
+                    deliberation = {
+                        status: 'skipped',
+                        reason: 'disabled',
+                        strategy: deliberationOptions.strategy
+                    };
+                }
+            }
+            else {
+                const reason = selectDeliberationReason({
+                    iteration,
+                    previousIteration,
+                    lastDeliberationIteration,
+                    minIntervalIterations: deliberationOptions.minIntervalIterations
+                });
+                if (!reason) {
+                    deliberation = {
+                        status: 'skipped',
+                        reason: 'not_due',
+                        strategy: deliberationOptions.strategy
+                    };
+                }
+                else if (deliberationRuns >= deliberationOptions.maxRuns) {
+                    deliberation = {
+                        status: 'skipped',
+                        reason: 'max_runs_reached',
+                        strategy: deliberationOptions.strategy
+                    };
+                }
+                else {
+                    deliberationRuns += 1;
+                    try {
+                        const result = await runDeliberationStep({
+                            options: deliberationOptions,
+                            goal: options.goal,
+                            iteration,
+                            reason,
+                            runDir,
+                            repoRoot: options.repoRoot,
+                            contextStore: options.contextStore,
+                            priorReads,
+                            priorSearches,
+                            priorSubcalls
+                        });
+                        deliberation = result.record;
+                        latestDeliberationBrief = result.brief;
+                        lastDeliberationIteration = iteration;
+                        log(`Deliberation ${formatDeliberationReason(reason)} ran for iteration ${iteration} (${result.record.strategy}).`);
+                    }
+                    catch (error) {
+                        deliberation = {
+                            status: 'error',
+                            reason: formatDeliberationReason(reason),
+                            strategy: deliberationOptions.strategy,
+                            artifact_paths: extractDeliberationArtifactPaths(error),
+                            error: error instanceof Error ? error.message : String(error)
+                        };
+                        log(`Deliberation ${formatDeliberationReason(reason)} failed for iteration ${iteration}: ${deliberation.error}`);
+                    }
+                }
+            }
             const promptResult = buildPlannerPrompt({
                 goal: options.goal,
                 contextStore: options.contextStore,
                 budgets: options.budgets,
                 priorReads,
                 priorSearches,
-                priorSubcalls
+                priorSubcalls,
+                deliberationBrief: deliberationOptions?.enabled && deliberationOptions.includeInPlannerPrompt
+                    ? latestDeliberationBrief
+                    : null
             });
             const plannerPrompt = promptResult.prompt;
             const plannerPromptBytes = byteLength(plannerPrompt);
@@ -512,7 +914,7 @@ export async function runSymbolicLoop(options) {
                 let validationError = null;
                 try {
                     validation = validatePlan(plan, options.budgets);
-                    validatePlanPointers(validation, options.contextStore);
+                    validatePlanPointers(validation, options.contextStore, subcallPointers);
                 }
                 catch {
                     validationError = 'plan_validation_error';
@@ -520,6 +922,11 @@ export async function runSymbolicLoop(options) {
                 if (!validationError && plan.intent === 'final' && !hasPriorSubcalls) {
                     validationError = 'final_requires_subcall';
                 }
+                if (!validationError && plan.intent === 'final' && plan.final_var) {
+                    if (!variableBindings.has(plan.final_var)) {
+                        validationError = 'final_var_unbound';
+                    }
+                }
                 if (validationError) {
                     plannerErrors.push(validationError);
                     await recordPlannerFailure({
@@ -542,12 +949,27 @@ export async function runSymbolicLoop(options) {
             const reads = [];
             const subcalls = [];
             const searches = [];
+            const iterationVariableBindings = [];
             if (plan.intent === 'final') {
+                let finalAnswer = plan.final_answer;
+                if (plan.final_var) {
+                    const binding = variableBindings.get(plan.final_var);
+                    if (!binding) {
+                        return await finalize({ status: 'invalid_config', exitCode: 5 });
+                    }
+                    try {
+                        finalAnswer = await readFile(binding.outputPath, 'utf8');
+                    }
+                    catch {
+                        return await finalize({ status: 'invalid_config', exitCode: 5 });
+                    }
+                }
                 state.symbolic_iterations.push({
                     iteration,
                     planner_prompt_bytes: plannerPromptBytes,
                     reads,
                     subcalls,
+                    deliberation,
                     searches,
                     planner_errors: plannerErrors.length > 0 ? plannerErrors : undefined,
                     clamped: {
@@ -558,7 +980,7 @@ export async function runSymbolicLoop(options) {
                     truncation: promptResult.truncation
                 });
                 await writeState(statePath, state);
-                return await finalize({ status: 'passed', exitCode: 0, final_answer: plan.final_answer });
+                return await finalize({ status: 'passed', exitCode: 0, final_answer: finalAnswer });
             }
             if (plan.intent === 'pause' || plan.intent === 'fail') {
                 state.symbolic_iterations.push({
@@ -566,6 +988,7 @@ export async function runSymbolicLoop(options) {
                     planner_prompt_bytes: plannerPromptBytes,
                     reads,
                     subcalls,
+                    deliberation,
                     searches,
                     planner_errors: plannerErrors.length > 0 ? plannerErrors : undefined,
                     clamped: {
@@ -596,19 +1019,14 @@ export async function runSymbolicLoop(options) {
             priorSearches = currentSearches;
             const readExcerpts = [];
             for (const read of validation.reads) {
-                if (read.pointer) {
-                    const result = await options.contextStore.read(read.pointer, read.offset ?? 0, read.bytes);
-                    readExcerpts.push({
-                        pointer: read.pointer,
-                        excerpt: truncateUtf8ToBytes(result.text, options.budgets.maxBytesPerChunkRead)
-                    });
-                }
-                else if (typeof read.start_byte === 'number') {
-                    const result = await options.contextStore.readSpan(read.start_byte, read.bytes);
-                    readExcerpts.push({
-                        pointer: `start_byte=${read.start_byte} bytes=${read.bytes}`,
-                        excerpt: truncateUtf8ToBytes(result.text, options.budgets.maxBytesPerChunkRead)
-                    });
+                const excerpt = await resolveReadExcerpt({
+                    read,
+                    contextStore: options.contextStore,
+                    subcallPointers,
+                    maxBytes: options.budgets.maxBytesPerChunkRead
+                });
+                if (excerpt) {
+                    readExcerpts.push(excerpt);
                 }
                 reads.push(read);
             }
@@ -650,14 +1068,12 @@ export async function runSymbolicLoop(options) {
                 });
                 const resolvedSnippets = [];
                 for (const snippet of snippets) {
-                    if (snippet.pointer) {
-                        const result = await options.contextStore.read(snippet.pointer, snippet.offset ?? 0, snippet.bytes);
-                        resolvedSnippets.push({ meta: snippet, text: result.text });
-                    }
-                    else if (typeof snippet.start_byte === 'number') {
-                        const result = await options.contextStore.readSpan(snippet.start_byte, snippet.bytes);
-                        resolvedSnippets.push({ meta: snippet, text: result.text });
-                    }
+                    const text = await resolveSnippetText({
+                        snippet,
+                        contextStore: options.contextStore,
+                        subcallPointers
+                    });
+                    resolvedSnippets.push({ meta: snippet, text });
                 }
                 for (const span of spans) {
                     const spanBytes = Math.max(0, span.end_byte - span.start_byte);
@@ -697,9 +1113,12 @@ export async function runSymbolicLoop(options) {
                 const promptPath = join(subcallDir, 'prompt.txt');
                 const outputPath = join(subcallDir, 'output.txt');
                 const metaPath = join(subcallDir, 'meta.json');
+                const outputPointer = buildSubcallPointer(iteration, subcallId);
                 await writeFile(inputPath, JSON.stringify({
                     id: subcallId,
                     purpose: rawSubcall.purpose,
+                    parent_pointer: rawSubcall.parent_pointer,
+                    output_var: rawSubcall.output_var,
                     max_input_bytes: maxInput,
                     snippets,
                     spans
@@ -714,10 +1133,21 @@ export async function runSymbolicLoop(options) {
                     clipped
                 }, null, 2), 'utf8');
                 const relativeBase = (filePath) => relative(options.repoRoot, filePath);
+                const outputPreview = truncateUtf8ToBytes(output, options.budgets.maxPreviewBytes);
+                subcallPointers.set(outputPointer, {
+                    pointer: outputPointer,
+                    iteration,
+                    subcallId,
+                    outputPath,
+                    outputBytes: byteLength(output)
+                });
                 return {
                     subcall: {
                         id: subcallId,
                         purpose: rawSubcall.purpose,
+                        parent_pointer: rawSubcall.parent_pointer,
+                        output_pointer: outputPointer,
+                        output_var: rawSubcall.output_var,
                         snippets: snippets.length > 0 ? snippets : undefined,
                         spans: spans.length > 0 ? spans : undefined,
                         max_input_bytes: rawSubcall.max_input_bytes,
@@ -735,12 +1165,36 @@ export async function runSymbolicLoop(options) {
                     },
                     output: {
                         id: subcallId,
-                        output: truncateUtf8ToBytes(output, options.budgets.maxBytesPerSnippet)
-                    }
+                        pointer: outputPointer,
+                        preview: outputPreview,
+                        output_bytes: byteLength(output),
+                        output_var: rawSubcall.output_var
+                    },
+                    binding: rawSubcall.output_var
+                        ? {
+                            name: rawSubcall.output_var,
+                            pointer: outputPointer,
+                            iteration,
+                            subcallId,
+                            outputPath,
+                            outputBytes: byteLength(output)
+                        }
+                        : null
                 };
             });
             for (const result of subcallResults) {
                 subcalls.push(result.subcall);
+                if (result.binding) {
+                    variableBindings.set(result.binding.name, result.binding);
+                    iterationVariableBindings.push({
+                        name: result.binding.name,
+                        pointer: result.binding.pointer,
+                        iteration: result.binding.iteration,
+                        subcall_id: result.binding.subcallId,
+                        output_bytes: result.binding.outputBytes,
+                        output_path: relative(options.repoRoot, result.binding.outputPath)
+                    });
+                }
             }
             priorSubcalls = subcallResults.map((result) => result.output);
             state.symbolic_iterations.push({
@@ -748,6 +1202,8 @@ export async function runSymbolicLoop(options) {
                 planner_prompt_bytes: plannerPromptBytes,
                 reads,
                 subcalls,
+                variable_bindings: iterationVariableBindings.length > 0 ? iterationVariableBindings : undefined,
+                deliberation,
                 searches,
                 planner_errors: plannerErrors.length > 0 ? plannerErrors : undefined,
                 clamped: {