@navels/neal 0.1.0

package/dist/neal/orchestrator/phases/planning.js

@@ -0,0 +1,540 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { CoderRoundError, ReviewerRoundError, runCoderPlanRound } from '../../agents.js';
+import { findCanonicalId, getNextCanonicalIndex, getOpenBlockingCanonicalSet, getReopenedCanonical, hasRepeatedUnresolvedBlockingCanonicals, isOpenBlockingFinding, isOpenNonBlockingFinding, mapDecisionToStatus, } from '../../adjudicator/execute.js';
+import { isDerivedPlanReviewState, plannerProviderStartsFreshSessions, resolvePlanningAdjudicationContext, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, } from '../../adjudicator/planning.js';
+import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
+import { getReviewStuckWindow } from '../../config.js';
+import { writeDiagnostic } from '../../diagnostic.js';
+import { getWorktreeStatus } from '../../git.js';
+import { formatPlanRefinementRoundLine, isPlanRefinementState } from '../../plan-refinement.js';
+import { validatePlanDocument } from '../../plan-validation.js';
+import { getCurrentScopeLabel, getExecutionPlanPath } from '../../scopes.js';
+import { saveState } from '../../state.js';
+import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, } from '../../worktree-status.js';
+import { writeExecutionArtifacts } from '../artifacts.js';
+import { isCoderTimeoutError, shouldNotifyFailure } from '../failures.js';
+import { flushDerivedPlanNotifications, notifyBlocked, notifyComplete, } from '../notifications.js';
+import { adoptAcceptedDerivedPlan, shouldNotifyDerivedPlanAcceptance, transitionPlanReviewWithoutOpenFindings, } from '../transitions.js';
+import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry } from './recovery.js';
+import { bestEffortCleanupTimedOutCoder, persistCoderFailureState, persistUnattendedBlockUnresolvedFailure, printReviewResult, scheduleCoderFreshSessionRetry, shouldRetryCoderWithFreshSession, } from './shared.js';
+function getNormalizedPlanArtifactPath(state, planPath) {
+    const parsed = parse(planPath);
+    const extension = parsed.ext || '.md';
+    return join(state.runDir, `${parsed.name}.normalized${extension}`);
+}
+export async function preparePlanReviewArtifact(args) {
+    const planDocument = await readFile(args.planPath, 'utf8');
+    const validation = validatePlanDocument(planDocument);
+    let reviewedPlanPath = args.planPath;
+    if (validation.normalization.applied && args.normalizedPlanPath) {
+        await mkdir(dirname(args.normalizedPlanPath), { recursive: true });
+        await writeFile(args.normalizedPlanPath, validation.normalization.normalizedDocument, 'utf8');
+        reviewedPlanPath = args.normalizedPlanPath;
+    }
+    return {
+        executionShape: validation.executionShape,
+        reviewedPlanPath,
+        originalPlanPath: args.planPath,
+        validation,
+    };
+}
+export async function synthesizePlanReviewFindings(args) {
+    const preparedReview = args.preparedReview ?? (await preparePlanReviewArtifact({ planPath: args.planPath }));
+    const { validation } = preparedReview;
+    if (validation.ok) {
+        return {
+            executionShape: validation.executionShape,
+            reviewedPlanPath: preparedReview.reviewedPlanPath,
+            findings: args.findings,
+        };
+    }
+    return {
+        executionShape: validation.executionShape,
+        reviewedPlanPath: preparedReview.reviewedPlanPath,
+        findings: [
+            ...args.findings,
+            ...validation.errors.map((error) => ({
+                round: args.round,
+                source: 'plan_structure',
+                severity: 'blocking',
+                files: [preparedReview.originalPlanPath],
+                claim: `Plan document structure is invalid: ${error}`,
+                requiredAction: 'Revise the plan document so it satisfies the required execution-shape and execution-queue contract.',
+                roundSummary: args.roundSummary,
+            })),
+        ],
+    };
+}
+function getPlanningCompletionProblem(marker) {
+    if (marker === 'AUTONOMY_BLOCKED') {
+        return null;
+    }
+    return marker === 'AUTONOMY_DONE' ? null : 'Planning mode must end with AUTONOMY_DONE or AUTONOMY_BLOCKED.';
+}
+function getDerivedPlanBlockedReason(state, reason) {
+    if (!isDerivedPlanReviewState(state)) {
+        return reason;
+    }
+    return `split-plan recovery failed to converge: ${reason}`;
+}
+async function getPlanPhaseDirtyWorktreeBlocker(state, phase) {
+    const allowedDirtyPaths = [...new Set([...state.allowedDirtyPaths, state.planDoc])];
+    let statusOutput;
+    try {
+        statusOutput = await getWorktreeStatus(state.cwd, { untrackedFiles: 'all' });
+    }
+    catch (error) {
+        if (error instanceof Error && /not a git repository/.test(error.message)) {
+            return null;
+        }
+        throw error;
+    }
+    const dirtyStatus = filterAllowedDirtyPathStatus(state.cwd, filterWrapperOwnedWorktreeStatus(statusOutput), allowedDirtyPaths);
+    if (dirtyStatus.trim() === '') {
+        return null;
+    }
+    return [
+        `Planner dirtied non-plan files during ${phase}.`,
+        'Plan phases may only update the plan artifact; implementation changes must happen during execution.',
+        '',
+        'Dirty files:',
+        dirtyStatus,
+    ].join('\n');
+}
+async function finalizePlanReviewResponseWithoutOpenFindings(state, statePath, phase, logger) {
+    const { spec, reviewMode } = resolvePlanningAdjudicationContext(state);
+    const signal = reviewMode === 'derived-plan' ? 'accept_derived_plan' : 'accept_plan';
+    assertAdjudicationTransitionSignal(spec, signal, `orchestrator:${phase}:settled`);
+    let nextState = await saveState(statePath, {
+        ...transitionPlanReviewWithoutOpenFindings(state, reviewMode),
+        pendingPlanReviewGuidance: null,
+    });
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase,
+        openFindings: 0,
+        nextPhase: nextState.phase,
+    });
+    nextState = await flushDerivedPlanNotifications(nextState, statePath, logger);
+    if (nextState.status === 'done') {
+        await notifyComplete(nextState, 'Plan review converged', logger);
+    }
+    return nextState;
+}
+export async function finalizeBlockedPlanReviewResponse(state, statePath, derivedPlanReview, blocker, logger) {
+    const { spec } = resolvePlanningAdjudicationContext(state);
+    assertAdjudicationTransitionSignal(spec, 'block_for_operator', 'orchestrator:planning:block_for_operator');
+    if (state.topLevelMode !== 'execute') {
+        // Site C: the top-level plan-review gate (`neal run`/`neal plan` plan stage).
+        // Attended runs leave `status:'blocked'` to be resumed via
+        // `pendingPlanReviewGuidance`; unattended runs have no operator to answer, so
+        // run the shared terminal-fail action instead of notifying + leaving the run
+        // blocked. The review-round/convergence cap already bounded the autonomous
+        // push, so there is no auto-resume here. Any plan artifact is preserved
+        // unsubmitted by the shared action, exactly as today's failed runs leave it.
+        // Gate structurally on the persisted flag, never on guidance text.
+        if (state.unattended) {
+            return persistUnattendedBlockUnresolvedFailure(state, statePath, 'reviewer_plan', logger);
+        }
+        if (!derivedPlanReview) {
+            await notifyBlocked(state, blocker, logger);
+        }
+        return flushDerivedPlanNotifications(state, statePath, logger, blocker);
+    }
+    const persistedState = await enterInteractiveBlockedRecovery(state, statePath, blocker, logger);
+    if (!derivedPlanReview && shouldNotifyInteractiveBlockedRecoveryEntry(persistedState)) {
+        await notifyBlocked(persistedState, blocker, logger);
+    }
+    return flushDerivedPlanNotifications(persistedState, statePath, logger, blocker);
+}
+export function getPlanningResponseRetryPhase(mode) {
+    return mode === 'optional' ? 'coder_plan_optional_response' : 'coder_plan_response';
+}
+export async function runCoderPlanPhase(state, statePath, logger) {
+    await logger?.event('phase.start', { phase: 'coder_plan' });
+    if (isPlanRefinementState(state)) {
+        writeDiagnostic(`${formatPlanRefinementRoundLine({ round: state.rounds.length + 1, maxRounds: state.maxRounds })}\n`, logger);
+    }
+    let workingState = state;
+    let codex;
+    if (state.plannerSessionHandle && state.plannerSessionProtocol === null) {
+        throw new Error('Cannot resume planner planning phase without plannerSessionProtocol.');
+    }
+    const activePlannerSessionProtocol = state.plannerSessionHandle
+        ? state.plannerSessionProtocol
+        : 'structured_json_v1';
+    try {
+        codex = await runCoderPlanRound({
+            coder: state.agentConfig.planner,
+            cwd: state.cwd,
+            planDoc: state.planDoc,
+            sessionHandle: state.plannerSessionHandle,
+            coderSessionProtocol: state.plannerSessionProtocol,
+            unattended: state.unattended,
+            // Reinforce an author-declared `one_shot` only for the top-level authored plan; the
+            // coder_plan phase only runs for top-level `neal plan` refinement (derived-plan
+            // revisions run through coder_plan_response).
+            authoredOneShot: !isDerivedPlanReviewState(state) && state.authoredExecutionShape === 'one_shot',
+            onSessionStarted: async (sessionHandle) => {
+                state.plannerSessionHandle = sessionHandle;
+                state.plannerSessionProtocol = activePlannerSessionProtocol;
+                workingState = await saveState(statePath, {
+                    ...workingState,
+                    plannerSessionHandle: sessionHandle,
+                    plannerSessionProtocol: activePlannerSessionProtocol,
+                });
+            },
+            logger,
+        });
+    }
+    catch (error) {
+        if (error instanceof CoderRoundError) {
+            if (shouldRetryCoderWithFreshSession(workingState, 'coder_plan', error)) {
+                return scheduleCoderFreshSessionRetry(workingState, statePath, 'coder_plan', error, logger);
+            }
+            if (isCoderTimeoutError(error)) {
+                await bestEffortCleanupTimedOutCoder(error.sessionHandle ?? workingState.plannerSessionHandle, logger);
+            }
+            const failedState = await persistCoderFailureState(workingState, statePath, 'coder_plan', error, logger);
+            if (shouldNotifyFailure(error)) {
+                await notifyBlocked(failedState, error.message, logger);
+            }
+        }
+        throw error;
+    }
+    const completionProblem = getPlanningCompletionProblem(codex.marker);
+    const dirtyWorktreeBlocker = await getPlanPhaseDirtyWorktreeBlocker(workingState, 'coder_plan');
+    const nextState = await saveState(statePath, {
+        ...workingState,
+        plannerSessionHandle: codex.sessionHandle,
+        plannerSessionProtocol: codex.sessionHandle ? activePlannerSessionProtocol : null,
+        lastScopeMarker: codex.marker,
+        phase: codex.marker === 'AUTONOMY_BLOCKED' || completionProblem || dirtyWorktreeBlocker ? 'blocked' : 'reviewer_plan',
+        status: codex.marker === 'AUTONOMY_BLOCKED' || completionProblem || dirtyWorktreeBlocker ? 'blocked' : 'running',
+        blockedFromPhase: codex.marker === 'AUTONOMY_BLOCKED' || completionProblem || dirtyWorktreeBlocker ? 'coder_plan' : null,
+    });
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: 'coder_plan',
+        marker: codex.marker,
+        sessionHandle: codex.sessionHandle,
+        nextPhase: nextState.phase,
+    });
+    if (nextState.status === 'blocked') {
+        const reason = dirtyWorktreeBlocker ?? completionProblem ?? 'The coder reported a blocker during plan revision';
+        if (nextState.topLevelMode !== 'execute') {
+            await notifyBlocked(nextState, reason, logger);
+            return nextState;
+        }
+        const persistedState = await enterInteractiveBlockedRecovery(nextState, statePath, reason, logger);
+        if (shouldNotifyInteractiveBlockedRecoveryEntry(persistedState)) {
+            await notifyBlocked(persistedState, reason, logger);
+        }
+        return persistedState;
+    }
+    return nextState;
+}
+export async function runPlanReviewPhase(state, statePath, logger) {
+    await logger?.event('phase.start', { phase: 'reviewer_plan', round: state.rounds.length + 1 });
+    const round = state.rounds.length + 1;
+    const normalizedPlanPath = getNormalizedPlanArtifactPath(state, resolvePlanningAdjudicationContext(state).reviewTargetPath);
+    let claude;
+    let context;
+    let preparedReview;
+    let synthesizedReview;
+    try {
+        ({
+            context,
+            preparedReview,
+            reviewerResult: claude,
+            synthesizedReview,
+        } = await runPlanningReviewerAdjudication({
+            state,
+            round,
+            reviewMarkdownPath: state.reviewMarkdownPath,
+            normalizedPlanPath,
+            logger,
+            preparePlanReviewArtifact,
+            synthesizePlanReviewFindings,
+        }));
+    }
+    catch (error) {
+        if (error instanceof ReviewerRoundError) {
+            const failedState = await saveState(statePath, {
+                ...state,
+                reviewerSessionHandle: null,
+                status: 'failed',
+            });
+            await writeExecutionArtifacts(failedState);
+            await logger?.event('phase.error', {
+                phase: 'reviewer_plan',
+                round,
+                sessionHandle: error.sessionHandle,
+                subtype: error.subtype,
+                message: error.message,
+            });
+            if (shouldNotifyFailure(error)) {
+                await notifyBlocked(failedState, error.message, logger);
+            }
+        }
+        throw error;
+    }
+    const { derivedPlanReview, roundLimit } = context;
+    // Plan refinement adopts the refined execution shape directly. An earlier hard clamp —
+    // forcing an author-declared `one_shot` plan back to `one_shot` and injecting a blocking
+    // shape-restoration finding when refinement expanded it — caused plan-review
+    // non-convergence on complex plans: the planner could not produce an accurate
+    // single-scope plan, so the reviewer kept (correctly) rejecting until the round cap
+    // failed the run. The over-decomposition concern the clamp targeted is better handled
+    // as a soft planner-prompt bias than a hard shape clamp.
+    const normalizedFindingInputs = synthesizedReview.findings;
+    printReviewResult('plan-review', claude.summary, normalizedFindingInputs, logger);
+    let nextCanonicalIndex = getNextCanonicalIndex(state.findings);
+    const findings = normalizedFindingInputs.map((finding, index) => {
+        const canonicalId = findCanonicalId(state.findings, finding) ?? `C${nextCanonicalIndex++}`;
+        return {
+            ...finding,
+            id: `R${round}-F${index + 1}`,
+            canonicalId,
+            status: 'open',
+            coderDisposition: null,
+            coderCommit: null,
+        };
+    });
+    const mergedFindings = [...state.findings, ...findings];
+    const hasBlockingFindings = findings.some((finding) => finding.severity === 'blocking');
+    const hasOpenNonBlockingFindings = mergedFindings.some(isOpenNonBlockingFinding);
+    const reachedMaxRounds = round >= roundLimit;
+    const openBlockingCanonicalSet = getOpenBlockingCanonicalSet(mergedFindings);
+    const openBlockingCanonicalIds = [...openBlockingCanonicalSet].sort();
+    const openBlockingCanonicalCount = openBlockingCanonicalSet.size;
+    const stalledBlockingCount = hasRepeatedUnresolvedBlockingCanonicals({
+        rounds: state.rounds,
+        currentOpenBlockingCanonicals: openBlockingCanonicalSet,
+        cwd: state.cwd,
+    });
+    const reopenedCanonical = getReopenedCanonical(mergedFindings);
+    const shouldBlockForConvergence = Boolean(reopenedCanonical || stalledBlockingCount);
+    const blockReason = reopenedCanonical
+        ? getDerivedPlanBlockedReason(state, `review_stuck: blocking finding ${reopenedCanonical} reopened across multiple reviewer rounds`)
+        : stalledBlockingCount
+            ? getDerivedPlanBlockedReason(state, `review_stuck: blocking findings did not decrease across ${getReviewStuckWindow(state.cwd)} consecutive reviewer rounds`)
+            : reachedMaxRounds && hasBlockingFindings
+                ? getDerivedPlanBlockedReason(state, `reached max review rounds (${roundLimit}) with blocking findings still open`)
+                : null;
+    const planningSignal = shouldBlockForConvergence || (hasBlockingFindings && reachedMaxRounds)
+        ? 'block_for_operator'
+        : hasBlockingFindings
+            ? 'request_revision'
+            : hasOpenNonBlockingFindings
+                ? 'optional_revision'
+                : derivedPlanReview
+                    ? 'accept_derived_plan'
+                    : 'accept_plan';
+    assertAdjudicationTransitionSignal(context.spec, planningSignal, 'orchestrator:reviewer_plan');
+    const nextState = await saveState(statePath, {
+        ...state,
+        reviewerSessionHandle: claude.sessionHandle,
+        executionShape: synthesizedReview.executionShape,
+        phase: shouldBlockForConvergence
+            ? 'blocked'
+            : hasBlockingFindings
+                ? reachedMaxRounds
+                    ? 'blocked'
+                    : 'coder_plan_response'
+                : hasOpenNonBlockingFindings
+                    ? 'coder_plan_optional_response'
+                    : derivedPlanReview
+                        ? 'awaiting_derived_plan_execution'
+                        : 'done',
+        status: shouldBlockForConvergence
+            ? 'blocked'
+            : hasBlockingFindings
+                ? reachedMaxRounds
+                    ? 'blocked'
+                    : 'running'
+                : hasOpenNonBlockingFindings
+                    ? 'running'
+                    : derivedPlanReview
+                        ? 'running'
+                        : 'done',
+        rounds: [
+            ...state.rounds,
+            {
+                round,
+                reviewerSessionHandle: claude.sessionHandle,
+                reviewedPlanPath: synthesizedReview.reviewedPlanPath,
+                normalizationApplied: preparedReview.validation.normalization.applied,
+                normalizationOperations: preparedReview.validation.normalization.operations,
+                normalizationScopeLabelMappings: preparedReview.validation.normalization.scopeLabelMappings,
+                commitRange: {
+                    base: state.baseCommit ?? '',
+                    head: state.finalCommit ?? state.baseCommit ?? '',
+                },
+                openBlockingCanonicalCount,
+                openBlockingCanonicalIds,
+                findings: findings.map((finding) => finding.id),
+            },
+        ],
+        findings: mergedFindings,
+        derivedPlanStatus: derivedPlanReview && !shouldBlockForConvergence && !hasBlockingFindings && !hasOpenNonBlockingFindings
+            ? 'accepted'
+            : state.derivedPlanStatus,
+        blockedFromPhase: shouldBlockForConvergence || (hasBlockingFindings && reachedMaxRounds)
+            ? 'reviewer_plan'
+            : null,
+    });
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: 'reviewer_plan',
+        round,
+        sessionHandle: claude.sessionHandle,
+        findings: findings.length,
+        blockingFindings: findings.filter((finding) => finding.severity === 'blocking').length,
+        nextPhase: nextState.phase,
+    });
+    if (nextState.status === 'blocked' && blockReason) {
+        return finalizeBlockedPlanReviewResponse(nextState, statePath, derivedPlanReview, blockReason, logger);
+    }
+    if (shouldNotifyDerivedPlanAcceptance(state, nextState)) {
+        return flushDerivedPlanNotifications(nextState, statePath, logger);
+    }
+    if (nextState.status === 'done') {
+        await notifyComplete(nextState, 'Plan review converged', logger);
+    }
+    return nextState;
+}
+export async function runPlanningResponsePhase(state, statePath, phase, logger) {
+    const planningContext = resolvePlanningAdjudicationContext(state);
+    const { spec, derivedPlanReview } = planningContext;
+    // Top-level `neal plan` refinement (reviewMode === 'plan', i.e. !derivedPlanReview) is normally
+    // authored by a persisted planner session, so a missing handle stays a hard error for
+    // resume-capable planner providers. Derived-plan revisions are authored by the coder and create
+    // no planner session, and no-resume planner providers (`supportsSessionResume: false`, e.g.
+    // generic-agentic and openai-compatible) never persist a planner handle at all — both start a
+    // fresh planner session instead.
+    if (!derivedPlanReview &&
+        !state.plannerSessionHandle &&
+        !plannerProviderStartsFreshSessions(state.agentConfig.planner)) {
+        throw new Error(`Cannot run ${phase} phase without an existing planner session`);
+    }
+    // Mirror the coder.ts:150-152 pattern: keep the existing protocol for a resumed planner
+    // session, otherwise mint 'structured_json_v1' for a freshly created derived-plan session so a
+    // non-null sessionHandle is never persisted with a null plannerSessionProtocol.
+    const activePlannerSessionProtocol = state.plannerSessionHandle ? state.plannerSessionProtocol : 'structured_json_v1';
+    const mode = phase === 'coder_plan_optional_response' ? 'optional' : 'required';
+    await logger?.event('phase.start', { phase });
+    if (isPlanRefinementState(state)) {
+        writeDiagnostic(`${formatPlanRefinementRoundLine({ round: state.rounds.length + 1, maxRounds: state.maxRounds })}\n`, logger);
+    }
+    const openFindings = state.findings.filter(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding);
+    if (openFindings.length === 0) {
+        return finalizePlanReviewResponseWithoutOpenFindings(state, statePath, phase, logger);
+    }
+    let codex;
+    try {
+        ({ response: codex } = await runPlanningResponseAdjudication({
+            state,
+            mode: mode === 'optional' ? 'optional' : undefined,
+            openFindings: openFindings.map((finding) => ({
+                id: finding.id,
+                source: finding.source,
+                claim: finding.claim,
+                requiredAction: finding.requiredAction,
+                severity: finding.severity,
+                files: finding.files,
+                roundSummary: finding.roundSummary,
+            })),
+            logger,
+        }));
+    }
+    catch (error) {
+        if (error instanceof CoderRoundError) {
+            const retryPhase = getPlanningResponseRetryPhase(mode);
+            if (shouldRetryCoderWithFreshSession(state, retryPhase, error)) {
+                return scheduleCoderFreshSessionRetry(state, statePath, retryPhase, error, logger);
+            }
+            if (isCoderTimeoutError(error)) {
+                await bestEffortCleanupTimedOutCoder(error.sessionHandle ?? state.plannerSessionHandle, logger);
+            }
+            const failedState = await persistCoderFailureState(state, statePath, retryPhase, error, logger);
+            if (shouldNotifyFailure(error)) {
+                await notifyBlocked(failedState, error.message, logger);
+            }
+        }
+        throw error;
+    }
+    const responseById = new Map(codex.payload.responses.map((response) => [response.id, response]));
+    assertAdjudicationTransitionSignal(spec, codex.payload.outcome === 'blocked' ? 'block_for_operator' : mode === 'optional' ? 'optional_revision' : 'request_revision', `orchestrator:${phase}`);
+    const dirtyWorktreeBlocker = await getPlanPhaseDirtyWorktreeBlocker(state, phase);
+    const findings = state.findings.map((finding) => {
+        const response = responseById.get(finding.id);
+        if (!response) {
+            return finding;
+        }
+        return {
+            ...finding,
+            status: mapDecisionToStatus(response.decision),
+            coderDisposition: response.summary,
+            coderCommit: null,
+        };
+    });
+    const nextState = await saveState(statePath, {
+        ...state,
+        plannerSessionHandle: codex.sessionHandle,
+        plannerSessionProtocol: codex.sessionHandle ? activePlannerSessionProtocol : null,
+        findings,
+        phase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
+            ? 'blocked'
+            : mode === 'optional'
+                ? derivedPlanReview
+                    ? 'awaiting_derived_plan_execution'
+                    : 'done'
+                : 'reviewer_plan',
+        status: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
+            ? 'blocked'
+            : mode === 'optional' && !derivedPlanReview
+                ? 'done'
+                : 'running',
+        derivedPlanStatus: mode === 'optional' && codex.payload.outcome !== 'blocked' && derivedPlanReview
+            ? 'accepted'
+            : state.derivedPlanStatus,
+        blockedFromPhase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked' ? phase : null,
+        pendingPlanReviewGuidance: null,
+    });
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase,
+        outcome: codex.payload.outcome,
+        respondedFindings: codex.payload.responses.length,
+        nextPhase: nextState.phase,
+    });
+    if (nextState.status === 'blocked') {
+        const blocker = getDerivedPlanBlockedReason(state, dirtyWorktreeBlocker ||
+            codex.payload.blocker?.trim() ||
+            codex.payload.summary.trim() ||
+            (mode === 'optional'
+                ? 'The coder reported a blocker while considering non-blocking plan findings'
+                : 'The coder reported a blocker during plan response'));
+        return finalizeBlockedPlanReviewResponse(nextState, statePath, derivedPlanReview, blocker, logger);
+    }
+    if (mode === 'optional' && shouldNotifyDerivedPlanAcceptance(state, nextState)) {
+        return flushDerivedPlanNotifications(nextState, statePath, logger);
+    }
+    if (mode === 'optional' && nextState.status === 'done') {
+        await notifyComplete(nextState, 'Plan review converged', logger);
+    }
+    return nextState;
+}
+export async function runAwaitingDerivedPlanExecutionPhase(state, statePath, logger) {
+    const nextState = await saveState(statePath, adoptAcceptedDerivedPlan(state));
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: 'awaiting_derived_plan_execution',
+        nextPhase: nextState.phase,
+        scopeNumber: getCurrentScopeLabel(nextState),
+        planDoc: getExecutionPlanPath(nextState),
+    });
+    return nextState;
+}