@navels/neal 0.1.0 → 0.3.0

package/dist/neal/providers/registry.js

@@ -1,7 +1,6 @@
 import { anthropicClaudeProviderDefinition } from './anthropic-claude.js';
-import { genericAgenticProviderDefinition } from './generic-agentic.js';
-import { openAICodexProviderDefinition } from './openai-codex.js';
 import { openAICompatibleProviderDefinition } from './openai-compatible.js';
+import { openAICodexProviderDefinition } from './openai-codex.js';
 // Computed lazily instead of as a top-level constant: openai-compatible.ts
 // imports config.ts, which imports this module, so the definition bindings may
 // still be in their temporal dead zone while this module body evaluates.
@@ -12,7 +11,6 @@ function getBuiltInProviderDefinitions() {
         openAICodexProviderDefinition,
         anthropicClaudeProviderDefinition,
         openAICompatibleProviderDefinition,
-        genericAgenticProviderDefinition,
     ];
 }
 const providerCapabilityOverrides = new Map();
@@ -108,15 +106,6 @@ function assertRoleCapabilities(args) {
             missingCapability: 'read_tool_access',
         });
     }
-    if (args.requirementContext.requireReadToolAccessOrInlineReviewerContext &&
-        !args.capabilities.toolAccess.read &&
-        !(args.capabilities.supported && args.capabilities.supportsStructuredOutput)) {
-        throwProviderCapabilityError({
-            requirementContext: args.requirementContext,
-            config: args.config,
-            missingCapability: 'read_tool_access_or_inline_reviewer_context',
-        });
-    }
     if (args.requirementContext.requireWriteToolAccess && !args.capabilities.toolAccess.write) {
         throwProviderCapabilityError({
             requirementContext: args.requirementContext,
@@ -161,9 +150,9 @@ function assertRoleCapabilities(args) {
 // Registry invariant: every *supported* structured-advisor (reviewer)
 // capability must be read-only. Reviewers inspect work and return verdicts;
 // they never mutate the checkout or run shell commands. Only `write`/`shell`
-// are constrained here — `read` is unconstrained (a reviewer may read the
-// checkout directly, or be a no-read inline-context reviewer). The `coder`
-// capability is intentionally not checked: coders keep write/shell.
+// are constrained here — `read` is not constrained by this assertion (the
+// writer-run capability gates separately require reviewer read access). The
+// `coder` capability is intentionally not checked: coders keep write/shell.
 export function assertStructuredAdvisorReadOnly(definition) {
     const capability = definition.capabilities['structured-advisor'];
     if (!capability.supported) {
@@ -280,11 +269,11 @@ export function assertAgentConfigSupportsWriterRun(agentConfig, options = {}) {
         role: 'reviewer',
         context,
         reason: 'Neal writer runs need a reviewer provider that can inspect work and return structured verdicts',
-        requireReadToolAccessOrInlineReviewerContext: true,
+        requireReadToolAccess: true,
         requireStructuredOutput: true,
         reasons: {
             structured_advisor_adapter: 'reviewer, plan-review, support, and final-completion verdicts run through the structured-advisor adapter',
-            read_tool_access_or_inline_reviewer_context: 'reviewer rounds must either inspect repository state, diffs, and run artifacts directly with read tools, or support structured output so Neal can supply inline reviewer context (full diff, plan document, run artifacts) in the prompt',
+            read_tool_access: 'reviewer rounds must inspect repository state, diffs, and run artifacts directly with read tools',
             structured_output: 'reviewer rounds return schema-validated structured verdicts',
             model_override: 'a non-null reviewer model override is configured for this writer run',
         },

package/dist/neal/providers/telemetry.js

@@ -63,6 +63,8 @@ async function writeRunEvent(event, options) {
             await logger.event('provider.turn_completed', {
                 ...commonEventData(event),
                 ...(event.usage !== undefined ? { usage: event.usage } : {}),
+                ...(event.costUsd !== undefined ? { costUsd: event.costUsd } : {}),
+                ...(event.costSource !== undefined ? { costSource: event.costSource } : {}),
             });
             break;
         case 'tool_started':
@@ -121,6 +123,8 @@ async function writeRunEvent(event, options) {
             await logger.event('provider.usage_reported', {
                 ...commonEventData(event),
                 usage: event.usage,
+                ...(event.costUsd !== undefined ? { costUsd: event.costUsd } : {}),
+                ...(event.costSource !== undefined ? { costSource: event.costSource } : {}),
             });
             break;
         case 'provider_error':

package/dist/neal/providers/types.js

@@ -1,3 +1,15 @@
+// Detects an OpenAI content-safety refusal in a provider-authored error or
+// exception message. OpenAI flags security-adjacent requests with a stable
+// notice ("This content was flagged for possible cybersecurity risk ... join
+// the Trusted Access for Cyber ..."); either substring is specific enough that
+// ordinary review findings mentioning "security" do not trip it. Callers must
+// only pass error-channel text (an embedded gateway error message or an
+// HTTP/transport exception message), never assistant review content.
+export function isContentSafetyRefusalMessage(message) {
+    const text = message.toLowerCase();
+    return (text.includes('flagged for possible cybersecurity risk') ||
+        text.includes('trusted access for cyber'));
+}
 export class NealProviderError extends Error {
     provider;
     role;

package/dist/neal/resume-decision.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { planResumeActions } from './resume-planner.js';
-import { getInteractiveRecoveryView } from './state-views.js';
+import { getInteractiveRecoveryView, getPlanReviewGuidanceOriginPhase } from './state-views.js';
 export function decideResumeAction(args) {
     const resumeCommand = formatResumeCommand(args.selectedRunId);
     const messageCommand = formatMessageCommand(args.selectedRunId);
@@ -86,11 +86,12 @@ export function decideResumeAction(args) {
     };
 }
 function isWaitingForPlanReviewGuidance(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
+    // (which carry a durable blockerReason); dirty-worktree safety blocks at the
+    // same response phase have blockerReason null and are excluded. Evaluated before
+    // planResumeActions in decideResumeAction, so this needs_message decision takes
+    // precedence over a bare-resume restore of a genuine coder-authored block.
+    return getPlanReviewGuidanceOriginPhase(state) !== null;
 }
 function hasPendingPlanReviewGuidance(state) {
     return state.topLevelMode === 'plan' && state.pendingPlanReviewGuidance !== null;

package/dist/neal/resume-planner.js

@@ -132,11 +132,13 @@ function applyPlannedStatusAction(state, action) {
                 ...state,
                 phase: action.phase,
                 status: 'running',
+                blockerReason: null,
             };
         case 'normalize_stopped_status':
             return {
                 ...state,
                 status: 'running',
+                blockerReason: null,
             };
         default:
             return state;
@@ -173,6 +175,7 @@ function applyPlannedDerivedPlanAction(state, action) {
                 phase: action.phase,
                 status: 'running',
                 blockedFromPhase: null,
+                blockerReason: null,
             };
         case 'block_rejected_abandoned_derived_plan':
             return {
@@ -197,6 +200,10 @@ async function restoreResumableBlockedPhase(state, statePath, logger, action) {
         ...state,
         phase: action.phase,
         status: 'running',
+        // A coder-authored plan-stage response block persists a durable blockerReason;
+        // the resume planner is its first blocked->running writer, so clear it here so
+        // the reason never outlives its block (and the state satisfies the invariant).
+        blockerReason: null,
     });
     await logger?.event('run.resumed_from_blocked', {
         statePath,
@@ -210,6 +217,7 @@ async function normalizeStoppedStatus(state, statePath, logger, action) {
     const nextState = await saveState(statePath, {
         ...state,
         status: 'running',
+        blockerReason: null,
     });
     await logger?.event('run.status_normalized_on_resume', {
         statePath,
@@ -228,6 +236,7 @@ async function promoteUnexecutedDerivedPlan(state, statePath, logger, action) {
         phase: action.phase,
         status: 'running',
         blockedFromPhase: null,
+        blockerReason: null,
     });
     await logger?.event(action.kind === 'promote_accepted_derived_plan'
         ? 'run.promoted_accepted_derived_plan_on_resume'

package/dist/neal/retrospective.js

@@ -28,6 +28,26 @@ function getArchivedRetrospectivePath(state, kind) {
     const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
     return join(state.runDir, `RETROSPECTIVE-final${suffix}.md`);
 }
+function getCurrentRunMetricsPath(runDir) {
+    return join(runDir, 'RUN_METRICS.json');
+}
+// Mirrors getArchivedRetrospectivePath's scope/kind/commit naming so the
+// machine-readable metrics archive lines up with the retrospective archive.
+function getArchivedRunMetricsPath(state, kind) {
+    const scopeLabel = getCurrentScopeLabel(state);
+    if (kind === 'scope_accepted') {
+        const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
+        return join(state.runDir, `RUN_METRICS-scope-${scopeLabel}${suffix}.json`);
+    }
+    if (kind === 'blocked') {
+        return join(state.runDir, `RUN_METRICS-blocked-scope-${scopeLabel}.json`);
+    }
+    if (kind === 'failed') {
+        return join(state.runDir, `RUN_METRICS-failed-scope-${scopeLabel}.json`);
+    }
+    const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
+    return join(state.runDir, `RUN_METRICS-final${suffix}.json`);
+}
 async function loadRunEvents(runDir) {
     try {
         const content = await readFile(getEventsPath(runDir), 'utf8');
@@ -228,7 +248,7 @@ function summarizeBlocker(state) {
     const persistedBlocker = latestCompletedScope?.blocker?.trim() || null;
     const recovery = state.interactiveBlockedRecovery;
     const recoveryBlocker = recovery?.blockedReason?.trim() || null;
-    const advice = recovery?.adjudicatorAdvice ?? null;
+    const advice = recovery?.consultantAdvice ?? null;
     const lines = [];
     if (persistedBlocker) {
         lines.push(`- Final blocker: ${persistedBlocker}`);
@@ -237,9 +257,9 @@ function summarizeBlocker(state) {
         lines.push(`- Recovery blocker: ${recoveryBlocker}`);
     }
     if (advice) {
-        lines.push(`- Adjudicator triage: ${advice.triageCategory} (recoverable: ${advice.recoverable ? 'yes' : 'no'})`);
+        lines.push(`- Consultant triage: ${advice.triageCategory} (recoverable: ${advice.recoverable ? 'yes' : 'no'})`);
         if (advice.resolutionDirective.trim()) {
-            lines.push(`- Adjudicator suggested directive: ${advice.resolutionDirective.trim()}`);
+            lines.push(`- Consultant suggested directive: ${advice.resolutionDirective.trim()}`);
         }
     }
     if (lines.length === 0) {
@@ -306,7 +326,8 @@ async function renderRetrospective(state, kind) {
     const changedFiles = await summarizeChangedFiles(state);
     const verificationSummary = summarizeVerification(scopeEvents);
     const metricsEvents = kind === 'done' ? events : scopeEvents;
-    const runMetricsSummary = renderRunMetricsMarkdown(summarizeRunMetrics(metricsEvents));
+    const metrics = summarizeRunMetrics(metricsEvents);
+    const runMetricsSummary = renderRunMetricsMarkdown(metrics);
     const assessment = buildAssessment(state, scopeEvents);
     const narrativeRetrospective = buildNarrativeRetrospective({
         state,
@@ -320,7 +341,7 @@ async function renderRetrospective(state, kind) {
     const derivedPlan = getDerivedPlanView(state);
     const showDerivedPlanContext = Boolean(derivedPlan);
     const parentScopeLabel = derivedPlan?.executing ? getParentScopeLabel(state) : null;
-    return [
+    const content = [
         `# Neal Retrospective`,
         '',
         `## Outcome`,
@@ -377,15 +398,23 @@ async function renderRetrospective(state, kind) {
         ...renderInteractiveBlockedRecoveryHistoryLines(state.interactiveBlockedRecoveryHistory),
         '',
     ].join('\n');
+    return { content, metrics };
 }
 async function writeRetrospectiveFile(path, content) {
     await writeTextAtomic(path, content);
 }
+async function writeRunMetricsFile(path, metrics) {
+    await writeTextAtomic(path, `${JSON.stringify(metrics, null, 2)}\n`);
+}
 export async function writeCheckpointRetrospective(state, kind) {
-    const content = await renderRetrospective(state, kind);
+    const { content, metrics } = await renderRetrospective(state, kind);
     const currentPath = getCurrentRetrospectivePath(state.runDir);
     const archivedPath = getArchivedRetrospectivePath(state, kind);
     await writeRetrospectiveFile(currentPath, content);
     await writeRetrospectiveFile(archivedPath, content);
-    return { currentPath, archivedPath };
+    const currentMetricsPath = getCurrentRunMetricsPath(state.runDir);
+    const archivedMetricsPath = getArchivedRunMetricsPath(state, kind);
+    await writeRunMetricsFile(currentMetricsPath, metrics);
+    await writeRunMetricsFile(archivedMetricsPath, metrics);
+    return { currentPath, archivedPath, currentMetricsPath, archivedMetricsPath };
 }

package/dist/neal/review-debt.js

@@ -16,3 +16,33 @@ export function toResidualReviewDebt(findings) {
         coderCommit: finding.coderCommit,
     }));
 }
+// Plan-review debt is a canonical-keyed *projection* of the current findings,
+// never an accumulator: for each canonicalId whose latest-round finding is a
+// deferred verification-hardening finding, emit exactly one debt item (latest
+// round wins). A canonical that later reopens (its latest finding goes back to
+// open) or is fixed/rejected simply drops out of the projection, so the debt
+// lifecycle is automatic — no stale or duplicate entries and no removal rule.
+export function toPlanReviewDebt(findings) {
+    const latestByCanonical = new Map();
+    for (const finding of findings) {
+        const existing = latestByCanonical.get(finding.canonicalId);
+        if (!existing || finding.round >= existing.round) {
+            latestByCanonical.set(finding.canonicalId, finding);
+        }
+    }
+    return [...latestByCanonical.values()]
+        .filter((finding) => finding.status === 'deferred' && finding.findingClass === 'verification_hardening')
+        .map((finding) => ({
+        id: finding.id,
+        canonicalId: finding.canonicalId,
+        status: 'deferred',
+        files: [...finding.files],
+        claim: finding.claim,
+        evidence: finding.evidence ?? null,
+        requiredAction: finding.requiredAction,
+        coderDisposition: finding.coderDisposition,
+        coderCommit: finding.coderCommit,
+        findingClass: finding.findingClass,
+        originRound: finding.round,
+    }));
+}

package/dist/neal/review-findings/provider.js

@@ -1,6 +1,6 @@
 import { getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getDefaultCoderModel, getDefaultCoderProvider, getDefaultReviewerModel, getDefaultReviewerProvider, getInactivityTimeoutMs, } from '../config.js';
 import { runCoderStructuredPrompt } from '../agents/structured-coder.js';
-import { createInlineSection, getReviewerDoctrineAccessMode, readOnlyReviewerNeedsInlinedDiff, renderInlineReviewerContext, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { getReviewerDoctrineAccessMode, readOnlyReviewerNeedsInlinedDiff, } from '../context/inline-review-context.js';
 import { runWithAgentTurnLiveness } from '../providers/liveness.js';
 import { assertProviderSupportsCoder, assertProviderSupportsStructuredAdvisor, getStructuredAdvisorAdapter, } from '../providers/registry.js';
 import { createProviderTelemetrySink } from '../providers/telemetry.js';
@@ -47,25 +47,21 @@ class AgentReviewFindingsProviderAdapter {
     async reviewDraft(args) {
         const reviewer = getStructuredAdvisorAdapter(this.args.agentConfig.reviewer);
         const schema = buildReviewFindingsReviewSchema();
-        // The base adjudication prompt only previews the diff. A reviewer without
-        // repository read access gets the full selected diff and the draft
-        // findings artifact inlined so it can adjudicate entirely from the
-        // prompt. A read-only reviewer (read tools, no shell) that exposes its own
-        // commit-range diff tool gets the read-only range-inspection section
-        // directing it to the git_diff tool with the exact resolved revisions; a
-        // read-only reviewer without a commit-range diff tool (native Claude/Codex)
-        // instead gets the full selected diff inlined and no git_diff-tool
-        // instruction, because it can neither run git commands, call a git_diff
-        // tool, nor rely on the truncated preview. Tool-access reviewers keep the
-        // built prompt byte-identical.
+        // The base adjudication prompt only previews the diff. A read-only
+        // reviewer (read tools, no shell) that exposes its own commit-range diff
+        // tool gets the read-only range-inspection section directing it to the
+        // git_diff tool with the exact resolved revisions; a read-only reviewer
+        // without a commit-range diff tool (native Claude/Codex) instead gets the
+        // full selected diff inlined and no git_diff-tool instruction, because it
+        // can neither run git commands, call a git_diff tool, nor rely on the
+        // truncated preview. Tool-access reviewers keep the built prompt
+        // byte-identical.
         const accessMode = getReviewerDoctrineAccessMode(this.args.agentConfig.reviewer);
-        const prompt = reviewerNeedsInlineContext(this.args.agentConfig.reviewer)
-            ? `${args.prompt}\n\n${renderInlineReviewerContext(buildReviewFindingsReviewInlineContext(args))}`
-            : accessMode === 'read-only'
-                ? readOnlyReviewerNeedsInlinedDiff(this.args.agentConfig.reviewer)
-                    ? `${args.prompt}\n\n${buildReviewFindingsInlinedDiffSection(args.context)}`
-                    : `${args.prompt}\n\n${buildReviewFindingsReadOnlyInspectionSection(args.context)}`
-                : args.prompt;
+        const prompt = accessMode === 'read-only'
+            ? readOnlyReviewerNeedsInlinedDiff(this.args.agentConfig.reviewer)
+                ? `${args.prompt}\n\n${buildReviewFindingsInlinedDiffSection(args.context)}`
+                : `${args.prompt}\n\n${buildReviewFindingsReadOnlyInspectionSection(args.context)}`
+            : args.prompt;
         const result = await runWithAgentTurnLiveness({
             provider: this.args.agentConfig.reviewer.provider,
             role: 'structured-advisor',
@@ -102,14 +98,6 @@ class AgentReviewFindingsProviderAdapter {
         return validateReviewFindingsReview(result.structured);
     }
 }
-function buildReviewFindingsReviewInlineContext(args) {
-    return {
-        sections: [
-            createInlineSection(`Full selected diff for range ${args.context.externalBaseCommit}..${args.context.externalHeadCommit}`, args.context.diff || '(empty diff)'),
-            createInlineSection('Draft findings artifact under adjudication', JSON.stringify(args.draft, null, 2)),
-        ],
-    };
-}
 function buildReviewFindingsProtocolSpec(args) {
     return {
         protocol: 'neal-json-block-v1',
@@ -160,11 +148,11 @@ function assertReviewAgentCapabilities(agentConfig) {
         role: 'reviewer',
         context: 'neal review',
         reason: 'neal review uses the configured reviewer provider to adjudicate and accept or revise the findings artifact',
-        requireReadToolAccessOrInlineReviewerContext: true,
+        requireReadToolAccess: true,
         requireStructuredOutput: true,
         reasons: {
             structured_advisor_adapter: 'review findings adjudication runs through the configured structured-advisor adapter',
-            read_tool_access_or_inline_reviewer_context: 'the reviewer must either inspect the draft, selected diff, and repository context directly with read tools, or support structured output so Neal can inline the draft findings artifact and the full selected diff into the adjudication prompt',
+            read_tool_access: 'the reviewer must inspect the draft, selected diff, and repository context directly with read tools',
             structured_output: 'the reviewer verdict must be schema-validated before Neal accepts the findings artifact',
             model_override: 'a non-null reviewer model override is configured for review adjudication',
         },

package/dist/neal/review.js

@@ -126,12 +126,28 @@ export function renderReviewMarkdown(state) {
         for (const round of rounds) {
             lines.push('', `## Round ${round} Findings`);
             for (const finding of state.findings.filter((item) => item.round === round)) {
-                lines.push('', `### ${finding.id}`, `- Canonical ID: ${finding.canonicalId}`, `- Source: ${finding.source}`, `- Severity: ${finding.severity}`, `- Status: ${finding.status}`, `- Files: ${finding.files.join(', ') || 'n/a'}`, `- Claim: ${finding.claim}`, `- Evidence: ${finding.evidence?.trim() || 'n/a'}`, `- Required action: ${finding.requiredAction}`, `- Round summary: ${finding.roundSummary}`, `- Coder disposition: ${finding.coderDisposition ?? 'pending'}`, `- Coder commit: ${finding.coderCommit ?? 'pending'}`);
+                lines.push('', `### ${finding.id}`, `- Canonical ID: ${finding.canonicalId}`, `- Source: ${finding.source}`, `- Severity: ${finding.severity}`, 
+                // 'n/a' keeps execute-review findings (which carry no class)
+                // semantically unchanged rather than mislabeling them plan_correctness.
+                `- Finding class: ${finding.findingClass ?? 'n/a'}`, `- Status: ${finding.status}`, `- Files: ${finding.files.join(', ') || 'n/a'}`, `- Claim: ${finding.claim}`, `- Evidence: ${finding.evidence?.trim() || 'n/a'}`, `- Required action: ${finding.requiredAction}`, `- Round summary: ${finding.roundSummary}`, `- Coder disposition: ${finding.coderDisposition ?? 'pending'}`, `- Coder commit: ${finding.coderCommit ?? 'pending'}`);
             }
         }
     }
+    lines.push('', '## Plan Review Debt');
+    appendPlanReviewDebtGroup(lines, 'Inherited', state.inheritedPlanReviewDebt);
+    appendPlanReviewDebtGroup(lines, 'Current', state.planReviewDebt);
     return `${lines.join('\n')}\n`;
 }
+function appendPlanReviewDebtGroup(lines, label, items) {
+    lines.push('', `### ${label}`);
+    if (items.length === 0) {
+        lines.push('- none');
+        return;
+    }
+    for (const item of items) {
+        lines.push(`- ${item.canonicalId}: findingClass=${item.findingClass ?? 'n/a'}; originRound=${item.originRound ?? 'n/a'}; claim=${item.claim}; requiredAction=${item.requiredAction}; coderDisposition=${item.coderDisposition ?? 'none'}`);
+    }
+}
 export async function writeReviewMarkdown(path, state) {
     await writeTextAtomic(path, renderReviewMarkdown(state));
 }

package/dist/neal/run-metrics.js

@@ -48,6 +48,21 @@ function addUsage(target, value) {
 function hasUsage(usage) {
     return Object.values(usage).some((value) => value > 0);
 }
+// Accumulate cost from one counted event into the provider bucket. Presence is
+// tracked separately from value: costUsd stays null until an event carries a
+// numeric costUsd, then it holds the running sum. A single provider/role bucket
+// has one source; if both appear, 'provider' wins.
+function accumulateCost(bucket, data) {
+    const raw = data.costUsd;
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+        return;
+    }
+    bucket.costUsd = (bucket.costUsd ?? 0) + raw;
+    const source = data.costSource;
+    if (source === 'provider' || source === 'rate') {
+        bucket.costSource = bucket.costSource === 'provider' || source === 'provider' ? 'provider' : 'rate';
+    }
+}
 function cloneEmptyUsage() {
     return { ...EMPTY_USAGE };
 }
@@ -210,10 +225,13 @@ export function summarizeRunMetrics(events) {
                 label: identity.label,
                 turns: 0,
                 usage: cloneEmptyUsage(),
+                costUsd: null,
+                costSource: null,
             };
             existing.turns += 1;
             if (!hasDedicatedUsageEvents) {
                 addUsage(existing.usage, data.usage);
+                accumulateCost(existing, data);
             }
             providers.set(identity.key, existing);
         }
@@ -226,8 +244,11 @@ export function summarizeRunMetrics(events) {
                 label: identity.label,
                 turns: 0,
                 usage: cloneEmptyUsage(),
+                costUsd: null,
+                costSource: null,
             };
             addUsage(existing.usage, data.usage);
+            accumulateCost(existing, data);
             providers.set(identity.key, existing);
         }
         else if (event.type === 'provider.command_completed') {
@@ -276,6 +297,25 @@ export function summarizeRunMetrics(events) {
         phase.durationMs = start !== null && end !== null && end >= start ? end - start : null;
     }
     const publicPhases = phases.map(({ startIndex: _startIndex, endIndex: _endIndex, ...phase }) => phase);
+    const providerSummaries = [...providers.values()].sort((left, right) => {
+        const turns = right.turns - left.turns;
+        if (turns !== 0) {
+            return turns;
+        }
+        return usageSortValue(right) - usageSortValue(left);
+    });
+    // Coverage is computed only over usage-bearing buckets so a partial subtotal
+    // never masquerades as a complete run total.
+    const usageBearing = providerSummaries.filter((provider) => hasUsage(provider.usage));
+    const pricedUsageBearing = usageBearing.filter((provider) => provider.costUsd !== null);
+    const costCoverage = pricedUsageBearing.length === 0
+        ? 'none'
+        : pricedUsageBearing.length === usageBearing.length
+            ? 'complete'
+            : 'partial';
+    const totalCostUsd = costCoverage === 'none'
+        ? null
+        : providerSummaries.reduce((sum, provider) => (provider.costUsd !== null ? sum + provider.costUsd : sum), 0);
     return {
         observedStartedAt: firstTimestamp,
         observedCompletedAt: lastTimestamp,
@@ -288,13 +328,9 @@ export function summarizeRunMetrics(events) {
         toolEventCount,
         fileChangeEventCount,
         phases: publicPhases,
-        providers: [...providers.values()].sort((left, right) => {
-            const turns = right.turns - left.turns;
-            if (turns !== 0) {
-                return turns;
-            }
-            return usageSortValue(right) - usageSortValue(left);
-        }),
+        providers: providerSummaries,
+        totalCostUsd,
+        costCoverage,
     };
 }
 function formatDuration(value) {
@@ -327,6 +363,31 @@ function formatProviderName(summary) {
 function usageCell(value) {
     return value > 0 ? formatNumber(value) : '-';
 }
+function formatCostAmount(value) {
+    return `$${value.toFixed(4)}`;
+}
+// Cost cell for the Provider Usage table: '-' when the bucket reported no cost,
+// otherwise the fixed-precision USD amount with a footnote marker on
+// rate-computed cells.
+function formatCost(value, source) {
+    if (value === null) {
+        return '-';
+    }
+    return source === 'rate' ? `${formatCostAmount(value)}*` : formatCostAmount(value);
+}
+// The top-summary cost line, labeled by coverage so a partial subtotal is never
+// presented as a complete run total.
+function formatEstimatedCostLine(metrics) {
+    if (metrics.costCoverage === 'none' || metrics.totalCostUsd === null) {
+        return '- Estimated cost: unknown';
+    }
+    if (metrics.costCoverage === 'partial') {
+        const usageBearing = metrics.providers.filter((provider) => hasUsage(provider.usage));
+        const priced = usageBearing.filter((provider) => provider.costUsd !== null);
+        return `- Estimated cost (partial — ${priced.length} of ${usageBearing.length} priced providers): ${formatCostAmount(metrics.totalCostUsd)}`;
+    }
+    return `- Estimated cost: ${formatCostAmount(metrics.totalCostUsd)}`;
+}
 export function renderRunMetricsMarkdown(metrics) {
     const commandSummary = metrics.resolvedNonZeroCommandCount > 0
         ? `- Commands: ${metrics.commandCount} total, ${metrics.unresolvedNonZeroCommandCount} unresolved non-zero or failed, ${metrics.resolvedNonZeroCommandCount} resolved by later passing rerun`
@@ -337,16 +398,20 @@ export function renderRunMetricsMarkdown(metrics) {
         commandSummary,
         `- Tool events: ${metrics.toolEventCount}`,
         `- File change events: ${metrics.fileChangeEventCount}`,
+        formatEstimatedCostLine(metrics),
     ];
     if (metrics.phases.length > 0) {
         lines.push('', '### Phase Timing', '', '| Phase | Duration | Provider turns | Commands | Non-zero commands | Tool events | File changes |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: |', ...metrics.phases.map((phase) => `| ${formatPhaseName(phase.phase)} | ${formatPhaseDuration(phase)} | ${phase.providerTurns} | ${phase.commandCount} | ${phase.nonZeroCommandCount} | ${phase.toolEventCount} | ${phase.fileChangeEventCount} |`));
     }
     const providersWithUsage = metrics.providers.filter((provider) => provider.turns > 0 || hasUsage(provider.usage));
     if (providersWithUsage.length > 0) {
-        lines.push('', '### Provider Usage', '', '| Provider / role | Turns | Input | Cached input | Cache created | Cache read | Output | Reasoning output | Total |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |', ...providersWithUsage.map((provider) => {
+        lines.push('', '### Provider Usage', '', '| Provider / role | Turns | Input | Cached input | Cache created | Cache read | Output | Reasoning output | Total | Cost |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |', ...providersWithUsage.map((provider) => {
             const usage = provider.usage;
-            return `| ${formatProviderName(provider)} | ${provider.turns} | ${usageCell(usage.inputTokens)} | ${usageCell(usage.cachedInputTokens)} | ${usageCell(usage.cacheCreationInputTokens)} | ${usageCell(usage.cacheReadInputTokens)} | ${usageCell(usage.outputTokens)} | ${usageCell(usage.reasoningOutputTokens)} | ${usageCell(usage.totalTokens)} |`;
+            return `| ${formatProviderName(provider)} | ${provider.turns} | ${usageCell(usage.inputTokens)} | ${usageCell(usage.cachedInputTokens)} | ${usageCell(usage.cacheCreationInputTokens)} | ${usageCell(usage.cacheReadInputTokens)} | ${usageCell(usage.outputTokens)} | ${usageCell(usage.reasoningOutputTokens)} | ${usageCell(usage.totalTokens)} | ${formatCost(provider.costUsd, provider.costSource)} |`;
         }));
+        if (providersWithUsage.some((provider) => provider.costUsd !== null && provider.costSource === 'rate')) {
+            lines.push('', '\\* Cost estimated from published or configured rates, not reported by the provider.');
+        }
     }
     else {
         lines.push('', '### Provider Usage', '', '- No provider usage events recorded.');

package/dist/neal/state-invariants.js

@@ -307,8 +307,10 @@ function assertValidPendingPlanReviewGuidance(state, context) {
         throwStateInvariant(context, 'pendingPlanReviewGuidance', `expected null for ${formatInvalidValue(state.topLevelMode)} mode`);
     }
     assertNonEmptyString(guidance.message, 'pendingPlanReviewGuidance.message', context);
-    if (guidance.sourcePhase !== 'reviewer_plan') {
-        throwStateInvariant(context, 'pendingPlanReviewGuidance.sourcePhase', `expected "reviewer_plan", received ${formatInvalidValue(guidance.sourcePhase)}`);
+    if (guidance.sourcePhase !== 'reviewer_plan' &&
+        guidance.sourcePhase !== 'coder_plan_response' &&
+        guidance.sourcePhase !== 'coder_plan_optional_response') {
+        throwStateInvariant(context, 'pendingPlanReviewGuidance.sourcePhase', `expected one of "reviewer_plan", "coder_plan_response", "coder_plan_optional_response", received ${formatInvalidValue(guidance.sourcePhase)}`);
     }
     if (typeof guidance.recordedAt !== 'string') {
         throwStateInvariant(context, 'pendingPlanReviewGuidance.recordedAt', `expected string, received ${formatInvalidValue(guidance.recordedAt)}`);
@@ -466,10 +468,16 @@ export function assertValidOrchestrationState(state, context) {
     if (activeStatusInTerminalPhase) {
         throwStateInvariant(context, 'status', `cannot be ${JSON.stringify(state.status)} while phase is terminal ${JSON.stringify(state.phase)}`);
     }
+    // The durable coder-authored plan-stage blocker reason must never outlive its
+    // block: any return to a non-blocked status (running/paused/done/failed) must
+    // have cleared it. This catches a missed clear at the next save/load.
+    if (state.status !== 'blocked' && state.blockerReason !== null) {
+        throwStateInvariant(context, 'blockerReason', `expected null when status is ${JSON.stringify(state.status)}, received ${formatInvalidValue(state.blockerReason)}`);
+    }
     assertSafeIntegerAtLeast(state.currentScopeNumber, 'currentScopeNumber', 0, context);
     assertSafeIntegerAtLeast(state.coderRetryCount, 'coderRetryCount', 0, context);
     assertSafeIntegerAtLeast(state.unattendedAutoResumeCount, 'unattendedAutoResumeCount', 0, context);
-    assertSafeIntegerAtLeast(state.reviewStuckArbiterCount, 'reviewStuckArbiterCount', 0, context);
+    assertSafeIntegerAtLeast(state.consultantAttemptCount, 'consultantAttemptCount', 0, context);
     assertSafeIntegerAtLeast(state.finalCompletionContinueExecutionCount, 'finalCompletionContinueExecutionCount', 0, context);
     assertSafeIntegerAtLeast(state.splitPlanCountForCurrentScope, 'splitPlanCountForCurrentScope', 0, context);
     assertSafeIntegerAtLeast(state.derivedPlanDepth, 'derivedPlanDepth', 0, context);

package/dist/neal/state-views.js

@@ -117,13 +117,35 @@ export function getInteractiveRecoveryView(state) {
         pendingOperatorGuidance,
     };
 }
+// The plan-stage blocked origin that a top-level plan run can answer via
+// `neal resume --message`, or null when the run is not in such a wait. The
+// reviewer-plan message-resume path is always eligible. A coder-authored
+// *response* block (coder_plan_response / coder_plan_optional_response) is
+// eligible only when it carries the durable `blockerReason`: Scope 6 sets that
+// reason exclusively for coder_authored landings and leaves it null for a
+// dirty-worktree safety block, which lands at the same phase but must stay a
+// normal blocked state (no --message route, no waiting-for-guidance status). The
+// initial `coder_plan` authoring block is deliberately excluded.
+export function getPlanReviewGuidanceOriginPhase(state) {
+    if (state.topLevelMode !== 'plan' ||
+        state.status !== 'blocked' ||
+        state.phase !== 'blocked' ||
+        state.pendingPlanReviewGuidance !== null) {
+        return null;
+    }
+    if (state.blockedFromPhase === 'reviewer_plan') {
+        return 'reviewer_plan';
+    }
+    if ((state.blockedFromPhase === 'coder_plan_response' ||
+        state.blockedFromPhase === 'coder_plan_optional_response') &&
+        state.blockerReason !== null) {
+        return state.blockedFromPhase;
+    }
+    return null;
+}
 export function getPlanReviewGuidanceView(state) {
     const pendingOperatorGuidance = state.topLevelMode === 'plan' && state.pendingPlanReviewGuidance !== null;
-    const waitingForOperatorGuidance = state.topLevelMode === 'plan' &&
-        state.status === 'blocked' &&
-        state.phase === 'blocked' &&
-        state.blockedFromPhase === 'reviewer_plan' &&
-        state.pendingPlanReviewGuidance === null;
+    const waitingForOperatorGuidance = getPlanReviewGuidanceOriginPhase(state) !== null;
     return {
         kind: 'plan_review_guidance',
         waitingForOperatorGuidance,