@navels/neal 0.1.0

package/config.yml

@@ -0,0 +1,104 @@
+# neal runtime configuration template.
+# This file is intentionally fully commented out:
+# - uncomment any setting you want to override for this repository; repo config
+#   takes precedence over ~/.neal/config.yml
+# - put machine-local overrides such as `neal.notify_bin` or role-specific model
+#   choices in ~/.neal/config.yml
+# - run `neal setup` for first-time writer-run provider configuration
+
+# neal:
+#   # Milliseconds between wrapper heartbeat messages on stderr.
+#   # Set to 0 to disable heartbeats entirely.
+#   phase_heartbeat_ms: 60000
+#
+#   # Maximum reviewer rounds before neal blocks on non-converging review.
+#   max_review_rounds: 20
+#
+#   # Consecutive rounds with no reduction in open blocking findings before
+#   # neal treats review as stuck and blocks early.
+#   review_stuck_window: 5
+#
+#   # Milliseconds of inactivity before a coder or reviewer turn times out.
+#   inactivity_timeout_ms: 600000
+#
+#   # Maximum retry attempts for transient API/internal provider failures.
+#   api_retry_limit: 10
+#
+#   # Milliseconds an agent turn may stay silent after starting, with no
+#   # observable progress (no tool use, commands, file changes, or assistant
+#   # text), before neal aborts and retries the turn; once any progress is
+#   # observed, inactivity_timeout_ms governs instead.
+#   agent_turn_startup_timeout_ms: 300000
+#
+#   # Maximum number of times neal retries an agent turn that was aborted for
+#   # startup silence before failing the turn.
+#   agent_turn_retry_limit: 1
+#
+#   # Maximum operator guidance turns allowed during interactive blocked recovery
+#   # before neal requires a terminal disposition.
+#   interactive_blocked_recovery_max_turns: 3
+#
+#   # Maximum number of times final completion review may send execution back
+#   # for more work before neal stops reopening the plan.
+#   final_completion_continue_execution_max: 2
+#
+#   # Optional local notification command. Leave commented to keep
+#   # notifications disabled.
+#   # notify_bin: /absolute/path/to/notify
+#
+# agent:
+#   # Fresh writer-run commands require explicit coder and reviewer providers.
+#   # These commented examples are templates only; run `neal setup` to write
+#   # active provider defaults to ~/.neal/config.yml, or uncomment and edit the
+#   # role settings here for repository-level defaults.
+#   coder:
+#     # Provider for new plan/execute/run workflows.
+#     provider: openai-codex
+#
+#     # Or run the coder against any OpenAI-compatible tool-calling endpoint
+#     # via the providers.openai_compatible block (see docs/providers.md):
+#     # provider: generic-agentic
+#
+#     # Optional default model override for the coder role.
+#     # Leave null to let the provider choose its default model.
+#     model: null
+#
+#     # Optional reasoning-effort override for the coder role.
+#     # Leave null or omit to use the provider default.
+#     # Supported values per provider:
+#     #   openai-codex:     minimal, low, medium, high, xhigh
+#     #   anthropic-claude: low, medium, high, xhigh, max
+#     # An effort value not supported by the configured provider is rejected
+#     # before a run starts.
+#     effort: null
+#
+#   reviewer:
+#     # Provider for the reviewer role.
+#     provider: anthropic-claude
+#
+#     # Optional default model override for the reviewer role.
+#     # Leave null to let the provider choose its default model.
+#     model: null
+#
+#     # Optional reasoning-effort override for the reviewer role.
+#     # Leave null or omit to use the provider default.
+#     # Supported values per provider:
+#     #   openai-codex:     minimal, low, medium, high, xhigh
+#     #   anthropic-claude: low, medium, high, xhigh, max
+#     effort: null
+#
+#   # The planner inherits the coder provider/model/effort unless configured
+#   # explicitly. Uncomment to override the planner independently.
+#   # planner:
+#   #   provider: openai-codex
+#   #   model: null
+#   #   effort: null
+#
+#   # Run headlessly when no operator is available to answer an operator block
+#   # (CI, cron, or a benchmark harness). When true, the execute-mode
+#   # interactive-recovery loop auto-resumes with conservative guidance for a
+#   # bounded number of turns and then fails cleanly, while the final-completion
+#   # and top-level plan-review gates fail cleanly and terminally instead of
+#   # waiting. Verification, authorization, and squash/grading are unchanged.
+#   # The `--unattended` CLI flag overrides this key. Defaults to false.
+#   unattended: false

package/dist/neal/activity-footer.js

@@ -0,0 +1,177 @@
+const DEFAULT_REFRESH_INTERVAL_MS = 1_000;
+const DEFAULT_MIN_REDRAW_INTERVAL_MS = 100;
+const DEFAULT_MIN_COLUMNS = 60;
+function formatElapsed(elapsedMs) {
+    const totalSeconds = Math.max(0, Math.round(elapsedMs / 1_000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`;
+}
+function truncateForColumns(text, columns) {
+    if (columns <= 0 || text.length <= columns) {
+        return text;
+    }
+    if (columns <= 3) {
+        return text.slice(0, columns);
+    }
+    return `${text.slice(0, columns - 3)}...`;
+}
+export function renderActivityFooterLine(state) {
+    const subject = state.subject ? ` ${state.subject}` : '';
+    const now = state.now ?? Date.now();
+    return [
+        `[neal] ${state.mode}${subject}`,
+        `activity: ${state.activity}`,
+        `elapsed: ${formatElapsed(now - state.startedAt)}`,
+        `status: ${state.status}`,
+    ].join(' | ');
+}
+export class ActivityFooter {
+    stream;
+    now;
+    refreshIntervalMs;
+    minRedrawIntervalMs;
+    minColumns;
+    refreshTimer = null;
+    redrawTimer = null;
+    resizeListener = null;
+    currentLine = '';
+    footerVisible = false;
+    lastRedrawAt = 0;
+    state = null;
+    disposed = false;
+    constructor(options = {}) {
+        this.stream = options.stream ?? process.stderr;
+        this.now = options.now ?? (() => Date.now());
+        this.refreshIntervalMs = options.refreshIntervalMs ?? DEFAULT_REFRESH_INTERVAL_MS;
+        this.minRedrawIntervalMs = options.minRedrawIntervalMs ?? DEFAULT_MIN_REDRAW_INTERVAL_MS;
+        this.minColumns = options.minColumns ?? DEFAULT_MIN_COLUMNS;
+        if (this.isEnabled() && this.stream === process.stderr) {
+            this.resizeListener = () => {
+                this.handleResize();
+            };
+            process.on('SIGWINCH', this.resizeListener);
+        }
+    }
+    isEnabled() {
+        return this.stream.isTTY === true;
+    }
+    setState(state) {
+        if (this.disposed) {
+            return;
+        }
+        this.state = state;
+        this.currentLine = renderActivityFooterLine({
+            ...state,
+            now: this.now(),
+        });
+        this.ensureRefreshTimer();
+        this.renderFooter(true);
+    }
+    write(message) {
+        if (!this.isEnabled() || this.disposed) {
+            this.stream.write(message);
+            return;
+        }
+        this.clearFooter();
+        this.stream.write(message);
+        if (message.endsWith('\n') || message.endsWith('\r\n')) {
+            this.renderFooter(true);
+        }
+    }
+    replaceView(message) {
+        if (!this.isEnabled() || this.disposed) {
+            this.stream.write(message);
+            return;
+        }
+        this.clearFooter();
+        this.stream.write('\x1b[H\x1b[2J');
+        if (message !== '') {
+            this.stream.write(message);
+        }
+        this.renderFooter(true);
+    }
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        if (this.refreshTimer) {
+            clearInterval(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        if (this.redrawTimer) {
+            clearTimeout(this.redrawTimer);
+            this.redrawTimer = null;
+        }
+        if (this.resizeListener) {
+            process.off('SIGWINCH', this.resizeListener);
+            this.resizeListener = null;
+        }
+        this.clearFooter();
+    }
+    handleResize() {
+        if (this.disposed) {
+            return;
+        }
+        if (!this.canRender()) {
+            this.clearFooter();
+            return;
+        }
+        this.refresh(true);
+    }
+    refresh(force = false) {
+        if (!this.state || this.disposed) {
+            return;
+        }
+        this.currentLine = renderActivityFooterLine({
+            ...this.state,
+            now: this.now(),
+        });
+        this.renderFooter(force);
+    }
+    ensureRefreshTimer() {
+        if (this.refreshTimer || this.disposed || this.refreshIntervalMs <= 0 || !this.isEnabled()) {
+            return;
+        }
+        this.refreshTimer = setInterval(() => {
+            this.refresh();
+        }, this.refreshIntervalMs);
+        this.refreshTimer.unref?.();
+    }
+    canRender() {
+        return (this.isEnabled() &&
+            !this.disposed &&
+            this.currentLine !== '' &&
+            (this.stream.columns ?? 0) >= this.minColumns);
+    }
+    renderFooter(force = false) {
+        if (!this.canRender()) {
+            this.clearFooter();
+            return;
+        }
+        const elapsed = this.now() - this.lastRedrawAt;
+        if (!force && elapsed < this.minRedrawIntervalMs) {
+            if (!this.redrawTimer) {
+                this.redrawTimer = setTimeout(() => {
+                    this.redrawTimer = null;
+                    this.renderFooter(true);
+                }, this.minRedrawIntervalMs - elapsed);
+                this.redrawTimer.unref?.();
+            }
+            return;
+        }
+        this.lastRedrawAt = this.now();
+        const columns = this.stream.columns ?? this.currentLine.length;
+        const line = truncateForColumns(this.currentLine, Math.max(0, columns - 1));
+        this.stream.write(`\r\x1b[2K${line}`);
+        this.footerVisible = true;
+    }
+    clearFooter() {
+        if (!this.footerVisible || !this.isEnabled()) {
+            return;
+        }
+        this.stream.write('\r\x1b[2K');
+        this.footerVisible = false;
+    }
+}

package/dist/neal/activity-reporting.js

@@ -0,0 +1 @@
+export {};

package/dist/neal/adjudicator/artifacts.js

@@ -0,0 +1,58 @@
+import { isExecuteFinalizationPhase } from '../execute-finalization.js';
+import { renderAdjudicatedLoopContractLines } from './contracts.js';
+import { resolveExecuteAdjudicationContext } from './execute.js';
+import { resolvePlanningAdjudicationContext } from './planning.js';
+import { getAdjudicationSpec } from './specs.js';
+import { hasFinalCompletionReviewState } from '../state-views.js';
+function resolveArtifactPhase(state) {
+    if (hasFinalCompletionReviewState(state)) {
+        return 'final_completion_review';
+    }
+    if (state.phase === 'blocked' && state.blockedFromPhase) {
+        return state.blockedFromPhase;
+    }
+    return state.phase;
+}
+export function resolveArtifactAdjudicationContract(state) {
+    const sourcePhase = resolveArtifactPhase(state);
+    if (sourcePhase === 'coder_plan' ||
+        sourcePhase === 'reviewer_plan' ||
+        sourcePhase === 'coder_plan_response' ||
+        sourcePhase === 'coder_plan_optional_response') {
+        return {
+            spec: resolvePlanningAdjudicationContext(state).spec,
+            sourcePhase,
+        };
+    }
+    if (sourcePhase === 'coder_scope' ||
+        sourcePhase === 'reviewer_scope' ||
+        sourcePhase === 'coder_response' ||
+        sourcePhase === 'coder_optional_response' ||
+        isExecuteFinalizationPhase(sourcePhase)) {
+        return {
+            spec: resolveExecuteAdjudicationContext(state).spec,
+            sourcePhase,
+        };
+    }
+    if (sourcePhase === 'final_completion_review') {
+        return {
+            spec: getAdjudicationSpec('final_completion_review'),
+            sourcePhase,
+        };
+    }
+    return null;
+}
+export function renderAdjudicationContractLines(state) {
+    const contract = resolveArtifactAdjudicationContract(state);
+    if (!contract) {
+        return [];
+    }
+    return [
+        '## Adjudication Contract',
+        `- Adjudication spec id: ${contract.spec.id}`,
+        `- Adjudication family: ${contract.spec.family}`,
+        ...renderAdjudicatedLoopContractLines(contract.spec.loopContract),
+        `- Allowed transition outcomes: ${contract.spec.transitionSignals.join(', ')}`,
+        '- Contract role: validated allowed outcomes for debugging; runtime routing remains explicit elsewhere.',
+    ];
+}

package/dist/neal/adjudicator/blocked-adjudicator.js

@@ -0,0 +1,223 @@
+import { resolve } from 'node:path';
+import { runBlockedAdjudicatorRound } 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
+// 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`
+// 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([
+    'reviewer_scope',
+    'reviewer_plan',
+    'coder_scope',
+    'coder_response',
+    'coder_optional_response',
+]);
+export function isReviewerAdjudicatorPhase(sourcePhase) {
+    return sourcePhase === 'reviewer_scope' || sourcePhase === 'reviewer_plan';
+}
+function isCoderAdjudicatorPhase(sourcePhase) {
+    return (sourcePhase === 'coder_scope' ||
+        sourcePhase === 'coder_response' ||
+        sourcePhase === 'coder_optional_response');
+}
+// --- Anti-thrash guard ------------------------------------------------------------
+// These helpers are PURE and read-only. They never write or persist state; the
+// recovery chokepoint is the sole writer of `state.recentBlocks`.
+function normalizeBlockerKey(input, cwd) {
+    const escapedCwd = cwd.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return input
+        .replace(new RegExp(escapedCwd, 'gi'), '')
+        .replace(/(?:[A-Za-z]:)?(?:\/[^/\s:]+){2,}\/((?:src|test|tests|benchmark|docs|tmp|packages|lib|app)\/[^\s:]+)/g, '$1')
+        .replace(/[^\S\r\n]+/g, ' ')
+        .replace(/[!?.,;:]{2,}/g, (match) => match[0] ?? '')
+        .replace(/[!?.,;:]+(?=\s|$)/g, '')
+        .trim()
+        .toLowerCase();
+}
+// The "new evidence" escape needs a signal that deterministically CHANGES when
+// the underlying situation changes, even when the blocker wording does not. The
+// blocker text itself cannot be that signal (subtracting the blocker from itself
+// is always empty), so the fingerprint is derived from the one persisted artifact
+// that moves exactly when the coder actually did new work: the scope's commit
+// trail. `state.createdCommits` is append-only for the lifetime of the anti-thrash
+// window (every transition that resets it also resets `recentBlocks`, and a scope
+// boundary changes the scope identity anyway), and the coder phases append the
+// 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
+// fire) and LLM free-text summaries/rationales (never byte-stable across rounds,
+// which would defeat the guard the same way).
+function commitTrailEvidenceFingerprint(state) {
+    return state.createdCommits.at(-1) ?? '';
+}
+// Build the anti-thrash candidate identity for a block from its `reason` + the
+// current scope identity. Identically worded blockers can hide genuinely
+// 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.
+export function buildRecentBlockCandidate(state, reason, sourcePhase) {
+    const blocker = reason.trim();
+    return {
+        scopeNumber: state.currentScopeNumber,
+        derivedScopeIndex: state.derivedScopeIndex,
+        sourcePhase,
+        normalizedKey: normalizeBlockerKey(blocker, state.cwd),
+        evidenceFingerprint: commitTrailEvidenceFingerprint(state),
+    };
+}
+// Return the most-recent window record that the candidate repeats, or `null` when
+// there is no repeat. A match requires the SAME scope identity (`scopeNumber` +
+// `derivedScopeIndex`), the same `sourcePhase`, and the same normalized blocker
+// key. When that record exists but the candidate carries materially new evidence
+// (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.
+export function findRepeatedRecentBlock(recentBlocks, candidate) {
+    for (const prior of [...recentBlocks].reverse()) {
+        if (prior.scopeNumber !== candidate.scopeNumber) {
+            continue;
+        }
+        if (prior.derivedScopeIndex !== candidate.derivedScopeIndex) {
+            continue;
+        }
+        if (prior.sourcePhase !== candidate.sourcePhase) {
+            continue;
+        }
+        if (prior.normalizedKey !== candidate.normalizedKey) {
+            continue;
+        }
+        if (candidate.evidenceFingerprint && candidate.evidenceFingerprint !== prior.evidenceFingerprint) {
+            return null;
+        }
+        return prior;
+    }
+    return null;
+}
+// Return a NEW window array that either appends the candidate as a fresh record
+// (`count:1`) or, on an exact match (per `findRepeatedRecentBlock`), increments the
+// matched record's `count` and refreshes its `recordedAt`. Pure: the input array
+// is never mutated.
+export function upsertRecentBlock(recentBlocks, candidate, now = new Date().toISOString()) {
+    const match = findRepeatedRecentBlock(recentBlocks, candidate);
+    if (match) {
+        return recentBlocks.map((record) => record === match ? { ...record, count: record.count + 1, recordedAt: now } : record);
+    }
+    return [...recentBlocks, { ...candidate, count: 1, recordedAt: now }];
+}
+// --- Inline context ---------------------------------------------------------------
+function renderOpenBlockingFindings(findings) {
+    if (findings.length === 0) {
+        return '(no open blocking findings recorded)';
+    }
+    return findings
+        .map((finding) => [
+        `- canonicalId: ${finding.canonicalId}`,
+        `  claim: ${finding.claim}`,
+        `  requiredAction: ${finding.requiredAction}`,
+        `  coderDisposition: ${finding.coderDisposition ?? '(none recorded)'}`,
+    ].join('\n'))
+        .join('\n');
+}
+function renderRecentRoundSnapshots(rounds) {
+    if (rounds.length === 0) {
+        return '(no reviewer rounds recorded)';
+    }
+    return rounds
+        .slice(-RECENT_ROUND_SNAPSHOT_LIMIT)
+        .map((round) => {
+        const openBlocking = round.openBlockingCanonicalIds ?? [];
+        const openBlockingText = openBlocking.length > 0 ? openBlocking.join(', ') : '(none)';
+        return `- round ${round.round}: openBlockingCanonicalIds: ${openBlockingText}`;
+    })
+        .join('\n');
+}
+async function buildReviewerInlineContext(state) {
+    const planContent = await readTextForInlineSection(resolve(state.cwd, getExecutionPlanPath(state)));
+    const openBlockingFindings = state.findings.filter((finding) => finding.severity === 'blocking' && finding.status === 'open');
+    return {
+        sections: [
+            createInlineSection('Execution plan content', planContent || '(plan document content unavailable)'),
+            createInlineSection('Open blocking findings', renderOpenBlockingFindings(openBlockingFindings)),
+            createInlineSection('Recent reviewer-round snapshots', renderRecentRoundSnapshots(state.rounds)),
+        ],
+    };
+}
+async function readChangedFilesBestEffort(state) {
+    const base = state.baseCommit;
+    if (!base) {
+        return '(no scope base commit recorded)';
+    }
+    try {
+        const head = await getHeadCommit(state.cwd);
+        const files = await getChangedFilesForRange(state.cwd, base, head);
+        return files.length > 0 ? files.map((file) => `- ${file}`).join('\n') : '(no changed files in the current scope)';
+    }
+    catch {
+        return '(changed-file context unavailable)';
+    }
+}
+async function buildCoderInlineContext(state, reason) {
+    const planContent = await readTextForInlineSection(resolve(state.cwd, getExecutionPlanPath(state)));
+    const changedFiles = await readChangedFilesBestEffort(state);
+    return {
+        sections: [
+            createInlineSection('Execution plan content', planContent || '(plan document content unavailable)'),
+            createInlineSection('Coder blocker summary', reason.trim() || '(no blocker summary provided)'),
+            createInlineSection('Changed files since scope base', changedFiles),
+        ],
+    };
+}
+// Always supplies a non-null InlineReviewerContext built entirely from in-memory
+// OrchestrationState artifacts, so the adjudicator 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
+// reach an LLM round.
+async function buildAdjudicatorInlineContext(state, reason, sourcePhase) {
+    if (isReviewerAdjudicatorPhase(sourcePhase)) {
+        return buildReviewerInlineContext(state);
+    }
+    if (isCoderAdjudicatorPhase(sourcePhase)) {
+        return buildCoderInlineContext(state, reason);
+    }
+    throw new Error(`Blocked adjudicator cannot build context for ineligible source phase: ${String(sourcePhase)}`);
+}
+// Thin, read-only adjudicator 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
+// (the recovery chokepoint), never here.
+export async function runBlockedAdjudicator(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.',
+        };
+    }
+    const inlineContext = await buildAdjudicatorInlineContext(state, reason, sourcePhase);
+    const { verdict } = await runBlockedAdjudicatorRound({
+        reviewer: state.agentConfig.reviewer,
+        cwd: state.cwd,
+        blockedReason: reason,
+        inlineContext,
+        logger,
+    });
+    return verdict;
+}