@navels/neal 0.5.0 → 0.6.0

package/dist/neal/adjudicator/execute.js

@@ -1,6 +1,6 @@
 import { mkdir } from 'node:fs/promises';
 import { runCoderResponseRound, runReviewerRound } from '../agents.js';
-import { readOnlyReviewerNeedsInlinedDiff } from '../context/inline-review-context.js';
+import { OPEN_FINDINGS_PROMPT_ITEM_LIMIT, readOnlyReviewerNeedsInlinedDiff, } from '../context/inline-review-context.js';
 import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
 import { getReviewStuckWindow } from '../config.js';
 import { getDiffForRangePaths } from '../git.js';
@@ -229,9 +229,19 @@ export function buildVerificationHint(state) {
         '- Rerun full test suites only if your new changes materially invalidate that reviewed baseline or the plan explicitly requires new end-of-scope full-suite verification.',
     ].join('\n');
 }
+// The bounded finding set for one coder response round. Both the response
+// prompt and validateExecuteResponseCoverage consume this same selection, so
+// the coder is asked to disposition exactly the findings it can see. At most
+// OPEN_FINDINGS_PROMPT_ITEM_LIMIT findings are presented per round; findings
+// beyond the limit stay open and synthesizeExecuteResponseState keeps the
+// response phase active, presenting the next batch immediately, until every
+// open finding of the round's kind has been dispositioned.
 export function getExecuteResponseOpenFindings(state, mode = 'blocking') {
     const selector = mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding;
-    return state.findings.filter(selector).map((finding) => ({
+    return state.findings
+        .filter(selector)
+        .slice(0, OPEN_FINDINGS_PROMPT_ITEM_LIMIT)
+        .map((finding) => ({
         id: finding.id,
         source: finding.source,
         claim: finding.claim,
@@ -266,7 +276,7 @@ function validateExecuteResponseCoverage(args) {
         throw new Error(`Coder ${args.mode} response returned duplicate finding dispositions: ${[...duplicateIds].join(', ')}`);
     }
     if (unknownIds.size > 0) {
-        throw new Error(`Coder ${args.mode} response returned dispositions for non-open findings: ${[...unknownIds].join(', ')}`);
+        throw new Error(`Coder ${args.mode} response returned dispositions for findings outside the presented open set: ${[...unknownIds].join(', ')}`);
     }
     if (args.response.payload.outcome !== 'responded') {
         return;
@@ -526,7 +536,12 @@ export function synthesizeExecuteReviewerState(args) {
         ];
         mergedFindings = [...args.state.findings, ...findings];
     }
-    const hasBlockingFindings = findings.some((finding) => finding.severity === 'blocking');
+    // Deliberately derived from the merged set as well as the current reviewer
+    // payload: a prior round's still-open blocker (for example one beyond the
+    // batched response round's presentation limit) must keep forcing a revision
+    // even when the current reviewer round is empty, so an empty round can never
+    // accept over an open blocking finding.
+    const hasBlockingFindings = findings.some((finding) => finding.severity === 'blocking') || mergedFindings.some(isOpenBlockingFinding);
     const hasOpenNonBlockingFindings = mergedFindings.some(isOpenNonBlockingFinding);
     const openBlockingCanonicalSet = getOpenBlockingCanonicalSet(mergedFindings);
     const openBlockingCanonicalIds = [...openBlockingCanonicalSet].sort();
@@ -633,11 +648,22 @@ export function synthesizeExecuteResponseState(args) {
         };
     });
     const outcome = args.response.payload.outcome;
+    // Response rounds batch: when open findings of this round's kind remain
+    // after the dispositions are applied (they were beyond the per-round
+    // presentation limit), stay in the same response phase so the next batch is
+    // presented immediately instead of spending a reviewer round per batch.
+    // Coverage validation guarantees the presented batch was fully
+    // dispositioned, so the backlog strictly shrinks and the loop terminates.
+    const hasNextResponseBatch = findings.some(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding);
     const nextPhase = outcome === 'blocked' || outcome === 'split_plan'
         ? 'blocked'
         : mode === 'optional'
-            ? EXECUTE_FINALIZATION_PHASE
-            : 'reviewer_scope';
+            ? hasNextResponseBatch
+                ? 'coder_optional_response'
+                : EXECUTE_FINALIZATION_PHASE
+            : hasNextResponseBatch
+                ? 'coder_response'
+                : 'reviewer_scope';
     return {
         findings,
         nextPhase,

package/dist/neal/agents/prompts.js

@@ -1,6 +1,6 @@
-import { assertNoReadPromptInstructionText, renderInlineReviewerContext, } from '../context/inline-review-context.js';
+import { assertNoReadPromptInstructionText, boundFreeTextValues, renderInlineReviewerContext, truncateInlineSectionBody, } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED as SHARED_AUTONOMY_BLOCKED, AUTONOMY_CHUNK_DONE as SHARED_AUTONOMY_CHUNK_DONE, AUTONOMY_DONE as SHARED_AUTONOMY_DONE, AUTONOMY_SCOPE_DONE as SHARED_AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN as SHARED_AUTONOMY_SPLIT_PLAN, buildProgressSection, getCanonicalPlanContractLines, getProtocolMarkerArtifactProhibitionLines, getStandalonePlanPayloadSourceOfTruthLines, } from '../prompts/shared.js';
-import { getUserGuidanceLines } from '../prompts/guidance.js';
+import { getUserGuidanceLines, USER_GUIDANCE_MAX_CHARS } from '../prompts/guidance.js';
 import { assertPromptBuilder, resolvePrimaryVariant } from '../prompts/assert-builder.js';
 export { buildCoderResponsePrompt, buildLegacyScopePrompt, buildReviewerPrompt, buildScopePrompt } from '../prompts/execute.js';
 export { buildCoderPlanResponsePrompt, buildLegacyPlanningPrompt, buildPlanReviewerPrompt, buildPlanningPrompt, } from '../prompts/planning.js';
@@ -41,7 +41,9 @@ export function buildConsultantPrompt(args) {
         ...staticInstructionLines,
         '',
         'Blocked reason:',
-        args.blockedReason,
+        // Agent-authored free text shares the fixed agent free-text cap at render
+        // time; the persisted blocked reason keeps its full text.
+        boundFreeTextValues([args.blockedReason])[0],
         '',
         renderInlineReviewerContext(args.inlineContext),
     ].join('\n');
@@ -102,9 +104,12 @@ export function buildBlockedRecoveryCoderPrompt(args) {
         'Do not treat operator guidance as authorization to skip verification, waive policy, or reinterpret the target beyond the current scope.',
         '',
         'Blocked recovery context:',
-        `- Blocked reason: ${args.blockedReason}`,
+        // The blocked reason is agent-authored free text and the guidance is
+        // operator-authored; each gets its class's render-time cap while the
+        // persisted values keep their full text.
+        `- Blocked reason: ${boundFreeTextValues([args.blockedReason])[0]}`,
         `- Recovery turns used: ${args.turnsTaken} of ${args.maxTurns}`,
-        `- Latest operator guidance: ${args.operatorGuidance}`,
+        `- Latest operator guidance: ${truncateInlineSectionBody(args.operatorGuidance, USER_GUIDANCE_MAX_CHARS)}`,
         '',
         'Current progress state:',
         buildProgressSection(args.progressText),

package/dist/neal/commands/check.js

@@ -4,6 +4,7 @@ import { verifyNotification } from '../../notifier.js';
 import { parseCheckArgs } from '../cli.js';
 import { assertWriterProvidersConfigured, getAgentTurnRetryLimit, getAgentTurnStartupTimeoutMs, getApiRetryLimit, getFinalCompletionContinueExecutionMax, getInactivityTimeoutMs, getInteractiveBlockedRecoveryMaxTurns, getMaxReviewRounds, getNotifyBin, getPhaseHeartbeatMs, getReviewStuckWindow, } from '../config.js';
 import { getNealDirGitIgnoreStatus } from '../git.js';
+import { collectGuidanceDiagnostics, USER_GUIDANCE_MAX_CHARS } from '../prompts/guidance.js';
 import { runWithAgentTurnLiveness } from '../providers/liveness.js';
 import { getCoderAdapter, getProviderDefinition, getStructuredAdvisorAdapter, } from '../providers/registry.js';
 import { sanitizeSensitiveText } from '../sensitive-text.js';
@@ -343,6 +344,11 @@ export async function runNealCheckCli(options = {}) {
     writeLine(stdout, `  ${describeRole('coder', agentConfig.coder)}`);
     writeLine(stdout, `  ${describeRole('reviewer', agentConfig.reviewer)}`);
     writeLine(stdout, `  ${describeNotificationScript(notifyBin)}`);
+    for (const entry of collectGuidanceDiagnostics()) {
+        if (entry.chars > USER_GUIDANCE_MAX_CHARS) {
+            writeLine(stdout, `  warning: ${entry.role} guidance at ${entry.path} is ${entry.chars} characters; prompts inline the first ${USER_GUIDANCE_MAX_CHARS} and truncate the rest. Trim the file.`);
+        }
+    }
     writeLine(stdout, '');
     // Native adapters drive their providers directly; any other writer provider is
     // an openai-compatible model that should be qualified end-to-end with `neal compat`.

package/dist/neal/config.js

@@ -19,7 +19,7 @@ const DEFAULT_CONFIG = {
         agent_turn_startup_timeout_ms: 300_000,
         agent_turn_retry_limit: 1,
         interactive_blocked_recovery_max_turns: 3,
-        final_completion_continue_execution_max: 2,
+        final_completion_continue_execution_max: 3,
         consultant_max_attempts: 1,
         notify_bin: null,
     },

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

@@ -4,6 +4,122 @@ import { getProviderDefinition, isRegisteredProviderId } from '../providers/regi
 // truncation posture of truncateForPrompt in src/neal/agents/structured-json.ts:
 // truncate with an explicit marker instead of silently dropping content.
 export const INLINE_SECTION_MAX_CHARS = 200_000;
+// Fixed aggregate character budget for the free-text values of one
+// agent-authored payload embedded in another agent's prompt (review-finding
+// text, progress justifications, completion summaries). The budget covers the
+// total rendered free text including truncation markers, so the free-text
+// contribution of a section never exceeds this constant. Control data (ids,
+// severities, statuses, file paths) never rides this budget: callers render it
+// separately and exactly via boundOpenFindingsForPrompt-style wrappers.
+export const AGENT_FREE_TEXT_SECTION_MAX_CHARS = 20_000;
+// Upper bound on one rendered truncation marker:
+// '\n[truncated N character(s)]' with N at most 16 digits.
+const TRUNCATION_MARKER_MAX_CHARS = 42;
+// Maximum open findings presented to the coder per response round. Response
+// selection (getExecuteResponseOpenFindings and the plan-review response
+// phase) and prompt rendering share this bound, so the coder always sees
+// exactly the finding set it must disposition; findings beyond the limit stay
+// open and are presented in later response rounds until every one is handled.
+// The limit also keeps boundFreeTextValues' cardinality precondition
+// satisfied: 3 free-text values per finding times this limit stays far under
+// AGENT_FREE_TEXT_SECTION_MAX_CHARS / TRUNCATION_MARKER_MAX_CHARS.
+export const OPEN_FINDINGS_PROMPT_ITEM_LIMIT = 50;
+function renderBoundedFreeTextValue(text, cap) {
+    if (text.length <= cap) {
+        return text;
+    }
+    if (cap <= 0) {
+        return `[truncated ${text.length} character(s)]`;
+    }
+    return `${text.slice(0, cap)}\n[truncated ${text.length - cap} character(s)]`;
+}
+// Largest equal per-value kept-character cap such that the values fit the
+// kept-character budget (water-filling): short values keep their full text and
+// long values share the remaining budget equally. Returns MAX_SAFE_INTEGER
+// when everything already fits.
+function computeFairValueCap(lengths, budget) {
+    const sorted = [...lengths].sort((left, right) => left - right);
+    let remaining = budget;
+    for (let index = 0; index < sorted.length; index += 1) {
+        const share = Math.floor(remaining / (sorted.length - index));
+        if (sorted[index] > share) {
+            return Math.max(share, 0);
+        }
+        remaining -= sorted[index];
+    }
+    return Number.MAX_SAFE_INTEGER;
+}
+// Bounds a fixed list of agent-authored free-text values to a fixed aggregate
+// budget, truncation markers included: marker allowance is reserved up front,
+// the kept characters are water-filled over the rest, so the total rendered
+// length is always <= budget. Positions are preserved one-to-one with the
+// input. Callers keep control data (ids, files, severities) out of this list
+// and enforce the finite cardinality this validates. Never mutates the input.
+export function boundFreeTextValues(texts, budget = AGENT_FREE_TEXT_SECTION_MAX_CHARS) {
+    if (texts.length * TRUNCATION_MARKER_MAX_CHARS > budget) {
+        throw new Error(`boundFreeTextValues received ${texts.length} free-text values; the aggregate budget of ${budget} characters supports at most ${Math.floor(budget / TRUNCATION_MARKER_MAX_CHARS)}. Bound the payload's item cardinality before rendering free text.`);
+    }
+    const keptBudget = budget - texts.length * TRUNCATION_MARKER_MAX_CHARS;
+    const cap = computeFairValueCap(texts.map((text) => text.length), keptBudget);
+    return texts.map((text) => renderBoundedFreeTextValue(text, cap));
+}
+// Render-only view of an open-findings list for prompt embedding. Every
+// finding renders: id, source, and severity are copied exactly, each files
+// path renders whole with the list length bounded via boundChangedFileList,
+// and only the claim, requiredAction, and roundSummary free text shares the
+// fixed aggregate budget. Callers must present at most
+// OPEN_FINDINGS_PROMPT_ITEM_LIMIT findings — the same bounded set their
+// response processing validates against — so this never drops a finding the
+// coder is required to disposition; it throws on a larger list instead of
+// silently diverging from the response contract. Never mutates the input.
+export function boundOpenFindingsForPrompt(findings) {
+    if (findings.length > OPEN_FINDINGS_PROMPT_ITEM_LIMIT) {
+        throw new Error(`boundOpenFindingsForPrompt received ${findings.length} findings; response rounds present at most ${OPEN_FINDINGS_PROMPT_ITEM_LIMIT}. Bound the selection where the response set is chosen.`);
+    }
+    const boundedTexts = boundFreeTextValues(findings.flatMap((finding) => [finding.claim, finding.requiredAction, finding.roundSummary]));
+    return findings.map((finding, index) => ({
+        ...finding,
+        claim: boundedTexts[index * 3],
+        requiredAction: boundedTexts[index * 3 + 1],
+        roundSummary: boundedTexts[index * 3 + 2],
+        files: boundChangedFileList(finding.files),
+    }));
+}
+// Maximum commit subjects rendered per commit-subject list that reaches a
+// prompt (the aggregate completion range and the scope review's commits-in-scope
+// list). Matches CHANGED_FILE_LIST_LIMIT so both run-scaling list bounds read
+// the same way.
+export const COMMIT_SUBJECT_LIST_LIMIT = 20;
+// Character cap for one rendered git summary block that grows with run length
+// (diff-stat output, one line per file). Applied via truncateInlineSectionBody,
+// so an over-cap block carries an explicit truncation marker.
+export const GIT_SUMMARY_SECTION_MAX_CHARS = 20_000;
+// Bounds a commit-subject list for prompt rendering: the first
+// COMMIT_SUBJECT_LIST_LIMIT subjects render with their text sharing the fixed
+// aggregate free-text budget (subjects are largely agent-authored), and the
+// rest collapse to an explicit "(+N more)" entry. The underlying arrays keep
+// every subject for non-prompt consumers. Never mutates the input.
+export function boundCommitSubjectList(subjects) {
+    const kept = boundFreeTextValues(subjects.slice(0, COMMIT_SUBJECT_LIST_LIMIT));
+    if (subjects.length <= COMMIT_SUBJECT_LIST_LIMIT) {
+        return kept;
+    }
+    return [...kept, `(+${subjects.length - COMMIT_SUBJECT_LIST_LIMIT} more)`];
+}
+// Maximum file paths rendered per changed-file list that reaches a prompt.
+// Matches the reviewer continuity packet's per-scope bound
+// (COMPLETED_SCOPE_CHANGED_FILE_LIMIT in src/neal/context/reviewer-context.ts).
+export const CHANGED_FILE_LIST_LIMIT = 20;
+// Bounds a changed-file list for prompt rendering: the first
+// CHANGED_FILE_LIST_LIMIT entries render and the rest collapse to an explicit
+// "(+N more)" marker entry. Callers join or JSON-embed the result; the
+// underlying arrays in state and packets keep every path.
+export function boundChangedFileList(files, limit = CHANGED_FILE_LIST_LIMIT) {
+    if (files.length <= limit) {
+        return [...files];
+    }
+    return [...files.slice(0, limit), `(+${files.length - limit} more)`];
+}
 // Canonical forbidden-phrase list for no-read prompts (today: the blocked-run
 // consultant, which always judges from Neal-inlined in-memory context). A
 // no-read prompt must contain no instruction that requires repository, file,

package/dist/neal/final-completion.js

@@ -1,11 +1,12 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getFinalCompletionContinueExecutionMax } from './config.js';
+import { boundChangedFileList } from './context/inline-review-context.js';
 import { getChangedFilesForRange, getCommitRange, getCommitSubjects, getDiffStatForRange, } from './git.js';
 import { toResidualReviewDebt } from './review-debt.js';
 import { buildScopeAccountingSummary, getCurrentScopeLabel } from './scopes.js';
 import { getDerivedPlanView, getFinalCompletionView } from './state-views.js';
-import { extractVerificationCommandResults, latestCommandResultPerCommand, summarizeVerificationCommandResults, } from './verification-events.js';
+import { buildVerificationTally, extractVerificationCommandResults, } from './verification-events.js';
 function getEventsPath(runDir) {
     return join(runDir, 'events.ndjson');
 }
@@ -27,7 +28,7 @@ function renderCompletedScopeSummary(scopes) {
     return scopes
         .map((scope) => {
         const changedFiles = scope.changedFiles.length > 0
-            ? `${scope.changedFiles.length} file(s): ${scope.changedFiles.join(', ')}`
+            ? `${scope.changedFiles.length} file(s): ${boundChangedFileList(scope.changedFiles).join(', ')}`
             : 'no changed files';
         const commit = scope.finalCommit ?? 'pending';
         const parent = scope.derivedFromParentScope ? ` | parent ${scope.derivedFromParentScope}` : '';
@@ -191,8 +192,6 @@ export async function buildFinalCompletionPacket(args) {
     const finalCommit = terminalScope?.finalCommit ?? args.state.finalCommit;
     const effectiveScopes = mergeCompletedScopesWithTerminalScope(args.state, terminalScope);
     const allVerificationCommandResults = await loadVerificationCommandResults(args.state.runDir);
-    const verificationCommandResults = latestCommandResultPerCommand(allVerificationCommandResults);
-    const verificationCommands = verificationCommandResults.map((result) => result.command);
     const scopeAccounting = buildScopeAccountingSummary(effectiveScopes);
     const terminalChangedFiles = [...(terminalScope?.changedFiles ?? [])];
     const planChangedFiles = uniqueFiles(effectiveScopes
@@ -219,9 +218,7 @@ export async function buildFinalCompletionPacket(args) {
         planChangedFilesSummary: summarizeChangedFiles(planChangedFiles),
         residualReviewDebt,
         residualReviewDebtSummary: summarizeResidualReviewDebt(effectiveScopes),
-        verificationCommands,
-        verificationCommandResults,
-        verificationSummary: summarizeVerificationCommandResults(verificationCommandResults),
+        verificationTally: buildVerificationTally(allVerificationCommandResults),
         lastNonEmptyImplementationScope: findLastNonEmptyImplementationScope(effectiveScopes, terminalScope, args.state),
         continueExecutionCount: finalCompletion?.continueExecutionCount ?? 0,
         continueExecutionMax: Math.max(0, getFinalCompletionContinueExecutionMax(args.state.cwd)),

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

@@ -5,6 +5,7 @@ import { isOpenBlockingFinding, isOpenNonBlockingFinding, mapDecisionToStatus, }
 import { getDerivedPlanBlockedReason, isDerivedPlanReviewState, plannerProviderStartsFreshSessions, resolvePlanningAdjudicationContext, runPlanningResponseAdjudication, runPlanningReviewerAdjudication, synthesizePlanReviewRound, } from '../../adjudicator/planning.js';
 import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
 import { getPlanReviewDebtRoundThreshold, getReviewStuckWindow } from '../../config.js';
+import { OPEN_FINDINGS_PROMPT_ITEM_LIMIT } from '../../context/inline-review-context.js';
 import { toPlanReviewDebt } from '../../review-debt.js';
 import { writeDiagnostic } from '../../diagnostic.js';
 import { getWorktreeStatus } from '../../git.js';
@@ -402,7 +403,14 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     if (isPlanRefinementState(state)) {
         writeDiagnostic(`${formatPlanRefinementRoundLine({ round: state.rounds.length + 1, maxRounds: state.maxRounds })}\n`, logger);
     }
-    const openFindings = state.findings.filter(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding);
+    // The bounded finding set for this response round: the prompt and the
+    // disposition eligibility below consume this same selection. Findings
+    // beyond the per-round limit stay open; when the presented set is fully
+    // dispositioned, this phase stays active and presents the next batch (see
+    // hasNextResponseBatch below), so the cap never strands a finding.
+    const openFindings = state.findings
+        .filter(mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding)
+        .slice(0, OPEN_FINDINGS_PROMPT_ITEM_LIMIT);
     // Recorded operator guidance must reach the planner. If a prior blocked response
     // closed every finding, the guidance would otherwise be silently discarded here
     // (finalizePlanReviewResponseWithoutOpenFindings clears pendingPlanReviewGuidance
@@ -459,6 +467,31 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
     // hardening finding cannot be silently un-banked by an out-of-band disposition)
     // and matches the replay harness's open-blocking eligibility guard.
     const openFindingIds = new Set(openFindings.map((finding) => finding.id));
+    // Optional responses must disposition every presented finding exactly once,
+    // matching execute optional response coverage: a partial optional response
+    // would otherwise land acceptance below while presented findings — and every
+    // overflow batch beyond the per-round presentation limit — were never
+    // resolved. Out-of-set ids keep their documented no-op tolerance.
+    if (mode === 'optional' && codex.payload.outcome === 'responded') {
+        const seenPresentedIds = new Set();
+        const duplicateIds = new Set();
+        for (const response of codex.payload.responses) {
+            if (!openFindingIds.has(response.id)) {
+                continue;
+            }
+            if (seenPresentedIds.has(response.id)) {
+                duplicateIds.add(response.id);
+            }
+            seenPresentedIds.add(response.id);
+        }
+        if (duplicateIds.size > 0) {
+            throw new Error(`Planner optional response returned duplicate finding dispositions: ${[...duplicateIds].join(', ')}`);
+        }
+        const missingIds = openFindings.map((finding) => finding.id).filter((id) => !seenPresentedIds.has(id));
+        if (missingIds.length > 0) {
+            throw new Error(`Planner optional response did not disposition every presented finding: ${missingIds.join(', ')}`);
+        }
+    }
     const findings = state.findings.map((finding) => {
         if (!openFindingIds.has(finding.id)) {
             return finding;
@@ -474,6 +507,16 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
             coderCommit: null,
         };
     });
+    // Response rounds batch: when the presented set was fully dispositioned but
+    // open findings of this round's kind remain (they were beyond the per-round
+    // presentation limit), stay in this response phase so the next batch is
+    // presented immediately instead of spending a plan-review round per batch.
+    // The full-disposition requirement guarantees the backlog strictly shrinks;
+    // a partially-skipped presented set falls through to the reviewer so the
+    // existing convergence machinery judges it.
+    const openSelector = mode === 'optional' ? isOpenNonBlockingFinding : isOpenBlockingFinding;
+    const presentedStillOpen = findings.some((finding) => openFindingIds.has(finding.id) && openSelector(finding));
+    const hasNextResponseBatch = !presentedStillOpen && findings.some(openSelector);
     const nextState = await saveState(statePath, {
         ...state,
         plannerSessionHandle: codex.sessionHandle,
@@ -485,17 +528,19 @@ export async function runPlanningResponsePhase(state, statePath, phase, logger)
         planReviewDebt: toPlanReviewDebt(findings),
         phase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
             ? 'blocked'
-            : mode === 'optional'
-                ? derivedPlanReview
-                    ? 'awaiting_derived_plan_execution'
-                    : 'done'
-                : 'reviewer_plan',
+            : hasNextResponseBatch
+                ? phase
+                : mode === 'optional'
+                    ? derivedPlanReview
+                        ? 'awaiting_derived_plan_execution'
+                        : 'done'
+                    : 'reviewer_plan',
         status: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked'
             ? 'blocked'
-            : mode === 'optional' && !derivedPlanReview
+            : mode === 'optional' && !derivedPlanReview && !hasNextResponseBatch
                 ? 'done'
                 : 'running',
-        derivedPlanStatus: mode === 'optional' && codex.payload.outcome !== 'blocked' && derivedPlanReview
+        derivedPlanStatus: mode === 'optional' && codex.payload.outcome !== 'blocked' && derivedPlanReview && !hasNextResponseBatch
             ? 'accepted'
             : state.derivedPlanStatus,
         blockedFromPhase: dirtyWorktreeBlocker || codex.payload.outcome === 'blocked' ? phase : null,

package/dist/neal/prompts/execute.js

@@ -1,4 +1,4 @@
-import { renderInlinedRangeDiffSection, truncateInlineSectionBody } from '../context/inline-review-context.js';
+import { AGENT_FREE_TEXT_SECTION_MAX_CHARS, boundChangedFileList, boundCommitSubjectList, boundFreeTextValues, boundOpenFindingsForPrompt, GIT_SUMMARY_SECTION_MAX_CHARS, renderInlinedRangeDiffSection, truncateInlineSectionBody, } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED, AUTONOMY_DONE, AUTONOMY_SCOPE_DONE, AUTONOMY_SPLIT_PLAN, buildProgressSection, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getExecuteScopeProgressPayloadContractLines, getProtocolMarkerArtifactProhibitionLines, getStandalonePlanPayloadSourceOfTruthLines, getTerminalMarkerArtifactBoundaryLines, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
 import { getUserGuidanceLines } from './guidance.js';
@@ -107,6 +107,23 @@ export function buildLegacyScopePrompt(planDoc, progressText) {
     ].join('\n');
 }
 export const EARLIER_SCOPE_CHANGES_SECTION_HEADING = '## Earlier-scope changes to files in this diff';
+// Render-only view of the coder's progress justification: the four free-text
+// fields share the fixed aggregate free-text budget; the stored payload keeps
+// its full text.
+function boundProgressJustificationForPrompt(justification) {
+    const bounded = boundFreeTextValues([
+        justification.milestoneTargeted,
+        justification.newEvidence,
+        justification.whyNotRedundant,
+        justification.nextStepUnlocked,
+    ]);
+    return {
+        milestoneTargeted: bounded[0],
+        newEvidence: bounded[1],
+        whyNotRedundant: bounded[2],
+        nextStepUnlocked: bounded[3],
+    };
+}
 // Rendered for every execute-scope review, with or without an overlap: a
 // tool-access reviewer can find earlier-scope history itself, and the rule
 // about what that history means must not depend on whether Neal inlined it.
@@ -124,8 +141,8 @@ export function buildReviewerPrompt(args) {
     // collected" (null/undefined) so an empty diff still rides the inlined channel
     // instead of falling back to git_diff-tool phrasing the reviewer cannot use.
     const rangeDiffInlined = accessMode === 'read-only' && args.inlinedRangeDiff !== null && args.inlinedRangeDiff !== undefined;
-    const changedFilesText = args.changedFiles.length > 0 ? args.changedFiles.join('\n') : '(no changed files)';
-    const commitsText = args.commits.length > 0 ? args.commits.join('\n') : '(no commits recorded)';
+    const changedFilesText = args.changedFiles.length > 0 ? boundChangedFileList(args.changedFiles).join('\n') : '(no changed files)';
+    const commitsText = args.commits.length > 0 ? boundCommitSubjectList(args.commits).join('\n') : '(no commits recorded)';
     const falsificationLines = getCodeReviewFalsificationLines({
         rangeLabel: 'commit range',
         gitInspectionExamples: `Use git commands against the repository, for example: git diff ${args.baseCommit}..${args.headCommit}, git show --stat ${args.headCommit}, and targeted path diffs or file reads for changed files.`,
@@ -181,7 +198,7 @@ export function buildReviewerPrompt(args) {
         commitsText,
         '',
         'Diff stat:',
-        args.diffStat || '(no diff stat)',
+        args.diffStat ? truncateInlineSectionBody(args.diffStat, GIT_SUMMARY_SECTION_MAX_CHARS) : '(no diff stat)',
         '',
         'Changed files:',
         changedFilesText,
@@ -200,10 +217,10 @@ export function buildReviewerPrompt(args) {
         'Use `meaningfulProgressRationale` to explain the convergence judgment against the parent objective and recent accepted-scope history. Do not use it to restate correctness findings.',
         '',
         'Coder progress justification for this scope:',
-        JSON.stringify(args.progressJustification, null, 2),
+        JSON.stringify(boundProgressJustificationForPrompt(args.progressJustification), null, 2),
         '',
         'Recent accepted scope history for this parent objective:',
-        args.recentHistorySummary,
+        truncateInlineSectionBody(args.recentHistorySummary, AGENT_FREE_TEXT_SECTION_MAX_CHARS),
         '',
         reviewHistoryLine,
         'If prior review history or continuity context describes a finding as fixed, rejected, or deferred, do not reopen the same claim from that history alone.',
@@ -302,7 +319,7 @@ export function buildCoderResponsePrompt(args) {
         ...getUserGuidanceLines('coder'),
         '',
         'Open findings:',
-        JSON.stringify(args.openFindings, null, 2),
+        JSON.stringify(boundOpenFindingsForPrompt(args.openFindings), null, 2),
         '',
         'Current progress state:',
         buildProgressSection(args.progressText),

package/dist/neal/prompts/guidance.js

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { truncateInlineSectionBody } from '../context/inline-review-context.js';
+// Per-role character cap for operator guidance inlined into prompts. Guidance
+// beyond the cap is truncated at render time with an explicit marker; the
+// guidance file itself is never modified. `neal check` warns when a guidance
+// file exceeds this cap.
+export const USER_GUIDANCE_MAX_CHARS = 20_000;
 export const GUIDANCE_ROLES = ['coder', 'reviewer', 'planner'];
 export const GUIDANCE_SECTION_HEADER = '## User Guidance';
 const cache = new Map();
@@ -38,7 +44,7 @@ export function getUserGuidanceLines(role) {
     if (!content) {
         return [];
     }
-    return ['', GUIDANCE_SECTION_HEADER, '', content];
+    return ['', GUIDANCE_SECTION_HEADER, '', truncateInlineSectionBody(content, USER_GUIDANCE_MAX_CHARS)];
 }
 export function clearUserGuidanceCache() {
     cache.clear();
@@ -52,6 +58,7 @@ export function collectGuidanceDiagnostics() {
         entries.push({
             role,
             bytes: Buffer.byteLength(entry.content, 'utf8'),
+            chars: entry.content.length,
             path: entry.path,
         });
     }

package/dist/neal/prompts/planning.js

@@ -1,6 +1,7 @@
+import { boundOpenFindingsForPrompt, truncateInlineSectionBody } from '../context/inline-review-context.js';
 import { AUTONOMY_BLOCKED, AUTONOMY_DONE, getCanonicalPlanContractLines, getDerivedPlanSectionContractLines, getProtocolMarkerArtifactProhibitionLines, getTerminalMarkerArtifactBoundaryLines, } from './shared.js';
 import { assertPromptBuilder } from './assert-builder.js';
-import { getUserGuidanceLines } from './guidance.js';
+import { getUserGuidanceLines, USER_GUIDANCE_MAX_CHARS } from './guidance.js';
 const PROMPT_MODULE_PATH = 'src/neal/prompts/planning.ts';
 const PLAN_VERIFICATION_NECESSITY_RULE = 'A repository-wide invariant or global regression guarantee belongs in the plan only when it is necessary for the requested change to be correct.';
 function getPlanVerificationScopeLines(role) {
@@ -278,6 +279,9 @@ export function buildCoderPlanResponsePrompt(args) {
         mode === 'blocking'
             ? 'Address the currently open review findings provided below.'
             : 'The currently open review findings below are non-blocking. Decide whether to address each one now or explicitly reject/defer it with rationale.',
+        ...(mode === 'optional'
+            ? ['Return exactly one disposition for every finding listed below; a partial response is rejected.']
+            : []),
         reviewMode === 'derived-plan'
             ? 'Edit only the derived plan artifact and directly related planning notes for that derived plan.'
             : 'Edit only the plan document and directly related planning artifacts.',
@@ -308,13 +312,15 @@ export function buildCoderPlanResponsePrompt(args) {
         ...(args.planReviewGuidance
             ? [
                 'Operator guidance for this blocked plan-review recovery:',
-                args.planReviewGuidance.message,
+                // Same render-time cap as the operator guidance files; the persisted
+                // guidance record keeps its full message.
+                truncateInlineSectionBody(args.planReviewGuidance.message, USER_GUIDANCE_MAX_CHARS),
                 '',
                 'This guidance supplements the open reviewer findings. It does not waive plan-contract requirements, verification requirements, or the need to address blocking findings.',
                 '',
             ]
             : []),
         'Open findings:',
-        JSON.stringify(args.openFindings, null, 2),
+        JSON.stringify(boundOpenFindingsForPrompt(args.openFindings), null, 2),
     ].join('\n');
 }