@navels/neal 0.2.0 → 0.3.1

package/dist/neal/agents/schemas.js

@@ -1,9 +1,14 @@
 import { z } from 'zod';
+import { normalizeExecutionShapeDeclaration, validatePlanDocument } from '../plan-validation.js';
 import { repairReviewerSquashMessageDraft, validateReviewerSquashMessageDraft } from '../squash-message.js';
 export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_START = 'NEAL_PROGRESS_JUSTIFICATION_JSON_START';
 export const EXECUTE_SCOPE_PROGRESS_PAYLOAD_END = 'NEAL_PROGRESS_JUSTIFICATION_JSON_END';
 // --- zod payload definitions (single source of truth) -----------------------
 const REVIEWER_FINDING_SEVERITIES = ['blocking', 'non_blocking'];
+export const PLAN_REVIEWER_FINDING_CLASSES = [
+    'plan_correctness',
+    'verification_hardening',
+];
 const REVIEWER_MEANINGFUL_PROGRESS_ACTIONS = [
     'accept',
     'block_for_operator',
@@ -11,7 +16,7 @@ const REVIEWER_MEANINGFUL_PROGRESS_ACTIONS = [
     'advance_parent',
 ];
 const EXECUTION_SHAPES = ['one_shot', 'multi_scope', 'multi_scope_unknown'];
-const BLOCKED_ADJUDICATOR_TRIAGE_CATEGORIES = [
+const CONSULTANT_TRIAGE_CATEGORIES = [
     'misunderstanding',
     'authorization',
     'external_precondition',
@@ -56,15 +61,24 @@ const planReviewerFindingSchema = z.object({
     files: z.array(z.string()),
     claim: z.string(),
     requiredAction: z.string(),
+    // Optional at the payload boundary: an absent class normalizes to the fail-safe
+    // plan_correctness downstream (see validatePlanReviewerPayload), while a
+    // present-but-invalid value is rejected by the sequential validator before any
+    // normalization runs. The reviewer round is a `neal-json-block-v1` structured
+    // round (the schema is advisory prompt context, not native strict output), so —
+    // like the consultant's optional targetCanonicalIds — this property is
+    // intentionally absent from the emitted `required` tuple and buildPlanReviewerSchema
+    // is excluded from the strict all-required contract.
+    findingClass: z.enum(PLAN_REVIEWER_FINDING_CLASSES).optional(),
 });
 const planReviewerPayloadSchema = z.object({
     summary: z.string(),
     executionShape: z.enum(EXECUTION_SHAPES),
     findings: z.array(planReviewerFindingSchema),
 });
-const blockedAdjudicatorPayloadSchema = z.object({
+const consultantPayloadSchema = z.object({
     recoverable: z.boolean(),
-    triageCategory: z.enum(BLOCKED_ADJUDICATOR_TRIAGE_CATEGORIES),
+    triageCategory: z.enum(CONSULTANT_TRIAGE_CATEGORIES),
     resolutionDirective: z.string(),
     targetCanonicalIds: z.array(z.string()).optional(),
     rationale: z.string(),
@@ -257,8 +271,8 @@ export function buildReviewerSchema() {
 export function buildPlanReviewerSchema() {
     return emitJsonSchema(planReviewerPayloadSchema);
 }
-export function buildBlockedAdjudicatorSchema() {
-    return emitJsonSchema(blockedAdjudicatorPayloadSchema);
+export function buildConsultantSchema() {
+    return emitJsonSchema(consultantPayloadSchema);
 }
 export function buildCoderResponseSchema() {
     return emitJsonSchema(coderResponsePayloadSchema);
@@ -401,7 +415,7 @@ function walkObjectSequential(schema, record, basePath) {
         // Historical optional/nullable field patterns performed one property
         // read for the undefined/null test and a FRESH read for validation when
         // the field was present, so stateful accessors observe both reads (the
-        // blocked-adjudicator targetCanonicalIds ternary and the coder-scope
+        // consultant targetCanonicalIds ternary and the coder-scope
         // manualGate ternary behaved this way).
         if (fieldSchema instanceof z.ZodOptional) {
             if (record[key] === undefined) {
@@ -495,15 +509,15 @@ export function validateReviewerPayload(payload) {
     };
 }
 // --- permissive validators ----------------------------------------------------
-// Validates a read-only review_stuck arbiter verdict. Exactly one triage
+// Validates a read-only review_stuck consultant verdict. Exactly one triage
 // category is autonomously recoverable: `misunderstanding` requires
 // recoverable=true plus a non-empty resolutionDirective; the three genuine-wall
 // categories (`authorization`, `external_precondition`, `impossible_task`)
 // require recoverable=false. Anything else (recoverable=true with another
 // triage, or recoverable=false paired with `misunderstanding`) is rejected so a
 // malformed verdict can never drive an autonomous recovery.
-export function validateBlockedAdjudicatorVerdictPayload(rawPayload) {
-    const parsed = parsePayload(blockedAdjudicatorPayloadSchema, rawPayload, 'Review-stuck arbiter payload');
+export function validateConsultantVerdictPayload(rawPayload) {
+    const parsed = parsePayload(consultantPayloadSchema, rawPayload, 'Consultant payload');
     const payload = {
         recoverable: parsed.recoverable,
         triageCategory: parsed.triageCategory,
@@ -514,18 +528,18 @@ export function validateBlockedAdjudicatorVerdictPayload(rawPayload) {
         rationale: parsed.rationale,
     };
     if (!payload.rationale.trim()) {
-        throw new Error('Review-stuck arbiter returned an empty rationale.');
+        throw new Error('Consultant returned an empty rationale.');
     }
     if (payload.recoverable) {
         if (payload.triageCategory !== 'misunderstanding') {
-            throw new Error('Review-stuck arbiter returned recoverable=true with a triageCategory other than misunderstanding.');
+            throw new Error('Consultant returned recoverable=true with a triageCategory other than misunderstanding.');
         }
         if (!payload.resolutionDirective.trim()) {
-            throw new Error('Review-stuck arbiter returned recoverable=true without a non-empty resolutionDirective.');
+            throw new Error('Consultant returned recoverable=true without a non-empty resolutionDirective.');
         }
     }
     else if (payload.triageCategory === 'misunderstanding') {
-        throw new Error('Review-stuck arbiter returned recoverable=false paired with triageCategory=misunderstanding.');
+        throw new Error('Consultant returned recoverable=false paired with triageCategory=misunderstanding.');
     }
     return payload;
 }
@@ -542,6 +556,10 @@ export function validatePlanReviewerPayload(payload) {
             // always forces an empty string.
             evidence: '',
             requiredAction: finding.requiredAction,
+            // Default only the absent case to plan_correctness (the fail-safe class).
+            // A present-but-invalid class was already rejected upstream in parsePayload,
+            // so this never silently downgrades a bad value.
+            findingClass: finding.findingClass ?? 'plan_correctness',
         })),
     };
 }
@@ -639,6 +657,22 @@ export function validateCoderPlanPayload(rawPayload) {
     if (payload.action === 'blocked' && !blockedReason) {
         throw new Error('Planner plan round returned action=blocked without a blockedReason payload.');
     }
+    // The refined plan is persisted over the plan document and sent straight to
+    // plan review, so it must satisfy the plan contract here — inside the
+    // structured-output validator — where a failure triggers the repair loop
+    // (the planner gets the errors and retries) instead of burning a reviewer
+    // round on an invalid document. Split-plan payloads already have this gate
+    // (validateSplitPlanPayload); a live run persisted a planner payload whose
+    // planBody was a 39-line refinement summary declaring multi_scope with no
+    // Execution Queue, and the reviewer round was spent rediscovering that.
+    if (payload.action === 'ready_for_review') {
+        const normalizedBody = normalizeExecutionShapeDeclaration(planBody, payload.executionShape);
+        const validation = validatePlanDocument(normalizedBody);
+        if (!validation.ok) {
+            throw new Error(`Planner plan round returned a planBody that is not a valid Neal plan document: ${validation.errors.join('; ')}. ` +
+                'Return the complete refined plan document, not a summary of the refinement.');
+        }
+    }
     return {
         ...payload,
         message: payload.message.trim(),

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 {