@navels/neal 0.1.0

package/dist/neal/storage-paths.js

@@ -0,0 +1,57 @@
+import { join } from 'node:path';
+export const NEAL_DIR_NAME = '.neal';
+export const RUNS_DIR_NAME = 'runs';
+export const QUEUES_DIR_NAME = 'queues';
+export const REVIEWS_DIR_NAME = 'reviews';
+export const CURRENT_RUN_POINTER_FILE = 'current.json';
+export const CURRENT_QUEUE_POINTER_FILE = 'current-queue.json';
+export const ACTIVE_RUN_LOCK_FILE = 'active-run.lock';
+export const RUN_STATE_FILE = 'RUN_STATE.json';
+export const QUEUE_STATE_FILE = 'QUEUE_STATE.json';
+export const QUEUE_LINK_FILE = 'QUEUE_LINK.json';
+export const QUEUE_SUMMARY_FILE = 'QUEUE_SUMMARY.md';
+export const PLAN_ORIGINAL_BACKUP_FILE = 'PLAN_ORIGINAL.md';
+export const SCRATCH_DIR_NAME = 'scratch';
+export function getNealDir(cwd) {
+    return join(cwd, NEAL_DIR_NAME);
+}
+export function getRunsDir(cwd) {
+    return join(getNealDir(cwd), RUNS_DIR_NAME);
+}
+export function getRunDir(cwd, runId) {
+    return join(getRunsDir(cwd), runId);
+}
+export function getQueuesDir(cwd) {
+    return join(getNealDir(cwd), QUEUES_DIR_NAME);
+}
+export function getReviewsDir(cwd) {
+    return join(getNealDir(cwd), REVIEWS_DIR_NAME);
+}
+export function getCurrentRunPointerPath(cwd) {
+    return join(getNealDir(cwd), CURRENT_RUN_POINTER_FILE);
+}
+export function getCurrentPlanAndExecuteQueuePointerPath(cwd) {
+    return join(getNealDir(cwd), CURRENT_QUEUE_POINTER_FILE);
+}
+export function getActiveRunLockPath(cwd) {
+    return join(getNealDir(cwd), ACTIVE_RUN_LOCK_FILE);
+}
+export function getRunStatePath(runDir) {
+    return join(runDir, RUN_STATE_FILE);
+}
+export function getPlanDocumentBackupPath(runDir) {
+    return join(runDir, PLAN_ORIGINAL_BACKUP_FILE);
+}
+export function getRunScratchDir(runDir) {
+    return join(runDir, SCRATCH_DIR_NAME);
+}
+export function getScopeReviewerScratchDir(runDir, scopeLabel, round) {
+    return join(getRunScratchDir(runDir), `reviewer-scope-${sanitizePathSegment(scopeLabel)}-round-${round}`);
+}
+export function getFinalCompletionReviewerScratchDir(runDir) {
+    return join(getRunScratchDir(runDir), 'final-completion-review');
+}
+function sanitizePathSegment(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]/g, '-');
+    return sanitized.length > 0 ? sanitized : 'scope';
+}

package/dist/neal/support.js

@@ -0,0 +1,58 @@
+import { writeTextAtomic } from './atomic-write.js';
+import { formatPublicPhase } from './phase-display.js';
+function appendInteractiveBlockedRecoverySection(lines, title, recovery, options) {
+    lines.push('', title, `- Source step: ${formatPublicPhase(recovery.sourcePhase)}`, `- Blocked reason: ${recovery.blockedReason}`, `- Max turns: ${recovery.maxTurns}`);
+    if (options?.resolvedAt && options.resolvedByAction && options.resultPhase) {
+        lines.push(`- Resolved at: ${options.resolvedAt}`, `- Resolution: ${options.resolvedByAction}`, `- Result step: ${formatPublicPhase(options.resultPhase)}`);
+    }
+    if (recovery.pendingDirective) {
+        lines.push(`- Pending terminal directive at ${recovery.pendingDirective.recordedAt}: ${recovery.pendingDirective.operatorGuidance}`);
+    }
+    if (recovery.adjudicatorAdvice) {
+        const advice = recovery.adjudicatorAdvice;
+        lines.push(`- Adjudicator advice at ${advice.recordedAt} (read-only, not auto-applied):`, `  - Recoverable: ${advice.recoverable ? 'yes' : 'no'}`, `  - Triage category: ${advice.triageCategory}`, `  - Suggested directive: ${advice.resolutionDirective || 'n/a'}`, `  - Rationale: ${advice.rationale}`);
+    }
+    if (recovery.turns.length === 0) {
+        lines.push('- Operator guidance: pending');
+        return;
+    }
+    for (const turn of recovery.turns) {
+        lines.push(`- Recovery turn ${turn.number} at ${turn.recordedAt}: ${turn.operatorGuidance}`);
+        if (turn.disposition) {
+            lines.push(`- Recovery turn ${turn.number} coder action: ${turn.disposition.action}`, `- Recovery turn ${turn.number} coder summary: ${turn.disposition.summary}`, `- Recovery turn ${turn.number} coder blocker: ${turn.disposition.blocker || 'n/a'}`, `- Recovery turn ${turn.number} coder rationale: ${turn.disposition.rationale}`, `- Recovery turn ${turn.number} resulting step: ${formatPublicPhase(turn.disposition.resultingPhase)}`);
+        }
+        else {
+            lines.push(`- Recovery turn ${turn.number} coder response: pending`);
+        }
+    }
+}
+export function renderRecoveryMarkdown(state) {
+    const lines = [
+        '# Interactive Blocked Recovery',
+        '',
+        '## Metadata',
+        `- Plan: ${state.planDoc}`,
+        `- Current step: ${formatPublicPhase(state.phase)}`,
+        `- Coder session: ${state.coderSessionHandle ?? 'pending'}`,
+        `- Reviewer session: ${state.reviewerSessionHandle ?? 'pending'}`,
+    ];
+    if (state.interactiveBlockedRecovery) {
+        appendInteractiveBlockedRecoverySection(lines, '## Active Recovery', state.interactiveBlockedRecovery);
+    }
+    if (state.interactiveBlockedRecoveryHistory.length > 0) {
+        for (const [index, recovery] of state.interactiveBlockedRecoveryHistory.entries()) {
+            appendInteractiveBlockedRecoverySection(lines, `## Recovery History ${index + 1}`, recovery, {
+                resolvedAt: recovery.resolvedAt,
+                resolvedByAction: recovery.resolvedByAction,
+                resultPhase: recovery.resultPhase,
+            });
+        }
+    }
+    if (!state.interactiveBlockedRecovery && state.interactiveBlockedRecoveryHistory.length === 0) {
+        lines.push('', 'No interactive blocked recovery yet.');
+    }
+    return `${lines.join('\n')}\n`;
+}
+export async function writeRecoveryMarkdown(path, state) {
+    await writeTextAtomic(path, renderRecoveryMarkdown(state));
+}

package/dist/neal/terminal-narrator.js

@@ -0,0 +1,435 @@
+import { basename } from 'node:path';
+import { buildBlockedGuidance } from './blocked-guidance.js';
+import { writeNarrative } from './diagnostic.js';
+import { EXECUTE_FINALIZATION_PHASE } from './execute-finalization.js';
+import { formatPublicPhase } from './phase-display.js';
+import { formatPublicRunStatus, getRunDisplayStatus } from './run-status.js';
+import { getCurrentExecutionScopeDescriptor, getCurrentScopeLabel, } from './scopes.js';
+import { getDerivedPlanView, getFinalCompletionView, getInteractiveRecoveryView, } from './state-views.js';
+export function createTerminalNarrator(options = {}) {
+    const seen = new Set();
+    const write = options.write ?? writeNarrative;
+    let previous = null;
+    let previousScopeDescriptor = null;
+    let announcedScopeContextKey = null;
+    let scopeIntroSequence = 0;
+    let started = false;
+    function emit(event) {
+        if (seen.has(event.signature)) {
+            return;
+        }
+        seen.add(event.signature);
+        write(`${event.line}\n`, options.logger);
+    }
+    async function observeState(state, includeStartEvent) {
+        const scopeDescriptor = await getNarrativeScopeDescriptor(state);
+        const currentScopeContextKey = getScopeContextKey(scopeDescriptor);
+        const previousScopeContextKey = getScopeContextKey(previousScopeDescriptor);
+        const currentIntroAlreadyPrinted = currentScopeContextKey !== null && currentScopeContextKey === announcedScopeContextKey;
+        const previousIntroAlreadyPrinted = previousScopeContextKey !== null && previousScopeContextKey === announcedScopeContextKey;
+        if (includeStartEvent && !started) {
+            started = true;
+            emit(renderRunStartEvent(state));
+        }
+        const events = renderTerminalNarrativeEvents(state, previous, {
+            current: scopeDescriptor,
+            previous: previousScopeDescriptor,
+            currentIntroAlreadyPrinted,
+            previousIntroAlreadyPrinted,
+            currentIntroSequence: scopeIntroSequence + 1,
+        });
+        for (const event of events) {
+            emit(event);
+        }
+        if (currentScopeContextKey && events.some((event) => event.signature.startsWith('scope-intro:'))) {
+            scopeIntroSequence += 1;
+            announcedScopeContextKey = currentScopeContextKey;
+        }
+        previous = state;
+        previousScopeDescriptor = scopeDescriptor;
+    }
+    return {
+        async start(state) {
+            await observeState(state, true);
+        },
+        async observe(state) {
+            await observeState(state, false);
+        },
+    };
+}
+export function renderTerminalNarrativeEvents(state, previous = null, scopeContext = {}) {
+    const currentScopeDescriptor = scopeContext.current ?? null;
+    const currentIntroAlreadyPrinted = scopeContext.currentIntroAlreadyPrinted ?? false;
+    const shouldRenderIntro = shouldRenderCurrentScopeIntro(state, currentScopeDescriptor, currentIntroAlreadyPrinted);
+    const scopeIntroEstablished = currentIntroAlreadyPrinted || shouldRenderIntro;
+    return [
+        ...renderCompletedScopeEvents(state, previous, scopeContext.previous ?? currentScopeDescriptor, scopeContext.previousIntroAlreadyPrinted ?? currentIntroAlreadyPrinted),
+        ...(shouldRenderIntro && currentScopeDescriptor
+            ? [renderScopeIntroEvent(state, currentScopeDescriptor, scopeContext.currentIntroSequence ?? 0)]
+            : []),
+        ...renderPhaseEvents(state, currentScopeDescriptor, { scopeIntroEstablished }),
+        ...renderFinalCompletionResolutionEvents(state, currentScopeDescriptor, { scopeIntroEstablished }),
+        ...renderLifecycleEvents(state, currentScopeDescriptor, { scopeIntroEstablished }),
+    ];
+}
+async function getNarrativeScopeDescriptor(state) {
+    if (state.topLevelMode !== 'execute') {
+        return null;
+    }
+    return getCurrentExecutionScopeDescriptor(state);
+}
+function renderRunStartEvent(state) {
+    const runId = basename(state.runDir);
+    const planName = basename(state.planDoc);
+    const action = hasPriorRunActivity(state) ? 'resuming' : 'starting';
+    const mode = state.topLevelMode === 'plan' ? 'plan refinement' : 'plan execution';
+    return {
+        signature: `run-start:${runId}`,
+        line: `[neal] ${action} ${mode} for ${planName}`,
+    };
+}
+function hasPriorRunActivity(state) {
+    return Boolean(state.rounds.length > 0 ||
+        state.completedScopes.length > 0 ||
+        state.createdCommits.length > 0 ||
+        state.coderSessionHandle ||
+        state.reviewerSessionHandle ||
+        state.finalCommit ||
+        state.interactiveBlockedRecovery ||
+        state.interactiveBlockedRecoveryHistory.length > 0 ||
+        state.finalCompletionSummary ||
+        state.finalCompletionReviewVerdict ||
+        state.finalCompletionResolvedAction);
+}
+function renderCompletedScopeEvents(state, previous, scopeDescriptor, scopeIntroEstablished) {
+    if (!previous || state.topLevelMode !== 'execute') {
+        return [];
+    }
+    const completedScopes = state.completedScopes.slice(previous.completedScopes.length);
+    return completedScopes.map((scope) => ({
+        signature: `scope-finalized:${basename(state.runDir)}:${scope.number}:${scope.finalCommit ?? 'pending'}`,
+        line: formatCompletedScopeLine(scope.number, scope.result, scopeDescriptor, { scopeIntroEstablished }),
+    }));
+}
+function renderPhaseEvents(state, scopeDescriptor, options) {
+    const runId = basename(state.runDir);
+    const scopeLabel = getCurrentScopeLabel(state);
+    const scopeReference = formatScopeReference(scopeLabel, scopeDescriptor);
+    const phase = state.phase;
+    const round = state.rounds.length + 1;
+    const recovery = getInteractiveRecoveryView(state);
+    const derivedPlan = getDerivedPlanView(state);
+    const finalCompletion = getFinalCompletionView(state);
+    const displayStatus = getRunDisplayStatus(state);
+    if (displayStatus.waitingForOperatorGuidance) {
+        const guidance = buildBlockedGuidance({
+            state,
+            runId,
+            waitingForOperatorGuidance: true,
+        });
+        const firstOption = guidance?.options[0]?.command;
+        if (guidance && firstOption) {
+            return [
+                {
+                    signature: `operator-waiting:${runId}:${recovery?.sourcePhase ?? state.blockedFromPhase ?? phase}:${recovery?.handledTurn ?? 0}:${guidance.category}`,
+                    line: `[neal] waiting for operator guidance: ${guidance.summary}; use: ${firstOption}`,
+                },
+            ];
+        }
+        return [
+            {
+                signature: `operator-waiting:${runId}:${recovery?.sourcePhase ?? state.blockedFromPhase ?? phase}:${recovery?.handledTurn ?? 0}`,
+                line: `[neal] waiting for operator guidance; use: neal resume --run ${runId} --message "..."`,
+            },
+        ];
+    }
+    if (displayStatus.pendingOperatorGuidance) {
+        return [
+            {
+                signature: `operator-pending:${runId}:${recovery?.pendingTurnCount ?? 0}:${recovery?.handledTurn ?? 0}`,
+                line: `Operator guidance is recorded; resuming will process it now.`,
+            },
+        ];
+    }
+    switch (phase) {
+        case 'coder_plan':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${round}`,
+                    line: `Planner is refining the plan.`,
+                },
+            ];
+        case 'reviewer_plan':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${round}:${derivedPlan?.state ?? 'ordinary'}`,
+                    line: derivedPlan?.reviewActive
+                        ? `Reviewer is checking the derived plan for scope ${derivedPlan.parentScopeNumber ?? scopeLabel}.`
+                        : `Reviewer is checking the plan.`,
+                },
+            ];
+        case 'coder_plan_response':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${round}`,
+                    line: `Planner is addressing requested plan revisions.`,
+                },
+            ];
+        case 'coder_plan_optional_response':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${round}`,
+                    line: `Planner is handling optional plan follow-up.`,
+                },
+            ];
+        case 'awaiting_derived_plan_execution':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${derivedPlan?.path ?? 'unknown'}`,
+                    line: `Derived plan accepted; preparing its first scope.`,
+                },
+            ];
+        case 'coder_scope':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${scopeLabel}:${state.baseCommit ?? 'no-base'}:${state.createdCommits.length}`,
+                    line: options.scopeIntroEstablished ? `Coder is implementing.` : `Coder is implementing ${scopeReference}.`,
+                },
+            ];
+        case 'manual_gate':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${state.manualGate?.id ?? 'unknown'}`,
+                    line: `Run is waiting for manual gate ${state.manualGate?.id ?? 'unknown'}.`,
+                },
+            ];
+        case 'reviewer_scope':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${scopeLabel}:${round}:${state.createdCommits.at(-1) ?? 'no-commit'}`,
+                    line: options.scopeIntroEstablished ? `Reviewer is checking.` : `Reviewer is checking ${scopeReference}.`,
+                },
+            ];
+        case 'coder_response':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${scopeLabel}:${round}`,
+                    line: options.scopeIntroEstablished
+                        ? `Reviewer requested revisions; coder is addressing them.`
+                        : `Reviewer requested revisions for ${scopeReference}; coder is addressing them.`,
+                },
+            ];
+        case 'coder_optional_response':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${scopeLabel}:${round}`,
+                    line: options.scopeIntroEstablished
+                        ? `Reviewer left optional follow-up; coder is handling it.`
+                        : `Reviewer left optional follow-up for ${scopeReference}; coder is handling it.`,
+                },
+            ];
+        case 'interactive_blocked_recovery':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${recovery?.sourcePhase ?? state.blockedFromPhase ?? 'unknown'}`,
+                    line: formatScopeRelatedPhase(recovery?.sourcePhase ?? state.blockedFromPhase ?? phase)
+                        ? options.scopeIntroEstablished
+                            ? `Interactive recovery is active for ${formatPublicPhase(recovery?.sourcePhase ?? state.blockedFromPhase ?? phase)}.`
+                            : `Interactive recovery is active for ${formatPublicPhase(recovery?.sourcePhase ?? state.blockedFromPhase ?? phase)} on ${scopeReference}.`
+                        : `Interactive recovery is active for ${formatPublicPhase(recovery?.sourcePhase ?? state.blockedFromPhase ?? phase)}.`,
+                },
+            ];
+        case EXECUTE_FINALIZATION_PHASE:
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${scopeLabel}:${state.createdCommits.length}`,
+                    line: options.scopeIntroEstablished
+                        ? `Reviewer accepted; finalizing.`
+                        : `Reviewer accepted ${scopeReference}; finalizing.`,
+                },
+            ];
+        case 'final_completion_review':
+            return [
+                {
+                    signature: `phase:${runId}:${phase}:${finalCompletion?.continueExecutionCount ?? 0}`,
+                    line: `Reviewer is checking final completion.`,
+                },
+            ];
+        case 'done':
+        case 'blocked':
+            return [];
+    }
+}
+function renderFinalCompletionResolutionEvents(state, scopeDescriptor, options) {
+    if (state.topLevelMode !== 'execute') {
+        return [];
+    }
+    const finalCompletion = getFinalCompletionView(state);
+    if (!finalCompletion?.hasResolvedAction) {
+        return [];
+    }
+    const runId = basename(state.runDir);
+    const action = finalCompletion.effectiveAction;
+    if (action === 'accept_complete') {
+        return [
+            {
+                signature: `final-completion:${runId}:${action}`,
+                line: `Final completion review accepted the implementation.`,
+            },
+        ];
+    }
+    if (action === 'continue_execution') {
+        const scopeReference = formatScopeReference(getCurrentScopeLabel(state), scopeDescriptor);
+        return [
+            {
+                signature: `final-completion:${runId}:${action}:${finalCompletion.continueExecutionCount}`,
+                line: options.scopeIntroEstablished
+                    ? `Final completion review reopened execution; continuing.`
+                    : `Final completion review reopened execution; continuing with ${scopeReference}.`,
+            },
+        ];
+    }
+    if (action === 'block_for_operator') {
+        return [
+            {
+                signature: `final-completion:${runId}:${action}:${finalCompletion.continueExecutionCount}`,
+                line: `Final completion review blocked completion for operator guidance.`,
+            },
+        ];
+    }
+    return [];
+}
+function renderLifecycleEvents(state, scopeDescriptor, options) {
+    const displayStatus = getRunDisplayStatus(state);
+    const publicStatus = formatPublicRunStatus(displayStatus);
+    const runId = basename(state.runDir);
+    const scopeReference = formatScopeReference(getCurrentScopeLabel(state), scopeDescriptor);
+    if (displayStatus.waitingForOperatorGuidance || displayStatus.pendingOperatorGuidance) {
+        return [];
+    }
+    if (state.status === 'paused') {
+        return [
+            {
+                signature: `lifecycle:${runId}:paused:${state.phase}:${getCurrentScopeLabel(state)}`,
+                line: options.scopeIntroEstablished ? `Run paused after this scope.` : `Run paused after ${scopeReference}.`,
+            },
+        ];
+    }
+    if (state.status === 'failed') {
+        return [
+            {
+                signature: `lifecycle:${runId}:failed:${state.phase}`,
+                line: `Run failed during ${formatPublicPhase(state.phase)}.`,
+            },
+        ];
+    }
+    if (state.status === 'blocked') {
+        const blockedPhase = state.blockedFromPhase ?? state.phase;
+        return [
+            {
+                signature: `lifecycle:${runId}:blocked:${blockedPhase}`,
+                line: formatScopeRelatedPhase(blockedPhase)
+                    ? options.scopeIntroEstablished
+                        ? `Run is blocked during ${formatPublicPhase(blockedPhase)}.`
+                        : `Run is blocked during ${formatPublicPhase(blockedPhase)} for ${scopeReference}.`
+                    : `Run is blocked during ${formatPublicPhase(blockedPhase)}.`,
+            },
+        ];
+    }
+    if (state.status === 'done') {
+        return [
+            {
+                signature: `lifecycle:${runId}:done:${state.topLevelMode}:${publicStatus}`,
+                line: state.topLevelMode === 'plan' ? `Plan refinement complete.` : `Implementation complete.`,
+            },
+        ];
+    }
+    return [];
+}
+function renderScopeIntroEvent(state, scopeDescriptor, sequence) {
+    const scopeContextKey = getScopeContextKey(scopeDescriptor) ?? scopeDescriptor.display;
+    return {
+        signature: `scope-intro:${basename(state.runDir)}:${sequence}:${scopeContextKey}`,
+        line: capitalizeLeadingScope(scopeDescriptor.display),
+    };
+}
+function shouldRenderCurrentScopeIntro(state, scopeDescriptor, currentIntroAlreadyPrinted) {
+    return Boolean(scopeDescriptor && !currentIntroAlreadyPrinted && hasCurrentScopeNarrativeEvent(state));
+}
+function hasCurrentScopeNarrativeEvent(state) {
+    if (state.topLevelMode !== 'execute') {
+        return false;
+    }
+    const displayStatus = getRunDisplayStatus(state);
+    if (displayStatus.waitingForOperatorGuidance || displayStatus.pendingOperatorGuidance) {
+        return false;
+    }
+    if (isScopeActionPhase(state.phase)) {
+        return true;
+    }
+    if (state.phase === 'interactive_blocked_recovery') {
+        const recovery = getInteractiveRecoveryView(state);
+        return formatScopeRelatedPhase(recovery?.sourcePhase ?? state.blockedFromPhase ?? state.phase);
+    }
+    const finalCompletion = getFinalCompletionView(state);
+    if (finalCompletion?.hasResolvedAction && finalCompletion.effectiveAction === 'continue_execution') {
+        return true;
+    }
+    if (state.status === 'paused') {
+        return true;
+    }
+    return state.status === 'blocked' && formatScopeRelatedPhase(state.blockedFromPhase ?? state.phase);
+}
+function formatScopeReference(scopeLabel, descriptor, options = {}) {
+    const reference = descriptor?.scopeLabel === scopeLabel ? descriptor.display : `scope ${scopeLabel}`;
+    if (!options.capitalized) {
+        return reference;
+    }
+    return reference[0]?.toUpperCase() + reference.slice(1);
+}
+function formatCompletedScopeLine(scopeLabel, result, descriptor, options) {
+    if (options.scopeIntroEstablished) {
+        return result === 'accepted' ? `Scope accepted.` : `Scope blocked.`;
+    }
+    if (descriptor?.scopeLabel !== scopeLabel || !descriptor.title) {
+        return `Scope ${scopeLabel} finalized and ${result}.`;
+    }
+    const scopeReference = formatScopeReference(scopeLabel, descriptor, { capitalized: true });
+    return `${scopeReference.replace(`: ${descriptor.title}`, '')} finalized and ${result}: ${descriptor.title}.`;
+}
+function getScopeContextKey(descriptor) {
+    if (!descriptor) {
+        return null;
+    }
+    return JSON.stringify([
+        descriptor.planPath,
+        descriptor.scopeLabel,
+        descriptor.planScopeNumber,
+        formatScopeCountKey(descriptor.scopeCount),
+        descriptor.title,
+        descriptor.display,
+    ]);
+}
+function formatScopeCountKey(scopeCount) {
+    return scopeCount.kind === 'known' ? `${scopeCount.kind}:${scopeCount.total}` : scopeCount.kind;
+}
+function capitalizeLeadingScope(value) {
+    if (value === '') {
+        return value;
+    }
+    return value[0].toUpperCase() + value.slice(1);
+}
+function isScopeActionPhase(phase) {
+    return (phase === 'coder_scope' ||
+        phase === 'reviewer_scope' ||
+        phase === 'coder_response' ||
+        phase === 'coder_optional_response' ||
+        phase === EXECUTE_FINALIZATION_PHASE);
+}
+function formatScopeRelatedPhase(phase) {
+    return (phase === 'coder_scope' ||
+        phase === 'reviewer_scope' ||
+        phase === 'coder_response' ||
+        phase === 'coder_optional_response' ||
+        phase === EXECUTE_FINALIZATION_PHASE);
+}

package/dist/neal/types.js

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

package/dist/neal/verification-events.js

@@ -0,0 +1,81 @@
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+export function isVerificationCommand(command) {
+    return /\b(test|tests|typecheck|tsc|lint|build|verify|validation|check|pytest|vitest|jest)\b/i.test(command);
+}
+function isCommandExecutionEvent(event) {
+    return (event.type === 'provider.command_completed' ||
+        event.type === 'coder.command_execution' ||
+        event.type === 'codex.command_execution');
+}
+export function extractCommandResults(events) {
+    return events
+        .filter(isCommandExecutionEvent)
+        .map((event) => {
+        const command = stringValue(event.data?.command);
+        if (!command) {
+            return null;
+        }
+        return {
+            command,
+            provider: stringValue(event.data?.provider),
+            status: stringValue(event.data?.status),
+            exitCode: numberValue(event.data?.exitCode),
+            cwd: stringValue(event.data?.cwd),
+            gitHead: stringValue(event.data?.gitHead),
+            completedAt: stringValue(event.ts),
+            itemId: stringValue(event.data?.itemId),
+            outputLength: numberValue(event.data?.outputLength),
+        };
+    })
+        .filter((result) => result !== null);
+}
+export function extractVerificationCommandResults(events) {
+    return extractCommandResults(events).filter((result) => isVerificationCommand(result.command));
+}
+export function latestCommandResultPerCommand(results) {
+    const byCommand = new Map();
+    for (const result of results) {
+        byCommand.set(result.command, result);
+    }
+    return [...byCommand.values()];
+}
+function renderCommandStatus(result) {
+    if (result.exitCode === 0) {
+        return 'passed';
+    }
+    if (typeof result.exitCode === 'number') {
+        return 'failed';
+    }
+    if (result.status === 'failed') {
+        return 'failed';
+    }
+    return 'unknown';
+}
+export function summarizeVerificationCommandResults(results) {
+    if (results.length === 0) {
+        return 'No verification commands were recorded in events.ndjson.';
+    }
+    const latestResults = latestCommandResultPerCommand(results);
+    const lines = ['Recorded latest verification command results for this run:'];
+    let unknownExitStatusCount = 0;
+    for (const result of latestResults) {
+        const renderedStatus = renderCommandStatus(result);
+        const exit = typeof result.exitCode === 'number' ? `exit ${result.exitCode}` : 'exit unknown';
+        const gitHead = result.gitHead ? `, git ${result.gitHead.slice(0, 12)}` : '';
+        const cwd = result.cwd ? `, cwd ${result.cwd}` : '';
+        const completedAt = result.completedAt ? `, at ${result.completedAt}` : '';
+        lines.push(`- ${renderedStatus} (${exit}${gitHead}${cwd}${completedAt}): ${result.command}`);
+        if (typeof result.exitCode !== 'number') {
+            unknownExitStatusCount += 1;
+        }
+    }
+    if (unknownExitStatusCount > 0) {
+        lines.push(`- ${unknownExitStatusCount} latest verification command(s) have unknown exit status, usually from older events recorded before structured command results were available.`);
+    }
+    return lines.join('\n');
+}

package/dist/neal/version.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { dirname } from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+const execFileAsync = promisify(execFile);
+let cachedBuildMetadata = null;
+export function getAppVersion() {
+    const packageJsonPath = new URL('../../package.json', import.meta.url);
+    const metadata = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    if (typeof metadata.version !== 'string' || metadata.version.trim() === '') {
+        throw new Error('package.json is missing a valid version');
+    }
+    return metadata.version;
+}
+export async function getNealBuildMetadata() {
+    cachedBuildMetadata ??= readNealBuildMetadata();
+    return cachedBuildMetadata;
+}
+async function readNealBuildMetadata() {
+    return {
+        packageVersion: getAppVersion(),
+        nodeVersion: process.version,
+        sourceGitSha: await readSourceGitSha(),
+    };
+}
+async function readSourceGitSha() {
+    const packageRoot = dirname(fileURLToPath(new URL('../../package.json', import.meta.url)));
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', packageRoot, 'rev-parse', 'HEAD']);
+        const sha = stdout.trim();
+        return /^[0-9a-f]{40}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}