@navels/neal 0.2.0 → 0.3.0

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

@@ -1,12 +1,12 @@
 import { CoderRoundError, runBlockedRecoveryCoderRound, } from '../../agents.js';
-import { ADJUDICATOR_ELIGIBLE_SOURCE_PHASES, buildRecentBlockCandidate, isReviewerAdjudicatorPhase, runBlockedAdjudicator, upsertRecentBlock, } from '../../adjudicator/blocked-adjudicator.js';
+import { CONSULTANT_ELIGIBLE_SOURCE_PHASES, buildRecentBlockCandidate, isReviewerConsultantPhase, runConsultant, upsertRecentBlock, } from '../../adjudicator/consultant.js';
 import { UNATTENDED_AUTO_RESUME_GUIDANCE } from '../../blocked-guidance.js';
-import { getInteractiveBlockedRecoveryMaxTurns, getReviewStuckArbiterMaxAttempts } from '../../config.js';
+import { getInteractiveBlockedRecoveryMaxTurns, getConsultantMaxAttempts } from '../../config.js';
 import { EXECUTE_FINALIZATION_PHASE } from '../../execute-finalization.js';
 import { hasPendingOperatorGuidance } from '../../run-status.js';
 import { getExecutionPlanPath } from '../../scopes.js';
 import { loadState, saveState } from '../../state.js';
-import { isActivePendingDerivedPlanReview } from '../../state-views.js';
+import { getInteractiveRecoveryView, isActivePendingDerivedPlanReview } from '../../state-views.js';
 import { writeExecutionArtifacts } from '../artifacts.js';
 import { isCoderTimeoutError, shouldNotifyFailure } from '../failures.js';
 import { flushDerivedPlanNotifications, notifyBlocked } from '../notifications.js';
@@ -48,8 +48,8 @@ function getInteractiveBlockedRecoverySourcePhase(phase) {
 function isInteractiveBlockedRecoveryTopLevelMode(state) {
     return state.topLevelMode === 'execute';
 }
-// The generalized adjudicator triages two block classes whose source phase is in
-// `ADJUDICATOR_ELIGIBLE_SOURCE_PHASES`:
+// The generalized consultant triages two block classes whose source phase is in
+// `CONSULTANT_ELIGIBLE_SOURCE_PHASES`:
 //   - a coder-blocked signal (`coder_scope`/`coder_response`/`coder_optional_response`,
 //     which also carries the rerouted split-plan invalid-payload block): the coder
 //     emits free-text blockers with no structural prefix, so ANY coder block on these
@@ -62,53 +62,54 @@ function isInteractiveBlockedRecoveryTopLevelMode(state) {
 // Every other accepted source phase (`coder_plan`, `coder_plan_response`,
 // `coder_plan_optional_response`, `awaiting_derived_plan_execution`,
 // `execute_finalization`, `final_completion_review`) is ineligible and keeps today's
-// generic recovery behavior with zero adjudicator invocations.
-function isAdjudicatorEligibleBlock(reason, sourcePhase) {
-    if (!ADJUDICATOR_ELIGIBLE_SOURCE_PHASES.has(sourcePhase)) {
+// generic recovery behavior with zero consultant invocations.
+function isConsultantEligibleBlock(reason, sourcePhase) {
+    if (!CONSULTANT_ELIGIBLE_SOURCE_PHASES.has(sourcePhase)) {
         return false;
     }
-    if (isReviewerAdjudicatorPhase(sourcePhase)) {
+    if (isReviewerConsultantPhase(sourcePhase)) {
         return reason.startsWith('review_stuck:');
     }
     return true;
 }
-// Whether the per-scope adjudicator budget allows another invocation. Returns
-// false when the disable knob is 0 or `reviewStuckArbiterCount` has reached the
+// Whether the per-scope consultant budget allows another invocation. Returns
+// false when the disable knob is 0 or `consultantAttemptCount` has reached the
 // configured maximum for the current scope. Both the disabled and the
-// budget-exhausted cases emit NO `review_stuck_arbiter.*` events so they preserve
-// the generic recovery path byte-for-byte: a disabled or exhausted adjudicator
-// must be indistinguishable from the adjudicator never having existed.
-// The single uniform budget is shared by both run modes — an invocation
-// consumes one unit whether it auto-acts (unattended) or only produces advice
-// (attended) — and is reset to 0 at every scope boundary (see the scope-advance
-// transitions and the split-plan persist) so one scope's adjudication never
-// exhausts a later scope.
-function isAdjudicatorBudgetAvailable(state) {
-    const maxAttempts = getReviewStuckArbiterMaxAttempts(state.cwd);
+// budget-exhausted cases emit NO `consultant.*` events so they preserve
+// the generic recovery path byte-for-byte: a disabled or exhausted consultant
+// must be indistinguishable from the consultant never having existed.
+// The single uniform budget is shared by both run modes — an invocation consumes
+// one unit whether it auto-applies a recoverable verdict (either mode) or, on a
+// non-recoverable verdict, finalizes terminally (unattended) or produces advice
+// and yields (attended) — and is reset to 0 at every scope boundary (see the
+// scope-advance transitions and the split-plan persist) so one scope's
+// adjudication never exhausts a later scope.
+function isConsultantBudgetAvailable(state) {
+    const maxAttempts = getConsultantMaxAttempts(state.cwd);
     if (maxAttempts <= 0) {
         return false;
     }
-    return state.reviewStuckArbiterCount < maxAttempts;
+    return state.consultantAttemptCount < maxAttempts;
 }
 // Unattended interception for every eligible block class. Runs the read-only
-// adjudicator (which may itself short-circuit on an anti-thrash repeat) and, on a
+// consultant (which may itself short-circuit on an anti-thrash repeat) and, on a
 // recoverable verdict with a concrete in-scope directive, enters interactive
 // recovery with that directive injected as the pending turn — bounded by a
-// SEPARATE counter (`reviewStuckArbiterCount`) that never touches
+// SEPARATE counter (`consultantAttemptCount`) that never touches
 // `unattendedAutoResumeCount` or the recovery turn cap. A non-recoverable verdict
 // (including a thrash repeat) is finalized TERMINALLY rather than silently
-// auto-resumed. Every gate that prevents the adjudicator from running — an
+// auto-resumed. Every gate that prevents the consultant from running — an
 // ineligible source phase, the disabled/exhausted budget, the turn cap, or an
-// adjudicator error — returns null so the caller falls through to the existing
+// consultant error — returns null so the caller falls through to the existing
 // generic auto-resume / terminal-fail path with `recentBlocks` left unchanged.
-// The adjudicator itself makes zero commits and zero file edits; this function is
+// The consultant itself makes zero commits and zero file edits; this function is
 // the sole writer of `recentBlocks`, and only on the branches where the
-// adjudicator actually ran.
+// consultant actually ran.
 async function maybeResolveBlockedUnattended(state, statePath, reason, sourcePhase, nextRecovery, logger) {
-    if (!isAdjudicatorEligibleBlock(reason, sourcePhase)) {
+    if (!isConsultantEligibleBlock(reason, sourcePhase)) {
         return null;
     }
-    if (!isAdjudicatorBudgetAvailable(state)) {
+    if (!isConsultantBudgetAvailable(state)) {
         return null;
     }
     // Never push past the recovery turn cap; if there is no room for a recovery
@@ -116,20 +117,20 @@ async function maybeResolveBlockedUnattended(state, statePath, reason, sourcePha
     if (nextRecovery.turns.length >= nextRecovery.maxTurns) {
         return null;
     }
-    await logger?.event('review_stuck_arbiter.start', {
+    await logger?.event('consultant.start', {
         scopeNumber: state.currentScopeNumber,
         sourcePhase,
         blockedReason: reason,
     });
     let verdict;
     try {
-        verdict = await runBlockedAdjudicator(state, reason, sourcePhase, logger);
+        verdict = await runConsultant(state, reason, sourcePhase, logger);
     }
     catch (error) {
-        // An adjudicator failure must never crash the run or weaken existing recovery;
+        // An consultant failure must never crash the run or weaken existing recovery;
         // record the decline and fall through to the generic path with `recentBlocks`
-        // unchanged (the adjudicator did not complete for this block).
-        await logger?.event('review_stuck_arbiter.declined', {
+        // unchanged (the consultant did not complete for this block).
+        await logger?.event('consultant.declined', {
             scopeNumber: state.currentScopeNumber,
             sourcePhase,
             blockedReason: reason,
@@ -137,11 +138,11 @@ async function maybeResolveBlockedUnattended(state, statePath, reason, sourcePha
         });
         return null;
     }
-    // The adjudicator ran (possibly short-circuiting internally on a thrash repeat),
+    // The consultant ran (possibly short-circuiting internally on a thrash repeat),
     // so this block is recorded in the anti-thrash window regardless of the verdict.
     // The candidate is built from the PRE-update array and written in this same
     // transition, so a block can never match itself. It MUST be built from the same
-    // `state` snapshot `runBlockedAdjudicator` checked: the candidate's evidence
+    // `state` snapshot `runConsultant` checked: the candidate's evidence
     // fingerprint is derived from `state.createdCommits`, and a divergent snapshot
     // would record a fingerprint the guard never compared against.
     const candidate = buildRecentBlockCandidate(state, reason, sourcePhase);
@@ -150,22 +151,22 @@ async function maybeResolveBlockedUnattended(state, statePath, reason, sourcePha
     if (!verdict.recoverable || !resolutionDirective) {
         // Genuine wall (recoverable:false) or a thrash repeat: an unattended run has
         // no operator to escalate to, so finalize TERMINALLY instead of synthesizing a
-        // generic auto-resume. The adjudicator actually ran, so this branch consumes
-        // one unit of the shared per-scope budget (`reviewStuckArbiterCount`) exactly
+        // generic auto-resume. The consultant actually ran, so this branch consumes
+        // one unit of the shared per-scope budget (`consultantAttemptCount`) exactly
         // like the recoverable branch, and persists the anti-thrash record via the
-        // threaded `recentBlocks`. Only the fallback paths where `runBlockedAdjudicator`
+        // threaded `recentBlocks`. Only the fallback paths where `runConsultant`
         // was never invoked leave the budget untouched.
-        await logger?.event('review_stuck_arbiter.declined', {
+        await logger?.event('consultant.declined', {
             scopeNumber: state.currentScopeNumber,
             sourcePhase,
             blockedReason: reason,
             recoverable: verdict.recoverable,
             triageCategory: verdict.triageCategory,
-            reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1,
+            consultantAttemptCount: state.consultantAttemptCount + 1,
         });
-        return failUnattendedRecoveryTerminally({ ...state, recentBlocks, reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1 }, statePath, 'terminal_block', state.coderSessionHandle, logger);
+        return failUnattendedRecoveryTerminally({ ...state, recentBlocks, consultantAttemptCount: state.consultantAttemptCount + 1 }, statePath, 'terminal_block', state.coderSessionHandle, logger);
     }
-    await logger?.event('review_stuck_arbiter.verdict', {
+    await logger?.event('consultant.verdict', {
         scopeNumber: state.currentScopeNumber,
         sourcePhase,
         blockedReason: reason,
@@ -174,92 +175,69 @@ async function maybeResolveBlockedUnattended(state, statePath, reason, sourcePha
         targetCanonicalIds: verdict.targetCanonicalIds,
         // Report the post-increment count this verdict is about to consume so the
         // verdict and the later `resolved` event agree on the budget figure.
-        reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1,
+        consultantAttemptCount: state.consultantAttemptCount + 1,
     });
-    // Enter recovery exactly as the generic unattended path does, but increment
-    // the SEPARATE adjudicator counter (never `unattendedAutoResumeCount`) and
-    // persist the anti-thrash record.
-    const enteredState = await saveState(statePath, {
-        ...state,
-        recentBlocks,
-        phase: 'interactive_blocked_recovery',
-        status: 'running',
-        blockedFromPhase: state.blockedFromPhase ?? state.phase,
-        reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1,
-        interactiveBlockedRecovery: {
-            ...nextRecovery,
-            sourcePhase,
-            blockedReason: reason,
-        },
-    });
-    await writeExecutionArtifacts(enteredState);
-    await logger?.event('interactive_blocked_recovery.entered', {
-        scopeNumber: enteredState.currentScopeNumber,
-        sourcePhase: enteredState.interactiveBlockedRecovery?.sourcePhase,
-        blockedReason: reason,
-    });
-    // Inject the adjudicator's in-scope directive as the pending recovery turn so
-    // the coder consumes it in runInteractiveBlockedRecoveryPhase, exactly like a
-    // human-supplied `neal resume --message`.
-    const resolvedState = await recordInteractiveBlockedRecoveryGuidance(statePath, resolutionDirective, logger);
-    await logger?.event('review_stuck_arbiter.resolved', {
-        scopeNumber: resolvedState.currentScopeNumber,
+    // Recoverable verdict with a concrete directive: auto-apply it (shared with the
+    // attended path) so the coder consumes the directive and the run continues.
+    return applyRecoverableConsultantDirective({
+        state,
+        statePath,
+        reason,
         sourcePhase,
-        blockedReason: reason,
-        recoverable: verdict.recoverable,
-        triageCategory: verdict.triageCategory,
-        targetCanonicalIds: verdict.targetCanonicalIds,
-        reviewStuckArbiterCount: resolvedState.reviewStuckArbiterCount,
+        nextRecovery,
+        recentBlocks,
+        resolutionDirective,
+        verdict,
+        logger,
     });
-    return resolvedState;
 }
-// Attended interception for every eligible block class. The adjudicator NEVER
+// Attended interception for every eligible block class. The consultant NEVER
 // auto-applies its verdict in attended mode; instead it triages read-only and the
 // verdict is returned as advice (plus the updated anti-thrash window) for the
 // caller to persist alongside the operator yield. Gated by the SAME eligibility +
 // disable knob + per-scope budget as the unattended path; when any gate blocks the
-// adjudicator (ineligible phase, knob 0, exhausted budget, or an adjudicator
+// consultant (ineligible phase, knob 0, exhausted budget, or an consultant
 // error) this returns null and the caller yields exactly as today with no advice,
 // no budget consumption, and `recentBlocks` unchanged.
 //
-// The adjudicator runs BEFORE any `review_stuck_arbiter.*` event is emitted, so an
-// adjudicator error degrades to today's plain attended yield with a byte-for-byte
-// generic observable surface: zero adjudicator events, no advice, and no
+// The consultant runs BEFORE any `consultant.*` event is emitted, so an
+// consultant error degrades to today's plain attended yield with a byte-for-byte
+// generic observable surface: zero consultant events, no advice, and no
 // counter/`recentBlocks` mutation. The `start`/`verdict` audit pair is emitted only
-// once the adjudicator has actually produced a verdict for this block.
-async function buildAttendedAdjudicatorAdvice(state, reason, sourcePhase, logger) {
-    if (!isAdjudicatorEligibleBlock(reason, sourcePhase)) {
+// once the consultant has actually produced a verdict for this block.
+async function buildAttendedConsultantAdvice(state, reason, sourcePhase, logger) {
+    if (!isConsultantEligibleBlock(reason, sourcePhase)) {
         return null;
     }
-    if (!isAdjudicatorBudgetAvailable(state)) {
+    if (!isConsultantBudgetAvailable(state)) {
         return null;
     }
     let verdict;
     try {
-        verdict = await runBlockedAdjudicator(state, reason, sourcePhase, logger);
+        verdict = await runConsultant(state, reason, sourcePhase, logger);
     }
     catch {
         // Degrade to today's plain attended yield: never crash the run, and emit NO
-        // `review_stuck_arbiter.*` events so the fallback is indistinguishable from the
+        // `consultant.*` events so the fallback is indistinguishable from the
         // disabled/exhausted/ineligible generic yield.
         return null;
     }
-    await logger?.event('review_stuck_arbiter.start', {
+    await logger?.event('consultant.start', {
         scopeNumber: state.currentScopeNumber,
         sourcePhase,
         blockedReason: reason,
     });
-    await logger?.event('review_stuck_arbiter.verdict', {
+    await logger?.event('consultant.verdict', {
         scopeNumber: state.currentScopeNumber,
         sourcePhase,
         blockedReason: reason,
         recoverable: verdict.recoverable,
         triageCategory: verdict.triageCategory,
         targetCanonicalIds: verdict.targetCanonicalIds,
-        reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1,
+        consultantAttemptCount: state.consultantAttemptCount + 1,
     });
     // Same-snapshot rule as the unattended writer: the recorded candidate's
-    // commit-trail evidence fingerprint must come from the `state` the adjudicator
+    // commit-trail evidence fingerprint must come from the `state` the consultant
     // just checked, never a fresher snapshot.
     const candidate = buildRecentBlockCandidate(state, reason, sourcePhase);
     const recentBlocks = upsertRecentBlock(state.recentBlocks, candidate);
@@ -270,7 +248,47 @@ async function buildAttendedAdjudicatorAdvice(state, reason, sourcePhase, logger
         resolutionDirective: verdict.resolutionDirective,
         rationale: verdict.rationale,
     };
-    return { advice, recentBlocks };
+    return { advice, recentBlocks, verdict };
+}
+// Applies a recoverable consultant verdict — shared by both run modes. Enters
+// interactive recovery and injects the consultant's in-scope directive as the
+// pending turn, exactly like a human-supplied `neal resume --message`, so the
+// coder consumes it and the run continues. Consumes one unit of the per-scope
+// consultant budget (`consultantAttemptCount`, never `unattendedAutoResumeCount`)
+// and persists the anti-thrash `recentBlocks`. The caller has already emitted the
+// `consultant.verdict` audit event for this verdict.
+async function applyRecoverableConsultantDirective(args) {
+    const { state, statePath, reason, sourcePhase, nextRecovery, recentBlocks, resolutionDirective, verdict, logger } = args;
+    const enteredState = await saveState(statePath, {
+        ...state,
+        recentBlocks,
+        phase: 'interactive_blocked_recovery',
+        status: 'running',
+        blockedFromPhase: state.blockedFromPhase ?? state.phase,
+        consultantAttemptCount: state.consultantAttemptCount + 1,
+        interactiveBlockedRecovery: {
+            ...nextRecovery,
+            sourcePhase,
+            blockedReason: reason,
+        },
+    });
+    await writeExecutionArtifacts(enteredState);
+    await logger?.event('interactive_blocked_recovery.entered', {
+        scopeNumber: enteredState.currentScopeNumber,
+        sourcePhase: enteredState.interactiveBlockedRecovery?.sourcePhase,
+        blockedReason: reason,
+    });
+    const resolvedState = await recordInteractiveBlockedRecoveryGuidance(statePath, resolutionDirective, logger);
+    await logger?.event('consultant.resolved', {
+        scopeNumber: resolvedState.currentScopeNumber,
+        sourcePhase,
+        blockedReason: reason,
+        recoverable: verdict.recoverable,
+        triageCategory: verdict.triageCategory,
+        targetCanonicalIds: verdict.targetCanonicalIds,
+        consultantAttemptCount: resolvedState.consultantAttemptCount,
+    });
+    return resolvedState;
 }
 export async function enterInteractiveBlockedRecovery(state, statePath, reason, logger) {
     if (!isInteractiveBlockedRecoveryTopLevelMode(state)) {
@@ -293,14 +311,14 @@ export async function enterInteractiveBlockedRecovery(state, statePath, reason,
     // the persisted counter and the recovery turn cap, never on guidance text.
     if (state.unattended) {
         // Before the generic auto-resume/terminal-fail decision, give the bounded
-        // read-only adjudicator a chance to triage the block: autonomously resolve it
+        // read-only consultant a chance to triage the block: autonomously resolve it
         // with an in-scope directive (recoverable) or finalize terminally (a genuine
         // wall or thrash repeat). Any ineligible source phase, disabled/exhausted
-        // budget, turn cap, or adjudicator error falls through to the existing generic
+        // budget, turn cap, or consultant error falls through to the existing generic
         // behavior unchanged.
-        const adjudicatorResolved = await maybeResolveBlockedUnattended(state, statePath, reason, sourcePhase, nextRecovery, logger);
-        if (adjudicatorResolved) {
-            return adjudicatorResolved;
+        const consultantResolved = await maybeResolveBlockedUnattended(state, statePath, reason, sourcePhase, nextRecovery, logger);
+        if (consultantResolved) {
+            return consultantResolved;
         }
         const canAutoResume = state.unattendedAutoResumeCount < UNATTENDED_MAX_AUTO_RESUMES &&
             nextRecovery.turns.length < nextRecovery.maxTurns;
@@ -341,16 +359,33 @@ export async function enterInteractiveBlockedRecovery(state, statePath, reason,
         // loop then proceeds into runInteractiveBlockedRecoveryPhase to consume it.
         return recordInteractiveBlockedRecoveryGuidance(statePath, UNATTENDED_AUTO_RESUME_GUIDANCE, logger);
     }
-    // Attended runs still stop and wait for the operator; the adjudicator only adds
-    // its verdict as advice (and never auto-applies it). When the disable knob,
-    // budget, or eligibility gate the adjudicator off, this returns null and the run
-    // yields exactly as today with no advice, no budget consumption, and
-    // `recentBlocks` unchanged.
-    const advisory = await buildAttendedAdjudicatorAdvice(state, reason, sourcePhase, logger);
+    // Attended runs run the same bounded read-only consultant. On a recoverable
+    // verdict with a concrete directive, they auto-apply it exactly as unattended
+    // runs do — the consultant's advice is acted on in both modes. On a genuine wall
+    // (recoverable:false), or when the disable knob / budget / eligibility gate the
+    // consultant off, the attended run yields for the operator, carrying the verdict
+    // as advice when there is one so the operator sees why it stopped.
+    const advisory = await buildAttendedConsultantAdvice(state, reason, sourcePhase, logger);
+    if (advisory) {
+        const resolutionDirective = advisory.advice.resolutionDirective.trim();
+        if (advisory.advice.recoverable && resolutionDirective) {
+            return applyRecoverableConsultantDirective({
+                state,
+                statePath,
+                reason,
+                sourcePhase,
+                nextRecovery,
+                recentBlocks: advisory.recentBlocks,
+                resolutionDirective,
+                verdict: advisory.verdict,
+                logger,
+            });
+        }
+    }
     const nextState = await saveState(statePath, {
         ...state,
         ...(advisory
-            ? { recentBlocks: advisory.recentBlocks, reviewStuckArbiterCount: state.reviewStuckArbiterCount + 1 }
+            ? { recentBlocks: advisory.recentBlocks, consultantAttemptCount: state.consultantAttemptCount + 1 }
             : {}),
         phase: 'interactive_blocked_recovery',
         status: 'running',
@@ -359,7 +394,7 @@ export async function enterInteractiveBlockedRecovery(state, statePath, reason,
             ...nextRecovery,
             sourcePhase,
             blockedReason: reason,
-            ...(advisory ? { adjudicatorAdvice: advisory.advice } : {}),
+            ...(advisory ? { consultantAdvice: advisory.advice } : {}),
         },
     });
     await writeExecutionArtifacts(nextState);
@@ -371,14 +406,15 @@ export async function enterInteractiveBlockedRecovery(state, statePath, reason,
     return nextState;
 }
 // Whether a caller of `enterInteractiveBlockedRecovery` should emit an attended
-// blocked / interactive-recovery notification for the returned state. Only
-// attended runs leave a pending operator block here; unattended runs instead
-// auto-resume (status:'running' with synthesized guidance) or terminally fail
-// (status:'failed', phase:'blocked'), neither of which warrants an attended
-// notification. Gate structurally on the persisted flag and resulting phase,
-// never on text.
+// blocked / interactive-recovery notification for the returned state. Notify only
+// when an attended run is actually WAITING for the operator. An attended run whose
+// block the consultant auto-fixed leaves a pending directive to consume (status
+// 'running', a recorded recovery turn) — that is `waitingForOperatorGuidance:
+// false`, so it must not notify. Unattended runs never wait here (they auto-resume
+// or terminally fail), so `!state.unattended` already excludes them. Gate
+// structurally on the derived recovery view, never on text.
 export function shouldNotifyInteractiveBlockedRecoveryEntry(state) {
-    return !state.unattended && state.phase === 'interactive_blocked_recovery';
+    return !state.unattended && (getInteractiveRecoveryView(state)?.waitingForOperatorGuidance ?? false);
 }
 export async function recordInteractiveBlockedRecoveryGuidance(statePath, operatorGuidance, logger) {
     const trimmedGuidance = operatorGuidance.trim();

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

@@ -5,7 +5,7 @@ import { getChangedFilesForRange, getCommitRange, getDiffForRange, getDiffStatFo
 import { writeDetail } from '../../diagnostic.js';
 import { saveState } from '../../state.js';
 import { writeExecutionArtifacts } from '../artifacts.js';
-import { shouldNotifyFailure } from '../failures.js';
+import { REVIEWER_CONTENT_REFUSED_BLOCK_REASON, shouldNotifyFailure } from '../failures.js';
 import { notifyBlocked } from '../notifications.js';
 import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry } from './recovery.js';
 import { printReviewResult } from './shared.js';
@@ -52,6 +52,33 @@ export async function runReviewPhase(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
+            // instead of a generic terminal failure. This must RETURN the terminal
+            // blocked state (phase:'blocked'/status:'blocked'), never throw — a thrown
+            // error over a persisted blocked state escapes executeRun, and the run loop
+            // only exits cleanly on a returned terminal phase.
+            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_scope',
+                    round: state.rounds.length + 1,
+                    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,

package/dist/neal/orchestrator/transitions.js

@@ -8,8 +8,14 @@ export function createScopeBoundaryReset() {
         currentScopeMeaningfulProgressVerdict: null,
         rounds: [],
         recentBlocks: [],
-        reviewStuckArbiterCount: 0,
+        consultantAttemptCount: 0,
         findings: [],
+        // planReviewDebt is a projection of the current findings, so clearing
+        // findings must clear it too (toPlanReviewDebt([]) === []); otherwise a new
+        // derived-plan negotiation would carry stale current-negotiation debt. The
+        // durable inheritedPlanReviewDebt is intentionally NOT reset here — it is
+        // write-once and survives scope boundaries.
+        planReviewDebt: [],
         createdCommits: [],
     };
 }

package/dist/neal/orchestrator.js

@@ -81,6 +81,9 @@ export async function initializeOrchestration(planDoc, cwd, agentConfig, topLeve
         reviewMarkdownPath: join(logger.runDir, 'REVIEW.md'),
         recoveryMarkdownPath: join(logger.runDir, 'RECOVERY.md'),
         maxRounds: getMaxReviewRounds(cwd),
+        // Only the `neal run` queue's execution stage supplies this; every other
+        // caller omits it and the durable inherited debt seeds to an empty array.
+        inheritedPlanReviewDebt: options?.inheritedPlanReviewDebt,
     };
     await mkdir(stateDir, { recursive: true });
     const baseCommit = await getHeadCommit(cwd);

package/dist/neal/plan-queue.js

@@ -9,7 +9,7 @@ import { writeExecutionArtifacts } from './orchestrator/artifacts.js';
 import { assertAgentConfigSupportsResume, assertAgentConfigSupportsWriterRun } from './providers/registry.js';
 import { writeCurrentRunPointer } from './run-registry.js';
 import { formatPublicRunStatus, getRunDisplayStatus } from './run-status.js';
-import { getRunStatePath, loadState, saveState } from './state.js';
+import { getRunStatePath, hydrateResidualReviewDebtItem, loadState, saveState } from './state.js';
 import { QUEUE_LINK_FILE, QUEUE_STATE_FILE, QUEUE_SUMMARY_FILE, getCurrentPlanAndExecuteQueuePointerPath as getStorageCurrentPlanAndExecuteQueuePointerPath, getQueuesDir, } from './storage-paths.js';
 import { executeRun, withPreparedWriterRun, } from './commands/runtime.js';
 import { filterAllowedDirtyPathStatus, filterWrapperOwnedWorktreeStatus, parseWorktreeStatusLine, } from './worktree-status.js';
@@ -114,6 +114,7 @@ export async function createPlanAndExecuteQueue(args) {
             planningRunId: null,
             planningStatePath: null,
             acceptedPlanPath: null,
+            planReviewDebt: [],
             executionRunId: null,
             executionStatePath: null,
             activeStage: null,
@@ -496,6 +497,10 @@ async function runFreshPlanAndExecuteChild(args, onInitialized) {
             // initialized, the run state is the single source of truth for
             // this run — `neal resume` reads it back from there.
             autoSquashOnCompletion: args.squashOnCompletion,
+            // Only the execution child inherits the accepted plan's plan-review
+            // debt (into the durable inheritedPlanReviewDebt state field). The
+            // planning child recomputes its own planReviewDebt from scratch.
+            inheritedPlanReviewDebt: args.stage === 'execution' ? args.item.planReviewDebt : undefined,
         });
         markInitialized();
         assertAgentConfigSupportsWriterRun(loaded.state.agentConfig, { context: `${args.stage} queue child` });
@@ -581,6 +586,11 @@ async function completePlanningStage(state, itemIndex, finalState, deps) {
             ...item,
             status: 'planned',
             acceptedPlanPath,
+            // Carry the accepted plan's current-negotiation debt onto the queue item
+            // so the fresh execution child inherits it (both the in-process completion
+            // and the cross-process continuePlanAndExecuteQueueFromChildRun resume
+            // route through here).
+            planReviewDebt: finalState.planReviewDebt,
             activeStage: null,
             stopReason: null,
         }),
@@ -916,6 +926,10 @@ function parsePlanAndExecuteQueueItem(value, expectedIndex, cwd) {
         planningRunId: requireNullableString(item.planningRunId, 'Invalid queue state: malformed planningRunId'),
         planningStatePath,
         acceptedPlanPath,
+        // Legacy-tolerant: queue items persisted before this field existed default
+        // to an empty debt array. Present arrays are hydrated with the shared
+        // residual-debt validator so an older/newer field shape is caught.
+        planReviewDebt: parseQueueItemPlanReviewDebt(item.planReviewDebt),
         executionRunId: requireNullableString(item.executionRunId, 'Invalid queue state: malformed executionRunId'),
         executionStatePath,
         activeStage: requireNullableQueueChildStage(item.activeStage, 'Invalid queue state: malformed activeStage'),
@@ -924,6 +938,20 @@ function parsePlanAndExecuteQueueItem(value, expectedIndex, cwd) {
         stopReason: requireNullableString(item.stopReason, 'Invalid queue state: malformed item stopReason'),
     };
 }
+function parseQueueItemPlanReviewDebt(value) {
+    // Legacy-tolerant ONLY for a genuinely absent field: queue items persisted
+    // before this field existed omit it entirely (undefined), and those default to
+    // an empty debt array. A PRESENT null (or any other non-array) is corrupted
+    // state that would silently erase accepted plan-review debt, so it is rejected
+    // as malformed rather than defaulted away.
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('Invalid queue state: malformed planReviewDebt');
+    }
+    return value.map((item, index) => hydrateResidualReviewDebtItem(item, `queue item planReviewDebt[${index}]`));
+}
 function parseCurrentPlanAndExecuteQueuePointer(value, cwd) {
     if (!value || typeof value !== 'object') {
         throw new Error('Invalid .neal/current-queue.json: expected object');