@navels/neal 0.2.0 → 0.3.0

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

@@ -1,10 +1,11 @@
 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, resolvePlanReviewDisposition, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, } from '../../adjudicator/planning.js';
+import { isOpenBlockingFinding, isOpenNonBlockingFinding, mapDecisionToStatus, } from '../../adjudicator/execute.js';
+import { getDerivedPlanBlockedReason, isDerivedPlanReviewState, plannerProviderStartsFreshSessions, resolvePlanningAdjudicationContext, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, synthesizePlanReviewRound, } from '../../adjudicator/planning.js';
 import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
-import { getReviewStuckWindow } from '../../config.js';
+import { getPlanReviewDebtRoundThreshold, getReviewStuckWindow } from '../../config.js';
+import { toPlanReviewDebt } from '../../review-debt.js';
 import { writeDiagnostic } from '../../diagnostic.js';
 import { getWorktreeStatus } from '../../git.js';
 import { formatPlanRefinementRoundLine, isPlanRefinementState } from '../../plan-refinement.js';
@@ -13,7 +14,7 @@ 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 { isCoderTimeoutError, REVIEWER_CONTENT_REFUSED_BLOCK_REASON, shouldNotifyFailure } from '../failures.js';
 import { flushDerivedPlanNotifications, notifyBlocked, notifyComplete, } from '../notifications.js';
 import { adoptAcceptedDerivedPlan, shouldNotifyDerivedPlanAcceptance, transitionPlanReviewWithoutOpenFindings, } from '../transitions.js';
 import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry } from './recovery.js';
@@ -58,6 +59,9 @@ export async function synthesizePlanReviewFindings(args) {
                 round: args.round,
                 source: 'plan_structure',
                 severity: 'blocking',
+                // Structural defects are always plan-correctness (fail-safe blocking);
+                // they must never be treated as convertible verification-hardening debt.
+                findingClass: 'plan_correctness',
                 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.',
@@ -72,12 +76,6 @@ function getPlanningCompletionProblem(marker) {
     }
     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;
@@ -122,18 +120,34 @@ async function finalizePlanReviewResponseWithoutOpenFindings(state, statePath, p
     }
     return nextState;
 }
-export async function finalizeBlockedPlanReviewResponse(state, statePath, derivedPlanReview, blocker, logger) {
+export async function finalizeBlockedPlanReviewResponse(state, statePath, derivedPlanReview, blocker, blockCause, 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.
+        // Top-level plan stage (`neal run`/`neal plan`).
+        if (blockCause === 'coder_authored') {
+            // Recoverable landing for a coder-authored *response* block: persist the
+            // durable blocker reason and leave `status:'blocked'` (writer exit 2) for
+            // an operator to answer via `neal resume --message`. Attended and
+            // unattended land identically now — both blocked-with-reason — because
+            // neither could previously answer this block (attended left it blocked but
+            // reason-less; unattended terminal-failed).
+            const blockedState = await saveState(statePath, {
+                ...state,
+                blockerReason: blocker,
+            });
+            if (!derivedPlanReview) {
+                await notifyBlocked(blockedState, blocker, logger);
+            }
+            return flushDerivedPlanNotifications(blockedState, statePath, logger, blocker);
+        }
+        // Site C: a `dirty_worktree` safety block or a `reviewer_convergence`
+        // cap/stall block. Attended runs leave `status:'blocked'`; unattended runs
+        // have no operator to answer, so run the shared terminal-fail action. The
+        // dirty-worktree case must not be silently converted to the recoverable
+        // landing (the planner dirtied non-plan files with no operator to clean it),
+        // and the convergence cap already bounded the autonomous push. Any plan
+        // artifact is preserved unsubmitted, exactly as today's failed runs leave it.
         if (state.unattended) {
             return persistUnattendedBlockUnresolvedFailure(state, statePath, 'reviewer_plan', logger);
         }
@@ -213,6 +227,9 @@ export async function runCoderPlanPhase(state, statePath, logger) {
         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,
+        // The initial coder_plan authoring block never carries the recoverable
+        // coder-response blocker reason; keep it cleared whether we advance or block.
+        blockerReason: null,
     });
     await writeExecutionArtifacts(nextState);
     await logger?.event('phase.complete', {
@@ -261,6 +278,31 @@ export async function runPlanReviewPhase(state, statePath, logger) {
     }
     catch (error) {
         if (error instanceof ReviewerRoundError) {
+            // A content-safety refusal is a distinct, terminal, non-coder-recoverable
+            // condition: end the run blocked (exit 2) with a durable actionable reason
+            // by RETURNING the terminal blocked state, never throwing (a thrown error
+            // over a persisted blocked state escapes executeRun).
+            if (error.kind === 'content_refused') {
+                const blockedState = await saveState(statePath, {
+                    ...state,
+                    reviewerSessionHandle: null,
+                    phase: 'blocked',
+                    status: 'blocked',
+                    blockedFromPhase: null,
+                    blockerReason: REVIEWER_CONTENT_REFUSED_BLOCK_REASON,
+                });
+                await writeExecutionArtifacts(blockedState);
+                await logger?.event('phase.error', {
+                    phase: 'reviewer_plan',
+                    round,
+                    sessionHandle: error.sessionHandle,
+                    subtype: error.subtype,
+                    errorKind: error.kind,
+                    message: error.message,
+                });
+                await notifyBlocked(blockedState, REVIEWER_CONTENT_REFUSED_BLOCK_REASON, logger);
+                return blockedState;
+            }
             const failedState = await saveState(statePath, {
                 ...state,
                 reviewerSessionHandle: null,
@@ -290,46 +332,25 @@ export async function runPlanReviewPhase(state, statePath, logger) {
     // 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 disposition = resolvePlanReviewDisposition({
-        shouldBlockForConvergence,
-        hasBlockingFindings,
-        reachedMaxRounds,
-        hasOpenNonBlockingFindings,
+    const { findings, mergedFindings, disposition, blockReason, roundRecord, planReviewDebt } = synthesizePlanReviewRound({
+        state,
+        round,
+        roundLimit,
+        reviewStuckWindow: getReviewStuckWindow(state.cwd),
+        debtRoundThreshold: getPlanReviewDebtRoundThreshold(state.cwd),
         derivedPlanReview,
         currentDerivedPlanStatus: state.derivedPlanStatus,
+        executionShape: synthesizedReview.executionShape,
+        findingInputs: normalizedFindingInputs,
+        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 ?? '',
+        },
     });
     assertAdjudicationTransitionSignal(context.spec, disposition.planningSignal, 'orchestrator:reviewer_plan');
     const nextState = await saveState(statePath, {
@@ -338,25 +359,11 @@ export async function runPlanReviewPhase(state, statePath, logger) {
         executionShape: synthesizedReview.executionShape,
         phase: disposition.phase,
         status: disposition.status,
-        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),
-            },
-        ],
+        rounds: [...state.rounds, roundRecord],
         findings: mergedFindings,
+        // Recompute the current-negotiation plan-review debt projection from the
+        // post-conversion merged findings. Never touches inheritedPlanReviewDebt.
+        planReviewDebt,
         derivedPlanStatus: disposition.derivedPlanStatus,
         blockedFromPhase: disposition.blockedFromPhase,
     });
@@ -370,7 +377,8 @@ export async function runPlanReviewPhase(state, statePath, logger) {
         nextPhase: nextState.phase,
     });
     if (nextState.status === 'blocked' && blockReason) {
-        return finalizeBlockedPlanReviewResponse(nextState, statePath, derivedPlanReview, blockReason, logger);
+        // A reviewer convergence/cap terminal block, never a coder-authored one.
+        return finalizeBlockedPlanReviewResponse(nextState, statePath, derivedPlanReview, blockReason, 'reviewer_convergence', logger);
     }
     if (shouldNotifyDerivedPlanAcceptance(state, nextState)) {
         return flushDerivedPlanNotifications(nextState, statePath, logger);
@@ -387,7 +395,7 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     // 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
+    // openai-compatible) never persist a planner handle at all — they start a
     // fresh planner session instead.
     if (!derivedPlanReview &&
         !state.plannerSessionHandle &&
@@ -404,7 +412,12 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
         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) {
+    // Recorded operator guidance must reach the planner. If a prior blocked response
+    // closed every finding, the guidance would otherwise be silently discarded here
+    // (finalizePlanReviewResponseWithoutOpenFindings clears pendingPlanReviewGuidance
+    // and accepts the plan) without ever delivering the operator's answer. Force a
+    // response adjudication whenever guidance is pending so it is delivered first.
+    if (openFindings.length === 0 && state.pendingPlanReviewGuidance === null) {
         return finalizePlanReviewResponseWithoutOpenFindings(state, statePath, phase, logger);
     }
     let codex;
@@ -443,7 +456,22 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     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);
+    // Response-eligibility contract: only findings this invocation actually
+    // presented to the coder (the mode-matching `openFindings` set — open blocking
+    // for a required response, open non-blocking for an optional one) may be
+    // dispositioned. The response `id` schema is an unconstrained `z.string()`, so a
+    // planner can name any finding; a response whose `id` is outside `openFindings`
+    // — an already-`deferred` banked-debt finding, a prior-round `fixed`/`rejected`
+    // finding, a wrong-mode finding (a blocking id in an optional response or the
+    // reverse), or an unknown id — is a no-op that never mutates status or
+    // coderDisposition. This keeps `toPlanReviewDebt`'s reservation intact (a banked
+    // hardening finding cannot be silently un-banked by an out-of-band disposition)
+    // and matches the replay harness's open-blocking eligibility guard.
+    const openFindingIds = new Set(openFindings.map((finding) => finding.id));
     const findings = state.findings.map((finding) => {
+        if (!openFindingIds.has(finding.id)) {
+            return finding;
+        }
         const response = responseById.get(finding.id);
         if (!response) {
             return finding;
@@ -460,6 +488,10 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
         plannerSessionHandle: codex.sessionHandle,
         plannerSessionProtocol: codex.sessionHandle ? activePlannerSessionProtocol : null,
         findings,
+        // Reproject the current-negotiation plan-review debt after applying coder
+        // dispositions (a re-defer keeps debt; a fix/reject/reopen drops it). Never
+        // touches inheritedPlanReviewDebt.
+        planReviewDebt: toPlanReviewDebt(findings),
         phase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
             ? 'blocked'
             : mode === 'optional'
@@ -477,6 +509,9 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
             : state.derivedPlanStatus,
         blockedFromPhase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked' ? phase : null,
         pendingPlanReviewGuidance: null,
+        // Clear any stale reason as we advance to running/done; the recoverable
+        // coder-authored blocked landing re-persists it in finalizeBlockedPlanReviewResponse.
+        blockerReason: null,
     });
     await writeExecutionArtifacts(nextState);
     await logger?.event('phase.complete', {
@@ -486,13 +521,15 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
         nextPhase: nextState.phase,
     });
     if (nextState.status === 'blocked') {
-        const blocker = getDerivedPlanBlockedReason(state, dirtyWorktreeBlocker ||
+        const blocker = getDerivedPlanBlockedReason(derivedPlanReview, 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);
+        // The coder authored the block unless the safety net tripped on a dirtied
+        // non-plan worktree; the cause drives the recoverable-vs-terminal landing.
+        return finalizeBlockedPlanReviewResponse(nextState, statePath, derivedPlanReview, blocker, dirtyWorktreeBlocker ? 'dirty_worktree' : 'coder_authored', logger);
     }
     if (mode === 'optional' && shouldNotifyDerivedPlanAcceptance(state, nextState)) {
         return flushDerivedPlanNotifications(nextState, statePath, logger);