@navels/neal 0.1.0 → 0.2.0

package/dist/neal/agents/structured-json.js

@@ -28,6 +28,42 @@ export function buildStructuredJsonPrompt(basePrompt, protocol) {
     }
     return lines.join('\n');
 }
+// Base-prompt output-format phrasings that contradict the neal-json transport
+// contract appended by buildStructuredJsonPrompt (which requires a final fenced
+// ```neal-json block, optionally preceded by prose). A structured-JSON base
+// prompt must not carry its own "no fences / no prose outside the JSON object"
+// instruction, because that flatly contradicts the transport for whichever
+// provider renders it. This mirrors the assertNoReadPromptInstructionText /
+// NO_READ_PROMPT_FORBIDDEN_MARKERS precedent in
+// src/neal/context/inline-review-context.ts: a shared marker list plus a
+// render-time guard, so a reintroduced contradiction throws at build time
+// instead of silently shipping. The markers are chosen so they never match the
+// transport wrapper's own lines above (no bare 'fence'/'fenced' marker).
+export const CONFLICTING_OUTPUT_FORMAT_MARKERS = [
+    'do not include markdown fences',
+    'markdown fences or prose outside',
+    'outside the JSON object',
+];
+// Implementation-side guard for builder-owned static output-format instruction
+// text in structured-JSON base prompts. Call it only on Neal-authored
+// instruction lines (never on dynamic content such as JSON.stringify segments
+// or coder-authored summaries, which may legitimately mention these phrases).
+export function assertNoConflictingOutputFormatInstruction(text, label) {
+    const lowered = text.toLowerCase();
+    const violations = CONFLICTING_OUTPUT_FORMAT_MARKERS.filter((marker) => lowered.includes(marker.toLowerCase()));
+    if (violations.length > 0) {
+        throw new Error(`${label} produced a structured-JSON base prompt with output-format instructions that conflict with the neal-json transport contract: ${violations.join(', ')}`);
+    }
+}
+// Single guarded-assembly seam for structured-JSON base-prompt output-format
+// lines: asserts the assembled lines carry no transport-conflicting phrasing,
+// then returns a defensive copy. Base-prompt builders funnel their
+// output-format instructions through this so a reintroduced contradiction
+// throws at render, and tests can inject a marker through this one unit.
+export function guardStructuredJsonOutputFormatLines(lines, label) {
+    assertNoConflictingOutputFormatInstruction(lines.join('\n'), label);
+    return [...lines];
+}
 export function extractStructuredJsonPayload(assistantText) {
     const blocks = findNealJsonBlocks(assistantText);
     if (blocks.length > 1) {

package/dist/neal/config.js

@@ -346,6 +346,28 @@ function parseOpenAICompatibleHeaders(value) {
     }
     return headers;
 }
+function parseOpenAICompatiblePricing(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Invalid providers.openai_compatible.pricing: expected a map with input_per_million, ' +
+            'cached_input_per_million, and output_per_million rates.');
+    }
+    const record = value;
+    const parseRate = (key) => {
+        const rate = record[key];
+        if (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0) {
+            throw new Error(`Invalid providers.openai_compatible.pricing: "${key}" must be a finite non-negative number.`);
+        }
+        return rate;
+    };
+    return {
+        inputPerMillion: parseRate('input_per_million'),
+        cachedInputPerMillion: parseRate('cached_input_per_million'),
+        outputPerMillion: parseRate('output_per_million'),
+    };
+}
 export function getOpenAICompatibleSettings(cwd = process.cwd(), env = process.env) {
     const config = loadConfigFile(cwd).providers?.openai_compatible;
     const baseUrl = parseStringValue(config?.base_url) ??
@@ -357,12 +379,14 @@ export function getOpenAICompatibleSettings(cwd = process.cwd(), env = process.e
         parseStringValue(env.OPENAI_COMPATIBLE_MODEL) ??
         null;
     const headers = parseOpenAICompatibleHeaders(config?.headers);
+    const pricing = parseOpenAICompatiblePricing(config?.pricing);
     return {
         baseUrl,
         apiKeyEnv,
         apiKey,
         defaultModel,
         headers,
+        pricing,
     };
 }
 export function getDefaultCoderProvider(cwd = process.cwd()) {

package/dist/neal/git.js

@@ -1,8 +1,14 @@
 import { execFile, spawn } from 'node:child_process';
 import { isAbsolute, resolve } from 'node:path';
+// Git output (diffs, status) scales with scope artifacts — a scope that
+// vendors or generates a large file produces a multi-megabyte diff, and
+// Node's default execFile maxBuffer (1 MiB) kills the run with
+// "stdout maxBuffer length exceeded". 64 MiB clears any realistic scope
+// diff while still bounding a runaway.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
 function runGit(args, cwd) {
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile('git', args, { cwd }, (error, stdout, stderr) => {
+        execFile('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER }, (error, stdout, stderr) => {
             if (error) {
                 rejectPromise(new Error(stderr.trim() || error.message));
                 return;
@@ -13,7 +19,7 @@ function runGit(args, cwd) {
 }
 function runGitOptionalConfig(args, cwd) {
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile('git', args, { cwd }, (error, stdout, stderr) => {
+        execFile('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER }, (error, stdout, stderr) => {
             if (!error) {
                 resolvePromise(stdout.trim());
                 return;
@@ -158,7 +164,7 @@ export async function resolveCommitRef(cwd, ref) {
 }
 export async function isAncestorCommit(cwd, ancestor, descendant) {
     return new Promise((resolvePromise, rejectPromise) => {
-        execFile('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd }, (error, _stdout, stderr) => {
+        execFile('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd, maxBuffer: GIT_MAX_BUFFER }, (error, _stdout, stderr) => {
             if (!error) {
                 resolvePromise(true);
                 return;

package/dist/neal/orchestrator/completion.js

@@ -11,8 +11,8 @@ import { getFinalCompletionReviewArtifactPath, readFinalCompletionUnstructuredOu
 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 { inspectPlanDocDisposition, withPlanDocPreserved } from '../plan-doc.js';
+import { appendDerivedSubScopeAndParentCompletion, appendParentCompletionFromAcceptedDerivedScopes, computeNextScopeStateAfterExecuteFinalization, computeNextScopeStateAfterParentAdvance, createNextScopeEntryReset, } from './transitions.js';
 import { writePlanProgressArtifacts } from '../progress.js';
 import { writeCheckpointRetrospective } from '../retrospective.js';
 import { renderReviewMarkdown, writeReviewMarkdown } from '../review.js';
@@ -105,7 +105,12 @@ function getFinalCompletionReviewBlockReason(args) {
     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' }));
+    // The plan document is a wrapper-owned overlay, not reviewer dirt: it may be
+    // an uncommitted modification of a tracked file (a reset --hard would
+    // silently swap in the committed content — a different plan — mid-run) or an
+    // untracked seed. Exclude it from the trigger and the post-check, and
+    // preserve its bytes across the destructive cleanup.
+    const statusOutput = filterAllowedDirtyPathStatus(args.state.cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(args.state.cwd, { untrackedFiles: 'all' })), [args.state.planDoc]);
     if (!statusOutput.trim()) {
         return;
     }
@@ -115,9 +120,11 @@ async function discardFinalCompletionReviewerWorktreeChanges(args) {
         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' }));
+    await withPlanDocPreserved(args.state.planDoc, async () => {
+        await resetHard(args.state.cwd, headCommit);
+        await cleanUntracked(args.state.cwd, ['.neal/', '.forge/', 'CURRENT_PLAN.md']);
+    });
+    const remainingStatusOutput = filterAllowedDirtyPathStatus(args.state.cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(args.state.cwd, { untrackedFiles: 'all' })), [args.state.planDoc]);
     if (remainingStatusOutput.trim()) {
         throw new Error(`Final completion review left a dirty worktree Neal could not restore:\n${remainingStatusOutput}`);
     }
@@ -149,7 +156,8 @@ async function runParentAdvanceFinalization(args) {
                 `Neal-created commits: ${formatCommitList(state.createdCommits)}`,
             ].join('\n'));
         }
-        await resetHard(state.cwd, state.baseCommit);
+        const parentBaseCommit = state.baseCommit;
+        await withPlanDocPreserved(state.planDoc, () => resetHard(state.cwd, parentBaseCommit));
     }
     const finalCommit = state.baseCommit;
     const archivedReviewPath = join(state.runDir, `REVIEW-${finalCommit}.md`);
@@ -203,11 +211,10 @@ async function runParentAdvanceFinalization(args) {
     }, 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 });
+// Dirty-worktree admission for execute finalization: capture the head commit,
+// filter the worktree status down to disallowed dirt, and refuse to finalize
+// (with the expected-scratch-dir diagnostic) when any remains.
+async function admitFinalizationWorktree(state) {
     const headCommit = await getHeadCommit(state.cwd);
     const statusOutput = filterAllowedDirtyPathStatus(state.cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(state.cwd)), state.allowedDirtyPaths);
     if (statusOutput) {
@@ -217,6 +224,132 @@ export async function runExecuteFinalizationPhase(state, statePath, logger, runt
         });
         throw new Error([`Cannot finalize with a dirty worktree:\n${statusOutput}`, diagnostic].filter(Boolean).join('\n\n'));
     }
+    return { headCommit, statusOutput };
+}
+// Raw material for final-commit message synthesis: the full message of the
+// latest Neal-created commit, falling back to the last recorded subject (with
+// any leading hash stripped) and then to the fixed default.
+async function readRawFinalCommitMessage(cwd, createdCommits) {
+    const commitSubjects = await getCommitSubjects(cwd, createdCommits);
+    const latestCreatedCommit = createdCommits.at(-1) ?? null;
+    return latestCreatedCommit
+        ? await getCommitMessage(cwd, latestCreatedCommit)
+        : commitSubjects.at(-1)?.replace(/^[a-f0-9]+\s+/, '') || 'Finalize scope work';
+}
+// Final-commit message synthesis: strip the scope prefix, normalize newlines
+// (falling back to the fixed default when stripping leaves nothing), apply the
+// plan-doc-only special case, and derive the subject line.
+function synthesizeFinalCommitMessage(args) {
+    const strippedFinalMessage = stripScopePrefixFromCommitMessage(args.rawFinalMessage);
+    const finalMessage = normalizeFinalCommitMessage(strippedFinalMessage.trim() ? strippedFinalMessage : 'Finalize scope work');
+    const onlyChangedFile = args.finalizationChangedFiles.length === 1 ? args.finalizationChangedFiles[0] : null;
+    const onlyChangedPlanDoc = onlyChangedFile !== null &&
+        args.planDocRepoRelativePath !== null &&
+        onlyChangedFile === args.planDocRepoRelativePath;
+    const finalCommitMessage = onlyChangedPlanDoc ? 'Record Neal plan document\n' : finalMessage;
+    const finalSubject = finalCommitMessage.split(/\r?\n/, 1)[0] || 'Finalize scope work';
+    return { finalCommitMessage, finalSubject };
+}
+// The one shared failure-persistence path for both summary-adjudication catch
+// branches. Ordering is pinned by test/execute-finalization-failure.test.ts:
+// failed state save, execution artifacts, failed final-completion review
+// artifact (coder-round branch only), checkpoint retrospective, phase.error,
+// gated notification (coder-round branch only).
+async function persistExecuteFinalizationFailure(args) {
+    const { state, coderRoundExtras } = args;
+    const failedState = await saveState(args.statePath, {
+        ...state,
+        finalCommit: args.finalCommit,
+        archivedReviewPath: args.archivedReviewPath,
+        completedScopes: args.completedScopes,
+        ...(coderRoundExtras
+            ? {
+                coderSessionHandle: coderRoundExtras.sessionHandleOverride,
+                coderSessionProtocol: coderRoundExtras.sessionHandleOverride
+                    ? state.coderSessionProtocol ?? 'structured_json_v1'
+                    : null,
+            }
+            : {}),
+        status: 'failed',
+    });
+    await args.runtime.writeExecutionArtifacts(failedState);
+    if (coderRoundExtras) {
+        await writeFailedFinalCompletionReviewArtifact({
+            state: failedState,
+            source: 'coder_summary',
+            sessionHandle: coderRoundExtras.sessionHandleOverride,
+        });
+    }
+    await writeCheckpointRetrospective({
+        ...failedState,
+        finalCompletionSummary: args.finalCompletionSummary,
+    }, 'failed');
+    await args.logger?.event('phase.error', {
+        phase: EXECUTE_FINALIZATION_PHASE,
+        sessionHandle: coderRoundExtras ? coderRoundExtras.sessionHandleOverride : state.coderSessionHandle,
+        message: args.errorMessage,
+    });
+    if (coderRoundExtras?.notify) {
+        await notifyBlocked(failedState, args.errorMessage, args.logger);
+    }
+}
+// Summary adjudication for a terminal finalization: archive the review, build
+// the final-completion packet, run the coder final-completion summary round,
+// and route BOTH failure branches through the shared persistence helper
+// before rethrowing.
+async function adjudicateFinalCompletionSummary(args) {
+    const { state, logger } = args;
+    await writeTextAtomic(args.archivedReviewPath, renderReviewMarkdown({ ...args.archivedReviewState, finalCompletionSummary: null, finalCompletionReviewVerdict: null }));
+    const packet = await buildFinalCompletionPacket({
+        state: args.retrospectiveState,
+        terminalScope: {
+            finalCommit: args.finalCommit,
+            commitSubject: args.finalSubject,
+            changedFiles: args.finalizationChangedFiles,
+            archivedReviewPath: args.archivedReviewPath,
+            marker: state.lastScopeMarker,
+        },
+    });
+    try {
+        const { summary: finalCompletion } = await runFinalCompletionSummaryAdjudication({
+            state,
+            packet,
+            logger,
+        });
+        return finalCompletion.summary;
+    }
+    catch (error) {
+        const coderRoundFailure = error instanceof CoderRoundError ? error : null;
+        await persistExecuteFinalizationFailure({
+            state,
+            statePath: args.statePath,
+            runtime: args.runtime,
+            logger,
+            finalCommit: args.finalCommit,
+            archivedReviewPath: args.archivedReviewPath,
+            completedScopes: args.completedScopes,
+            finalCompletionSummary: args.finalCompletionSummary,
+            errorMessage: coderRoundFailure
+                ? coderRoundFailure.message
+                : error instanceof Error
+                    ? error.message
+                    : String(error),
+            coderRoundExtras: coderRoundFailure
+                ? {
+                    sessionHandleOverride: coderRoundFailure.sessionHandle ?? state.coderSessionHandle,
+                    notify: shouldNotifyFailure(coderRoundFailure),
+                }
+                : null,
+        });
+        throw error;
+    }
+}
+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, statusOutput } = await admitFinalizationWorktree(state);
     if (state.currentScopeMeaningfulProgressVerdict?.action === 'advance_parent') {
         return runParentAdvanceFinalization({
             state,
@@ -227,13 +360,7 @@ export async function runExecuteFinalizationPhase(state, statePath, logger, runt
             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 rawFinalMessage = await readRawFinalCommitMessage(state.cwd, state.createdCommits);
     const planDocInspection = await inspectPlanDocDisposition(state.cwd, state.planDoc);
     if (planDocInspection.eligibleForCommit && planDocInspection.repoRelativePath) {
         await stagePath(state.cwd, planDocInspection.repoRelativePath);
@@ -242,12 +369,11 @@ export async function runExecuteFinalizationPhase(state, statePath, logger, runt
     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 { finalCommitMessage, finalSubject } = synthesizeFinalCommitMessage({
+        rawFinalMessage,
+        finalizationChangedFiles,
+        planDocRepoRelativePath: planDocInspection.repoRelativePath,
+    });
     const finalCommit = finalizationChangedFiles.length > 0
         ? await createScopeFinalizationCommit(state.cwd, state.baseCommit, finalCommitMessage)
         : headCommit;
@@ -278,78 +404,20 @@ export async function runExecuteFinalizationPhase(state, statePath, logger, runt
     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,
-            },
+        finalCompletionSummary = await adjudicateFinalCompletionSummary({
+            state,
+            statePath,
+            logger,
+            runtime,
+            finalCommit,
+            archivedReviewPath,
+            archivedReviewState,
+            retrospectiveState,
+            completedScopes,
+            finalSubject,
+            finalizationChangedFiles,
+            finalCompletionSummary,
         });
-        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
         ? {
@@ -462,32 +530,19 @@ export async function runFinalCompletionReviewPhase(state, statePath, logger, ru
         : actionResolution.effectiveAction === 'continue_execution'
             ? await saveState(statePath, {
                 ...baseState,
-                baseCommit: state.finalCommit,
-                finalCommit: null,
-                archivedReviewPath: null,
-                coderSessionHandle: null,
-                coderSessionProtocol: null,
+                ...createNextScopeEntryReset(state.finalCommit),
                 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,
+                // (`reviewStuckArbiterCount` resets via the shared next-scope
+                // reset spread above.)
                 splitPlanCountForCurrentScope: 0,
-                findings: [],
-                createdCommits: [],
                 blockedFromPhase: null,
-                phase: 'coder_scope',
-                status: 'running',
             })
             : unattendedFinalCompletionBlock
                 ? await persistUnattendedBlockUnresolvedFailure({

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

@@ -2,7 +2,7 @@ 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 { isDerivedPlanReviewState, plannerProviderStartsFreshSessions, resolvePlanningAdjudicationContext, resolvePlanReviewDisposition, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, } from '../../adjudicator/planning.js';
 import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
 import { getReviewStuckWindow } from '../../config.js';
 import { writeDiagnostic } from '../../diagnostic.js';
@@ -323,42 +323,21 @@ export async function runPlanReviewPhase(state, statePath, logger) {
             : 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 disposition = resolvePlanReviewDisposition({
+        shouldBlockForConvergence,
+        hasBlockingFindings,
+        reachedMaxRounds,
+        hasOpenNonBlockingFindings,
+        derivedPlanReview,
+        currentDerivedPlanStatus: state.derivedPlanStatus,
+    });
+    assertAdjudicationTransitionSignal(context.spec, disposition.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',
+        phase: disposition.phase,
+        status: disposition.status,
         rounds: [
             ...state.rounds,
             {
@@ -378,12 +357,8 @@ export async function runPlanReviewPhase(state, statePath, logger) {
             },
         ],
         findings: mergedFindings,
-        derivedPlanStatus: derivedPlanReview && !shouldBlockForConvergence && !hasBlockingFindings && !hasOpenNonBlockingFindings
-            ? 'accepted'
-            : state.derivedPlanStatus,
-        blockedFromPhase: shouldBlockForConvergence || (hasBlockingFindings && reachedMaxRounds)
-            ? 'reviewer_plan'
-            : null,
+        derivedPlanStatus: disposition.derivedPlanStatus,
+        blockedFromPhase: disposition.blockedFromPhase,
     });
     await writeExecutionArtifacts(nextState);
     await logger?.event('phase.complete', {

package/dist/neal/orchestrator/split-plan.js

@@ -2,12 +2,14 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { writeTextAtomic } from '../atomic-write.js';
 import { cleanUntracked, getStagedDiff, getUnstagedDiff, getUntrackedFiles, getWorktreeStatus, resetHard, } from '../git.js';
+import { withPlanDocPreserved } from '../plan-doc.js';
 import { validatePlanDocument } from '../plan-validation.js';
 import { saveState } from '../state.js';
 import { getDerivedPlanCountersView } from '../state-views.js';
-import { filterWrapperOwnedWorktreeStatus, isWrapperOwnedPath, } from '../worktree-status.js';
+import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, isWrapperOwnedPath, } from '../worktree-status.js';
 import { flushDerivedPlanNotifications, notifyBlocked } from './notifications.js';
 import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry, } from './phases/recovery.js';
+import { createScopeBoundaryReset } from './transitions.js';
 const MAX_SPLIT_PLANS_PER_SCOPE = 10;
 function getSplitPlanArtifactPaths(state) {
     return {
@@ -108,9 +110,14 @@ async function discardScopeWorktree(state) {
     if (!state.baseCommit) {
         throw new Error('Cannot discard scope worktree without a baseCommit');
     }
-    await resetHard(state.cwd, state.baseCommit);
-    await cleanUntracked(state.cwd, ['.neal', '.forge']);
-    const remainingStatus = filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(state.cwd));
+    // Preserve the plan-doc overlay (tracked-and-modified or untracked seed)
+    // across the reset; it is wrapper-owned, not scope work being discarded.
+    const scopeBaseCommit = state.baseCommit;
+    await withPlanDocPreserved(state.planDoc, async () => {
+        await resetHard(state.cwd, scopeBaseCommit);
+        await cleanUntracked(state.cwd, ['.neal', '.forge']);
+    });
+    const remainingStatus = filterAllowedDirtyPathStatus(state.cwd, filterWrapperOwnedWorktreeStatus(await getWorktreeStatus(state.cwd)), [state.planDoc]);
     if (remainingStatus) {
         throw new Error(`Failed to restore worktree to scope base ${state.baseCommit}:\n${remainingStatus}`);
     }
@@ -200,12 +207,11 @@ export async function persistSplitPlanRecovery(state, statePath, args, deps) {
     await discardScopeWorktree(state);
     const nextState = await saveState(statePath, {
         ...state,
+        ...createScopeBoundaryReset(),
         lastScopeMarker: 'AUTONOMY_SPLIT_PLAN',
         phase: 'reviewer_plan',
         status: 'running',
         blockedFromPhase: null,
-        currentScopeProgressJustification: null,
-        currentScopeMeaningfulProgressVerdict: null,
         interactiveBlockedRecovery: null,
         derivedPlanPath,
         derivedFromScopeNumber: state.currentScopeNumber,
@@ -215,11 +221,6 @@ export async function persistSplitPlanRecovery(state, statePath, args, deps) {
         splitPlanBlockedNotified: false,
         derivedScopeIndex: null,
         splitPlanCountForCurrentScope: state.splitPlanCountForCurrentScope + 1,
-        rounds: [],
-        recentBlocks: [],
-        reviewStuckArbiterCount: 0,
-        findings: [],
-        createdCommits: [],
         coderRetryCount: 0,
         reviewerSessionHandle: null,
     });