@navels/neal 0.1.0

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

@@ -0,0 +1,136 @@
+import { ReviewerRoundError } from '../../agents.js';
+import { runExecuteReviewerAdjudication, synthesizeExecuteReviewerState, } from '../../adjudicator/execute.js';
+import { assertAdjudicationTransitionSignal } from '../../adjudicator/specs.js';
+import { getChangedFilesForRange, getCommitRange, getDiffForRange, getDiffStatForRange, getHeadCommit, } from '../../git.js';
+import { writeDetail } from '../../diagnostic.js';
+import { saveState } from '../../state.js';
+import { writeExecutionArtifacts } from '../artifacts.js';
+import { shouldNotifyFailure } from '../failures.js';
+import { notifyBlocked } from '../notifications.js';
+import { enterInteractiveBlockedRecovery, shouldNotifyInteractiveBlockedRecoveryEntry } from './recovery.js';
+import { printReviewResult } from './shared.js';
+function getExecuteReviewDispositionSignal(args) {
+    if (args.phase === 'execute_finalization') {
+        return args.meaningfulProgressAction === 'advance_parent' ? 'advance_parent' : 'accept_scope';
+    }
+    if (args.phase === 'coder_response') {
+        return 'request_revision';
+    }
+    if (args.phase === 'coder_optional_response') {
+        return 'optional_revision';
+    }
+    return args.meaningfulProgressAction === 'replace_plan' ? 'replace_plan' : 'block_for_operator';
+}
+export async function runReviewPhase(state, statePath, logger) {
+    await logger?.event('phase.start', { phase: 'reviewer_scope', round: state.rounds.length + 1 });
+    let claude;
+    let headCommit;
+    let changedFiles;
+    let reviewContext;
+    let reviewerSynthesis;
+    try {
+        ({
+            context: reviewContext,
+            reviewerResult: claude,
+            reviewInput: { headCommit, changedFiles },
+        } = await runExecuteReviewerAdjudication({
+            state,
+            logger,
+            getHeadCommit,
+            getCommitRange,
+            getDiffStatForRange,
+            getChangedFilesForRange,
+            getDiffForRange,
+        }));
+        reviewerSynthesis = synthesizeExecuteReviewerState({
+            state,
+            context: reviewContext,
+            headCommit,
+            changedFiles,
+            reviewerResult: claude,
+        });
+    }
+    catch (error) {
+        if (error instanceof ReviewerRoundError) {
+            const failedState = await saveState(statePath, {
+                ...state,
+                reviewerSessionHandle: null,
+                status: 'failed',
+            });
+            await writeExecutionArtifacts(failedState);
+            await logger?.event('phase.error', {
+                phase: 'reviewer_scope',
+                round: state.rounds.length + 1,
+                sessionHandle: error.sessionHandle,
+                subtype: error.subtype,
+                message: error.message,
+            });
+            if (shouldNotifyFailure(error)) {
+                await notifyBlocked(failedState, error.message, logger);
+            }
+        }
+        throw error;
+    }
+    printReviewResult('review', claude.summary, claude.findings, logger);
+    const meaningfulProgressVerdict = reviewerSynthesis.meaningfulProgressVerdict;
+    writeDetail(`[reviewer:review] meaningful progress: ${meaningfulProgressVerdict.action} - ${meaningfulProgressVerdict.rationale}\n`, logger, {
+        phase: 'reviewer_scope',
+        role: 'reviewer',
+    });
+    assertAdjudicationTransitionSignal(reviewContext.spec, getExecuteReviewDispositionSignal({
+        phase: reviewerSynthesis.disposition.phase,
+        meaningfulProgressAction: meaningfulProgressVerdict.action,
+    }), 'orchestrator:reviewer_scope');
+    const adjudicatedState = {
+        ...state,
+        reviewerSessionHandle: claude.sessionHandle,
+        phase: reviewerSynthesis.disposition.phase,
+        status: reviewerSynthesis.disposition.status,
+        rounds: [
+            ...state.rounds,
+            reviewerSynthesis.roundRecord,
+        ],
+        findings: reviewerSynthesis.mergedFindings,
+        blockedFromPhase: reviewerSynthesis.disposition.blockedFromPhase,
+        currentScopeMeaningfulProgressVerdict: meaningfulProgressVerdict,
+    };
+    const nextState = await saveState(statePath, adjudicatedState);
+    const parentAdvanceClassification = reviewerSynthesis.parentAdvanceClassification;
+    const parentAdvanceMessage = meaningfulProgressVerdict.action === 'advance_parent'
+        ? (`advance_parent will advance parent scope ${parentAdvanceClassification?.parentScopeLabel ?? reviewContext.parentScopeLabel} ` +
+            `after empty derived scope ${parentAdvanceClassification?.currentScopeLabel ?? 'unknown'} ` +
+            'without accepting the current no-op sub-scope.')
+        : null;
+    if (meaningfulProgressVerdict.action === 'advance_parent') {
+        await logger?.event('review.meaningful_progress.advance_parent', {
+            message: parentAdvanceMessage ?? 'Advancing parent scope after an empty derived scope.',
+            parentScopeLabel: parentAdvanceClassification?.parentScopeLabel ?? reviewContext.parentScopeLabel,
+            currentScopeLabel: parentAdvanceClassification?.currentScopeLabel ?? null,
+            source: parentAdvanceClassification?.source ?? null,
+            priorEmptyCount: parentAdvanceClassification?.priorEmptyCount ?? null,
+            priorSubstantiveCount: parentAdvanceClassification?.priorSubstantiveCount ?? null,
+            aggregateChangedFileCount: parentAdvanceClassification?.aggregateChangedFiles.length ?? null,
+            failedPreconditions: parentAdvanceClassification?.failedPreconditions ?? [],
+        });
+    }
+    await writeExecutionArtifacts(nextState);
+    await logger?.event('phase.complete', {
+        phase: 'reviewer_scope',
+        round: reviewContext.round,
+        sessionHandle: claude.sessionHandle,
+        findings: reviewerSynthesis.findings.length,
+        blockingFindings: reviewerSynthesis.findings.filter((finding) => finding.severity === 'blocking').length,
+        meaningfulProgressAction: meaningfulProgressVerdict.action,
+        originalMeaningfulProgressAction: claude.meaningfulProgress.action,
+        message: parentAdvanceMessage ?? undefined,
+        nextPhase: nextState.phase,
+    });
+    if (nextState.status === 'blocked' && reviewerSynthesis.blockReason) {
+        const persistedState = await enterInteractiveBlockedRecovery(nextState, statePath, reviewerSynthesis.blockReason, logger);
+        if (shouldNotifyInteractiveBlockedRecoveryEntry(persistedState)) {
+            await notifyBlocked(persistedState, reviewerSynthesis.blockReason, logger);
+        }
+        return persistedState;
+    }
+    return nextState;
+}

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

@@ -0,0 +1,279 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { writeDetail } from '../../diagnostic.js';
+import { writeCheckpointRetrospective } from '../../retrospective.js';
+import { getCurrentScopeLabel, getParentScopeLabel, isExecutingDerivedPlan } from '../../scopes.js';
+import { saveState } from '../../state.js';
+import { getDerivedPlanView } from '../../state-views.js';
+import { writeExecutionArtifacts } from '../artifacts.js';
+import { isCoderFreshSessionRetryableError, isCoderTimeoutError } from '../failures.js';
+import { notifyRetry } from '../notifications.js';
+import { appendCompletedScope } from '../transitions.js';
+const execFile = promisify(execFileCallback);
+function getWriterSessionRoleForPhase(phase) {
+    return phase === 'coder_plan' || phase === 'coder_plan_response' || phase === 'coder_plan_optional_response'
+        ? 'planner'
+        : 'coder';
+}
+function getWriterSessionState(args) {
+    const role = getWriterSessionRoleForPhase(args.phase);
+    if (role === 'planner') {
+        const sessionHandle = args.errorSessionHandle ?? args.state.plannerSessionHandle;
+        return {
+            role,
+            sessionHandle,
+            protocol: sessionHandle ? args.state.plannerSessionProtocol ?? 'structured_json_v1' : null,
+        };
+    }
+    const sessionHandle = args.errorSessionHandle ?? args.state.coderSessionHandle;
+    return {
+        role,
+        sessionHandle,
+        protocol: sessionHandle ? args.state.coderSessionProtocol ?? 'structured_json_v1' : null,
+    };
+}
+function formatReviewFindings(findings) {
+    if (findings.length === 0) {
+        return '  Findings: none\n';
+    }
+    return findings
+        .map((finding, index) => {
+        const files = finding.files.length > 0 ? finding.files.join(', ') : 'n/a';
+        const source = finding.source ? ` [${finding.source}]` : '';
+        return [
+            `  ${index + 1}. [${finding.severity}]${source} ${finding.claim}`,
+            `     Files: ${files}`,
+            `     Action: ${finding.requiredAction}`,
+        ].join('\n');
+    })
+        .join('\n') + '\n';
+}
+export function printReviewResult(kind, summary, findings, logger) {
+    const blocking = findings.filter((finding) => finding.severity === 'blocking').length;
+    const nonBlocking = findings.length - blocking;
+    const header = kind === 'review' ? '[reviewer:review]' : '[reviewer:plan-review]';
+    const message = [
+        `${header} summary: ${summary}`,
+        `${header} findings: ${blocking} blocking, ${nonBlocking} non-blocking`,
+        formatReviewFindings(findings),
+    ].join('\n');
+    writeDetail(`${message}\n`, logger, {
+        role: 'reviewer',
+    });
+}
+export async function persistCoderFailureState(state, statePath, phase, error, logger) {
+    const writerSession = getWriterSessionState({ state, phase, errorSessionHandle: error.sessionHandle });
+    const failedState = await saveState(statePath, {
+        ...state,
+        ...(writerSession.role === 'planner'
+            ? {
+                plannerSessionHandle: writerSession.sessionHandle,
+                plannerSessionProtocol: writerSession.protocol,
+            }
+            : {
+                coderSessionHandle: writerSession.sessionHandle,
+                coderSessionProtocol: writerSession.protocol,
+            }),
+        status: 'failed',
+    });
+    await writeExecutionArtifacts(failedState);
+    await writeCheckpointRetrospective(failedState, 'failed');
+    await logger?.event('phase.error', {
+        phase,
+        role: writerSession.role,
+        sessionHandle: writerSession.sessionHandle,
+        message: error.message,
+    });
+    return failedState;
+}
+// Shared terminal-fail action for the three operator-block sites under
+// `unattended`. Mirrors `persistCoderFailureState`: save `status:'failed'`,
+// re-render the execution artifacts, write a `failed` checkpoint retrospective,
+// and emit a classified log event — deliberately WITHOUT `notifyBlocked` (that
+// is the attended wait notification). Any produced diff/plan is left in the
+// worktree/run dir as an artifact and is not submitted, exactly as today's
+// failed runs leave it. `phase`/`blockedFromPhase` are preserved for
+// diagnostics (defaulting `blockedFromPhase` to the current phase).
+export async function persistUnattendedBlockUnresolvedFailure(state, statePath, site, logger) {
+    const blockedFromPhase = state.blockedFromPhase ?? state.phase;
+    const failedState = await saveState(statePath, {
+        ...state,
+        status: 'failed',
+        blockedFromPhase,
+    });
+    await writeExecutionArtifacts(failedState);
+    await writeCheckpointRetrospective(failedState, 'failed');
+    await logger?.event('unattended.block_unresolved', {
+        reason: 'unattended_block_unresolved',
+        site,
+        blockedFromPhase,
+        phase: failedState.phase,
+        scopeNumber: failedState.currentScopeNumber,
+    });
+    return failedState;
+}
+export async function persistBlockedScope(state, statePath, reason) {
+    const scopeLabel = getCurrentScopeLabel(state);
+    if (state.completedScopes.some((scope) => scope.number === scopeLabel)) {
+        return state;
+    }
+    const derivedPlan = getDerivedPlanView(state);
+    const blockedDuringDerivedPlanReview = !derivedPlan?.executing &&
+        derivedPlan?.unexecuted === true &&
+        derivedPlan.parentScopeNumber === state.currentScopeNumber;
+    const nextState = await saveState(statePath, {
+        ...state,
+        blockedFromPhase: state.blockedFromPhase ?? state.phase,
+        completedScopes: appendCompletedScope(state, 'blocked', {
+            scopeLabel: getCurrentScopeLabel(state),
+            finalCommit: null,
+            summary: null,
+            commitSubject: null,
+            archivedReviewPath: state.archivedReviewPath,
+            blocker: reason,
+            derivedFromParentScope: isExecutingDerivedPlan(state) ? getParentScopeLabel(state) : null,
+            replacedByDerivedPlanPath: blockedDuringDerivedPlanReview ? derivedPlan.path : null,
+        }),
+    });
+    await writeExecutionArtifacts(nextState);
+    return nextState;
+}
+export function shouldRetryCoderWithFreshSession(state, phase, error) {
+    if (!isCoderFreshSessionRetryableError(error) || state.coderRetryCount >= 1) {
+        return false;
+    }
+    if (state.topLevelMode === 'execute') {
+        return (phase === 'coder_scope' ||
+            phase === 'coder_response' ||
+            phase === 'coder_optional_response' ||
+            phase === 'interactive_blocked_recovery');
+    }
+    return phase === 'coder_plan' || phase === 'coder_plan_response' || phase === 'coder_plan_optional_response';
+}
+function escapeForPkillPattern(text) {
+    return text.replace(/[\\.^$|?*+()[\]{}]/g, '\\$&');
+}
+function parseProcessRows(output) {
+    const rows = [];
+    for (const line of output.split('\n')) {
+        const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/);
+        if (!match) {
+            continue;
+        }
+        rows.push({
+            pid: Number(match[1]),
+            ppid: Number(match[2]),
+            command: match[3],
+        });
+    }
+    return rows;
+}
+async function findOwnCodexExecChildPids() {
+    const { stdout } = await execFile('ps', ['-axo', 'pid=,ppid=,command=']);
+    return parseProcessRows(stdout)
+        .filter((row) => row.ppid === process.pid)
+        .filter((row) => /\bcodex exec\b/.test(row.command))
+        .map((row) => row.pid);
+}
+async function killOwnCodexExecChildren(logger, sessionHandle) {
+    let pids;
+    try {
+        pids = await findOwnCodexExecChildPids();
+    }
+    catch (error) {
+        await logger?.event('coder.timeout_cleanup_child_scan_failed', {
+            sessionHandle,
+            details: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+    if (pids.length === 0) {
+        return false;
+    }
+    const termResults = [];
+    for (const pid of pids) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            termResults.push({ pid, result: 'signaled' });
+        }
+        catch (error) {
+            termResults.push({
+                pid,
+                result: 'failed',
+                details: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    await logger?.event('coder.timeout_cleanup', {
+        sessionHandle,
+        pids,
+        result: 'killed_child_codex_exec',
+        signals: termResults,
+    });
+    return true;
+}
+export async function bestEffortCleanupTimedOutCoder(sessionHandle, logger) {
+    if (!sessionHandle) {
+        return;
+    }
+    const killedChild = await killOwnCodexExecChildren(logger, sessionHandle);
+    if (killedChild) {
+        return;
+    }
+    const pattern = `codex.*resume ${escapeForPkillPattern(sessionHandle)}`;
+    try {
+        await execFile('pkill', ['-f', pattern]);
+        await logger?.event('coder.timeout_cleanup', {
+            sessionHandle,
+            pattern,
+            result: 'killed',
+        });
+    }
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        await logger?.event('coder.timeout_cleanup', {
+            sessionHandle,
+            pattern,
+            result: 'not_found_or_failed',
+            details,
+        });
+    }
+}
+function getCoderFreshSessionRetryMessage(state, phase, error) {
+    const reason = isCoderTimeoutError(error) ? 'timed out' : 'hit an unusable resume session';
+    const role = getWriterSessionRoleForPhase(phase);
+    return state.topLevelMode === 'plan'
+        ? `planning phase ${phase} ${reason}; retrying with a fresh ${role} session`
+        : `scope ${state.currentScopeNumber} ${reason} in ${phase}; retrying with a fresh ${role} session`;
+}
+export async function scheduleCoderFreshSessionRetry(state, statePath, phase, error, logger) {
+    const writerSession = getWriterSessionState({ state, phase, errorSessionHandle: error.sessionHandle });
+    if (isCoderTimeoutError(error)) {
+        await bestEffortCleanupTimedOutCoder(writerSession.sessionHandle, logger);
+    }
+    const retryState = await saveState(statePath, {
+        ...state,
+        ...(writerSession.role === 'planner'
+            ? {
+                plannerSessionHandle: null,
+                plannerSessionProtocol: null,
+            }
+            : {
+                coderSessionHandle: null,
+                coderSessionProtocol: null,
+            }),
+        coderRetryCount: state.coderRetryCount + 1,
+        status: 'running',
+        phase,
+    });
+    await writeExecutionArtifacts(retryState);
+    await logger?.event('phase.retry', {
+        phase,
+        role: writerSession.role,
+        sessionHandle: writerSession.sessionHandle,
+        retryCount: retryState.coderRetryCount,
+        message: error.message,
+    });
+    await notifyRetry(retryState, getCoderFreshSessionRetryMessage(retryState, phase, error), logger);
+    return retryState;
+}

package/dist/neal/orchestrator/run-loop.js

@@ -0,0 +1,113 @@
+import { EXECUTE_FINALIZATION_PHASE, isExecuteFinalizationPhase } from '../execute-finalization.js';
+export const PLAN_RUNNABLE_PHASE_REGISTRY = {
+    coder_plan: 'coder_plan',
+    reviewer_plan: 'reviewer_plan',
+    coder_plan_response: 'coder_plan_response',
+    coder_plan_optional_response: 'coder_plan_response',
+};
+export const EXECUTE_RUNNABLE_PHASE_REGISTRY = {
+    awaiting_derived_plan_execution: 'awaiting_derived_plan_execution',
+    coder_scope: 'coder_scope',
+    reviewer_scope: 'reviewer_scope',
+    coder_response: 'coder_response',
+    coder_optional_response: 'coder_response',
+};
+export const RECOVERY_RUNNABLE_PHASE_REGISTRY = {
+    interactive_blocked_recovery: 'interactive_blocked_recovery',
+};
+export const EXECUTE_FINALIZATION_RUNNABLE_PHASE_REGISTRY = {
+    [EXECUTE_FINALIZATION_PHASE]: EXECUTE_FINALIZATION_PHASE,
+    final_completion_review: 'final_completion_review',
+};
+export const RUNNABLE_PHASE_PURPOSE_REGISTRIES = {
+    plan: PLAN_RUNNABLE_PHASE_REGISTRY,
+    execute: EXECUTE_RUNNABLE_PHASE_REGISTRY,
+    recovery: RECOVERY_RUNNABLE_PHASE_REGISTRY,
+    executeFinalization: EXECUTE_FINALIZATION_RUNNABLE_PHASE_REGISTRY,
+};
+export const RUNNABLE_PHASE_REGISTRY = {
+    ...PLAN_RUNNABLE_PHASE_REGISTRY,
+    ...EXECUTE_RUNNABLE_PHASE_REGISTRY,
+    ...RECOVERY_RUNNABLE_PHASE_REGISTRY,
+    ...EXECUTE_FINALIZATION_RUNNABLE_PHASE_REGISTRY,
+};
+export const RUNNABLE_PHASES_BY_TOP_LEVEL_MODE = {
+    plan: [
+        'coder_plan',
+        'reviewer_plan',
+        'coder_plan_response',
+        'coder_plan_optional_response',
+    ],
+    execute: [
+        'reviewer_plan',
+        'coder_plan_response',
+        'coder_plan_optional_response',
+        'awaiting_derived_plan_execution',
+        'coder_scope',
+        'reviewer_scope',
+        'coder_response',
+        'coder_optional_response',
+        'interactive_blocked_recovery',
+        EXECUTE_FINALIZATION_PHASE,
+        'final_completion_review',
+    ],
+};
+const RUNNABLE_PHASE_SETS_BY_TOP_LEVEL_MODE = {
+    plan: new Set(RUNNABLE_PHASES_BY_TOP_LEVEL_MODE.plan),
+    execute: new Set(RUNNABLE_PHASES_BY_TOP_LEVEL_MODE.execute),
+};
+export function isRunnablePhase(phase) {
+    return Object.prototype.hasOwnProperty.call(RUNNABLE_PHASE_REGISTRY, phase);
+}
+export function getRunnablePhasesForTopLevelMode(topLevelMode) {
+    return RUNNABLE_PHASES_BY_TOP_LEVEL_MODE[topLevelMode];
+}
+export function isRunnablePhaseForTopLevelMode(phase, topLevelMode) {
+    return isRunnablePhase(phase) && RUNNABLE_PHASE_SETS_BY_TOP_LEVEL_MODE[topLevelMode].has(phase);
+}
+export async function runOnePass(args) {
+    const { state, logger, options, runtime, handlers } = args;
+    let currentState = state;
+    while (isRunnablePhase(currentState.phase) &&
+        (currentState.phase !== 'interactive_blocked_recovery' || runtime.hasPendingInteractiveBlockedRecoveryTurn(currentState))) {
+        const phaseStartedAt = Date.now();
+        await options?.onDisplayState?.(currentState, phaseStartedAt);
+        const stopHeartbeat = runtime.startPhaseHeartbeat(currentState.phase, () => currentState, logger);
+        try {
+            const currentPhase = currentState.phase;
+            currentState = await handlers[RUNNABLE_PHASE_REGISTRY[currentPhase]](currentState);
+            await options?.onDisplayState?.(currentState, Date.now());
+            const pausedAfterScopeBoundary = currentState.phase === 'coder_scope' &&
+                currentState.status === 'running' &&
+                (isExecuteFinalizationPhase(currentPhase) ||
+                    currentPhase === 'final_completion_review' ||
+                    currentPhase === 'awaiting_derived_plan_execution') &&
+                options?.shouldStopAfterCurrentScope?.();
+            if (pausedAfterScopeBoundary) {
+                await logger?.event('run.paused_after_scope', {
+                    currentScopeNumber: currentState.currentScopeNumber,
+                    phase: currentState.phase,
+                    status: currentState.status,
+                });
+                return currentState;
+            }
+        }
+        finally {
+            stopHeartbeat();
+        }
+    }
+    await logger?.event('run.complete', {
+        phase: currentState.phase,
+        status: currentState.status,
+        finalCommit: currentState.finalCommit,
+        archivedReviewPath: currentState.archivedReviewPath,
+    });
+    if (currentState.phase === 'blocked' || currentState.phase === 'done') {
+        // A terminal-failed run (e.g. unattended site-A terminal-fail lands on
+        // phase:'blocked' with status:'failed') must keep its failed retrospective
+        // rather than be overwritten as a blocked one.
+        const retrospectiveReason = currentState.status === 'failed' ? 'failed' : currentState.phase === 'blocked' ? 'blocked' : 'done';
+        await runtime.writeCheckpointRetrospective(currentState, retrospectiveReason);
+    }
+    return currentState;
+}