@navels/neal 0.2.0 → 0.3.0

package/SECURITY.md

@@ -1,9 +1,8 @@
 # Security
 
 neal is a local planner/coder/reviewer loop that delegates work to
-provider-owned agent runtimes on your machine. This document describes neal's
-trust model so you can run it safely, and how to report a suspected
-vulnerability.
+provider-owned agent runtimes on your machine. Here's neal's trust model so you
+can run it safely, and how to report a suspected vulnerability.
 
 ## Trust Model
 
@@ -21,7 +20,7 @@ these providers:
 - The Claude coder runs with `permissionMode: bypassPermissions`.
 - The Codex coder runs with `approvalPolicy: never` and
   `sandboxMode: danger-full-access`.
-- The `generic-agentic` coder drives a neal-owned agentic loop whose `run` tool
+- The `openai-compatible` coder drives a neal-owned agentic loop whose `run` tool
   is unsandboxed shell.
 
 Treat any provider acting in the coder or planner role as capable of running
@@ -33,20 +32,18 @@ have added external sandboxing yourself.
 The reviewer role is **read-only**, enforced in two layers:
 
 - **Declared capability.** Every provider definition must declare its reviewer
-  (structured-advisor) capability with `write:false, shell:false`; the registry
+  (structured-advisor) capability with `write:false, shell:false`. The registry
   validates this at every provider resolution, so a writable reviewer
   definition cannot be handed out.
 - **Adapter wiring.** Each adapter enforces the declaration mechanically:
   - The Codex reviewer runs under `sandboxMode: read-only`, which Codex
-    enforces with an OS-level sandbox (Seatbelt on macOS, Landlock on Linux) —
-    the strongest guarantee of the four.
+    enforces with an OS-level sandbox (Seatbelt on macOS, Landlock on Linux),
+    the strongest guarantee of the three.
   - The Claude reviewer is limited to the `Read`, `Grep`, and `Glob` tools at
-    the SDK level; no write or shell tool exists in the reviewer session.
-  - The `generic-agentic` reviewer is bound to a neal-owned read-only toolset
+    the SDK level. No write or shell tool exists in the reviewer session.
+  - The `openai-compatible` reviewer is bound to a neal-owned read-only toolset
     (`read_file`, `list_dir`, `grep`, and a read-only `git_diff` over a commit
-    range); write and shell tools are absent from that toolset by construction.
-  - The `openai-compatible` reviewer has no tools at all; it judges
-    neal-inlined context.
+    range). Write and shell tools are absent from that toolset by construction.
 
 Both layers are pinned by tests, including a registry-driven conformance test
 (`test/reviewer-readonly-conformance.test.ts`) that fails if a provider is
@@ -55,10 +52,10 @@ Codex reviewer, enforcement is process-level (SDK and tool wiring), not an
 external sandbox, so it is only as strong as the adapter and the runtime under
 it.
 
-**Read-only is not read-jailed.** Only the `generic-agentic` reviewer restricts
+**Read-only is not read-jailed.** Only the `openai-compatible` reviewer restricts
 *reads* to the repository (path-jailed, with symlink resolution). The Claude
-and Codex reviewers can read anything the invoking user can read — including
-files outside the repository such as `~/.ssh` or cloud credentials — and file
+and Codex reviewers can read anything the invoking user can read (including
+files outside the repository such as `~/.ssh` or cloud credentials), and file
 contents they read are sent to the provider's API. On sensitive machines,
 follow the conservative guidance in the README
 [Safety Notes](README.md#safety-notes): run neal in a disposable checkout,
@@ -68,17 +65,17 @@ branch, worktree, container, or VM.
 judges findings with the read-only reviewer adapter, but the agent that
 *drafts* candidate findings runs on the coder provider with coder privileges.
 neal verifies after every drafting call that the worktree and neal's own run
-state are byte-unchanged and fails the review otherwise — detection, not
+state are byte-unchanged and fails the review otherwise: detection, not
 prevention. See [docs/providers.md](docs/providers.md) for the exact guarantee
 split.
 
 ### Untrusted or unknown models
 
-Running an unknown or untrusted model in the coder role — for example via
+Running an unknown or untrusted model in the coder role (for example via
 `neal compat` against an arbitrary OpenAI-compatible / OpenRouter slug on the
-`generic-agentic` provider — grants that model **coder-level unsandboxed shell
+`openai-compatible` provider) grants that model **coder-level unsandboxed shell
 access** in the working directory. Run untrusted models inside a container or
-disposable sandbox; do not point a coder-role untrusted model at a repository or
+disposable sandbox. Do not point a coder-role untrusted model at a repository or
 machine you care about.
 
 See [docs/providers.md](docs/providers.md) for the per-provider permission

package/dist/neal/adjudicator/{blocked-adjudicator.js → consultant.js}

@@ -1,30 +1,30 @@
 import { resolve } from 'node:path';
-import { runBlockedAdjudicatorRound } from '../agents/rounds.js';
+import { runConsultantRound } from '../agents/rounds.js';
 import { createInlineSection, readTextForInlineSection, } from '../context/inline-review-context.js';
 import { getChangedFilesForRange, getHeadCommit } from '../git.js';
 import { getExecutionPlanPath } from '../scopes.js';
 // Maximum number of most-recent reviewer rounds inlined as snapshots for the
-// adjudicator. The deadlock signal is dominated by the latest rounds, so a small
+// consultant. The deadlock signal is dominated by the latest rounds, so a small
 // window keeps the prompt bounded while still showing how the disagreement
 // evolved.
 const RECENT_ROUND_SNAPSHOT_LIMIT = 5;
-// The source phases the generalized adjudicator triages: a reviewer `review_stuck`
+// The source phases the generalized consultant triages: a reviewer `review_stuck`
 // deadlock (`reviewer_scope`/`reviewer_plan`) and a coder-blocked signal
 // (`coder_scope`/`coder_response`/`coder_optional_response`, which after the
 // split-plan reroute also carries the invalid-payload block). Every other accepted
 // recovery source phase is ineligible and keeps today's generic recovery behavior;
 // the recovery chokepoint enforces this gate.
-export const ADJUDICATOR_ELIGIBLE_SOURCE_PHASES = new Set([
+export const CONSULTANT_ELIGIBLE_SOURCE_PHASES = new Set([
     'reviewer_scope',
     'reviewer_plan',
     'coder_scope',
     'coder_response',
     'coder_optional_response',
 ]);
-export function isReviewerAdjudicatorPhase(sourcePhase) {
+export function isReviewerConsultantPhase(sourcePhase) {
     return sourcePhase === 'reviewer_scope' || sourcePhase === 'reviewer_plan';
 }
-function isCoderAdjudicatorPhase(sourcePhase) {
+function isCoderConsultantPhase(sourcePhase) {
     return (sourcePhase === 'coder_scope' ||
         sourcePhase === 'coder_response' ||
         sourcePhase === 'coder_optional_response');
@@ -54,7 +54,7 @@ function normalizeBlockerKey(input, cwd) {
 // blocked round's commits BEFORE the recovery chokepoint runs, so the tail hash
 // alone captures "the coder committed new work since the recorded block".
 // Deliberately NOT evidence: recovery turns/history (they accrue mechanically on
-// every adjudicated block, so every repeat would escape and the guard would never
+// every triaged block, so every repeat would escape and the guard would never
 // fire) and LLM free-text summaries/rationales (never byte-stable across rounds,
 // which would defeat the guard the same way).
 function commitTrailEvidenceFingerprint(state) {
@@ -65,7 +65,7 @@ function commitTrailEvidenceFingerprint(state) {
 // different underlying causes, so the candidate also carries the commit-trail
 // evidence fingerprint: when the coder has committed new work since a prior
 // identical block, `findRepeatedRecentBlock` treats the block as carrying new
-// evidence and the adjudicator runs instead of short-circuiting.
+// evidence and the consultant runs instead of short-circuiting.
 export function buildRecentBlockCandidate(state, reason, sourcePhase) {
     const blocker = reason.trim();
     return {
@@ -83,7 +83,7 @@ export function buildRecentBlockCandidate(state, reason, sourcePhase) {
 // (a non-empty `evidenceFingerprint` that differs from the prior one — i.e. the
 // coder has committed new work since the recorded block), it is NOT a repeat —
 // the underlying situation has changed even though the blocker text has not — so
-// `null` is returned and the adjudicator gets to look again.
+// `null` is returned and the consultant gets to look again.
 export function findRepeatedRecentBlock(recentBlocks, candidate) {
     for (const prior of [...recentBlocks].reverse()) {
         if (prior.scopeNumber !== candidate.scopeNumber) {
@@ -180,39 +180,39 @@ async function buildCoderInlineContext(state, reason) {
     };
 }
 // Always supplies a non-null InlineReviewerContext built entirely from in-memory
-// OrchestrationState artifacts, so the adjudicator works for every reviewer
+// OrchestrationState artifacts, so the consultant works for every reviewer
 // provider including no-read providers. Throws for any source phase outside
-// `ADJUDICATOR_ELIGIBLE_SOURCE_PHASES`, so an ineligible phase can never silently
+// `CONSULTANT_ELIGIBLE_SOURCE_PHASES`, so an ineligible phase can never silently
 // reach an LLM round.
-async function buildAdjudicatorInlineContext(state, reason, sourcePhase) {
-    if (isReviewerAdjudicatorPhase(sourcePhase)) {
+async function buildConsultantInlineContext(state, reason, sourcePhase) {
+    if (isReviewerConsultantPhase(sourcePhase)) {
         return buildReviewerInlineContext(state);
     }
-    if (isCoderAdjudicatorPhase(sourcePhase)) {
+    if (isCoderConsultantPhase(sourcePhase)) {
         return buildCoderInlineContext(state, reason);
     }
-    throw new Error(`Blocked adjudicator cannot build context for ineligible source phase: ${String(sourcePhase)}`);
+    throw new Error(`Consultant cannot build context for ineligible source phase: ${String(sourcePhase)}`);
 }
-// Thin, read-only adjudicator for every triaged block class. It first applies the
+// Thin, read-only consultant for every triaged block class. It first applies the
 // pure anti-thrash guard against `state.recentBlocks`: if this block repeats a
 // recent block for the same scope identity + sourcePhase + normalized key with no
 // new evidence, it returns a non-recoverable verdict WITHOUT running an LLM round.
 // Otherwise it assembles the InlineReviewerContext for the source phase and runs
 // the reviewer round. The module performs NO writes and NO commits — it only
-// returns a `BlockedAdjudicatorVerdict`; `state.recentBlocks` is written elsewhere
+// returns a `ConsultantVerdict`; `state.recentBlocks` is written elsewhere
 // (the recovery chokepoint), never here.
-export async function runBlockedAdjudicator(state, reason, sourcePhase, logger) {
+export async function runConsultant(state, reason, sourcePhase, logger) {
     const candidate = buildRecentBlockCandidate(state, reason, sourcePhase);
     if (findRepeatedRecentBlock(state.recentBlocks, candidate)) {
         return {
             recoverable: false,
             triageCategory: 'impossible_task',
             resolutionDirective: '',
-            rationale: 'This blocker repeats a recent block for the same scope with no new evidence; the adjudicator short-circuited to avoid thrashing without re-running a reviewer round.',
+            rationale: 'This blocker repeats a recent block for the same scope with no new evidence; the consultant short-circuited to avoid thrashing without re-running a reviewer round.',
         };
     }
-    const inlineContext = await buildAdjudicatorInlineContext(state, reason, sourcePhase);
-    const { verdict } = await runBlockedAdjudicatorRound({
+    const inlineContext = await buildConsultantInlineContext(state, reason, sourcePhase);
+    const { verdict } = await runConsultantRound({
         reviewer: state.agentConfig.reviewer,
         cwd: state.cwd,
         blockedReason: reason,

package/dist/neal/adjudicator/execute.js

@@ -1,7 +1,6 @@
 import { mkdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import { runCoderResponseRound, runReviewerRound } from '../agents.js';
-import { createInlineSection, readOnlyReviewerNeedsInlinedDiff, readTextForInlineSection, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { readOnlyReviewerNeedsInlinedDiff } from '../context/inline-review-context.js';
 import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
 import { getReviewStuckWindow } from '../config.js';
 import { EXECUTE_FINALIZATION_PHASE } from '../execute-finalization.js';
@@ -132,11 +131,16 @@ function canonicalSetsEqual(left, right) {
     }
     return true;
 }
-export function hasRepeatedUnresolvedBlockingCanonicals(args) {
+// Pure convergence helper: it takes the already-resolved review-stuck window so
+// a side-effect-free caller (the plan-review round core) can resolve config once
+// outside and pass the value in. The cwd-taking wrapper below preserves the
+// existing public behavior — execute-review keeps calling it — and now resolves
+// the window a single time before delegating, so no path reads config twice.
+export function hasRepeatedUnresolvedBlockingCanonicalsForWindow(args) {
     if (args.currentOpenBlockingCanonicals.size === 0) {
         return false;
     }
-    const reviewStuckWindow = getReviewStuckWindow(args.cwd);
+    const { reviewStuckWindow } = args;
     const snapshots = [
         ...args.rounds.map((round) => round.openBlockingCanonicalIds ? new Set(round.openBlockingCanonicalIds) : null),
         args.currentOpenBlockingCanonicals,
@@ -147,7 +151,7 @@ export function hasRepeatedUnresolvedBlockingCanonicals(args) {
     const recentSnapshots = snapshots.slice(-reviewStuckWindow);
     if (recentSnapshots.some((snapshot) => snapshot === null)) {
         // Older round records predate canonical-set snapshots; fall back to count-based stuckness.
-        return hasRepeatedNonReduction(args.rounds, args.currentOpenBlockingCanonicals.size, args.cwd);
+        return hasRepeatedNonReductionForWindow(args.rounds, args.currentOpenBlockingCanonicals.size, reviewStuckWindow);
     }
     for (let index = 1; index < recentSnapshots.length; index += 1) {
         if (!canonicalSetsEqual(recentSnapshots[index], recentSnapshots[index - 1])) {
@@ -156,9 +160,15 @@ export function hasRepeatedUnresolvedBlockingCanonicals(args) {
     }
     return true;
 }
-export function hasRepeatedNonReduction(rounds, currentCount, cwd) {
+export function hasRepeatedUnresolvedBlockingCanonicals(args) {
+    return hasRepeatedUnresolvedBlockingCanonicalsForWindow({
+        rounds: args.rounds,
+        currentOpenBlockingCanonicals: args.currentOpenBlockingCanonicals,
+        reviewStuckWindow: getReviewStuckWindow(args.cwd),
+    });
+}
+export function hasRepeatedNonReductionForWindow(rounds, currentCount, reviewStuckWindow) {
     const counts = [...rounds.map((round) => round.openBlockingCanonicalCount), currentCount];
-    const reviewStuckWindow = getReviewStuckWindow(cwd);
     if (counts.length < reviewStuckWindow || currentCount <= 0) {
         return false;
     }
@@ -170,6 +180,9 @@ export function hasRepeatedNonReduction(rounds, currentCount, cwd) {
     }
     return true;
 }
+export function hasRepeatedNonReduction(rounds, currentCount, cwd) {
+    return hasRepeatedNonReductionForWindow(rounds, currentCount, getReviewStuckWindow(cwd));
+}
 export function getReopenedCanonical(findings) {
     const roundsByCanonical = new Map();
     for (const finding of findings) {
@@ -261,18 +274,6 @@ function validateExecuteResponseCoverage(args) {
         throw new Error(`Coder ${args.mode} response did not disposition every open finding: ${[...missingIds].join(', ')}`);
     }
 }
-async function buildExecuteReviewerInlineContext(args) {
-    const diff = await args.getDiffForRange(args.state.cwd, args.baseCommit, args.headCommit);
-    const planContent = await readTextForInlineSection(resolve(args.state.cwd, args.planDoc));
-    const reviewHistory = await readTextForInlineSection(args.state.reviewMarkdownPath);
-    return {
-        sections: [
-            createInlineSection(`Full diff for commit range ${args.baseCommit}..${args.headCommit}`, diff || '(empty diff)'),
-            createInlineSection(`Plan document content (${args.planDoc})`, planContent || '(plan document content unavailable)'),
-            createInlineSection('Prior review history (REVIEW.md content)', reviewHistory || '(no prior review history)'),
-        ],
-    };
-}
 export async function runExecuteReviewerAdjudication(args) {
     if (!args.state.baseCommit) {
         throw new Error('Cannot run execute reviewer adjudication without baseCommit.');
@@ -288,27 +289,20 @@ export async function runExecuteReviewerAdjudication(args) {
     const changedFiles = await args.getChangedFilesForRange(args.state.cwd, args.state.baseCommit, headCommit);
     const scratchDir = getScopeReviewerScratchDir(args.state.runDir, context.parentScopeLabel, context.round);
     await mkdir(scratchDir, { recursive: true });
-    // Full diffs are collected only for reviewers without repository read
-    // access; read-capable reviewers inspect the range with their own tools.
-    const inlineContext = reviewerNeedsInlineContext(args.state.agentConfig.reviewer)
-        ? await buildExecuteReviewerInlineContext({
-            state: args.state,
-            planDoc: context.planDoc,
-            baseCommit: args.state.baseCommit,
-            headCommit,
-            getDiffForRange: args.getDiffForRange,
-        })
-        : null;
     // Read-only reviewers with read tools but no commit-range diff tool (native
     // Claude/Codex) get the commit-range diff inlined directly so they can see
     // exactly what changed without shell access; read-only reviewers that expose
-    // their own commit-range diff tool (generic-agentic) inspect the range with
+    // their own commit-range diff tool (openai-compatible) inspect the range with
     // that tool instead.
     const inlinedRangeDiff = readOnlyReviewerNeedsInlinedDiff(args.state.agentConfig.reviewer)
         ? await args.getDiffForRange(args.state.cwd, args.state.baseCommit, headCommit)
         : null;
     const reviewerResult = await (args.runReviewerRound ?? runReviewerRound)({
         reviewer: args.state.agentConfig.reviewer,
+        // Resume the reviewer's own session from the previous round of this
+        // scope's review engagement (null on round 1: scope-boundary resets clear
+        // it). Sessionless providers are filtered at the round layer.
+        resumeHandle: args.state.reviewerSessionHandle,
         cwd: args.state.cwd,
         planDoc: context.planDoc,
         baseCommit: args.state.baseCommit,
@@ -324,7 +318,6 @@ export async function runExecuteReviewerAdjudication(args) {
         recentHistorySummary: context.recentHistorySummary,
         scratchDir,
         reviewerContext: await buildAndPersistReviewerContextPacket({ state: args.state }),
-        inlineContext,
         inlinedRangeDiff,
         unattended: args.state.unattended,
         logger: args.logger,
@@ -498,11 +491,18 @@ export function synthesizeExecuteReviewerState(args) {
     const openBlockingCanonicalSet = getOpenBlockingCanonicalSet(mergedFindings);
     const openBlockingCanonicalIds = [...openBlockingCanonicalSet].sort();
     const openBlockingCanonicalCount = openBlockingCanonicalSet.size;
+    // Two stall shapes route to the consultant: the identical canonical set
+    // persisting across the window (a hard deadlock on the same findings), and
+    // the open-blocking COUNT failing to decrease across the window while the
+    // canonicals rotate — the one-novel-finding-per-round trickle, where each
+    // round retires a canonical and mints a new one so the set-based detector
+    // never fires (observed live: 6 flat rounds of 1 novel finding each, 11
+    // rounds total on one scope, zero re-opens).
     const stalledBlockingCount = hasRepeatedUnresolvedBlockingCanonicals({
         rounds: args.state.rounds,
         currentOpenBlockingCanonicals: openBlockingCanonicalSet,
         cwd: args.state.cwd,
-    });
+    }) || hasRepeatedNonReduction(args.state.rounds, openBlockingCanonicalCount, args.state.cwd);
     const reopenedCanonical = getReopenedCanonical(mergedFindings);
     const shouldBlockForConvergence = Boolean(reopenedCanonical || stalledBlockingCount);
     const disposition = resolveExecuteReviewDisposition({

package/dist/neal/adjudicator/final-completion.js

@@ -1,7 +1,6 @@
 import { mkdir } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import { runCoderFinalCompletionSummaryRound, runReviewerFinalCompletionRound, } from '../agents.js';
-import { createInlineSection, readOnlyReviewerNeedsInlinedDiff, readTextForInlineSection, reviewerNeedsInlineContext, } from '../context/inline-review-context.js';
+import { readOnlyReviewerNeedsInlinedDiff } from '../context/inline-review-context.js';
 import { buildAndPersistReviewerContextPacket } from '../context/reviewer-context.js';
 import { getDiffForRange } from '../git.js';
 import { getFinalCompletionView } from '../state-views.js';
@@ -35,23 +34,6 @@ export async function runFinalCompletionSummaryAdjudication(args) {
         summary,
     };
 }
-async function buildFinalCompletionReviewerInlineContext(args) {
-    const aggregate = args.packet.aggregateReviewContext;
-    const sections = [];
-    if (aggregate.unavailableReason !== null || !aggregate.baseCommit || !aggregate.headCommit) {
-        // Inline the evidence-gap statement instead of a diff so the no-read
-        // reviewer treats the missing aggregate range as a completion-review
-        // evidence gap rather than proof of correctness.
-        sections.push(createInlineSection('Aggregate review evidence gap', `The aggregate diff for this completion review is unavailable: ${aggregate.unavailableReason ?? 'no aggregate commit range was resolved'}. Treat this as a completion-review evidence gap rather than proof that the aggregate implementation is correct.`));
-    }
-    else {
-        const diff = await args.getDiffForRange(args.state.cwd, aggregate.baseCommit, aggregate.headCommit);
-        sections.push(createInlineSection(`Full aggregate diff for range ${aggregate.range ?? `${aggregate.baseCommit}..${aggregate.headCommit}`}`, diff || '(empty diff)'));
-    }
-    const planContent = await readTextForInlineSection(resolve(args.state.cwd, args.state.planDoc));
-    sections.push(createInlineSection(`Plan document content (${args.state.planDoc})`, planContent || '(plan document content unavailable)'));
-    return { sections };
-}
 export async function runFinalCompletionReviewerAdjudication(args) {
     const finalCompletion = getFinalCompletionView(args.state);
     if (!finalCompletion?.summary) {
@@ -63,20 +45,10 @@ export async function runFinalCompletionReviewerAdjudication(args) {
     });
     const scratchDir = getFinalCompletionReviewerScratchDir(args.state.runDir);
     await mkdir(scratchDir, { recursive: true });
-    // The aggregate diff is collected only for reviewers without repository read
-    // access; read-capable reviewers inspect the aggregate range with their own
-    // tools.
-    const inlineContext = reviewerNeedsInlineContext(args.state.agentConfig.reviewer)
-        ? await buildFinalCompletionReviewerInlineContext({
-            state: args.state,
-            packet: context.packet,
-            getDiffForRange: args.getDiffForRange ?? getDiffForRange,
-        })
-        : null;
     // Read-only reviewers with read tools but no commit-range diff tool (native
     // Claude/Codex) get the aggregate commit-range diff inlined directly when the
     // aggregate range is available; read-only reviewers that expose their own
-    // commit-range diff tool (generic-agentic) inspect the range with that tool.
+    // commit-range diff tool (openai-compatible) inspect the range with that tool.
     const aggregate = context.packet.aggregateReviewContext;
     const inlinedRangeDiff = readOnlyReviewerNeedsInlinedDiff(args.state.agentConfig.reviewer) &&
         aggregate.unavailableReason === null &&
@@ -92,7 +64,6 @@ export async function runFinalCompletionReviewerAdjudication(args) {
         summary: finalCompletion.summary,
         scratchDir,
         reviewerContext: await buildAndPersistReviewerContextPacket({ state: args.state }),
-        inlineContext,
         inlinedRangeDiff,
         unattended: args.state.unattended,
         logger: args.logger,