@navels/neal 0.1.0

package/dist/neal/orchestrator/completion.js

@@ -0,0 +1,531 @@
+import { join } from 'node:path';
+import { CoderRoundError, FinalCompletionReviewerVerdictError, ReviewerRoundError } from '../agents.js';
+import { writeTextAtomic } from '../atomic-write.js';
+import { runFinalCompletionReviewerAdjudication, runFinalCompletionSummaryAdjudication, } from '../adjudicator/final-completion.js';
+import { assertAdjudicationTransitionSignal } from '../adjudicator/specs.js';
+import { stripScopePrefixFromCommitMessage } from '../commit-message.js';
+import { getFinalCompletionContinueExecutionMax } from '../config.js';
+import { writeDetail } from '../diagnostic.js';
+import { buildFinalCompletionPacket } from '../final-completion.js';
+import { getFinalCompletionReviewArtifactPath, readFinalCompletionUnstructuredOutput, writeFinalCompletionReviewMarkdown, } from '../final-completion-review.js';
+import { EXECUTE_FINALIZATION_PHASE } from '../execute-finalization.js';
+import { getChangedFilesForRange, getCommitRange, getCommitMessage, getCommitSubjects, getHeadCommit, getStagedChangedFiles, getWorktreeStatus, assertNoIgnoredChangedFiles, cleanUntracked, resetHard, squashCommits as createScopeFinalizationCommit, stagePath, } from '../git.js';
+import { notifyBlocked, notifyComplete, notifyScopeAccepted } from './notifications.js';
+import { inspectPlanDocDisposition } from '../plan-doc.js';
+import { appendDerivedSubScopeAndParentCompletion, appendParentCompletionFromAcceptedDerivedScopes, computeNextScopeStateAfterExecuteFinalization, computeNextScopeStateAfterParentAdvance, } from './transitions.js';
+import { writePlanProgressArtifacts } from '../progress.js';
+import { writeCheckpointRetrospective } from '../retrospective.js';
+import { renderReviewMarkdown, writeReviewMarkdown } from '../review.js';
+import { getCurrentScopeLabel, getParentScopeLabel, shouldAdvanceTopLevelScopeNumber } from '../scopes.js';
+import { saveState } from '../state.js';
+import { getFinalCompletionReviewerScratchDir, getScopeReviewerScratchDir } from '../storage-paths.js';
+import { requireFinalCompletionView, resolveFinalCompletionReviewAction, } from '../state-views.js';
+import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, formatDirtyWorktreeDiagnostic, } from '../worktree-status.js';
+import { shouldNotifyFailure } from './failures.js';
+import { persistUnattendedBlockUnresolvedFailure } from './phases/shared.js';
+async function writeFailedFinalCompletionReviewArtifact(args) {
+    const unstructuredOutput = await readFinalCompletionUnstructuredOutput({
+        runDir: args.state.runDir,
+        source: args.source,
+        sessionHandle: args.sessionHandle,
+    });
+    await writeFinalCompletionReviewMarkdown(getFinalCompletionReviewArtifactPath(args.state.runDir), args.state, { unstructuredOutput });
+}
+async function persistFailedFinalCompletionReview(args) {
+    const failedState = await saveState(args.statePath, {
+        ...args.state,
+        phase: 'final_completion_review',
+        reviewerSessionHandle: null,
+        status: 'failed',
+    });
+    await args.runtime.writeExecutionArtifacts(failedState);
+    await writeFailedFinalCompletionReviewArtifact({
+        state: failedState,
+        source: 'reviewer_verdict',
+        sessionHandle: args.error.sessionHandle,
+    });
+    await args.logger?.event('phase.error', {
+        phase: 'final_completion_review',
+        sessionHandle: args.error.sessionHandle,
+        subtype: args.error.subtype,
+        message: args.error.message,
+    });
+    return failedState;
+}
+function normalizeFinalCommitMessage(message) {
+    const normalizedNewlines = message.replace(/\r\n/g, '\n');
+    const convertedEscapes = normalizedNewlines.replace(/\\n(?=- )/g, '\n');
+    return convertedEscapes.replace(/\n+$/, '') + '\n';
+}
+function printFinalCompletionReviewResult(args, logger) {
+    const message = [
+        `[reviewer:final-completion] action: ${args.action}`,
+        `[reviewer:final-completion] summary: ${args.summary}`,
+        `[reviewer:final-completion] rationale: ${args.rationale}`,
+    ].join('\n');
+    writeDetail(`${message}\n`, logger, {
+        phase: 'final_completion_review',
+        role: 'reviewer',
+    });
+}
+function getTerminalCompletedScope(state) {
+    const currentScopeLabel = getCurrentScopeLabel(state);
+    return state.completedScopes.find((scope) => scope.number === currentScopeLabel) ?? null;
+}
+function formatCommitList(commits) {
+    return commits.length > 0 ? commits.join(', ') : '(none)';
+}
+function haveSameCommitSequence(left, right) {
+    return left.length === right.length && left.every((commit, index) => commit === right[index]);
+}
+function unionChangedFiles(...groups) {
+    return [...new Set(groups.flat())];
+}
+function getFinalizationExpectedScratchDirs(state) {
+    const scratchDirs = [];
+    const lastReviewRound = state.rounds.at(-1)?.round ?? null;
+    if (lastReviewRound !== null) {
+        scratchDirs.push(getScopeReviewerScratchDir(state.runDir, getParentScopeLabel(state), lastReviewRound));
+    }
+    if (state.lastScopeMarker === 'AUTONOMY_DONE' || state.finalCompletionSummary) {
+        scratchDirs.push(getFinalCompletionReviewerScratchDir(state.runDir));
+    }
+    return scratchDirs;
+}
+function getFinalCompletionReviewBlockReason(args) {
+    if (args.effectiveAction === 'continue_execution') {
+        return `final_completion_review: reviewer reopened execution. ${args.rationale}`;
+    }
+    if (args.reviewerAction === 'continue_execution' && args.capReached) {
+        return ('final_completion_review: reviewer requested more execution, ' +
+            `but the continue_execution cap (${args.continueExecutionLimit}) is already exhausted ` +
+            `after ${args.continueExecutionCount} reopen cycle(s). ${args.rationale} ` +
+            'One available next step is to inspect with `neal status` and provide guidance with `neal resume --message "..."` only if the run is waiting for operator guidance.');
+    }
+    return `final_completion_review: reviewer blocked completion for operator guidance. ${args.rationale} One available next step is to inspect with \`neal status\` and provide guidance with \`neal resume --message "..."\` only if the run is waiting for operator guidance.`;
+}
+async function discardFinalCompletionReviewerWorktreeChanges(args) {
+    const statusOutput = filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(args.state.cwd, { untrackedFiles: 'all' }));
+    if (!statusOutput.trim()) {
+        return;
+    }
+    const headCommit = await getHeadCommit(args.state.cwd);
+    await args.logger?.event('final_completion_review.discarded_dirty_worktree', {
+        headCommit,
+        statusOutput,
+        message: 'Final completion review is read-only; discarding reviewer-created worktree changes before state transition.',
+    });
+    await resetHard(args.state.cwd, headCommit);
+    await cleanUntracked(args.state.cwd, ['.neal/', '.forge/', 'CURRENT_PLAN.md']);
+    const remainingStatusOutput = filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(args.state.cwd, { untrackedFiles: 'all' }));
+    if (remainingStatusOutput.trim()) {
+        throw new Error(`Final completion review left a dirty worktree Neal could not restore:\n${remainingStatusOutput}`);
+    }
+}
+async function runParentAdvanceFinalization(args) {
+    const { state, statePath, logger, runtime, headCommit, statusOutput } = args;
+    if (!state.baseCommit) {
+        throw new Error('Cannot advance parent without a baseCommit');
+    }
+    if (statusOutput) {
+        throw new Error(`Cannot advance parent with a dirty worktree because resetting an empty derived range would be destructive:\n${statusOutput}`);
+    }
+    const parentScopeLabel = getParentScopeLabel(state);
+    const currentScopeLabel = getCurrentScopeLabel(state);
+    const currentRangeCommits = await getCommitRange(state.cwd, state.baseCommit, headCommit);
+    const changedFilesSinceBase = await getChangedFilesForRange(state.cwd, state.baseCommit, headCommit);
+    if (changedFilesSinceBase.length > 0) {
+        throw new Error([
+            `Cannot advance parent scope ${parentScopeLabel} through empty derived scope ${currentScopeLabel}: current range has changed files.`,
+            ...changedFilesSinceBase.map((file) => `- ${file}`),
+        ].join('\n'));
+    }
+    await assertNoIgnoredChangedFiles(state.cwd, changedFilesSinceBase, 'Execute parent advancement');
+    if (headCommit !== state.baseCommit) {
+        if (!haveSameCommitSequence(currentRangeCommits, state.createdCommits)) {
+            throw new Error([
+                `Cannot advance parent scope ${parentScopeLabel} by dropping empty derived scope ${currentScopeLabel}: current range commits do not exactly match Neal-created commits.`,
+                `Range commits: ${formatCommitList(currentRangeCommits)}`,
+                `Neal-created commits: ${formatCommitList(state.createdCommits)}`,
+            ].join('\n'));
+        }
+        await resetHard(state.cwd, state.baseCommit);
+    }
+    const finalCommit = state.baseCommit;
+    const archivedReviewPath = join(state.runDir, `REVIEW-${finalCommit}.md`);
+    const completedScopes = appendParentCompletionFromAcceptedDerivedScopes({
+        state,
+        finalCommit,
+        archivedReviewPath,
+    });
+    const archivedReviewState = {
+        ...state,
+        finalCommit,
+        archivedReviewPath,
+        completedScopes,
+    };
+    const retrospectiveState = archivedReviewState;
+    const nextState = await saveState(statePath, computeNextScopeStateAfterParentAdvance({
+        state,
+        finalCommit,
+        completedScopes,
+    }));
+    const parentScope = completedScopes.find((scope) => scope.number === parentScopeLabel && scope.derivedFromParentScope === null);
+    const aggregateChangedFileCount = parentScope?.changedFiles.length ?? 0;
+    const parentAdvanceMessage = `advance_parent completed parent scope ${parentScopeLabel} via derived plan; dropped empty derived scope ${currentScopeLabel} without accepting it.`;
+    await logger?.event('execute_finalization.advance_parent', {
+        message: parentAdvanceMessage,
+        parentScopeLabel,
+        currentScopeLabel,
+        priorDerivedCount: state.completedScopes.filter((scope) => scope.result === 'accepted' && scope.derivedFromParentScope === parentScopeLabel).length,
+        aggregateChangedFileCount,
+        droppedCommitCount: currentRangeCommits.length,
+        finalParentCommit: finalCommit,
+    });
+    await writeTextAtomic(archivedReviewPath, renderReviewMarkdown({ ...archivedReviewState, finalCompletionSummary: null, finalCompletionReviewVerdict: null }));
+    await writeCheckpointRetrospective(retrospectiveState, 'scope_accepted');
+    await runtime.writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: EXECUTE_FINALIZATION_PHASE,
+        finalCommit,
+        archivedReviewPath,
+        continueScopes: true,
+        meaningfulProgressAction: 'advance_parent',
+        message: parentAdvanceMessage,
+    });
+    await notifyScopeAccepted({
+        ...state,
+        currentScopeNumber: state.derivedFromScopeNumber ?? state.currentScopeNumber,
+        derivedPlanPath: null,
+        derivedFromScopeNumber: null,
+        derivedPlanStatus: null,
+        derivedScopeIndex: null,
+    }, parentScope?.commitSubject ?? `Parent scope ${parentScopeLabel} complete via derived plan`, logger);
+    return nextState;
+}
+export async function runExecuteFinalizationPhase(state, statePath, logger, runtime) {
+    if (!state.baseCommit) {
+        throw new Error('Cannot finalize without a baseCommit');
+    }
+    await logger?.event('phase.start', { phase: EXECUTE_FINALIZATION_PHASE });
+    const headCommit = await getHeadCommit(state.cwd);
+    const statusOutput = filterAllowedDirtyPathStatus(state.cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(state.cwd)), state.allowedDirtyPaths);
+    if (statusOutput) {
+        const diagnostic = formatDirtyWorktreeDiagnostic({
+            statusOutput,
+            expectedScratchDirs: getFinalizationExpectedScratchDirs(state),
+        });
+        throw new Error([`Cannot finalize with a dirty worktree:\n${statusOutput}`, diagnostic].filter(Boolean).join('\n\n'));
+    }
+    if (state.currentScopeMeaningfulProgressVerdict?.action === 'advance_parent') {
+        return runParentAdvanceFinalization({
+            state,
+            statePath,
+            logger,
+            runtime,
+            headCommit,
+            statusOutput,
+        });
+    }
+    const commitSubjects = await getCommitSubjects(state.cwd, state.createdCommits);
+    const latestCreatedCommit = state.createdCommits.at(-1) ?? null;
+    const rawFinalMessage = latestCreatedCommit
+        ? await getCommitMessage(state.cwd, latestCreatedCommit)
+        : commitSubjects.at(-1)?.replace(/^[a-f0-9]+\s+/, '') || 'Finalize scope work';
+    const strippedFinalMessage = stripScopePrefixFromCommitMessage(rawFinalMessage);
+    const finalMessage = normalizeFinalCommitMessage(strippedFinalMessage.trim() ? strippedFinalMessage : 'Finalize scope work');
+    const planDocInspection = await inspectPlanDocDisposition(state.cwd, state.planDoc);
+    if (planDocInspection.eligibleForCommit && planDocInspection.repoRelativePath) {
+        await stagePath(state.cwd, planDocInspection.repoRelativePath);
+    }
+    const changedFilesSinceBase = await getChangedFilesForRange(state.cwd, state.baseCommit, headCommit);
+    const stagedChangedFiles = await getStagedChangedFiles(state.cwd);
+    const finalizationChangedFiles = unionChangedFiles(changedFilesSinceBase, stagedChangedFiles);
+    await assertNoIgnoredChangedFiles(state.cwd, finalizationChangedFiles, 'Execute finalization');
+    const onlyChangedFile = finalizationChangedFiles.length === 1 ? finalizationChangedFiles[0] : null;
+    const onlyChangedPlanDoc = onlyChangedFile !== null &&
+        planDocInspection.repoRelativePath !== null &&
+        onlyChangedFile === planDocInspection.repoRelativePath;
+    const finalCommitMessage = onlyChangedPlanDoc ? 'Record Neal plan document\n' : finalMessage;
+    const finalSubject = finalCommitMessage.split(/\r?\n/, 1)[0] || 'Finalize scope work';
+    const finalCommit = finalizationChangedFiles.length > 0
+        ? await createScopeFinalizationCommit(state.cwd, state.baseCommit, finalCommitMessage)
+        : headCommit;
+    const archivedReviewPath = join(state.runDir, `REVIEW-${finalCommit}.md`);
+    const archivedReviewState = {
+        ...state,
+        finalCommit,
+        archivedReviewPath,
+    };
+    const completedScopes = appendDerivedSubScopeAndParentCompletion({
+        state,
+        finalCommit,
+        finalSubject,
+        changedFiles: finalizationChangedFiles,
+        archivedReviewPath,
+    });
+    const retrospectiveState = {
+        ...archivedReviewState,
+        completedScopes,
+    };
+    const provisionalNextState = computeNextScopeStateAfterExecuteFinalization({
+        state,
+        finalCommit,
+        completedScopes,
+        archivedReviewPath,
+    });
+    const continueScopes = provisionalNextState.phase === 'coder_scope' && provisionalNextState.status === 'running';
+    const initialFinalCompletion = requireFinalCompletionView(state, 'run execute finalization');
+    let finalCompletionSummary = initialFinalCompletion.summary;
+    if (!continueScopes && !finalCompletionSummary) {
+        await writeTextAtomic(archivedReviewPath, renderReviewMarkdown({ ...archivedReviewState, finalCompletionSummary: null, finalCompletionReviewVerdict: null }));
+        const packet = await buildFinalCompletionPacket({
+            state: retrospectiveState,
+            terminalScope: {
+                finalCommit,
+                commitSubject: finalSubject,
+                changedFiles: finalizationChangedFiles,
+                archivedReviewPath,
+                marker: state.lastScopeMarker,
+            },
+        });
+        try {
+            const { summary: finalCompletion } = await runFinalCompletionSummaryAdjudication({
+                state,
+                packet,
+                logger,
+            });
+            finalCompletionSummary = finalCompletion.summary;
+        }
+        catch (error) {
+            if (error instanceof CoderRoundError) {
+                const failedState = await saveState(statePath, {
+                    ...state,
+                    finalCommit,
+                    archivedReviewPath,
+                    completedScopes,
+                    coderSessionHandle: error.sessionHandle ?? state.coderSessionHandle,
+                    coderSessionProtocol: (error.sessionHandle ?? state.coderSessionHandle)
+                        ? state.coderSessionProtocol ?? 'structured_json_v1'
+                        : null,
+                    status: 'failed',
+                });
+                await runtime.writeExecutionArtifacts(failedState);
+                await writeFailedFinalCompletionReviewArtifact({
+                    state: failedState,
+                    source: 'coder_summary',
+                    sessionHandle: error.sessionHandle ?? state.coderSessionHandle,
+                });
+                await writeCheckpointRetrospective({
+                    ...failedState,
+                    finalCompletionSummary,
+                }, 'failed');
+                await logger?.event('phase.error', {
+                    phase: EXECUTE_FINALIZATION_PHASE,
+                    sessionHandle: error.sessionHandle ?? state.coderSessionHandle,
+                    message: error.message,
+                });
+                if (shouldNotifyFailure(error)) {
+                    await notifyBlocked(failedState, error.message, logger);
+                }
+            }
+            else {
+                const failedState = await saveState(statePath, {
+                    ...state,
+                    finalCommit,
+                    archivedReviewPath,
+                    completedScopes,
+                    status: 'failed',
+                });
+                await runtime.writeExecutionArtifacts(failedState);
+                await writeCheckpointRetrospective({
+                    ...failedState,
+                    finalCompletionSummary,
+                }, 'failed');
+                await logger?.event('phase.error', {
+                    phase: EXECUTE_FINALIZATION_PHASE,
+                    sessionHandle: state.coderSessionHandle,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+            throw error;
+        }
+    }
+    const nextState = await saveState(statePath, continueScopes
+        ? {
+            ...provisionalNextState,
+            finalCompletionSummary,
+        }
+        : {
+            ...provisionalNextState,
+            blockedFromPhase: null,
+            finalCompletionSummary,
+            finalCompletionReviewVerdict: null,
+            finalCompletionResolvedAction: null,
+            finalCompletionContinueExecutionCapReached: false,
+        });
+    await writeTextAtomic(archivedReviewPath, renderReviewMarkdown({ ...archivedReviewState, finalCompletionSummary, finalCompletionReviewVerdict: null }));
+    await writeCheckpointRetrospective(retrospectiveState, 'scope_accepted');
+    if (continueScopes) {
+        await runtime.writeExecutionArtifacts(nextState);
+    }
+    else {
+        await writeReviewMarkdown(nextState.reviewMarkdownPath, { ...nextState, finalCommit, archivedReviewPath });
+        await writePlanProgressArtifacts(nextState);
+        await writeFinalCompletionReviewMarkdown(getFinalCompletionReviewArtifactPath(nextState.runDir), { ...nextState, finalCommit, archivedReviewPath });
+    }
+    await logger?.event('phase.complete', {
+        phase: EXECUTE_FINALIZATION_PHASE,
+        finalCommit,
+        archivedReviewPath,
+        continueScopes,
+    });
+    await notifyScopeAccepted(state, finalSubject, logger);
+    return nextState;
+}
+export async function runFinalCompletionReviewPhase(state, statePath, logger, runtime) {
+    const finalCompletion = requireFinalCompletionView(state, 'run final completion review');
+    if (!finalCompletion.summary) {
+        throw new Error('Cannot run final completion review without a final completion summary');
+    }
+    await logger?.event('phase.start', { phase: 'final_completion_review' });
+    const terminalScope = getTerminalCompletedScope(state);
+    const packet = await buildFinalCompletionPacket({
+        state,
+        terminalScope: terminalScope
+            ? {
+                finalCommit: terminalScope.finalCommit,
+                commitSubject: terminalScope.commitSubject,
+                changedFiles: terminalScope.changedFiles,
+                archivedReviewPath: terminalScope.archivedReviewPath,
+                marker: terminalScope.marker,
+            }
+            : null,
+    });
+    let context;
+    let reviewerResult;
+    try {
+        ({ context, reviewerResult } = await runFinalCompletionReviewerAdjudication({
+            state,
+            packet,
+            logger,
+        }));
+    }
+    catch (error) {
+        if (error instanceof ReviewerRoundError || error instanceof FinalCompletionReviewerVerdictError) {
+            const failedState = await persistFailedFinalCompletionReview({
+                state,
+                statePath,
+                error,
+                logger,
+                runtime,
+            });
+            if (error instanceof ReviewerRoundError && shouldNotifyFailure(error)) {
+                await notifyBlocked(failedState, error.message, logger);
+            }
+        }
+        throw error;
+    }
+    printFinalCompletionReviewResult(reviewerResult.verdict, logger);
+    await discardFinalCompletionReviewerWorktreeChanges({ state, logger });
+    const continueExecutionLimit = Math.max(0, getFinalCompletionContinueExecutionMax(state.cwd));
+    const actionResolution = resolveFinalCompletionReviewAction({
+        finalCompletion,
+        reviewerAction: reviewerResult.verdict.action,
+        continueExecutionLimit,
+    });
+    const baseState = {
+        ...state,
+        reviewerSessionHandle: reviewerResult.sessionHandle,
+        finalCompletionReviewVerdict: reviewerResult.verdict,
+        finalCompletionResolvedAction: actionResolution.effectiveAction,
+        finalCompletionContinueExecutionCount: actionResolution.continueExecutionCount,
+        finalCompletionContinueExecutionCapReached: actionResolution.continueExecutionCapReached,
+    };
+    assertAdjudicationTransitionSignal(context.spec, actionResolution.effectiveAction, 'orchestrator:final_completion_review');
+    // Site B: the final-completion review gate. Under `unattended` a
+    // `block_for_operator` resolution (model-chosen or the forced
+    // continue-execution cap folded into `effectiveAction`) has no operator to
+    // answer, so run the shared terminal-fail action instead of saving
+    // `status:'blocked'`. The continue-execution cap already bounded the
+    // autonomous push, so there is no auto-resume. The aggregate diff is preserved
+    // unsubmitted by the shared action. Gate structurally on the persisted flag,
+    // never on guidance text.
+    const unattendedFinalCompletionBlock = actionResolution.effectiveAction === 'block_for_operator' && state.unattended;
+    const nextState = actionResolution.effectiveAction === 'accept_complete'
+        ? await saveState(statePath, {
+            ...baseState,
+            phase: 'done',
+            status: 'done',
+            blockedFromPhase: null,
+        })
+        : actionResolution.effectiveAction === 'continue_execution'
+            ? await saveState(statePath, {
+                ...baseState,
+                baseCommit: state.finalCommit,
+                finalCommit: null,
+                archivedReviewPath: null,
+                coderSessionHandle: null,
+                coderSessionProtocol: null,
+                coderRetryCount: 0,
+                currentScopeNumber: shouldAdvanceTopLevelScopeNumber(state)
+                    ? state.currentScopeNumber + 1
+                    : state.currentScopeNumber,
+                lastScopeMarker: null,
+                currentScopeProgressJustification: null,
+                currentScopeMeaningfulProgressVerdict: null,
+                finalCompletionSummary: null,
+                rounds: [],
+                recentBlocks: [],
+                // The reopened follow-on scope is a fresh scope boundary: per-scope
+                // budgets reset here exactly as they do at every scope-advance
+                // transition, so an earlier scope's adjudication or split-plan
+                // consumption never exhausts the reopened scope's budget.
+                reviewStuckArbiterCount: 0,
+                splitPlanCountForCurrentScope: 0,
+                findings: [],
+                createdCommits: [],
+                blockedFromPhase: null,
+                phase: 'coder_scope',
+                status: 'running',
+            })
+            : unattendedFinalCompletionBlock
+                ? await persistUnattendedBlockUnresolvedFailure({
+                    ...baseState,
+                    phase: 'blocked',
+                    blockedFromPhase: 'final_completion_review',
+                }, statePath, 'final_completion_review', logger)
+                : await saveState(statePath, {
+                    ...baseState,
+                    phase: 'blocked',
+                    status: 'blocked',
+                    blockedFromPhase: 'final_completion_review',
+                });
+    await runtime.writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: 'final_completion_review',
+        action: reviewerResult.verdict.action,
+        resultingAction: actionResolution.effectiveAction,
+        continueExecutionCount: actionResolution.continueExecutionCount,
+        continueExecutionLimit: actionResolution.continueExecutionLimit,
+        continueExecutionCapReached: actionResolution.continueExecutionCapReached,
+        reviewerSessionHandle: reviewerResult.sessionHandle,
+        nextPhase: nextState.phase,
+    });
+    if (actionResolution.effectiveAction === 'accept_complete') {
+        const finalSubject = terminalScope?.commitSubject ?? 'Finalize scope work';
+        await notifyComplete(nextState, finalSubject, logger);
+    }
+    else if (actionResolution.effectiveAction === 'block_for_operator' && !state.unattended) {
+        const reason = getFinalCompletionReviewBlockReason({
+            reviewerAction: reviewerResult.verdict.action === 'accept_complete' ? 'block_for_operator' : reviewerResult.verdict.action,
+            effectiveAction: actionResolution.effectiveAction,
+            rationale: reviewerResult.verdict.rationale,
+            continueExecutionCount: actionResolution.continueExecutionCount,
+            continueExecutionLimit: actionResolution.continueExecutionLimit,
+            capReached: actionResolution.continueExecutionCapReached,
+        });
+        await notifyBlocked(nextState, reason, logger);
+    }
+    return nextState;
+}

package/dist/neal/orchestrator/failures.js

@@ -0,0 +1,31 @@
+import { CoderRoundError } from '../agents.js';
+export function isCoderTimeoutError(error) {
+    return (error.kind === 'timeout' ||
+        error.kind === 'no_progress_timeout' ||
+        /\btimed out after\b/i.test(error.message));
+}
+export function isCoderResumeHistoryError(error) {
+    const text = error.message.toLowerCase();
+    return (text.includes('property_name_above_max_length') ||
+        text.includes('orphan function call output') ||
+        text.includes('failed to record rollout items'));
+}
+export function isCoderFreshSessionRetryableError(error) {
+    return isCoderTimeoutError(error) || isCoderResumeHistoryError(error);
+}
+export function isTransientApiFailureMessage(message, subtype) {
+    const text = `${subtype ?? ''} ${message}`.toLowerCase();
+    return (text.includes('api_error') ||
+        text.includes('api error') ||
+        text.includes('internal server error') ||
+        text.includes('overloaded') ||
+        text.includes('rate limit') ||
+        text.includes('temporar') ||
+        text.includes('try again'));
+}
+export function shouldNotifyFailure(error) {
+    if (error instanceof CoderRoundError) {
+        return isCoderTimeoutError(error) || isTransientApiFailureMessage(error.message);
+    }
+    return isTransientApiFailureMessage(error.message, error.subtype ?? undefined);
+}