@navels/neal 0.1.0 → 0.3.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/blocked-guidance.js

@@ -4,6 +4,7 @@ import { formatPublicPhase } from './phase-display.js';
 import { getRunDisplayStatus } from './run-status.js';
 import { getCurrentScopeLabel } from './scopes.js';
 import { sanitizeSensitiveText } from './sensitive-text.js';
+import { getPlanReviewGuidanceOriginPhase } from './state-views.js';
 import { getRunStatePath } from './state.js';
 const FALLBACK_REASON = 'Neal is waiting for operator guidance before it can continue.';
 const PLAN_REVIEW_REASON = 'Plan review requires operator guidance before Neal can continue.';
@@ -134,11 +135,11 @@ export function renderBlockedGuidanceSections(guidance) {
     return lines;
 }
 function isPlanReviewGuidanceWaiting(state) {
-    return (state.topLevelMode === 'plan' &&
-        state.status === 'blocked' &&
-        state.phase === 'blocked' &&
-        state.blockedFromPhase === 'reviewer_plan' &&
-        state.pendingPlanReviewGuidance === null);
+    // Shared discriminator: reviewer_plan plus coder-authored *response* blocks
+    // (blockerReason non-null). A dirty-worktree safety block at the same response
+    // phase has blockerReason null and is not a guidance wait, so it renders as a
+    // normal blocked state rather than a plan-review-guidance panel.
+    return getPlanReviewGuidanceOriginPhase(state) !== null;
 }
 function getReasonAndPhase(state, planReviewWaiting) {
     if (state.interactiveBlockedRecovery) {
@@ -148,9 +149,15 @@ function getReasonAndPhase(state, planReviewWaiting) {
         };
     }
     if (planReviewWaiting) {
+        // A coder-authored *response* block carries a durable, operator-facing reason;
+        // surface it (and its origin phase) so the guidance render shows the coder's
+        // concrete question rather than the generic reviewer-plan message. The
+        // reviewer-plan message-resume path leaves blockerReason null and keeps the
+        // generic reason + `reviewer_plan` source phase unchanged.
+        const blockerReason = state.blockerReason?.trim();
         return {
-            reason: PLAN_REVIEW_REASON,
-            sourcePhase: 'reviewer_plan',
+            reason: blockerReason ? state.blockerReason : PLAN_REVIEW_REASON,
+            sourcePhase: state.blockedFromPhase ?? 'reviewer_plan',
         };
     }
     return {
@@ -167,8 +174,8 @@ function buildCandidateText(state, reason) {
         state.currentScopeMeaningfulProgressVerdict?.rationale,
         recovery?.blockedReason,
         recovery?.pendingDirective?.operatorGuidance,
-        recovery?.adjudicatorAdvice?.resolutionDirective,
-        recovery?.adjudicatorAdvice?.rationale,
+        recovery?.consultantAdvice?.resolutionDirective,
+        recovery?.consultantAdvice?.rationale,
     ].filter(Boolean).join(' '));
 }
 function classifyBlockedGuidance(state, reason, candidateText, planReviewWaiting) {

package/dist/neal/cli.js

@@ -12,7 +12,7 @@ export function buildUsageLines(version) {
         '   or: neal review [message] (--last <n> | --since <base>)',
         '   or: neal squash [plan.md]',
         '   or: neal check',
-        '   or: neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|generic-agentic:<model>] [--json]',
+        '   or: neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|openai-compatible:<model>] [--json]',
         '   or: neal status [--json] [--run <run-id>]',
         '   or: neal status [--json] --all',
         '   or: neal version',
@@ -38,7 +38,7 @@ export function buildUsageLines(version) {
         '  neal status',
         '  neal status --all',
         '  neal check',
-        '  neal compat --model deepseek/deepseek-chat --role all --reference openai-codex --json  # --model runs the slug on generic-agentic; reference roles run on the native adapter',
+        '  neal compat --model deepseek/deepseek-chat --role all --reference openai-codex --json  # --model runs the slug on openai-compatible; reference roles run on the native adapter',
         '  neal setup',
         '  neal setup --provider anthropic-claude --all-roles',
         '  neal version',

package/dist/neal/commands/check.js

@@ -345,11 +345,11 @@ export async function runNealCheckCli(options = {}) {
     writeLine(stdout, `  ${describeNotificationScript(notifyBin)}`);
     writeLine(stdout, '');
     // Native adapters drive their providers directly; any other writer provider is
-    // a generic-agentic model that should be qualified end-to-end with `neal compat`.
+    // an openai-compatible model that should be qualified end-to-end with `neal compat`.
     const NATIVE_WRITER_PROVIDERS = new Set(['openai-codex', 'anthropic-claude']);
     if (!NATIVE_WRITER_PROVIDERS.has(agentConfig.coder.provider) ||
         !NATIVE_WRITER_PROVIDERS.has(agentConfig.reviewer.provider)) {
-        writeLine(stdout, 'This is a generic-agentic model - run `neal compat` to confirm it can drive the full loop.');
+        writeLine(stdout, 'This is an openai-compatible model - run `neal compat` to confirm it can drive the full loop.');
         writeLine(stdout, '');
     }
     const ignoreStatus = await getNealDirGitIgnoreStatus(cwd);

package/dist/neal/commands/compat.js

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { cpSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join, relative, resolve } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import process from 'node:process';
 import { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
@@ -14,17 +14,18 @@ import { validatePlanDocument } from '../plan-validation.js';
 import { getReviewFindingsArtifactPaths } from '../review-findings/artifacts.js';
 import { createAgentReviewFindingsProviderAdapter } from '../review-findings/provider.js';
 import { runNealReviewCli } from '../review-findings/run.js';
+import { enableAgentSettingsIsolation } from '../providers/agent-settings-isolation.js';
 import { isNealProviderError } from '../providers/types.js';
 import { getRunDir } from '../storage-paths.js';
 import { verifyConfiguredProviders } from './check.js';
 import { executeRun } from './runtime.js';
 // Native adapters drive their providers' own CLIs/SDKs directly; every other
-// provider id is "generic-agentic" and should be qualified via `neal compat`.
+// provider id is "openai-compatible" and should be qualified via `neal compat`.
 export const NATIVE_PROVIDER_IDS = new Set([
     'openai-codex',
     'anthropic-claude',
 ]);
-export function isGenericAgenticProvider(provider) {
+export function isOpenAICompatibleProvider(provider) {
     return !NATIVE_PROVIDER_IDS.has(provider);
 }
 // Default model per native reference provider. `neal compat` routes the
@@ -35,7 +36,7 @@ export const REFERENCE_DEFAULT_MODELS = {
     'anthropic-claude': 'claude-opus-4-8',
 };
 // A compat reference is either a native provider id (run at its built-in default model)
-// or `generic-agentic:<openrouter-slug>` to use a *validated* OpenRouter model as the
+// or `openai-compatible:<openrouter-slug>` to use a *validated* OpenRouter model as the
 // known-good partner. The latter is the follow-up the routing plan anticipated once a
 // rock-solid OpenRouter reference was identified: it removes the codex reference and so
 // uncaps parallelism (no shared native-provider capacity pool). Use ONLY a model that
@@ -183,11 +184,11 @@ export function parseCompatArgs(args) {
                 const colon = value.indexOf(':');
                 if (colon === -1) {
                     if (!NATIVE_PROVIDER_IDS.has(value)) {
-                        throw new Error('neal compat --reference must be a native provider id (openai-codex or anthropic-claude) or generic-agentic:<openrouter-model>');
+                        throw new Error('neal compat --reference must be a native provider id (openai-codex or anthropic-claude) or openai-compatible:<openrouter-model>');
                     }
                 }
-                else if (value.slice(0, colon) !== 'generic-agentic' || value.slice(colon + 1).trim() === '') {
-                    throw new Error('neal compat --reference provider:model form must be generic-agentic:<openrouter-model>');
+                else if (value.slice(0, colon) !== 'openai-compatible' || value.slice(colon + 1).trim() === '') {
+                    throw new Error('neal compat --reference provider:model form must be openai-compatible:<openrouter-model>');
                 }
                 reference = value;
                 index += 2;
@@ -223,14 +224,14 @@ export function deriveCandidateConfig(base, options) {
     };
     const routingActive = options.model !== null || options.reference !== null;
     const reference = resolveReference(options.reference);
-    // Tested role: when a candidate slug is given, force the generic-agentic
+    // Tested role: when a candidate slug is given, force the openai-compatible
     // provider and drop any configured effort so the slug drives a clean
     // OpenRouter call. Otherwise leave the configured provider/model untouched.
     if (options.model !== null) {
-        next[options.testedRole] = { provider: 'generic-agentic', model: options.model };
+        next[options.testedRole] = { provider: 'openai-compatible', model: options.model };
     }
     // Non-tested roles: when either flag is given, route them onto the reference
-    // (a native adapter at its default model, or generic-agentic:<slug> for a validated
+    // (a native adapter at its default model, or openai-compatible:<slug> for a validated
     // OpenRouter partner). When neither flag is given, leave every role as configured
     // (pure pass-through).
     if (routingActive) {
@@ -290,7 +291,12 @@ function applyAndCommitDiff(cwd, diffPath, message) {
 }
 function copyFixtureProject(compatDir, fixture) {
     const dir = mkdtempSync(join(tmpdir(), `neal-compat-${fixture.id}-`));
-    cpSync(join(compatDir, fixture.projectDir), dir, { recursive: true });
+    cpSync(join(compatDir, fixture.projectDir), dir, {
+        recursive: true,
+        // Never hand committed neal run state to a candidate model: those artifacts
+        // describe the pre-fix state and contradict an applied good diff.
+        filter: (source) => !source.split(sep).includes('.neal'),
+    });
     return dir;
 }
 function cleanProcessEnv() {
@@ -431,8 +437,8 @@ export function classifyWriterFailure(args) {
     // status 'failed' with no conclusive structural signal.
     return 'provider_failed';
 }
-function makeCell(role, fixtureId, pass, failureMode, detail, diffKind = null) {
-    return { role, fixtureId, diffKind, pass, failureMode, detail };
+function makeCell(role, fixtureId, pass, failureMode, detail, diffKind = null, blockingCount = null) {
+    return { role, fixtureId, diffKind, blockingCount, pass, failureMode, detail };
 }
 // ---------------------------------------------------------------------------
 // Coder fixture evaluation
@@ -513,8 +519,21 @@ export async function evaluatePlannerFixture(args) {
 // ---------------------------------------------------------------------------
 // Reviewer fixture evaluation
 // ---------------------------------------------------------------------------
-export function hasBlockingFinding(result) {
-    return result.draft.findings.some((finding) => finding.severity === 'blocking');
+export function collectBlockingFindings(result) {
+    return result.draft.findings.filter((finding) => finding.severity === 'blocking');
+}
+export function countBlockingFindings(result) {
+    return collectBlockingFindings(result).length;
+}
+function normalizeFindingText(text) {
+    const collapsed = text.replace(/\s+/gu, ' ').trim();
+    return collapsed.length > 120 ? `${collapsed.slice(0, 120)}…` : collapsed;
+}
+export function summarizeBlockingFindings(findings, limit = 2) {
+    return findings
+        .slice(0, limit)
+        .map((finding) => `${normalizeFindingText(finding.claim)} — ${normalizeFindingText(finding.requiredAction)}`)
+        .join('; ');
 }
 export function classifyNonAcceptedReviewOutcome(outcome) {
     switch (outcome) {
@@ -570,7 +589,7 @@ function buildReviewParsedArgs() {
         selector: { kind: 'last', count: 1 },
     };
 }
-async function evaluateReviewerDiff(args) {
+async function runReviewerDiff(args) {
     const { fixture, diffKind } = args;
     if (!fixture.reviewer || !fixture.verifyCommand) {
         throw new Error(`compat: reviewer fixture ${fixture.id} is missing diffs/verifyCommand`);
@@ -604,20 +623,18 @@ async function evaluateReviewerDiff(args) {
             // schema failures collapse to `structured_output`.
             const outcome = await readReviewOutcome(throwawayCwd, reviewId);
             const failureMode = classifyReviewerThrownFailure(error, outcome);
-            return makeCell('reviewer', fixture.id, false, failureMode, error instanceof Error ? error.message : String(error), diffKind);
-        }
-        const blocking = hasBlockingFinding(result);
-        if (diffKind === 'good') {
-            if (!blocking) {
-                return makeCell('reviewer', fixture.id, true, null, null, 'good');
-            }
-            return makeCell('reviewer', fixture.id, false, 'wrong_or_empty_output', 'reviewer flagged the known-good diff with a blocking finding', 'good');
+            return {
+                status: 'error',
+                cell: makeCell('reviewer', fixture.id, false, failureMode, error instanceof Error ? error.message : String(error), diffKind, null),
+            };
         }
-        // broken diff: PASS requires ≥1 blocking finding.
-        if (blocking) {
-            return makeCell('reviewer', fixture.id, true, null, null, 'broken');
-        }
-        return makeCell('reviewer', fixture.id, false, 'wrong_or_empty_output', 'reviewer accepted the deliberately broken diff without a blocking finding', 'broken');
+        // No pass/fail judgement here: the verdict is a property of the pair.
+        const blocking = collectBlockingFindings(result);
+        return {
+            status: 'scored',
+            blockingCount: blocking.length,
+            blockingSummary: summarizeBlockingFindings(blocking),
+        };
     }
     finally {
         rmSync(throwawayCwd, { recursive: true, force: true });
@@ -641,9 +658,51 @@ async function readReviewOutcome(cwd, reviewId) {
     }
 }
 export async function evaluateReviewerFixture(args) {
-    const good = await evaluateReviewerDiff({ ...args, diffKind: 'good' });
-    const broken = await evaluateReviewerDiff({ ...args, diffKind: 'broken' });
-    return { good, broken };
+    const good = await runReviewerDiff({ ...args, diffKind: 'good' });
+    const broken = await runReviewerDiff({ ...args, diffKind: 'broken' });
+    // Either diff erroring makes the pair unscoreable: no discrimination verdict
+    // is computable, so attribute the systematic cause to both cells.
+    if (good.status === 'error' && broken.status === 'error') {
+        return { good: good.cell, broken: broken.cell };
+    }
+    if (good.status === 'error') {
+        return {
+            good: good.cell,
+            broken: broken.status === 'scored'
+                ? unscoreableCell(args.fixture.id, 'broken', broken.blockingCount, good.cell)
+                : broken.cell,
+        };
+    }
+    if (broken.status === 'error') {
+        return {
+            good: unscoreableCell(args.fixture.id, 'good', good.blockingCount, broken.cell),
+            broken: broken.cell,
+        };
+    }
+    // Discrimination criterion: severity calibration is not graded. A reviewer may
+    // raise blocking findings on the good diff and still PASS, as long as the
+    // broken diff draws strictly more.
+    const pass = broken.blockingCount >= 1 && good.blockingCount < broken.blockingCount;
+    if (pass) {
+        return {
+            good: makeCell('reviewer', args.fixture.id, true, null, null, 'good', good.blockingCount),
+            broken: makeCell('reviewer', args.fixture.id, true, null, null, 'broken', broken.blockingCount),
+        };
+    }
+    const base = broken.blockingCount === 0
+        ? `reviewer raised no blocking finding on the broken diff (blocking good=${good.blockingCount}, broken=0)`
+        : `reviewer did not discriminate: blocking good=${good.blockingCount} >= broken=${broken.blockingCount}`;
+    const detailFor = (summary) => summary === '' ? base : `${base} | blocking: ${summary}`;
+    return {
+        good: makeCell('reviewer', args.fixture.id, false, 'wrong_or_empty_output', detailFor(good.blockingSummary), 'good', good.blockingCount),
+        broken: makeCell('reviewer', args.fixture.id, false, 'wrong_or_empty_output', detailFor(broken.blockingSummary), 'broken', broken.blockingCount),
+    };
+}
+// A scored diff whose partner errored: carry the partner's failure mode so
+// smoke aggregation attributes the systematic cause rather than a bogus verdict.
+function unscoreableCell(fixtureId, diffKind, blockingCount, partnerCell) {
+    const partnerDiffKind = diffKind === 'good' ? 'broken' : 'good';
+    return makeCell('reviewer', fixtureId, false, partnerCell.failureMode, `pair unscoreable: the ${partnerDiffKind} diff review failed (${partnerCell.failureMode ?? 'unknown'})`, diffKind, blockingCount);
 }
 // ---------------------------------------------------------------------------
 // Output formatting
@@ -704,6 +763,11 @@ export function formatCompatTable(report) {
 }
 export async function runCompat(args) {
     const { cwd, parsed } = args;
+    // compat is a hermetic capability probe that runs the whole role matrix
+    // through the native SDKs. Isolate those adapters from the operator's
+    // interactive config so the probe stays quiet (no per-turn notifier hooks)
+    // and repeatable. Normal neal runs never call this, so they honor the config.
+    enableAgentSettingsIsolation();
     const deps = args.deps ?? {};
     const compatDir = deps.compatDir ?? getCompatExamplesDir();
     const manifest = deps.manifest ?? loadCompatManifest(compatDir);
@@ -778,14 +842,14 @@ export async function runCompat(args) {
     const roles = buildRoleRollups(cells, targetedRoles);
     const overallPass = roles.length > 0 && roles.every((rollup) => rollup.pass);
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         model: parsed.model,
         reference: parsed.reference,
         role: parsed.role,
         candidateProviders: {
-            coder: parsed.model !== null ? 'generic-agentic' : baseConfig.coder.provider,
-            reviewer: parsed.model !== null ? 'generic-agentic' : baseConfig.reviewer.provider,
-            planner: parsed.model !== null ? 'generic-agentic' : baseConfig.planner.provider,
+            coder: parsed.model !== null ? 'openai-compatible' : baseConfig.coder.provider,
+            reviewer: parsed.model !== null ? 'openai-compatible' : baseConfig.reviewer.provider,
+            planner: parsed.model !== null ? 'openai-compatible' : baseConfig.planner.provider,
         },
         cells,
         roles,

package/dist/neal/commands/interactive-activity.js

@@ -1,7 +1,7 @@
 import { Writable } from 'node:stream';
 import { ActivityFooter } from '../activity-footer.js';
 import { clearDiagnosticFooter, configureDiagnosticFooter, resetDiagnosticDetailState, setDiagnosticDetailContext, writeNarrative, } from '../diagnostic.js';
-import { createInteractiveKeyController } from '../interactive-controls.js';
+import { createInteractiveKeyController, renderInteractiveKeyHint } from '../interactive-controls.js';
 export async function withInteractiveActivity(options, action) {
     let detailContext = {};
     resetDiagnosticDetailState(detailContext);
@@ -34,7 +34,7 @@ export async function withInteractiveActivity(options, action) {
     };
     try {
         if (process.stdin.isTTY) {
-            writeNarrative('[neal] keys: v show/hide details\n');
+            writeNarrative(renderInteractiveKeyHint(false));
         }
         return await action({
             stderr: createNarrativeWritable(),

package/dist/neal/commands/recovery-guidance.js

@@ -6,6 +6,7 @@ import { assertAgentConfigSupportsResume } from '../providers/registry.js';
 import { formatPublicPhase } from '../phase-display.js';
 import { logUserGuidanceApplied } from '../prompts/guidance.js';
 import { decideResumeAction } from '../resume-decision.js';
+import { getPlanReviewGuidanceOriginPhase } from '../state-views.js';
 import { loadState, saveState } from '../state.js';
 function getSelectedRunId(state, selectedRunId) {
     return selectedRunId && selectedRunId !== 'latest' ? selectedRunId : basename(state.runDir);
@@ -67,11 +68,10 @@ function formatGuidanceDecisionRejection(decision) {
     }
 }
 function isEligiblePlanReviewGuidanceState(state) {
-    return (state.topLevelMode === 'plan' &&
-        state.status === 'blocked' &&
-        state.phase === 'blocked' &&
-        state.blockedFromPhase === 'reviewer_plan' &&
-        state.pendingPlanReviewGuidance === null);
+    // Shared discriminator: reviewer_plan plus coder-authored *response* blocks
+    // (blockerReason non-null). A dirty-worktree safety block lands at the same
+    // response phase with blockerReason null and is not answerable via --message.
+    return getPlanReviewGuidanceOriginPhase(state) !== null;
 }
 async function recordPlanReviewGuidance(args) {
     const resumeCommand = getResumeCommand(args.state, args.target);
@@ -97,6 +97,16 @@ async function recordPlanReviewGuidance(args) {
     if (!isEligiblePlanReviewGuidanceState(args.state)) {
         throw new Error(describePlanReviewGuidanceStateProblem(args.state, args.target));
     }
+    const originPhase = getPlanReviewGuidanceOriginPhase(args.state);
+    if (originPhase === null) {
+        throw new Error(describePlanReviewGuidanceStateProblem(args.state, args.target));
+    }
+    // Map the origin block to the phase that will actually consume the guidance:
+    // a reviewer_plan block delivers to coder_plan_response (unchanged behavior),
+    // while a coder-authored response block returns to its own origin phase so the
+    // resumed round selects the right open findings and delivers the guidance
+    // instead of accepting on an empty blocking set.
+    const resumePhase = originPhase === 'reviewer_plan' ? 'coder_plan_response' : originPhase;
     assertAgentConfigSupportsResume(args.state.agentConfig, args.state, {
         context: 'record plan-review guidance for resume',
     });
@@ -110,19 +120,21 @@ async function recordPlanReviewGuidance(args) {
     await logUserGuidanceApplied(logger);
     const nextState = await saveState(args.target.statePath, {
         ...args.state,
-        phase: 'coder_plan_response',
+        phase: resumePhase,
         status: 'running',
         blockedFromPhase: null,
+        // Returning to running clears the durable coder-authored blocker reason.
+        blockerReason: null,
         pendingPlanReviewGuidance: {
             message: trimmedGuidance,
-            sourcePhase: 'reviewer_plan',
+            sourcePhase: originPhase,
             recordedAt: new Date().toISOString(),
         },
     });
     await writeExecutionArtifacts(nextState);
     await logger.event('plan_review_guidance.recorded', {
         statePath: args.target.statePath,
-        sourcePhase: 'reviewer_plan',
+        sourcePhase: originPhase,
         guidanceBytes: Buffer.byteLength(trimmedGuidance, 'utf8'),
     });
     return {

package/dist/neal/commands/runtime.js

@@ -3,7 +3,7 @@ import { basename, dirname, join } from 'node:path';
 import process from 'node:process';
 import { clearDiagnosticFooter, configureDiagnosticFooter, resetDiagnosticDetailState, setDiagnosticDetailContext, writeDiagnostic, } from '../diagnostic.js';
 import { buildBlockedGuidance, renderBlockedGuidanceSections, } from '../blocked-guidance.js';
-import { createInteractiveKeyController } from '../interactive-controls.js';
+import { createInteractiveKeyController, renderInteractiveKeyHint } from '../interactive-controls.js';
 import { createRunId } from '../logger.js';
 import { runOnePass } from '../orchestrator.js';
 import { writeExecutionArtifacts } from '../orchestrator/artifacts.js';
@@ -399,14 +399,16 @@ export async function executeRun(state, statePath, logger, options = {}) {
     await footer.setState(state, displayedPhaseStartedAt);
     const narrator = createTerminalNarrator({ logger });
     await narrator.start(state);
+    const allowStopRequest = state.topLevelMode === 'execute';
     const stopController = createInteractiveKeyController({
+        allowStopRequest,
         getDetailFilter() {
             return currentDetailContext;
         },
     });
     try {
         if (process.stdin.isTTY) {
-            writeDiagnostic('[neal] keys: q stop after current scope, v show/hide details\n');
+            writeDiagnostic(renderInteractiveKeyHint(allowStopRequest));
         }
         let finalState;
         try {

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;
     }
@@ -346,6 +355,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 +388,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()) {