agentic-orchestrator 0.1.27 → 0.2.0

package/dist/apps/control-plane/supervisor/worker-decision-loop.js

@@ -1,5 +1,7 @@
-import { TOOLS } from '../core/constants.js';
+import path from 'node:path';
+import { STATUS, TOOLS } from '../core/constants.js';
 import { ERROR_CODES } from '../core/error-codes.js';
+import { resolvePlannerPhaseFromContext } from './planner-phase.js';
 import { appendWorkerRuntimeEvent } from './worker-event-journal.js';
 const PLAN_TOP_LEVEL_KEYS = new Set([
     'feature_id',
@@ -11,6 +13,7 @@ const PLAN_TOP_LEVEL_KEYS = new Set([
     'files',
     'contracts',
     'acceptance_criteria',
+    'plan_trace',
     'gate_targets',
     'risk',
     'revision_of',
@@ -20,6 +23,23 @@ const PLAN_TOP_LEVEL_KEYS = new Set([
 function asRecord(value) {
     return value && typeof value === 'object' ? value : {};
 }
+function extractNonErrorMessage(value) {
+    if (!value || typeof value !== 'object') {
+        return typeof value === 'string' ? value : null;
+    }
+    const obj = value;
+    const normalized = obj['normalizedResponse'];
+    if (normalized?.['error'] && typeof normalized['error'] === 'object') {
+        const err = normalized['error'];
+        if (typeof err['message'] === 'string') {
+            return err['message'];
+        }
+    }
+    if (typeof obj['message'] === 'string') {
+        return obj['message'];
+    }
+    return null;
+}
 function asNonEmptyString(value) {
     if (typeof value !== 'string') {
         return null;
@@ -63,23 +83,153 @@ function asOutputs(result) {
     }
     return [asRecord(result)];
 }
+function readInteractiveFallbackReason(result) {
+    return asNonEmptyString(asRecord(result.provider_meta).parse_fallback_reason);
+}
+function isBlockingAskUserInputOutput(output) {
+    const request = asRecord(output.request ?? output);
+    const action = asNonEmptyString(request.action ?? request.request_type)?.toLowerCase();
+    const prompt = asNonEmptyString(request.prompt);
+    return action === 'ask_user_input' && prompt !== null;
+}
 function makeEmptyResult() {
     return {
         planSubmission: false,
+        intakeSubmission: false,
         patchApplied: false,
         noteLogged: false,
         requestHandled: false,
+        questionRequested: false,
+        contextStall: false,
+        contextRequestCount: 0,
+        lastContextRequestAt: null,
+        lastContextRequestRole: null,
         invalidOutput: false,
+        errorCode: null,
         noProgress: false,
         outputTypes: [],
         rawOutputs: [],
         priorityOrder: [],
         toolResults: [],
+        interactiveOutcome: null,
+        checkpoint: null,
+        usageRecords: [],
     };
 }
+/** No-op decision runner that always returns an empty result with no progress. */
 export const NOOP_WORKER_DECISION_RUNNER = {
     execute: () => Promise.resolve(makeEmptyResult()),
 };
+function normalizeList(values) {
+    return Array.from(new Set(values.map((item) => item.trim()).filter((item) => item.length > 0)));
+}
+function readToolFailureDetails(error) {
+    if (!error || typeof error !== 'object') {
+        return null;
+    }
+    const direct = asRecord(error.error);
+    const normalized = asRecord(asRecord(error.normalizedResponse).error);
+    const payload = Object.keys(normalized).length > 0 ? normalized : direct;
+    if (Object.keys(payload).length === 0) {
+        return null;
+    }
+    return {
+        code: asNonEmptyString(payload.code),
+        message: asNonEmptyString(payload.message),
+        details: asRecord(payload.details),
+    };
+}
+function readAllIntakeAmbiguities(contextBundle) {
+    const intake = asRecord(contextBundle.intake);
+    const review = asRecord(intake.review);
+    const ambiguities = Array.isArray(review.ambiguities) ? review.ambiguities : [];
+    const results = [];
+    for (const item of ambiguities) {
+        const record = asRecord(item);
+        const id = asNonEmptyString(record.id);
+        const summary = asNonEmptyString(record.summary);
+        if (!id || !summary) {
+            continue;
+        }
+        results.push({
+            id,
+            summary,
+            obligationIds: asStringArray(record.obligation_ids),
+        });
+    }
+    return results;
+}
+function readOpenIntakeAmbiguities(contextBundle) {
+    const intake = asRecord(contextBundle.intake);
+    const review = asRecord(intake.review);
+    const openIds = new Set((Array.isArray(review.ambiguities) ? review.ambiguities : [])
+        .map((item) => asRecord(item))
+        .filter((item) => asNonEmptyString(item.status) === 'open')
+        .map((item) => asNonEmptyString(item.id))
+        .filter((item) => item !== null));
+    return readAllIntakeAmbiguities(contextBundle).filter((item) => openIds.has(item.id));
+}
+function readIntakeAmbiguitiesForRecovery(contextBundle, ambiguityIds) {
+    const normalizedIds = normalizeList(ambiguityIds);
+    if (normalizedIds.length === 0) {
+        return readOpenIntakeAmbiguities(contextBundle);
+    }
+    const byId = new Map(readAllIntakeAmbiguities(contextBundle).map((item) => [item.id, item]));
+    return normalizedIds.map((ambiguityId) => {
+        const existing = byId.get(ambiguityId);
+        if (existing) {
+            return existing;
+        }
+        return {
+            id: ambiguityId,
+            summary: 'Clarify this ambiguity before verifying the intake manifest.',
+            obligationIds: [],
+        };
+    });
+}
+function hasOpenIntakeQuestion(contextBundle) {
+    const humanInput = asRecord(contextBundle.human_input);
+    const openQuestions = Array.isArray(humanInput.open_questions) ? humanInput.open_questions : [];
+    return openQuestions.length > 0;
+}
+function readAnsweredIntakeClarifications(contextBundle) {
+    const intake = asRecord(contextBundle.intake);
+    const review = asRecord(intake.review);
+    const clarificationAnswers = Array.isArray(review.clarification_answers)
+        ? review.clarification_answers
+        : [];
+    return clarificationAnswers
+        .map((item) => asRecord(item))
+        .filter((item) => asStringArray(item.ambiguity_ids).length > 0)
+        .map((item) => ({
+        questionId: asNonEmptyString(item.question_id) ?? 'unknown',
+        ambiguityIds: asStringArray(item.ambiguity_ids),
+        answer: typeof item.answer === 'string'
+            ? item.answer
+            : JSON.stringify(asRecord(item.answer) ?? {}, null, 2),
+        answeredAt: asNonEmptyString(item.answered_at),
+    }));
+}
+function buildIntakeClarificationPrompt(ambiguities, recoveryReason, priorAnswers) {
+    const intro = ambiguities.length === 1
+        ? 'Execution planning cannot begin because this intake ambiguity is still unresolved:'
+        : 'Execution planning cannot begin because these intake ambiguities are still unresolved:';
+    const items = ambiguities.map((ambiguity) => `- ${ambiguity.id}: ${ambiguity.summary}`);
+    const priorAnswerLines = ambiguities.flatMap((ambiguity) => priorAnswers
+        .filter((answer) => answer.ambiguityIds.includes(ambiguity.id))
+        .map((answer) => `- ${ambiguity.id} via ${answer.questionId}${answer.answeredAt ? ` at ${answer.answeredAt}` : ''}: ${answer.answer}`));
+    const priorAnswersBlock = priorAnswerLines.length > 0
+        ? `\nPrior answered clarification evidence:\n${priorAnswerLines.join('\n')}\nUse this prior answer evidence. Only ask a narrower follow-up if it is still insufficient to resolve the ambiguity.`
+        : '';
+    return `${intro}\n${items.join('\n')}${priorAnswersBlock}\nRespond in free text and explicitly address each ambiguity ID. Recovery reason: ${recoveryReason}.`;
+}
+/**
+ * Core decision loop that drives a single agent worker turn.
+ *
+ * Invokes the provider, classifies outputs (plans, patches, notes, requests),
+ * dispatches tool calls, handles context-refresh retries, and supports both
+ * deterministic and interactive execution modes.
+ */
 export class WorkerDecisionLoop {
     provider;
     toolCaller;
@@ -87,6 +237,7 @@ export class WorkerDecisionLoop {
     repoRoot;
     runId;
     resolveExecutionModeOverride;
+    resolveRuntimeSelectionOverride;
     resolveInteractiveConfigOverride;
     watchdog;
     checkpointService;
@@ -99,17 +250,28 @@ export class WorkerDecisionLoop {
         this.repoRoot = dependencies.repoRoot ?? null;
         this.runId = dependencies.runId ?? null;
         this.resolveExecutionModeOverride = dependencies.resolveExecutionMode;
+        this.resolveRuntimeSelectionOverride = dependencies.resolveRuntimeSelection;
         this.resolveInteractiveConfigOverride = dependencies.resolveInteractiveConfig;
         this.watchdog = dependencies.watchdog;
         this.checkpointService = dependencies.checkpointService;
         this.resolveWorktreePath = dependencies.resolveWorktreePath;
         this.resolveRoleSessionId = dependencies.resolveRoleSessionId;
     }
+    /**
+     * Execute one decision turn: invoke the worker, process all outputs, and
+     * optionally retry once on a context-refresh request.
+     * @returns Aggregated result describing every action taken and diagnostics.
+     */
     async execute(input) {
         const result = makeEmptyResult();
+        const plannerState = {
+            currentPlanVersion: readPlanVersion(asRecord(input.contextBundle.plan).plan_version),
+            planMutationApplied: false,
+        };
         if (typeof this.provider.runWorker !== 'function') {
             return result;
         }
+        const runtimeSelection = await this.resolveRuntimeSelection(input.featureId, input.role);
         const requestedExecutionMode = await this.resolveExecutionMode(input.featureId, input.role);
         const interactiveEligible = this.isInteractiveEligible(requestedExecutionMode, input.role);
         const executionMode = requestedExecutionMode === 'interactive' && interactiveEligible
@@ -128,6 +290,7 @@ export class WorkerDecisionLoop {
                 valid: true,
                 errorCode: null,
                 executionMode,
+                runtimeSelection,
             });
         }
         await this.appendWorkerEvent({
@@ -142,16 +305,95 @@ export class WorkerDecisionLoop {
             valid: true,
             errorCode: null,
             executionMode,
+            runtimeSelection,
         });
+        let finalRun = await this.runWorkerTurn(input, executionMode, runtimeSelection, interactiveEligible);
+        if (finalRun.usage) {
+            result.usageRecords.push(finalRun.usage);
+        }
+        const firstPass = await this.processOutputs({
+            input,
+            workerRun: finalRun,
+            result,
+            plannerState,
+            allowContextRefreshRetry: true,
+        });
+        if (firstPass.contextRefreshRequested && firstPass.refreshedContext) {
+            finalRun = await this.runWorkerTurn({
+                ...input,
+                contextBundle: firstPass.refreshedContext,
+                lastToolResults: this.buildContextRetryToolResults(input, firstPass.refreshedContext),
+            }, executionMode, runtimeSelection, interactiveEligible);
+            if (finalRun.usage) {
+                result.usageRecords.push(finalRun.usage);
+            }
+            const secondPass = await this.processOutputs({
+                input: {
+                    ...input,
+                    contextBundle: firstPass.refreshedContext,
+                    lastToolResults: this.buildContextRetryToolResults(input, firstPass.refreshedContext),
+                },
+                workerRun: finalRun,
+                result,
+                plannerState,
+                allowContextRefreshRetry: false,
+            });
+            if (secondPass.contextRefreshRequested) {
+                const hasInteractiveWork = finalRun.interactiveSummary?.hasNetNewWorktreeChanges === true &&
+                    finalRun.interactiveSummary.changedFiles.length > 0;
+                if (!hasInteractiveWork) {
+                    result.contextStall = true;
+                    result.errorCode = ERROR_CODES.PROVIDER_CONTEXT_STALL;
+                }
+            }
+        }
+        this.finalizeInteractiveOutcome(result, finalRun.interactiveSummary);
+        const hasProgress = result.planSubmission ||
+            result.intakeSubmission ||
+            result.patchApplied ||
+            result.requestHandled ||
+            result.questionRequested;
+        result.noProgress = !hasProgress;
+        await this.appendWorkerEvent({
+            eventType: 'worker_completed',
+            featureId: input.featureId,
+            role: input.role,
+            outputTypes: result.outputTypes,
+            patchCount: result.outputTypes.filter((type) => type === 'PATCH').length,
+            planSubmissionCount: result.outputTypes.filter((type) => type === 'PLAN_SUBMISSION' || type === 'INTAKE_SUBMISSION').length,
+            requestCount: result.outputTypes.filter((type) => type === 'REQUEST').length,
+            noteCount: result.outputTypes.filter((type) => type === 'NOTE').length,
+            valid: !result.invalidOutput && result.errorCode === null,
+            errorCode: result.errorCode,
+            interactiveOutcome: result.interactiveOutcome ?? null,
+            checkpointId: result.checkpoint?.checkpoint_id ?? null,
+            checkpointDiffHash: typeof result.checkpoint?.diff_hash === 'string' ? result.checkpoint.diff_hash : null,
+            checkpointNetNewWorktreeChange: result.checkpoint?.net_new_worktree_change ?? null,
+            checkpointValidationStatus: typeof result.checkpoint?.validation_status === 'string'
+                ? result.checkpoint.validation_status
+                : null,
+            executionMode,
+            runtimeSelection,
+            usage: finalRun.usage,
+        });
+        if (this.activityMonitor) {
+            await this.activityMonitor.checkAndNotifyStuck(input.featureId);
+        }
+        return result;
+    }
+    async runWorkerTurn(input, executionMode, runtimeSelection, interactiveEligible) {
         let workerOutput;
         let interactiveSummary = null;
         try {
             if (interactiveEligible) {
-                interactiveSummary = await this.runInteractiveWorker(input);
+                interactiveSummary =
+                    input.role === 'planner'
+                        ? await this.runInteractivePlanner(input, runtimeSelection)
+                        : await this.runInteractiveWorker(input, runtimeSelection);
                 workerOutput = interactiveSummary.workerOutput;
             }
             else {
-                workerOutput = await this.provider.runWorker(this.buildRunInput(input, executionMode, undefined));
+                workerOutput = await this.provider.runWorker(this.buildRunInput(input, executionMode, undefined, runtimeSelection));
             }
         }
         catch (error) {
@@ -188,86 +430,138 @@ export class WorkerDecisionLoop {
                 elapsedMs: typeof typed.details?.elapsed_ms === 'number' ? typed.details.elapsed_ms : undefined,
                 signal: typeof typed.details?.signal === 'string' ? typed.details.signal : null,
                 exitCode: typeof typed.details?.exit_code === 'number' ? typed.details.exit_code : undefined,
+                stderr: typeof typed.details?.stderr === 'string' && typed.details.stderr.length > 0
+                    ? typed.details.stderr
+                    : undefined,
                 executionMode,
+                runtimeSelection,
             });
             throw error;
         }
-        const outputs = asOutputs(workerOutput);
-        result.rawOutputs = outputs.map((output) => structuredClone(output));
-        const allowedTypes = new Set(['PLAN_SUBMISSION', 'PATCH', 'NOTE', 'REQUEST']);
-        let planSubmissionCount = 0;
-        let patchCount = 0;
-        let requestCount = 0;
-        let noteCount = 0;
+        // Extract usage telemetry from provider output (if available).
+        const rawUsage = workerOutput.usage;
+        const usage = rawUsage &&
+            typeof rawUsage === 'object' &&
+            'status' in rawUsage &&
+            typeof rawUsage.status === 'string'
+            ? rawUsage
+            : null;
+        return {
+            workerOutput,
+            interactiveSummary,
+            executionMode,
+            runtimeSelection,
+            usage,
+        };
+    }
+    buildContextRetryToolResults(input, refreshedContext) {
+        return [
+            ...(input.lastToolResults ?? []),
+            {
+                tool_name: TOOLS.FEATURE_GET_CONTEXT,
+                feature_id: input.featureId,
+                refreshed_context: structuredClone(refreshedContext),
+            },
+        ];
+    }
+    async processOutputs(input) {
+        const { result, plannerState, allowContextRefreshRetry } = input;
+        const workerInput = input.input;
+        const outputs = asOutputs(input.workerRun.workerOutput);
+        result.rawOutputs.push(...outputs.map((output) => structuredClone(output)));
+        const blockingQuestionOutput = outputs.find((output) => isBlockingAskUserInputOutput(output));
+        if (blockingQuestionOutput) {
+            result.outputTypes.push('REQUEST');
+            await this.routeRequest(workerInput, blockingQuestionOutput, result, plannerState, allowContextRefreshRetry);
+            return { contextRefreshRequested: false, refreshedContext: null };
+        }
+        const allowedTypes = new Set([
+            'PLAN_SUBMISSION',
+            'INTAKE_SUBMISSION',
+            'PATCH',
+            'NOTE',
+            'REQUEST',
+        ]);
         for (const output of outputs) {
             const outputType = asNonEmptyString(output.type)?.toUpperCase();
             if (!outputType) {
                 result.invalidOutput = true;
+                result.errorCode = ERROR_CODES.PROVIDER_OUTPUT_INVALID;
+                result.interactiveOutcome = input.workerRun.interactiveSummary
+                    ? 'provider_output_invalid'
+                    : null;
                 continue;
             }
             result.outputTypes.push(outputType);
             if (!allowedTypes.has(outputType)) {
                 result.invalidOutput = true;
+                result.errorCode = ERROR_CODES.PROVIDER_OUTPUT_INVALID;
+                result.interactiveOutcome = input.workerRun.interactiveSummary
+                    ? 'provider_output_invalid'
+                    : null;
                 continue;
             }
             if (outputType === 'PLAN_SUBMISSION') {
-                planSubmissionCount += 1;
-                await this.routePlanSubmission(input, output, result);
+                await this.routePlanSubmission(workerInput, output, result, plannerState);
+                continue;
+            }
+            if (outputType === 'INTAKE_SUBMISSION') {
+                await this.routeIntakeSubmission(workerInput, output, result, plannerState);
                 continue;
             }
             if (outputType === 'PATCH') {
-                patchCount += 1;
-                if (interactiveSummary) {
-                    const hasPatchPayload = Boolean(asNonEmptyString(output.unified_diff ?? output.diff));
-                    if (hasPatchPayload) {
-                        result.patchApplied = true;
-                    }
-                }
-                else {
-                    await this.routePatch(input, output, result);
+                if (!input.workerRun.interactiveSummary) {
+                    await this.routePatch(workerInput, output, result);
                 }
                 continue;
             }
             if (outputType === 'NOTE') {
-                noteCount += 1;
-                await this.routeNote(input.featureId, output, result);
+                if (input.workerRun.interactiveSummary &&
+                    input.workerRun.interactiveSummary.fallbackReason !== null &&
+                    !input.workerRun.interactiveSummary.hasNetNewWorktreeChanges) {
+                    result.invalidOutput = true;
+                    result.errorCode = ERROR_CODES.PROVIDER_OUTPUT_INVALID;
+                    result.interactiveOutcome = 'provider_output_invalid';
+                    continue;
+                }
+                await this.routeNote(workerInput.featureId, output, result);
                 continue;
             }
-            if (outputType === 'REQUEST') {
-                requestCount += 1;
-                await this.routeRequest(input, output, result);
+            const requestResult = await this.routeRequest(workerInput, output, result, plannerState, allowContextRefreshRetry);
+            if (requestResult.contextRefreshRequested) {
+                return requestResult;
             }
         }
-        if (interactiveSummary) {
+        return { contextRefreshRequested: false, refreshedContext: null };
+    }
+    finalizeInteractiveOutcome(result, interactiveSummary) {
+        if (!interactiveSummary) {
+            return;
+        }
+        result.checkpoint = structuredClone(interactiveSummary.finalCheckpoint);
+        if (interactiveSummary.finalCheckpoint) {
             result.toolResults.push({
                 checkpoint: structuredClone(interactiveSummary.finalCheckpoint),
             });
-            if (interactiveSummary.changedFiles.length > 0) {
-                result.patchApplied = true;
-            }
-            if (interactiveSummary.checkpointInvalid) {
-                result.invalidOutput = true;
-            }
         }
-        const hasProgress = result.planSubmission || result.patchApplied || result.requestHandled;
-        result.noProgress = !hasProgress;
-        await this.appendWorkerEvent({
-            eventType: 'worker_completed',
-            featureId: input.featureId,
-            role: input.role,
-            outputTypes: result.outputTypes,
-            patchCount,
-            planSubmissionCount,
-            requestCount,
-            noteCount,
-            valid: !result.invalidOutput,
-            errorCode: result.invalidOutput ? ERROR_CODES.PROVIDER_OUTPUT_INVALID : null,
-            executionMode,
-        });
-        if (this.activityMonitor) {
-            await this.activityMonitor.checkAndNotifyStuck(input.featureId);
+        if (interactiveSummary.finalCheckpoint &&
+            interactiveSummary.hasNetNewWorktreeChanges &&
+            interactiveSummary.changedFiles.length > 0) {
+            result.patchApplied = true;
+        }
+        if (interactiveSummary.checkpointInvalid) {
+            result.errorCode = ERROR_CODES.INTERACTIVE_CHECKPOINT_INVALID;
+            result.interactiveOutcome = 'checkpoint_invalid';
+        }
+        else if (result.invalidOutput) {
+            result.interactiveOutcome = 'provider_output_invalid';
+        }
+        else if (result.patchApplied) {
+            result.interactiveOutcome = 'progress_applied';
+        }
+        else if (!result.planSubmission && !result.requestHandled && !result.questionRequested) {
+            result.interactiveOutcome = 'no_new_work';
         }
-        return result;
     }
     async resolveExecutionMode(featureId, role) {
         if (this.resolveExecutionModeOverride) {
@@ -275,21 +569,33 @@ export class WorkerDecisionLoop {
         }
         return 'deterministic';
     }
+    async resolveRuntimeSelection(featureId, role) {
+        if (this.resolveRuntimeSelectionOverride) {
+            return await this.resolveRuntimeSelectionOverride(featureId, role);
+        }
+        return this.provider.selection;
+    }
     isInteractiveEligible(executionMode, role) {
         if (executionMode !== 'interactive') {
             return false;
         }
-        if (role !== 'builder' && role !== 'qa') {
+        const capabilities = this.provider.getCapabilities?.();
+        const supportsInteractive = !capabilities
+            ? true
+            : capabilities.supportsInteractiveMode && capabilities.supportsWorkingDirectory;
+        if (!supportsInteractive) {
             return false;
         }
-        if (!this.repoRoot || !this.watchdog || !this.checkpointService || !this.resolveWorktreePath) {
+        if (role === 'planner') {
+            return Boolean(this.repoRoot);
+        }
+        if (role !== 'builder' && role !== 'qa' && role !== 'reconciler') {
             return false;
         }
-        const capabilities = this.provider.getCapabilities?.();
-        if (!capabilities) {
-            return true;
+        if (!this.repoRoot || !this.watchdog || !this.checkpointService || !this.resolveWorktreePath) {
+            return false;
         }
-        return capabilities.supportsInteractiveMode && capabilities.supportsWorkingDirectory;
+        return true;
     }
     resolveInteractiveConfig() {
         if (this.resolveInteractiveConfigOverride) {
@@ -304,31 +610,38 @@ export class WorkerDecisionLoop {
             violationSeverity: 'warning',
         };
     }
-    buildRunInput(input, executionMode, workingDirectory) {
+    buildRunInput(input, executionMode, workingDirectory, runtimeSelection) {
         return {
             role: input.role,
             feature_id: input.featureId,
+            ...(input.role === 'planner'
+                ? { planner_phase: resolvePlannerPhaseFromContext(input.contextBundle) }
+                : {}),
             context_bundle: input.contextBundle,
-            instructions: input.instructions,
+            instructions: this.resolvePromptInstructions(input, executionMode),
             last_tool_results: input.lastToolResults ?? [],
             runtime_selection: {
-                provider: this.provider.selection.provider,
-                model: this.provider.selection.model,
-                provider_config_ref: this.provider.selection.provider_config_ref,
+                provider: runtimeSelection.provider,
+                model: runtimeSelection.model,
+                provider_config_env: runtimeSelection.provider_config_env ?? null,
+                provider_config_ref: runtimeSelection.provider_config_ref,
+                agent_config: runtimeSelection.agent_config ?? null,
             },
             execution_mode: executionMode,
             working_directory: workingDirectory,
             pause_resume_protocol: 'none',
         };
     }
-    async runInteractiveWorker(input) {
+    async runInteractiveWorker(input, runtimeSelection) {
         if (!this.repoRoot || !this.watchdog || !this.checkpointService || !this.resolveWorktreePath) {
-            const fallbackOutput = await this.provider.runWorker(this.buildRunInput(input, 'deterministic', undefined));
+            const fallbackOutput = await this.provider.runWorker(this.buildRunInput(input, 'deterministic', undefined, runtimeSelection));
             return {
                 workerOutput: fallbackOutput,
                 finalCheckpoint: this.createSyntheticCheckpoint(input.featureId),
                 changedFiles: [],
+                hasNetNewWorktreeChanges: false,
                 checkpointInvalid: false,
+                fallbackReason: readInteractiveFallbackReason(fallbackOutput),
             };
         }
         const interactiveConfig = this.resolveInteractiveConfig();
@@ -343,6 +656,7 @@ export class WorkerDecisionLoop {
         });
         let latestCheckpoint = null;
         let checkpointInvalid = false;
+        let lastCheckpointFailureReason = null;
         let lastCheckpointAt = 0;
         const checkpointDebounceMs = 5_000;
         let checkpointQueue = Promise.resolve();
@@ -360,11 +674,15 @@ export class WorkerDecisionLoop {
                     });
                     if (checkpoint) {
                         latestCheckpoint = checkpoint.checkpoint;
-                        checkpointInvalid = checkpointInvalid || !checkpoint.valid || checkpoint.blockMerge;
+                        checkpointInvalid = checkpointInvalid || checkpoint.blockMerge;
                     }
                 }
-                catch {
+                catch (checkpointError) {
                     checkpointInvalid = true;
+                    lastCheckpointFailureReason =
+                        checkpointError instanceof Error
+                            ? checkpointError.message
+                            : (extractNonErrorMessage(checkpointError) ?? 'checkpoint creation failed');
                 }
                 finally {
                     lastCheckpointAt = Date.now();
@@ -385,14 +703,18 @@ export class WorkerDecisionLoop {
         }, interactiveConfig.checkpointIntervalMs);
         timer.unref?.();
         try {
-            const workerOutput = await this.provider.runWorker(this.buildRunInput(input, 'interactive', worktreePath));
+            const workerOutput = await this.provider.runWorker(this.buildRunInput(input, 'interactive', worktreePath, runtimeSelection));
             await enqueueCheckpoint('final');
             const changedFiles = latestCheckpoint?.files_changed ?? [];
+            const hasNetNewWorktreeChanges = latestCheckpoint?.net_new_worktree_change === true;
             return {
                 workerOutput,
-                finalCheckpoint: latestCheckpoint ?? this.createSyntheticCheckpoint(input.featureId),
+                finalCheckpoint: latestCheckpoint ??
+                    this.createSyntheticCheckpoint(input.featureId, lastCheckpointFailureReason),
                 changedFiles,
+                hasNetNewWorktreeChanges,
                 checkpointInvalid,
+                fallbackReason: readInteractiveFallbackReason(workerOutput),
             };
         }
         finally {
@@ -402,33 +724,119 @@ export class WorkerDecisionLoop {
             await this.watchdog.stopWatching(input.featureId);
         }
     }
-    createSyntheticCheckpoint(featureId) {
+    createSyntheticCheckpoint(featureId, failureReason = null) {
         return {
             checkpoint_id: `checkpoint-synthetic-${Date.now()}`,
             timestamp: new Date().toISOString(),
             files_changed: [],
-            validation_status: 'skipped',
-            violations: [],
+            validation_status: failureReason ? 'invalid' : 'skipped',
+            violations: failureReason ? [failureReason] : [],
             diff_snapshot: `.aop/features/${featureId}/checkpoints/synthetic.diff`,
+            net_new_worktree_change: false,
+        };
+    }
+    async runInteractivePlanner(input, runtimeSelection) {
+        const workerOutput = await this.provider.runWorker(this.buildRunInput(input, 'interactive', this.resolvePlannerWorkingDirectory(input.featureId), runtimeSelection));
+        return {
+            workerOutput,
+            finalCheckpoint: null,
+            changedFiles: [],
+            hasNetNewWorktreeChanges: false,
+            checkpointInvalid: false,
+            fallbackReason: readInteractiveFallbackReason(workerOutput),
         };
     }
-    async routePlanSubmission(input, output, result) {
+    resolvePromptInstructions(input, executionMode) {
+        const baseInstructions = input.instructions.trim();
+        if (executionMode !== 'interactive') {
+            return baseInstructions;
+        }
+        if (input.role === 'builder' || input.role === 'qa' || input.role === 'reconciler') {
+            const interactiveOverride = input.role === 'builder'
+                ? [
+                    'Interactive mode override:',
+                    '- Edit planned files directly in the working directory.',
+                    '- Ignore any generic instruction that asks you to emit PATCH or unified diff output.',
+                    '- Use the accepted plan, allowed areas, planned file list, and latest evidence in the context summary below as your execution contract.',
+                    '- Return NOTE only after making planned file changes.',
+                    '- If the safe fix surface exceeds the accepted plan, return REQUEST.action=more_context with a concrete blocker.',
+                    '- Use ask_user_input only for genuine human decisions, approvals, or policy exceptions you cannot resolve from the plan and repo.',
+                ].join('\n')
+                : input.role === 'qa'
+                    ? [
+                        'Interactive mode override:',
+                        '- Edit files directly in the working directory.',
+                        '- Ignore any generic instruction that asks you to emit PATCH or unified diff output.',
+                        '- Use the accepted plan, qa_test_index, and latest evidence in the context summary below as your verification contract.',
+                        '- Return NOTE only after making file changes that address a reproduced failure or verification gap.',
+                        '- Use more_context/context_refresh only when evidence is stale or the accepted plan does not authorize the safe fix surface.',
+                        '- Use ask_user_input only for genuine operator decisions, approvals, or risk acknowledgements.',
+                    ].join('\n')
+                    : [
+                        'Interactive mode override:',
+                        '- Edit files directly in the conflicted worktree.',
+                        '- Ignore any generic instruction that asks you to emit PATCH or unified diff output.',
+                        '- Use the spec, accepted plan, conflict status, approved collision context, and latest evidence in the context summary below as your reconciliation contract.',
+                        '- Return NOTE only after resolving conflicted files and performing proportionate verification.',
+                        '- Use more_context/context_refresh only when the conflict snapshot or surrounding repo state is stale.',
+                        '- Use ask_user_input only when preserving mainline semantics and feature intent requires an operator choice.',
+                    ].join('\n');
+            return baseInstructions.length > 0
+                ? `${interactiveOverride}\n\nAdditional task context:\n${baseInstructions}`
+                : interactiveOverride;
+        }
+        if (input.role === 'planner') {
+            const plannerOverride = resolvePlannerPhaseFromContext(input.contextBundle) === 'intake'
+                ? [
+                    'Interactive mode override:',
+                    '- Read and update the intake artifacts directly on disk.',
+                    '- Emit INTAKE_SUBMISSION when the verified manifest is ready.',
+                    '- Emit REQUEST.action=ask_user_input only for blocking requirement clarification.',
+                    '- If you ask for user input, stop there for the turn and wait for the persisted answer before promoting the manifest.',
+                    '- Never self-assert human_review_confirmed without an answered manifest-review confirmation question in context.',
+                    '- Return NOTE only when you intentionally keep intake unchanged and can justify that decision from the observed feature state.',
+                ].join('\n')
+                : [
+                    'Interactive mode override:',
+                    '- Read and update the planning artifacts directly on disk.',
+                    '- Emit PLAN_SUBMISSION or REQUEST.action=amend_plan when the accepted plan must change.',
+                    '- Return NOTE only when you intentionally keep the accepted plan unchanged and can justify that decision from the observed feature state.',
+                ].join('\n');
+            return baseInstructions.length > 0
+                ? `${plannerOverride}\n\nAdditional task context:\n${baseInstructions}`
+                : plannerOverride;
+        }
+        return baseInstructions;
+    }
+    resolvePlannerWorkingDirectory(featureId) {
+        if (!this.repoRoot) {
+            return undefined;
+        }
+        return path.join(this.repoRoot, '.aop', 'features', featureId);
+    }
+    async routePlanSubmission(input, output, result, plannerState) {
         if (input.role !== 'planner') {
             return;
         }
+        if (plannerState.planMutationApplied) {
+            return;
+        }
         const planJson = sanitizePlannerPlan(asRecord(output.plan_json ?? output.plan));
         if (Object.keys(planJson).length === 0) {
             return;
         }
-        const contextPlan = asRecord(input.contextBundle.plan);
-        const existingVersion = readPlanVersion(contextPlan.plan_version);
+        if ((await this.requestIntakeClarificationForPlanMutation(input, result, ERROR_CODES.VERIFIED_MANIFEST_REQUIRED)) === true) {
+            return;
+        }
         const requestedExpectedVersion = readPlanVersion(output.expected_plan_version);
+        const existingVersion = plannerState.currentPlanVersion;
         if (existingVersion == null) {
             const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
                 feature_id: input.featureId,
                 plan_json: planJson,
             });
             result.toolResults.push(asRecord(response.data));
+            this.recordPlannerMutation(plannerState, response.data, planJson);
             result.planSubmission = true;
             return;
         }
@@ -439,10 +847,73 @@ export class WorkerDecisionLoop {
             plan_json: planJson,
         });
         result.toolResults.push(asRecord(response.data));
+        this.recordPlannerMutation(plannerState, response.data, planJson);
         result.planSubmission = true;
     }
+    async routeIntakeSubmission(input, output, result, plannerState) {
+        if (input.role !== 'planner' || plannerState.planMutationApplied) {
+            return;
+        }
+        const intakeSubmission = asRecord(output.intake_submission);
+        if (!intakeSubmission) {
+            return;
+        }
+        try {
+            const response = await this.toolCaller.callTool('planner', TOOLS.FEATURE_INTAKE_SUBMIT, {
+                feature_id: input.featureId,
+                intake_submission: intakeSubmission,
+            });
+            result.toolResults.push(asRecord(response.data));
+            result.intakeSubmission = true;
+        }
+        catch (error) {
+            const failure = readToolFailureDetails(error);
+            const plannerPhase = resolvePlannerPhaseFromContext(input.contextBundle);
+            if (failure?.code !== ERROR_CODES.INTAKE_SUBMISSION_INVALID || plannerPhase !== 'intake') {
+                throw error;
+            }
+            const ambiguityIds = normalizeList([
+                ...asStringArray(failure.details.missing_ambiguity_evidence_ids),
+                ...asStringArray(failure.details.open_ambiguity_ids),
+            ]);
+            if (!hasOpenIntakeQuestion(input.contextBundle)) {
+                const ambiguities = readIntakeAmbiguitiesForRecovery(input.contextBundle, ambiguityIds);
+                const priorAnswers = readAnsweredIntakeClarifications(input.contextBundle).filter((answer) => ambiguityIds.length === 0 ||
+                    answer.ambiguityIds.some((ambiguityId) => ambiguityIds.includes(ambiguityId)));
+                const sessionId = this.resolveRoleSessionId?.(input.role, input.featureId) ?? `bootstrap:${input.role}`;
+                const response = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_QUESTION_CREATE, {
+                    feature_id: input.featureId,
+                    role: 'planner',
+                    session_id: sessionId,
+                    question_type: 'clarification',
+                    prompt: buildIntakeClarificationPrompt(ambiguities, failure.code ?? ERROR_CODES.INTAKE_SUBMISSION_INVALID, priorAnswers),
+                    details: {
+                        ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+                        obligation_ids: normalizeList(ambiguities.flatMap((ambiguity) => ambiguity.obligationIds)),
+                        prior_answered_ambiguity_ids: ambiguities
+                            .filter((ambiguity) => priorAnswers.some((answer) => answer.ambiguityIds.includes(ambiguity.id)))
+                            .map((ambiguity) => ambiguity.id),
+                        recovery_reason: failure.code ?? ERROR_CODES.INTAKE_SUBMISSION_INVALID,
+                        recovery_source: 'intake_submission_validation',
+                        validation_message: failure.message,
+                    },
+                    expected_answer: {
+                        kind: 'free_text',
+                    },
+                    blocking: true,
+                    phase: STATUS.INTAKE,
+                    request_action: 'ask_user_input',
+                    resume_status: STATUS.INTAKE,
+                    resume_phase: STATUS.INTAKE,
+                });
+                result.toolResults.push(asRecord(response.data));
+            }
+            result.requestHandled = true;
+            result.questionRequested = true;
+        }
+    }
     async routePatch(input, output, result) {
-        if (input.role !== 'builder' && input.role !== 'qa') {
+        if (input.role !== 'builder' && input.role !== 'qa' && input.role !== 'reconciler') {
             return;
         }
         const unifiedDiff = asNonEmptyString(output.unified_diff ?? output.diff);
@@ -470,11 +941,11 @@ export class WorkerDecisionLoop {
             // Global logs are best-effort for parity with prior orphan-session logging.
         }
     }
-    async routeRequest(input, output, result) {
+    async routeRequest(input, output, result, plannerState, allowContextRefreshRetry) {
         const request = asRecord(output.request ?? output);
         const action = asNonEmptyString(request.action ?? request.request_type)?.toLowerCase();
         if (!action) {
-            return;
+            return { contextRefreshRequested: false, refreshedContext: null };
         }
         if (action === 'prioritize') {
             const featureOrder = asStringArray(request.feature_order);
@@ -482,12 +953,12 @@ export class WorkerDecisionLoop {
                 result.priorityOrder = featureOrder;
                 result.requestHandled = true;
             }
-            return;
+            return { contextRefreshRequested: false, refreshedContext: null };
         }
         if (action === 'lock_acquire') {
             const resources = asStringArray(request.resources);
             if (resources.length === 0) {
-                return;
+                return { contextRefreshRequested: false, refreshedContext: null };
             }
             const response = await this.toolCaller.callTool('orchestrator', TOOLS.LOCKS_ACQUIRE, {
                 feature_id: input.featureId,
@@ -495,12 +966,12 @@ export class WorkerDecisionLoop {
             });
             result.toolResults.push(asRecord(response.data));
             result.requestHandled = true;
-            return;
+            return { contextRefreshRequested: false, refreshedContext: null };
         }
         if (action === 'lock_release') {
             const resources = asStringArray(request.resources);
             if (resources.length === 0) {
-                return;
+                return { contextRefreshRequested: false, refreshedContext: null };
             }
             const response = await this.toolCaller.callTool('orchestrator', TOOLS.LOCKS_RELEASE, {
                 feature_id: input.featureId,
@@ -508,33 +979,89 @@ export class WorkerDecisionLoop {
             });
             result.toolResults.push(asRecord(response.data));
             result.requestHandled = true;
-            return;
+            return { contextRefreshRequested: false, refreshedContext: null };
         }
         if (action === 'more_context' || action === 'context_refresh') {
+            result.contextRequestCount += 1;
+            result.lastContextRequestAt = new Date().toISOString();
+            result.lastContextRequestRole = input.role;
+            if (!allowContextRefreshRetry) {
+                return { contextRefreshRequested: true, refreshedContext: null };
+            }
             const response = await this.toolCaller.callTool(input.role, TOOLS.FEATURE_GET_CONTEXT, {
                 feature_id: input.featureId,
             });
             result.toolResults.push(asRecord(response.data));
+            this.refreshPlannerStateFromContext(plannerState, response.data);
+            return {
+                contextRefreshRequested: true,
+                refreshedContext: asRecord(response.data) ?? {},
+            };
+        }
+        if (action === 'ask_user_input') {
+            const prompt = asNonEmptyString(request.prompt);
+            if (!prompt) {
+                return { contextRefreshRequested: false, refreshedContext: null };
+            }
+            const sessionId = this.resolveRoleSessionId?.(input.role, input.featureId) ?? `bootstrap:${input.role}`;
+            const currentStatus = asNonEmptyString(asRecord(asRecord(input.contextBundle.state).front_matter).status);
+            const plannerPhase = input.role === 'planner' ? resolvePlannerPhaseFromContext(input.contextBundle) : 'planning';
+            const response = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_QUESTION_CREATE, {
+                feature_id: input.featureId,
+                role: input.role,
+                session_id: sessionId,
+                question_type: asNonEmptyString(request.question_type) ?? 'clarification',
+                prompt,
+                details: asRecord(request.details) ?? {},
+                expected_answer: asRecord(request.expected_answer) ?? undefined,
+                blocking: request.blocking !== false,
+                phase: plannerPhase === 'intake' ? STATUS.INTAKE : (currentStatus ?? input.role),
+                request_action: action,
+                resume_status: plannerPhase === 'intake' ? STATUS.INTAKE : undefined,
+                resume_phase: plannerPhase === 'intake' ? STATUS.INTAKE : undefined,
+            });
+            result.toolResults.push(asRecord(response.data));
             result.requestHandled = true;
-            return;
+            result.questionRequested = true;
+            try {
+                await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+                    feature_id: input.featureId,
+                    note: JSON.stringify({
+                        action,
+                        question_id: asRecord(response.data)?.question_id ?? null,
+                        role: input.role,
+                        prompt,
+                    }),
+                });
+            }
+            catch (_error) {
+                // Best effort log for observability.
+            }
+            return { contextRefreshRequested: false, refreshedContext: null };
         }
         if (action === 'amend_plan' && input.role === 'planner') {
+            if (plannerState.planMutationApplied) {
+                return { contextRefreshRequested: false, refreshedContext: null };
+            }
             const planJson = sanitizePlannerPlan(asRecord(request.plan_json));
             if (Object.keys(planJson).length === 0) {
-                return;
+                return { contextRefreshRequested: false, refreshedContext: null };
+            }
+            if ((await this.requestIntakeClarificationForPlanMutation(input, result, ERROR_CODES.VERIFIED_MANIFEST_REQUIRED)) === true) {
+                return { contextRefreshRequested: false, refreshedContext: null };
             }
-            const contextPlan = asRecord(input.contextBundle.plan);
-            const existingVersion = readPlanVersion(contextPlan.plan_version);
             const requestedExpectedVersion = readPlanVersion(request.expected_plan_version);
+            const existingVersion = plannerState.currentPlanVersion;
             if (existingVersion == null) {
                 const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_SUBMIT, {
                     feature_id: input.featureId,
                     plan_json: planJson,
                 });
                 result.toolResults.push(asRecord(response.data));
+                this.recordPlannerMutation(plannerState, response.data, planJson);
                 result.requestHandled = true;
                 result.planSubmission = true;
-                return;
+                return { contextRefreshRequested: false, refreshedContext: null };
             }
             const response = await this.toolCaller.callTool('planner', TOOLS.PLAN_UPDATE, {
                 feature_id: input.featureId,
@@ -542,8 +1069,100 @@ export class WorkerDecisionLoop {
                 plan_json: planJson,
             });
             result.toolResults.push(asRecord(response.data));
+            this.recordPlannerMutation(plannerState, response.data, planJson);
             result.requestHandled = true;
             result.planSubmission = true;
+            return { contextRefreshRequested: false, refreshedContext: null };
+        }
+        try {
+            await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+                feature_id: input.featureId,
+                note: JSON.stringify({
+                    action: 'unknown_request_action',
+                    requested_action: action,
+                    role: input.role,
+                }),
+            });
+        }
+        catch (_error) {
+            // Best effort observability for unknown actions.
+        }
+        return { contextRefreshRequested: false, refreshedContext: null };
+    }
+    async requestIntakeClarificationForPlanMutation(input, result, recoveryReason) {
+        if (input.role !== 'planner' ||
+            resolvePlannerPhaseFromContext(input.contextBundle) !== 'intake') {
+            return false;
+        }
+        const verifiedManifest = asRecord(asRecord(input.contextBundle.intake).verified_manifest);
+        if (Object.keys(verifiedManifest).length > 0) {
+            return false;
+        }
+        if (hasOpenIntakeQuestion(input.contextBundle)) {
+            result.requestHandled = true;
+            return true;
+        }
+        const ambiguities = readOpenIntakeAmbiguities(input.contextBundle);
+        const priorAnswers = readAnsweredIntakeClarifications(input.contextBundle);
+        if (ambiguities.length === 0) {
+            result.requestHandled = true;
+            return true;
+        }
+        const sessionId = this.resolveRoleSessionId?.(input.role, input.featureId) ?? `bootstrap:${input.role}`;
+        const response = await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_QUESTION_CREATE, {
+            feature_id: input.featureId,
+            role: input.role,
+            session_id: sessionId,
+            question_type: 'clarification',
+            prompt: buildIntakeClarificationPrompt(ambiguities, recoveryReason, priorAnswers),
+            details: {
+                ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+                obligation_ids: ambiguities.flatMap((ambiguity) => ambiguity.obligationIds),
+                recovery_reason: recoveryReason,
+                recovery_source: 'worker_decision_loop',
+            },
+            expected_answer: {
+                kind: 'free_text',
+            },
+            blocking: true,
+            phase: STATUS.INTAKE,
+            request_action: 'ask_user_input',
+            resume_status: STATUS.INTAKE,
+            resume_phase: STATUS.INTAKE,
+        });
+        result.toolResults.push(asRecord(response.data));
+        result.requestHandled = true;
+        result.questionRequested = true;
+        try {
+            await this.toolCaller.callTool('orchestrator', TOOLS.FEATURE_LOG_APPEND, {
+                feature_id: input.featureId,
+                note: JSON.stringify({
+                    action: 'ask_user_input',
+                    question_id: asRecord(response.data)?.question_id ?? null,
+                    role: input.role,
+                    recovery_reason: recoveryReason,
+                    recovery_source: 'worker_decision_loop',
+                    ambiguity_ids: ambiguities.map((ambiguity) => ambiguity.id),
+                }),
+            });
+        }
+        catch (_error) {
+            // Best effort observability for intake rerouting.
+        }
+        return true;
+    }
+    refreshPlannerStateFromContext(plannerState, context) {
+        const refreshedPlanVersion = readPlanVersion(asRecord(asRecord(context).plan).plan_version);
+        if (refreshedPlanVersion != null) {
+            plannerState.currentPlanVersion = refreshedPlanVersion;
+        }
+    }
+    recordPlannerMutation(plannerState, responseData, planJson) {
+        plannerState.planMutationApplied = true;
+        const acceptedPlanVersion = readPlanVersion(asRecord(responseData).plan_version) ??
+            readPlanVersion(planJson.plan_version);
+        if (acceptedPlanVersion != null) {
+            plannerState.currentPlanVersion = acceptedPlanVersion;
         }
     }
     resolveRunId() {
@@ -576,8 +1195,22 @@ export class WorkerDecisionLoop {
             note_count: event.noteCount,
             valid: event.valid,
             error_code: event.errorCode,
-            provider: this.provider.selection.provider,
-            model: this.provider.selection.model,
+            interactive_outcome: event.interactiveOutcome ?? null,
+            checkpoint_id: event.checkpointId ?? null,
+            checkpoint_diff_hash: event.checkpointDiffHash ?? null,
+            checkpoint_net_new_worktree_change: event.checkpointNetNewWorktreeChange ?? null,
+            checkpoint_validation_status: event.checkpointValidationStatus ?? null,
+            provider: event.runtimeSelection.provider,
+            model: event.runtimeSelection.model,
+            usage: event.usage
+                ? {
+                    status: event.usage.status,
+                    input_tokens: event.usage.input_tokens,
+                    output_tokens: event.usage.output_tokens,
+                    total_tokens: event.usage.total_tokens,
+                    estimated_cost_usd: event.usage.estimated_cost_usd,
+                }
+                : null,
             watchdog_reason: event.watchdogReason ?? null,
             timeout_ms: event.timeoutMs,
             idle_timeout_ms: event.idleTimeoutMs,
@@ -586,6 +1219,7 @@ export class WorkerDecisionLoop {
             elapsed_ms: event.elapsedMs,
             signal: event.signal ?? null,
             exit_code: event.exitCode,
+            stderr: event.stderr,
         };
         await appendWorkerRuntimeEvent({
             repoRoot: this.repoRoot,