agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/src/supervisor/worker-decision-loop.ts

@@ -1,7 +1,15 @@
-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 type { ExecutionMode, WorkerProvider, WorkerRunInput } from '../providers/providers.js';
+import type {
+  ExecutionMode,
+  ProviderSelection,
+  WorkerProvider,
+  WorkerRunInput,
+} from '../providers/providers.js';
+import type { NormalizedUsageRecord } from '../application/usage-types.js';
 import type { RuntimeRole, SupervisorToolCaller } from './types.js';
+import { resolvePlannerPhaseFromContext } from './planner-phase.js';
 import type { ActivityMonitorService } from '../application/services/activity-monitor-service.js';
 import { appendWorkerRuntimeEvent } from './worker-event-journal.js';
 import type {
@@ -22,6 +30,7 @@ const PLAN_TOP_LEVEL_KEYS = new Set([
   'files',
   'contracts',
   'acceptance_criteria',
+  'plan_trace',
   'gate_targets',
   'risk',
   'revision_of',
@@ -29,28 +38,71 @@ const PLAN_TOP_LEVEL_KEYS = new Set([
   'verification_overrides',
 ]);
 
+/** Input payload for a single worker decision turn. */
 export interface WorkerDecisionInput {
+  /** Agent role executing this turn (planner, builder, or qa). */
   role: RuntimeRole;
+  /** Target feature identifier. */
   featureId: string;
+  /** Aggregated context bundle passed to the worker provider. */
   contextBundle: AnyRecord;
+  /** Natural-language instructions for the worker. */
   instructions: string;
+  /** Tool results from a previous turn, used for context-refresh retries. */
   lastToolResults?: AnyRecord[];
 }
 
+/** Outcome of a single worker decision turn, summarising all actions taken and diagnostics. */
 export interface WorkerDecisionResult {
+  /** Whether a plan was submitted during this turn. */
   planSubmission: boolean;
+  /** Whether an intake manifest was submitted during this turn. */
+  intakeSubmission: boolean;
+  /** Whether at least one code patch was applied. */
   patchApplied: boolean;
+  /** Whether a log note was recorded. */
   noteLogged: boolean;
+  /** Whether a structured request (e.g. context refresh) was handled. */
   requestHandled: boolean;
+  /** Whether the worker emitted a human-input question. */
+  questionRequested: boolean;
+  /** Whether the worker stalled requesting context without making progress. */
+  contextStall: boolean;
+  /** Number of context-refresh requests seen across outputs. */
+  contextRequestCount: number;
+  /** ISO timestamp of the most recent context-refresh request, if any. */
+  lastContextRequestAt: string | null;
+  /** Role that issued the most recent context-refresh request. */
+  lastContextRequestRole: RuntimeRole | null;
+  /** Whether the provider output failed validation. */
   invalidOutput: boolean;
+  /** Structured error code if an error occurred, otherwise null. */
+  errorCode?: string | null;
+  /** True when the turn produced no forward progress. */
   noProgress: boolean;
+  /** Classified output types emitted by the worker (e.g. PATCH, PLAN_SUBMISSION, NOTE). */
   outputTypes: string[];
+  /** Raw output records returned by the provider. */
   rawOutputs: AnyRecord[];
+  /** Priority-ordered list of output types processed. */
   priorityOrder: string[];
+  /** Accumulated tool-call results from the turn. */
   toolResults: AnyRecord[];
+  /** Outcome classification for interactive-mode executions. */
+  interactiveOutcome?:
+    | 'progress_applied'
+    | 'no_new_work'
+    | 'checkpoint_invalid'
+    | 'provider_output_invalid'
+    | null;
+  /** Worktree checkpoint captured at the end of an interactive turn. */
+  checkpoint?: CheckpointRecord | null;
+  usageRecords?: NormalizedUsageRecord[];
 }
 
+/** Strategy interface for executing a single worker decision turn. */
 export interface WorkerDecisionRunner {
+  /** Run one decision turn for the given input and return the aggregated result. */
   execute(input: WorkerDecisionInput): Promise<WorkerDecisionResult>;
 }
 
@@ -58,6 +110,24 @@ function asRecord(value: unknown): AnyRecord {
   return value && typeof value === 'object' ? (value as AnyRecord) : {};
 }
 
+function extractNonErrorMessage(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return typeof value === 'string' ? value : null;
+  }
+  const obj = value as AnyRecord;
+  const normalized = obj['normalizedResponse'] as AnyRecord | undefined;
+  if (normalized?.['error'] && typeof normalized['error'] === 'object') {
+    const err = normalized['error'] as AnyRecord;
+    if (typeof err['message'] === 'string') {
+      return err['message'];
+    }
+  }
+  if (typeof obj['message'] === 'string') {
+    return obj['message'];
+  }
+  return null;
+}
+
 function asNonEmptyString(value: unknown): string | null {
   if (typeof value !== 'string') {
     return null;
@@ -106,21 +176,43 @@ function asOutputs(result: Record<string, unknown>): AnyRecord[] {
   return [asRecord(result)];
 }
 
+function readInteractiveFallbackReason(result: Record<string, unknown>): string | null {
+  return asNonEmptyString(asRecord(result.provider_meta).parse_fallback_reason);
+}
+
+function isBlockingAskUserInputOutput(output: AnyRecord): boolean {
+  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(): WorkerDecisionResult {
   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: WorkerDecisionRunner = {
   execute: () => Promise.resolve(makeEmptyResult()),
 };
@@ -132,6 +224,10 @@ interface WorkerDecisionLoopDependencies {
   repoRoot?: string;
   runId?: string | (() => string);
   resolveExecutionMode?: (featureId: string, role: RuntimeRole) => Promise<ExecutionMode>;
+  resolveRuntimeSelection?: (
+    featureId: string,
+    role: RuntimeRole,
+  ) => ProviderSelection | Promise<ProviderSelection>;
   resolveInteractiveConfig?: () => InteractiveExecutionConfig;
   watchdog?: WorktreeWatchdogService;
   checkpointService?: CheckpointService;
@@ -141,11 +237,192 @@ interface WorkerDecisionLoopDependencies {
 
 interface InteractiveRunSummary {
   workerOutput: Record<string, unknown>;
-  finalCheckpoint: CheckpointRecord;
+  finalCheckpoint: CheckpointRecord | null;
   changedFiles: string[];
+  hasNetNewWorktreeChanges: boolean;
   checkpointInvalid: boolean;
+  fallbackReason: string | null;
+}
+
+interface PlannerExecutionState {
+  currentPlanVersion: number | null;
+  planMutationApplied: boolean;
 }
 
+interface WorkerRunResult {
+  workerOutput: Record<string, unknown>;
+  interactiveSummary: InteractiveRunSummary | null;
+  executionMode: ExecutionMode;
+  runtimeSelection: ProviderSelection;
+  usage: NormalizedUsageRecord | null;
+}
+
+interface RequestRoutingResult {
+  contextRefreshRequested: boolean;
+  refreshedContext: AnyRecord | null;
+}
+
+interface IntakeClarificationAmbiguity {
+  id: string;
+  summary: string;
+  obligationIds: string[];
+}
+
+interface IntakeClarificationAnswer {
+  questionId: string;
+  ambiguityIds: string[];
+  answer: string;
+  answeredAt: string | null;
+}
+
+interface ToolFailureDetails {
+  code: string | null;
+  message: string | null;
+  details: AnyRecord;
+}
+
+function normalizeList(values: string[]): string[] {
+  return Array.from(new Set(values.map((item) => item.trim()).filter((item) => item.length > 0)));
+}
+
+function readToolFailureDetails(error: unknown): ToolFailureDetails | null {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+
+  const direct = asRecord((error as { error?: unknown }).error);
+  const normalized = asRecord(
+    asRecord((error as { normalizedResponse?: unknown }).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: AnyRecord): IntakeClarificationAmbiguity[] {
+  const intake = asRecord(contextBundle.intake);
+  const review = asRecord(intake.review);
+  const ambiguities = Array.isArray(review.ambiguities) ? review.ambiguities : [];
+  const results: IntakeClarificationAmbiguity[] = [];
+  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: AnyRecord): IntakeClarificationAmbiguity[] {
+  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 is string => item !== null),
+  );
+  return readAllIntakeAmbiguities(contextBundle).filter((item) => openIds.has(item.id));
+}
+
+function readIntakeAmbiguitiesForRecovery(
+  contextBundle: AnyRecord,
+  ambiguityIds: string[],
+): IntakeClarificationAmbiguity[] {
+  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: AnyRecord): boolean {
+  const humanInput = asRecord(contextBundle.human_input);
+  const openQuestions = Array.isArray(humanInput.open_questions) ? humanInput.open_questions : [];
+  return openQuestions.length > 0;
+}
+
+function readAnsweredIntakeClarifications(contextBundle: AnyRecord): IntakeClarificationAnswer[] {
+  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: IntakeClarificationAmbiguity[],
+  recoveryReason: string,
+  priorAnswers: IntakeClarificationAnswer[],
+): string {
+  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 implements WorkerDecisionRunner {
   private readonly provider: WorkerProvider;
   private readonly toolCaller: SupervisorToolCaller;
@@ -155,6 +432,9 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
   private readonly resolveExecutionModeOverride:
     | ((featureId: string, role: RuntimeRole) => Promise<ExecutionMode>)
     | undefined;
+  private readonly resolveRuntimeSelectionOverride:
+    | ((featureId: string, role: RuntimeRole) => ProviderSelection | Promise<ProviderSelection>)
+    | undefined;
   private readonly resolveInteractiveConfigOverride: (() => InteractiveExecutionConfig) | undefined;
   private readonly watchdog: WorktreeWatchdogService | undefined;
   private readonly checkpointService: CheckpointService | undefined;
@@ -170,6 +450,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     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;
@@ -177,11 +458,21 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     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: WorkerDecisionInput): Promise<WorkerDecisionResult> {
     const result = makeEmptyResult();
+    const plannerState: PlannerExecutionState = {
+      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: ExecutionMode =
@@ -201,6 +492,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
         valid: true,
         errorCode: null,
         executionMode,
+        runtimeSelection,
       });
     }
     await this.appendWorkerEvent({
@@ -215,17 +507,124 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       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;
+  }
+
+  private async runWorkerTurn(
+    input: WorkerDecisionInput,
+    executionMode: ExecutionMode,
+    runtimeSelection: ProviderSelection,
+    interactiveEligible: boolean,
+  ): Promise<WorkerRunResult> {
     let workerOutput: Record<string, unknown>;
     let interactiveSummary: InteractiveRunSummary | null = 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),
+          this.buildRunInput(input, executionMode, undefined, runtimeSelection),
         );
       }
     } catch (error) {
@@ -270,92 +669,177 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
         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: NormalizedUsageRecord | null =
+      rawUsage &&
+      typeof rawUsage === 'object' &&
+      'status' in rawUsage &&
+      typeof (rawUsage as NormalizedUsageRecord).status === 'string'
+        ? (rawUsage as NormalizedUsageRecord)
+        : null;
+
+    return {
+      workerOutput,
+      interactiveSummary,
+      executionMode,
+      runtimeSelection,
+      usage,
+    };
+  }
+
+  private buildContextRetryToolResults(
+    input: WorkerDecisionInput,
+    refreshedContext: AnyRecord,
+  ): AnyRecord[] {
+    return [
+      ...(input.lastToolResults ?? []),
+      {
+        tool_name: TOOLS.FEATURE_GET_CONTEXT,
+        feature_id: input.featureId,
+        refreshed_context: structuredClone(refreshedContext),
+      },
+    ];
+  }
+
+  private async processOutputs(input: {
+    input: WorkerDecisionInput;
+    workerRun: WorkerRunResult;
+    result: WorkerDecisionResult;
+    plannerState: PlannerExecutionState;
+    allowContextRefreshRetry: boolean;
+  }): Promise<RequestRoutingResult> {
+    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 };
+  }
+
+  private finalizeInteractiveOutcome(
+    result: WorkerDecisionResult,
+    interactiveSummary: InteractiveRunSummary | null,
+  ): void {
+    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;
   }
 
   private async resolveExecutionMode(featureId: string, role: RuntimeRole): Promise<ExecutionMode> {
@@ -365,21 +849,37 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     return 'deterministic';
   }
 
+  private async resolveRuntimeSelection(
+    featureId: string,
+    role: RuntimeRole,
+  ): Promise<ProviderSelection> {
+    if (this.resolveRuntimeSelectionOverride) {
+      return await this.resolveRuntimeSelectionOverride(featureId, role);
+    }
+    return this.provider.selection;
+  }
+
   private isInteractiveEligible(executionMode: ExecutionMode, role: RuntimeRole): boolean {
     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;
   }
 
   private resolveInteractiveConfig(): InteractiveExecutionConfig {
@@ -400,17 +900,23 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     input: WorkerDecisionInput,
     executionMode: ExecutionMode,
     workingDirectory: string | undefined,
+    runtimeSelection: ProviderSelection,
   ): WorkerRunInput {
     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,
@@ -418,16 +924,21 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     };
   }
 
-  private async runInteractiveWorker(input: WorkerDecisionInput): Promise<InteractiveRunSummary> {
+  private async runInteractiveWorker(
+    input: WorkerDecisionInput,
+    runtimeSelection: ProviderSelection,
+  ): Promise<InteractiveRunSummary> {
     if (!this.repoRoot || !this.watchdog || !this.checkpointService || !this.resolveWorktreePath) {
       const fallbackOutput = await this.provider.runWorker(
-        this.buildRunInput(input, 'deterministic', undefined),
+        this.buildRunInput(input, 'deterministic', undefined, runtimeSelection),
       );
       return {
         workerOutput: fallbackOutput,
         finalCheckpoint: this.createSyntheticCheckpoint(input.featureId),
         changedFiles: [],
+        hasNetNewWorktreeChanges: false,
         checkpointInvalid: false,
+        fallbackReason: readInteractiveFallbackReason(fallbackOutput),
       };
     }
 
@@ -444,6 +955,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
 
     let latestCheckpoint: CheckpointRecord | null = null;
     let checkpointInvalid = false;
+    let lastCheckpointFailureReason: string | null = null;
     let lastCheckpointAt = 0;
     const checkpointDebounceMs = 5_000;
     let checkpointQueue = Promise.resolve();
@@ -464,10 +976,14 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
           });
           if (checkpoint) {
             latestCheckpoint = checkpoint.checkpoint;
-            checkpointInvalid = checkpointInvalid || !checkpoint.valid || checkpoint.blockMerge;
+            checkpointInvalid = checkpointInvalid || checkpoint.blockMerge;
           }
-        } catch {
+        } catch (checkpointError: unknown) {
           checkpointInvalid = true;
+          lastCheckpointFailureReason =
+            checkpointError instanceof Error
+              ? checkpointError.message
+              : (extractNonErrorMessage(checkpointError) ?? 'checkpoint creation failed');
         } finally {
           lastCheckpointAt = Date.now();
         }
@@ -491,15 +1007,20 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
 
     try {
       const workerOutput = await this.provider.runWorker(
-        this.buildRunInput(input, 'interactive', worktreePath),
+        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 {
       clearInterval(timer);
@@ -509,34 +1030,152 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     }
   }
 
-  private createSyntheticCheckpoint(featureId: string): CheckpointRecord {
+  private createSyntheticCheckpoint(
+    featureId: string,
+    failureReason: string | null = null,
+  ): CheckpointRecord {
     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,
     };
   }
 
+  private async runInteractivePlanner(
+    input: WorkerDecisionInput,
+    runtimeSelection: ProviderSelection,
+  ): Promise<InteractiveRunSummary> {
+    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),
+    };
+  }
+
+  private resolvePromptInstructions(
+    input: WorkerDecisionInput,
+    executionMode: ExecutionMode,
+  ): string {
+    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;
+  }
+
+  private resolvePlannerWorkingDirectory(featureId: string): string | undefined {
+    if (!this.repoRoot) {
+      return undefined;
+    }
+    return path.join(this.repoRoot, '.aop', 'features', featureId);
+  }
+
   private async routePlanSubmission(
     input: WorkerDecisionInput,
     output: AnyRecord,
     result: WorkerDecisionResult,
+    plannerState: PlannerExecutionState,
   ): Promise<void> {
     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, {
@@ -544,6 +1183,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
         plan_json: planJson,
       });
       result.toolResults.push(asRecord(response.data));
+      this.recordPlannerMutation(plannerState, response.data, planJson);
       result.planSubmission = true;
       return;
     }
@@ -555,15 +1195,102 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       plan_json: planJson,
     });
     result.toolResults.push(asRecord(response.data));
+    this.recordPlannerMutation(plannerState, response.data, planJson);
     result.planSubmission = true;
   }
 
+  private async routeIntakeSubmission(
+    input: WorkerDecisionInput,
+    output: AnyRecord,
+    result: WorkerDecisionResult,
+    plannerState: PlannerExecutionState,
+  ): Promise<void> {
+    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;
+    }
+  }
+
   private async routePatch(
     input: WorkerDecisionInput,
     output: AnyRecord,
     result: WorkerDecisionResult,
   ): Promise<void> {
-    if (input.role !== 'builder' && input.role !== 'qa') {
+    if (input.role !== 'builder' && input.role !== 'qa' && input.role !== 'reconciler') {
       return;
     }
 
@@ -602,11 +1329,13 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     input: WorkerDecisionInput,
     output: AnyRecord,
     result: WorkerDecisionResult,
-  ): Promise<void> {
+    plannerState: PlannerExecutionState,
+    allowContextRefreshRetry: boolean,
+  ): Promise<RequestRoutingResult> {
     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') {
@@ -615,13 +1344,13 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
         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,
@@ -629,13 +1358,13 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       });
       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,
@@ -643,36 +1372,108 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       });
       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, {
@@ -681,8 +1482,122 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
         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 };
+  }
+
+  private async requestIntakeClarificationForPlanMutation(
+    input: WorkerDecisionInput,
+    result: WorkerDecisionResult,
+    recoveryReason: string,
+  ): Promise<boolean> {
+    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;
+  }
+
+  private refreshPlannerStateFromContext(
+    plannerState: PlannerExecutionState,
+    context: unknown,
+  ): void {
+    const refreshedPlanVersion = readPlanVersion(asRecord(asRecord(context).plan).plan_version);
+    if (refreshedPlanVersion != null) {
+      plannerState.currentPlanVersion = refreshedPlanVersion;
+    }
+  }
+
+  private recordPlannerMutation(
+    plannerState: PlannerExecutionState,
+    responseData: unknown,
+    planJson: AnyRecord,
+  ): void {
+    plannerState.planMutationApplied = true;
+    const acceptedPlanVersion =
+      readPlanVersion(asRecord(responseData).plan_version) ??
+      readPlanVersion(planJson.plan_version);
+    if (acceptedPlanVersion != null) {
+      plannerState.currentPlanVersion = acceptedPlanVersion;
     }
   }
 
@@ -709,6 +1624,11 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     noteCount: number;
     valid: boolean;
     errorCode: string | null;
+    interactiveOutcome?: WorkerDecisionResult['interactiveOutcome'];
+    checkpointId?: string | null;
+    checkpointDiffHash?: string | null;
+    checkpointNetNewWorktreeChange?: boolean | null;
+    checkpointValidationStatus?: string | null;
     watchdogReason?: string | null;
     timeoutMs?: number;
     idleTimeoutMs?: number;
@@ -717,6 +1637,9 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
     elapsedMs?: number;
     signal?: string | null;
     exitCode?: number;
+    stderr?: string;
+    runtimeSelection: ProviderSelection;
+    usage?: NormalizedUsageRecord | null;
   }): Promise<void> {
     if (!this.repoRoot) {
       return;
@@ -738,8 +1661,22 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       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,
@@ -748,6 +1685,7 @@ export class WorkerDecisionLoop implements WorkerDecisionRunner {
       elapsed_ms: event.elapsedMs,
       signal: event.signal ?? null,
       exit_code: event.exitCode,
+      stderr: event.stderr,
     };
 
     await appendWorkerRuntimeEvent({