@navels/neal 0.2.0 → 0.3.1

package/dist/neal/config.js

@@ -13,13 +13,14 @@ const DEFAULT_CONFIG = {
         phase_heartbeat_ms: 60_000,
         max_review_rounds: 20,
         review_stuck_window: 5,
+        plan_review_debt_round_threshold: 3,
         inactivity_timeout_ms: 600_000,
         api_retry_limit: 10,
         agent_turn_startup_timeout_ms: 300_000,
         agent_turn_retry_limit: 1,
         interactive_blocked_recovery_max_turns: 3,
         final_completion_continue_execution_max: 2,
-        review_stuck_arbiter_max_attempts: 1,
+        consultant_max_attempts: 1,
         notify_bin: null,
     },
     agent: {
@@ -51,7 +52,7 @@ function buildWriterProviderSetupLines(guidance, missingProviderKeys) {
     }
     return [
         'Neal is not set up yet.',
-        `Run \`neal setup\` to choose providers, or set ${formatInlineList(missingKeys)} in config.yml.`,
+        `Run \`neal setup\` to choose providers, or set ${formatInlineList(missingKeys)} in neal.yml.`,
     ];
 }
 function formatInlineList(values) {
@@ -173,7 +174,7 @@ function mergeConfig(base, override) {
     };
 }
 export function getConfigSourceInfo(cwd = process.cwd()) {
-    const repoPath = resolve(cwd, 'config.yml');
+    const repoPath = resolve(cwd, 'neal.yml');
     const userPath = join(homedir(), '.neal', 'config.yml');
     return {
         repo: {
@@ -293,11 +294,19 @@ export function getReviewStuckWindow(cwd = process.cwd()) {
     return (parseNumberValue(config.neal?.review_stuck_window) ??
         DEFAULT_CONFIG.neal.review_stuck_window);
 }
-export function getReviewStuckArbiterMaxAttempts(cwd = process.cwd()) {
+// The reviewer round at or past which a novel verification-hardening plan-review
+// finding converts to recorded plan-review debt instead of forcing another
+// revision round. Read at the decision site by cwd, mirroring getMaxReviewRounds.
+export function getPlanReviewDebtRoundThreshold(cwd = process.cwd()) {
     const config = loadConfigFile(cwd);
-    const raw = parseNumberValue(config.neal?.review_stuck_arbiter_max_attempts) ??
-        DEFAULT_CONFIG.neal.review_stuck_arbiter_max_attempts;
-    // Clamp to a non-negative integer (0 disables the arbiter entirely).
+    return (parseNumberValue(config.neal?.plan_review_debt_round_threshold) ??
+        DEFAULT_CONFIG.neal.plan_review_debt_round_threshold);
+}
+export function getConsultantMaxAttempts(cwd = process.cwd()) {
+    const config = loadConfigFile(cwd);
+    const raw = parseNumberValue(config.neal?.consultant_max_attempts) ??
+        DEFAULT_CONFIG.neal.consultant_max_attempts;
+    // Clamp to a non-negative integer (0 disables the consultant entirely).
     if (!Number.isFinite(raw) || raw <= 0) {
         return 0;
     }

package/dist/neal/context/inline-review-context.js

@@ -4,8 +4,9 @@ import { getProviderDefinition, isRegisteredProviderId } from '../providers/regi
 // truncation posture of truncateForPrompt in src/neal/agents/structured-json.ts:
 // truncate with an explicit marker instead of silently dropping content.
 export const INLINE_SECTION_MAX_CHARS = 200_000;
-// Canonical forbidden-phrase list for no-read reviewer prompts. A no-read
-// reviewer prompt must contain no instruction that requires repository, file,
+// Canonical forbidden-phrase list for no-read prompts (today: the blocked-run
+// consultant, which always judges from Neal-inlined in-memory context). A
+// no-read prompt must contain no instruction that requires repository, file,
 // tool, or shell access of any kind. Both the prompt-builder implementations
 // and the runtime capture tests assert against this shared list, so a newly
 // added repo-access phrase fails the shared assertion rather than silently
@@ -22,31 +23,18 @@ export const NO_READ_PROMPT_FORBIDDEN_MARKERS = [
     'is available at',
     'Inspect cited artifacts',
 ];
-// True when the configured reviewer provider's structured-advisor role has no
-// repository read access, so Neal must inline the review context (diff, plan,
-// artifacts) into reviewer prompts.
-export function reviewerNeedsInlineContext(reviewer) {
-    if (!isRegisteredProviderId(reviewer.provider)) {
-        return false;
-    }
-    return getProviderDefinition(reviewer.provider).capabilities['structured-advisor'].toolAccess.read === false;
-}
-// Three-way review-doctrine access mode for the configured reviewer provider's
-// structured-advisor role. Unregistered provider ids default to 'tool-access',
-// mirroring reviewerNeedsInlineContext's false. No repository read access
-// selects 'no-read' (Neal inlines the review context); read access without
-// shell access selects 'read-only' (the reviewer inspects the repository with
-// read tools but must not be instructed to run commands); read plus shell
-// access selects 'tool-access'. Write access does not affect review doctrine:
-// reviews never instruct repository mutation.
+// Two-way review-doctrine access mode for the configured reviewer provider's
+// structured-advisor role. Unregistered provider ids default to 'tool-access'.
+// Every registered reviewer provider has repository read access; read access
+// without shell access selects 'read-only' (the reviewer inspects the
+// repository with read tools but must not be instructed to run commands);
+// read plus shell access selects 'tool-access'. Write access does not affect
+// review doctrine: reviews never instruct repository mutation.
 export function getReviewerDoctrineAccessMode(reviewer) {
     if (!isRegisteredProviderId(reviewer.provider)) {
         return 'tool-access';
     }
     const toolAccess = getProviderDefinition(reviewer.provider).capabilities['structured-advisor'].toolAccess;
-    if (toolAccess.read === false) {
-        return 'no-read';
-    }
     if (toolAccess.shell === false) {
         return 'read-only';
     }
@@ -55,12 +43,9 @@ export function getReviewerDoctrineAccessMode(reviewer) {
 // True when the configured reviewer is a read-only reviewer (read tools, no
 // shell) that has no commit-range diff tool of its own, so Neal must inline the
 // commit-range diff into its reviewer prompt. Read-only reviewers that expose a
-// commit-range diff tool (providesRangeDiffTool === true, e.g. generic-agentic)
-// inspect the range with that tool and do not receive an inlined diff; no-read
-// reviewers get the full inlineContext instead, and tool-access reviewers run
-// shell git themselves. The inlined commit-range diff rides a dedicated prompt
-// channel separate from the no-read inlineContext channel, so it never trips
-// resolveReviewerPromptAccessMode's no-read-only inlineContext guard.
+// commit-range diff tool (providesRangeDiffTool === true, e.g. openai-compatible)
+// inspect the range with that tool and do not receive an inlined diff, and
+// tool-access reviewers run shell git themselves.
 export function readOnlyReviewerNeedsInlinedDiff(reviewer) {
     if (!isRegisteredProviderId(reviewer.provider)) {
         return false;

package/dist/neal/context/reviewer-context.js

@@ -37,6 +37,13 @@ export function buildReviewerContextPacket(args) {
         claim: finding.claim,
         requiredAction: finding.requiredAction,
     }));
+    const inheritedPlanReviewDebt = state.inheritedPlanReviewDebt.map((item) => ({
+        canonicalId: item.canonicalId,
+        findingClass: item.findingClass ?? null,
+        originRound: item.originRound ?? null,
+        claim: item.claim,
+        requiredAction: item.requiredAction,
+    }));
     const finalCompletion = summarizeFinalCompletion(state);
     const packetWithoutMarkdown = {
         version: 1,
@@ -55,6 +62,7 @@ export function buildReviewerContextPacket(args) {
         },
         completedScopes,
         findings,
+        inheritedPlanReviewDebt,
         finalCompletion,
         citations: buildReviewerContextCitations(state),
         limits: {
@@ -100,21 +108,21 @@ function buildReviewerContextCitations(state) {
         { label: REVIEWER_CONTEXT_MARKDOWN, path: toDisplayPath(state.cwd, join(state.runDir, REVIEWER_CONTEXT_MARKDOWN)) },
     ];
 }
-export function renderReviewerContextMarkdown(packet, options = {}) {
-    const mode = options.mode ?? 'tool-access';
+export function renderReviewerContextMarkdown(packet) {
     const scopeLines = packet.completedScopes.length
         ? packet.completedScopes.map((scope) => `- Scope ${scope.number}: ${scope.result}; marker=${scope.marker}; finalCommit=${scope.finalCommit ?? 'none'}; reviewRounds=${scope.reviewRounds}; findings=${scope.findings}; residualDebt=${scope.residualReviewDebt}; summary=${scope.summary ?? 'none'}`)
         : ['- none'];
     const findingLines = packet.findings.length
         ? packet.findings.map((finding) => `- ${finding.canonicalId} (${finding.id}): ${finding.severity}/${finding.status}; source=${finding.source}; files=${finding.files.join(', ') || 'none'}; claim=${finding.claim}; requiredAction=${finding.requiredAction}`)
         : ['- none'];
+    const inheritedDebtLines = packet.inheritedPlanReviewDebt.length
+        ? packet.inheritedPlanReviewDebt.map((item) => `- ${item.canonicalId}: findingClass=${item.findingClass ?? 'n/a'}; originRound=${item.originRound ?? 'n/a'}; claim=${item.claim}; requiredAction=${item.requiredAction}`)
+        : ['- none'];
     const finalCompletion = packet.finalCompletion;
     return [
         '# Reviewer Continuity Context',
         '',
-        mode === 'inline'
-            ? 'Use this bounded Neal-owned context for continuity only. All required review context is inlined into this prompt; you have no access to the cited run artifacts or the checkout.'
-            : 'Use this bounded Neal-owned context for continuity only. Inspect cited artifacts or repository state directly before making findings.',
+        'Use this bounded Neal-owned context for continuity only. Inspect cited artifacts or repository state directly before making findings.',
         '',
         '## Run',
         `- id: ${packet.run.id}`,
@@ -137,19 +145,16 @@ export function renderReviewerContextMarkdown(packet, options = {}) {
             ? `- truncated: showing latest ${packet.findings.length} of ${packet.limits.findingCount}`
             : '- truncated: no',
         '',
+        '## Inherited Plan-Review Debt',
+        ...inheritedDebtLines,
+        '',
         '## Final Completion',
         finalCompletion
             ? `- state=${finalCompletion.state}; effectiveAction=${finalCompletion.effectiveAction ?? 'none'}; hasSummary=${finalCompletion.hasSummary}; hasReviewVerdict=${finalCompletion.hasReviewVerdict}; continueExecutionCount=${finalCompletion.continueExecutionCount}; capReached=${finalCompletion.continueExecutionCapReached}`
             : '- not applicable',
-        // Citation paths are reading instructions; a no-read reviewer cannot
-        // follow them, so the inline rendering omits the section entirely.
-        ...(mode === 'inline'
-            ? []
-            : [
-                '',
-                '## Citations',
-                ...packet.citations.map((citation) => `- ${citation.label}: ${citation.path}`),
-            ]),
+        '',
+        '## Citations',
+        ...packet.citations.map((citation) => `- ${citation.label}: ${citation.path}`),
     ].join('\n');
 }
 function runIdFromDir(runDir) {

package/dist/neal/eval/reviewer-eval-manifest.js

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+function fail(context, message) {
+    throw new Error(`reviewer-eval manifest: ${context} ${message}`);
+}
+function asString(value, context, field) {
+    const candidate = value[field];
+    if (typeof candidate !== 'string' || candidate.trim() === '') {
+        fail(context, `must define a non-empty string ${field}`);
+    }
+    return candidate;
+}
+function parseExpectedFinding(raw, context) {
+    if (typeof raw !== 'object' || raw === null) {
+        fail(context, 'each expectedFindings entry must be an object');
+    }
+    return {
+        file: asString(raw, context, 'file'),
+        defectClass: asString(raw, context, 'defectClass'),
+        description: asString(raw, context, 'description'),
+    };
+}
+// Every path the diff adds or modifies, read from its `+++ b/<path>` headers.
+function diffTargetFiles(diffText) {
+    const files = new Set();
+    for (const line of diffText.split('\n')) {
+        const match = /^\+\+\+ b\/(.+)$/.exec(line);
+        if (match) {
+            files.add(match[1].trim());
+        }
+    }
+    return files;
+}
+export function loadReviewerEvalManifest(manifestDir) {
+    const dir = isAbsolute(manifestDir) ? manifestDir : resolve(manifestDir);
+    const manifestPath = join(dir, 'manifest.json');
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const rawFixtures = parsed.fixtures;
+    if (!Array.isArray(rawFixtures) || rawFixtures.length === 0) {
+        fail('manifest.json', 'must define a non-empty fixtures array');
+    }
+    const seen = new Set();
+    return rawFixtures.map((raw, index) => {
+        const context = `fixtures[${index}]`;
+        if (typeof raw !== 'object' || raw === null) {
+            fail(context, 'must be an object');
+        }
+        const id = asString(raw, context, 'id');
+        if (seen.has(id)) {
+            fail(context, `duplicate fixture id ${id}`);
+        }
+        seen.add(id);
+        const kind = raw.kind;
+        if (kind !== 'defective' && kind !== 'clean') {
+            fail(id, "kind must be 'defective' or 'clean'");
+        }
+        const diff = asString(raw, id, 'diff');
+        const baseDirRelative = asString(raw, id, 'baseDir');
+        const rawExpected = raw.expectedFindings;
+        if (!Array.isArray(rawExpected)) {
+            fail(id, 'expectedFindings must be an array');
+        }
+        const expectedFindings = rawExpected.map((entry) => parseExpectedFinding(entry, id));
+        if (kind === 'defective' && expectedFindings.length === 0) {
+            fail(id, 'a defective fixture must label at least one expected finding');
+        }
+        if (kind === 'clean' && expectedFindings.length > 0) {
+            fail(id, 'a clean fixture must not label any expected findings');
+        }
+        const diffPath = join(dir, diff);
+        const diffText = readFileSync(diffPath, 'utf8');
+        const targetFiles = diffTargetFiles(diffText);
+        for (const expected of expectedFindings) {
+            if (!targetFiles.has(expected.file)) {
+                fail(id, `expected finding file ${expected.file} is not modified by ${diff}`);
+            }
+        }
+        return {
+            id,
+            kind,
+            expectedFindings,
+            diffPath,
+            baseDir: join(dir, baseDirRelative),
+        };
+    });
+}

package/dist/neal/eval/reviewer-eval.js

@@ -0,0 +1,155 @@
+// Reviewer-recall eval scoring (issue #22 Phase B).
+//
+// Given a labeled fixture set — diffs with known defects, plus clean diffs —
+// and the findings a reviewer produced for each, this computes recall,
+// precision, and blocking-finding rate. It is the measurement instrument for
+// the eval-gated reviewer-doctrine rewrite (Phase C): run it against a
+// reviewer prompt before and after a change and compare the numbers.
+//
+// The scoring here is pure and deterministic; the live reviewer invocation
+// lives in scripts/eval-reviewer.mjs (operator-run, subscription-billed, like
+// scripts/qualify-sdk.sh). Matching is intentionally coarse — a blocking
+// finding matches an expected label when they name the same file — because a
+// finer match (defect-class, line range) would encode judgment the labels
+// cannot reliably carry. The coarseness is documented so a reader does not
+// over-trust the numbers: recall counts "did the reviewer flag the right
+// file", not "did it describe the exact defect".
+/**
+ * Projects a reviewer round's raw findings (as produced by the review-findings
+ * loop: objects carrying at least a severity and a files list) into a scored
+ * observation. Unknown severities are treated as non_blocking so a malformed
+ * finding cannot inflate the blocking count, and a missing files list becomes
+ * empty. Keeping this here lets the operator runner stay a thin shell over the
+ * tested scoring core.
+ */
+export function toReviewerEvalObservation(fixtureId, rawFindings) {
+    const findings = rawFindings.map((finding) => ({
+        severity: finding.severity === 'blocking' ? 'blocking' : 'non_blocking',
+        files: Array.isArray(finding.files) ? finding.files.filter((file) => typeof file === 'string') : [],
+    }));
+    return { fixtureId, findings };
+}
+function normalizeFilePath(path) {
+    return path.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function findingFileSet(observation) {
+    const files = new Set();
+    for (const finding of observation.findings) {
+        if (finding.severity !== 'blocking') {
+            continue;
+        }
+        for (const file of finding.files) {
+            files.add(normalizeFilePath(file));
+        }
+    }
+    return files;
+}
+/**
+ * Scores reviewer observations against labeled fixtures. Every fixture must
+ * have exactly one observation (missing observations throw — a fixture the
+ * runner failed to evaluate must not silently count as perfect recall).
+ */
+export function scoreReviewerEval(fixtures, observations) {
+    const observationById = new Map(observations.map((observation) => [observation.fixtureId, observation]));
+    const fixtureResults = [];
+    let totalExpectedLabels = 0;
+    let matchedLabels = 0;
+    let totalBlockingFindings = 0;
+    let truePositiveFindings = 0;
+    let falsePositiveFindings = 0;
+    let cleanFixturesFlagged = 0;
+    for (const fixture of fixtures) {
+        const observation = observationById.get(fixture.id);
+        if (!observation) {
+            throw new Error(`scoreReviewerEval: no observation for fixture ${fixture.id}`);
+        }
+        const blockingFindings = observation.findings.filter((finding) => finding.severity === 'blocking');
+        const blockingFindingCount = blockingFindings.length;
+        const findingFiles = findingFileSet(observation);
+        const matched = [];
+        const missed = [];
+        const labeledFiles = new Set();
+        for (const expected of fixture.expectedFindings) {
+            const file = normalizeFilePath(expected.file);
+            labeledFiles.add(file);
+            if (findingFiles.has(file)) {
+                matched.push(expected);
+            }
+            else {
+                missed.push(expected);
+            }
+        }
+        // A blocking finding is a true positive when it touches at least one
+        // labeled file; every other blocking finding (all of them on a clean
+        // fixture) is a false positive.
+        let truePositiveFindingCount = 0;
+        let falsePositiveFindingCount = 0;
+        for (const finding of blockingFindings) {
+            const touchesLabel = finding.files.some((file) => labeledFiles.has(normalizeFilePath(file)));
+            if (touchesLabel) {
+                truePositiveFindingCount += 1;
+            }
+            else {
+                falsePositiveFindingCount += 1;
+            }
+        }
+        totalExpectedLabels += fixture.expectedFindings.length;
+        matchedLabels += matched.length;
+        totalBlockingFindings += blockingFindingCount;
+        truePositiveFindings += truePositiveFindingCount;
+        falsePositiveFindings += falsePositiveFindingCount;
+        if (fixture.kind === 'clean' && blockingFindingCount > 0) {
+            cleanFixturesFlagged += 1;
+        }
+        fixtureResults.push({
+            fixtureId: fixture.id,
+            kind: fixture.kind,
+            matchedLabels: matched,
+            missedLabels: missed,
+            truePositiveFindingCount,
+            falsePositiveFindingCount,
+            blockingFindingCount,
+        });
+    }
+    const defectiveFixtures = fixtures.filter((fixture) => fixture.kind === 'defective').length;
+    const cleanFixtures = fixtures.filter((fixture) => fixture.kind === 'clean').length;
+    return {
+        fixtures: fixtureResults,
+        totalFixtures: fixtures.length,
+        defectiveFixtures,
+        cleanFixtures,
+        recall: totalExpectedLabels === 0 ? null : matchedLabels / totalExpectedLabels,
+        precision: totalBlockingFindings === 0 ? null : truePositiveFindings / totalBlockingFindings,
+        totalExpectedLabels,
+        matchedLabels,
+        totalBlockingFindings,
+        truePositiveFindings,
+        falsePositiveFindings,
+        cleanFalsePositiveRate: cleanFixtures === 0 ? null : cleanFixturesFlagged / cleanFixtures,
+        cleanFixturesFlagged,
+        blockingFindingRate: fixtures.length === 0 ? 0 : totalBlockingFindings / fixtures.length,
+    };
+}
+/**
+ * Renders a report as a compact human-readable table plus a summary line.
+ * The machine-readable form is the ReviewerEvalReport itself (write it as
+ * JSON); this is for terminal output.
+ */
+export function renderReviewerEvalReport(report) {
+    const pct = (value) => (value === null ? 'n/a' : `${(value * 100).toFixed(1)}%`);
+    const lines = [];
+    lines.push('| Fixture | Kind | Labels hit | Blocking | False+ |');
+    lines.push('|---|---|---:|---:|---:|');
+    for (const fixture of report.fixtures) {
+        const labels = fixture.kind === 'defective'
+            ? `${fixture.matchedLabels.length}/${fixture.matchedLabels.length + fixture.missedLabels.length}`
+            : '—';
+        lines.push(`| ${fixture.fixtureId} | ${fixture.kind} | ${labels} | ${fixture.blockingFindingCount} | ${fixture.falsePositiveFindingCount} |`);
+    }
+    lines.push('');
+    lines.push(`Recall ${pct(report.recall)} (${report.matchedLabels}/${report.totalExpectedLabels} labels) · ` +
+        `Precision ${pct(report.precision)} (${report.truePositiveFindings}/${report.totalBlockingFindings} findings) · ` +
+        `Clean false-positive ${pct(report.cleanFalsePositiveRate)} (${report.cleanFixturesFlagged}/${report.cleanFixtures}) · ` +
+        `Blocking rate ${report.blockingFindingRate.toFixed(2)}/fixture`);
+    return lines.join('\n');
+}

package/dist/neal/interactive-controls.js

@@ -1,6 +1,11 @@
 import { existsSync } from 'node:fs';
 import readline from 'node:readline';
 import { clearDiagnosticFooter, getBufferedDetailSnapshot, isDiagnosticDetailVisible, showDiagnosticDetailView, showDiagnosticNarrativeView, writeNarrative, } from './diagnostic.js';
+export function renderInteractiveKeyHint(allowStopRequest) {
+    return allowStopRequest
+        ? '[neal] keys: q stop after current scope, v show/hide details\n'
+        : '[neal] keys: v show/hide details\n';
+}
 export function createInteractiveKeyController(options = {}) {
     let stopRequested = false;
     let cleanedUp = false;

package/dist/neal/orchestrator/completion.js

@@ -21,7 +21,7 @@ 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 { REVIEWER_CONTENT_REFUSED_BLOCK_REASON, shouldNotifyFailure } from './failures.js';
 import { persistUnattendedBlockUnresolvedFailure } from './phases/shared.js';
 async function writeFailedFinalCompletionReviewArtifact(args) {
     const unstructuredOutput = await readFinalCompletionUnstructuredOutput({
@@ -52,6 +52,38 @@ async function persistFailedFinalCompletionReview(args) {
     });
     return failedState;
 }
+// Sibling of persistFailedFinalCompletionReview for the terminal blocked
+// landing of a reviewer content-safety refusal (`content_refused`). Only a
+// ReviewerRoundError can carry that kind; FinalCompletionReviewerVerdictError
+// never does, so persistFailedFinalCompletionReview keeps serving the
+// verdict-invalid path unchanged. Persists a terminal
+// phase:'blocked'/status:'blocked' state so the run ends blocked (exit 2)
+// rather than as a generic terminal failure, still writing the failed
+// final-completion review artifact and execution artifacts.
+async function persistBlockedFinalCompletionReview(args) {
+    const blockedState = await saveState(args.statePath, {
+        ...args.state,
+        phase: 'blocked',
+        reviewerSessionHandle: null,
+        status: 'blocked',
+        blockedFromPhase: null,
+        blockerReason: REVIEWER_CONTENT_REFUSED_BLOCK_REASON,
+    });
+    await args.runtime.writeExecutionArtifacts(blockedState);
+    await writeFailedFinalCompletionReviewArtifact({
+        state: blockedState,
+        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,
+        errorKind: args.error.kind,
+        message: args.error.message,
+    });
+    return blockedState;
+}
 function normalizeFinalCommitMessage(message) {
     const normalizedNewlines = message.replace(/\r\n/g, '\n');
     const convertedEscapes = normalizedNewlines.replace(/\\n(?=- )/g, '\n');
@@ -480,6 +512,21 @@ export async function runFinalCompletionReviewPhase(state, statePath, logger, ru
         }));
     }
     catch (error) {
+        // A reviewer content-safety refusal ends the run blocked (exit 2) with a
+        // durable actionable reason, by RETURNING the terminal blocked state rather
+        // than throwing. Only a ReviewerRoundError carries `content_refused`; the
+        // verdict-invalid error never does, so it stays on the failed path below.
+        if (error instanceof ReviewerRoundError && error.kind === 'content_refused') {
+            const blockedState = await persistBlockedFinalCompletionReview({
+                state,
+                statePath,
+                error,
+                logger,
+                runtime,
+            });
+            await notifyBlocked(blockedState, REVIEWER_CONTENT_REFUSED_BLOCK_REASON, logger);
+            return blockedState;
+        }
         if (error instanceof ReviewerRoundError || error instanceof FinalCompletionReviewerVerdictError) {
             const failedState = await persistFailedFinalCompletionReview({
                 state,
@@ -539,7 +586,7 @@ export async function runFinalCompletionReviewPhase(state, statePath, logger, ru
                 // 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` resets via the shared next-scope
+                // (`consultantAttemptCount` resets via the shared next-scope
                 // reset spread above.)
                 splitPlanCountForCurrentScope: 0,
                 blockedFromPhase: null,

package/dist/neal/orchestrator/failures.js

@@ -1,4 +1,11 @@
 import { CoderRoundError } from '../agents.js';
+// Shared, durable blocked reason for a reviewer content-safety refusal
+// (`content_refused`). Defined once so the wording cannot drift across the
+// three reviewer-phase catch sites that route it to a terminal blocked landing.
+export const REVIEWER_CONTENT_REFUSED_BLOCK_REASON = 'The reviewer refused this content on content-safety grounds. The change ' +
+    'under review may read as security-adjacent. Switch the reviewer to a ' +
+    'different provider, rephrase the scope, or seek provider authorization, ' +
+    'then re-run.';
 export function isCoderTimeoutError(error) {
     return (error.kind === 'timeout' ||
         error.kind === 'no_progress_timeout' ||

package/dist/neal/orchestrator/notifications.js

@@ -3,40 +3,40 @@ import { notify } from '../../notifier.js';
 import { getCurrentScopeLabel, getExecutionPlanPath, getExecutionPlanScopeCount, getParentScopeLabel, renderScopeProgressSegments, } from '../scopes.js';
 import { saveState } from '../state.js';
 import { getDerivedPlanView } from '../state-views.js';
-// Concise representation of the read-only blocked-adjudicator advice for the
+// Concise representation of the read-only consultant advice for the
 // operator notification surface. Present only on an attended run whose active
-// interactive-blocked-recovery record carries adjudicator advice (knob > 0,
+// interactive-blocked-recovery record carries consultant advice (knob > 0,
 // budget available, eligible source phase). Returns '' otherwise so notification
 // behavior for recovery states without advice — and terminal blocked
 // notifications, where the active record is already finalized to null — is
 // unchanged.
-function adjudicatorAdviceNotificationSuffix(state) {
-    const advice = state.interactiveBlockedRecovery?.adjudicatorAdvice;
+function consultantAdviceNotificationSuffix(state) {
+    const advice = state.interactiveBlockedRecovery?.consultantAdvice;
     if (!advice) {
         return '';
     }
     const directive = advice.resolutionDirective.trim() || 'n/a';
-    return ` | adjudicator advice (read-only): triage ${advice.triageCategory}; suggested directive: ${directive}`;
+    return ` | consultant advice (read-only): triage ${advice.triageCategory}; suggested directive: ${directive}`;
 }
 async function notifyBlocked(state, reason, logger) {
     const planName = basename(state.planDoc);
-    const adviceSuffix = adjudicatorAdviceNotificationSuffix(state);
+    const adviceSuffix = consultantAdviceNotificationSuffix(state);
     await logger?.event('notify.blocked', {
         reason,
         planName,
-        adjudicatorAdvice: state.interactiveBlockedRecovery?.adjudicatorAdvice ?? null,
+        consultantAdvice: state.interactiveBlockedRecovery?.consultantAdvice ?? null,
     });
     await notify('blocked', `[neal] ${planName}: ${reason}${adviceSuffix}`, state.cwd);
 }
 async function notifyInteractiveBlockedRecovery(state, reason, logger) {
     const planName = basename(state.planDoc);
     const scopeLabel = getCurrentScopeLabel(state);
-    const adviceSuffix = adjudicatorAdviceNotificationSuffix(state);
+    const adviceSuffix = consultantAdviceNotificationSuffix(state);
     await logger?.event('notify.interactive_blocked_recovery', {
         reason,
         planName,
         scopeNumber: scopeLabel,
-        adjudicatorAdvice: state.interactiveBlockedRecovery?.adjudicatorAdvice ?? null,
+        consultantAdvice: state.interactiveBlockedRecovery?.consultantAdvice ?? null,
     });
     await notify('retry', `[neal] ${planName}: interactive blocked recovery for scope ${scopeLabel}: ${reason}${adviceSuffix}`, state.cwd);
 }