@navels/neal 0.1.0

package/dist/neal/resume-decision.js

@@ -0,0 +1,220 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { planResumeActions } from './resume-planner.js';
+import { getInteractiveRecoveryView } from './state-views.js';
+export function decideResumeAction(args) {
+    const resumeCommand = formatResumeCommand(args.selectedRunId);
+    const messageCommand = formatMessageCommand(args.selectedRunId);
+    const statusCommand = formatStatusCommand(args.selectedRunId);
+    const lockDecision = decideLockAction(args.lock, args.selectedRunId, statusCommand);
+    if (lockDecision) {
+        return lockDecision;
+    }
+    const queueDecision = decideQueueAction(args.queue, statusCommand);
+    if (queueDecision) {
+        // A consumed queue child whose run itself completed is the ordinary
+        // "nothing left to resume" case, not a queue inconsistency: the queue
+        // recorded the outcome and moved on. Report it as done instead of
+        // surfacing queue-internal bookkeeping as a resume error.
+        if (args.queue?.kind === 'consumed_child' && isOrdinaryDone(planResumeActions(args.state))) {
+            return {
+                kind: 'done',
+                summary: args.retrospectivePath
+                    ? `Run ${args.selectedRunId} is already complete. Latest retrospective: ${args.retrospectivePath}.`
+                    : `Run ${args.selectedRunId} is already complete.`,
+                statusCommand,
+                retrospectivePath: args.retrospectivePath ?? null,
+            };
+        }
+        return queueDecision;
+    }
+    const interactiveRecovery = getInteractiveRecoveryView(args.state);
+    if (interactiveRecovery?.active) {
+        if (interactiveRecovery.waitingForOperatorGuidance) {
+            return {
+                kind: 'needs_message',
+                blocker: interactiveRecovery.blockedReason,
+                messageCommand,
+                statusCommand,
+            };
+        }
+        if (interactiveRecovery.pendingOperatorGuidance) {
+            return {
+                kind: 'pending_message',
+                reason: 'Operator guidance is recorded and ready for Neal to process.',
+                resumeCommand,
+            };
+        }
+    }
+    if (isWaitingForPlanReviewGuidance(args.state)) {
+        return {
+            kind: 'needs_message',
+            blocker: formatPlanReviewGuidanceBlocker(args.state),
+            messageCommand,
+            statusCommand,
+        };
+    }
+    if (hasPendingPlanReviewGuidance(args.state)) {
+        return {
+            kind: 'pending_message',
+            reason: 'Operator guidance is recorded and ready for Neal to process.',
+            resumeCommand,
+        };
+    }
+    const actions = planResumeActions(args.state);
+    if (onlyKeepsBlocked(actions)) {
+        return {
+            kind: 'cannot_resume',
+            reason: formatKeptBlockedReason(args.state),
+            statusCommand,
+        };
+    }
+    if (isOrdinaryDone(actions)) {
+        return {
+            kind: 'done',
+            summary: args.retrospectivePath
+                ? `Run ${args.selectedRunId} is already complete. Latest retrospective: ${args.retrospectivePath}.`
+                : `Run ${args.selectedRunId} is already complete.`,
+            statusCommand,
+            retrospectivePath: args.retrospectivePath ?? null,
+        };
+    }
+    return {
+        kind: 'continue',
+        reason: formatContinueReason(actions),
+        resumeCommand,
+    };
+}
+function isWaitingForPlanReviewGuidance(state) {
+    return (state.topLevelMode === 'plan' &&
+        state.status === 'blocked' &&
+        state.phase === 'blocked' &&
+        state.blockedFromPhase === 'reviewer_plan' &&
+        state.pendingPlanReviewGuidance === null);
+}
+function hasPendingPlanReviewGuidance(state) {
+    return state.topLevelMode === 'plan' && state.pendingPlanReviewGuidance !== null;
+}
+function formatPlanReviewGuidanceBlocker(state) {
+    const blockedFrom = state.blockedFromPhase ? ` from ${state.blockedFromPhase}` : '';
+    return `Run is blocked${blockedFrom} and is waiting for operator guidance via neal resume --message.`;
+}
+function decideLockAction(lock, selectedRunId, selectedStatusCommand) {
+    switch (lock?.kind) {
+        case undefined:
+        case 'none':
+        case 'stale_same_run':
+        case 'stale_different_run':
+            return null;
+        case 'live_same_run':
+            return {
+                kind: 'already_running',
+                reason: `Run ${selectedRunId} appears to already be running under the active writer lock.`,
+                statusCommand: selectedStatusCommand,
+            };
+        case 'live_different_run':
+            return {
+                kind: 'cannot_resume',
+                reason: `Another Neal writer run is active in this checkout: ${lock.runId}. Continue it with ${formatResumeCommand(lock.runId)} or inspect it with ${formatStatusCommand(lock.runId)}.`,
+                statusCommand: formatStatusCommand(lock.runId),
+            };
+        case 'cross_host':
+            return {
+                kind: 'cannot_resume',
+                reason: `The active writer lock belongs to host ${lock.hostname ?? 'unknown'} for run ${lock.runId}. Inspect that host before resuming a writer run here.`,
+                statusCommand: selectedStatusCommand,
+            };
+        case 'unreadable':
+            return {
+                kind: 'cannot_resume',
+                reason: `The active writer lock could not be read: ${lock.reason}. Inspect the lock before resuming a writer run.`,
+                statusCommand: selectedStatusCommand,
+            };
+    }
+}
+function decideQueueAction(queue, statusCommand) {
+    switch (queue?.kind) {
+        case undefined:
+        case 'not_linked':
+        case 'active_child':
+            return null;
+        case 'consumed_child':
+        case 'stale_child':
+        case 'mismatched_child':
+        case 'mismatched_stage':
+        case 'unreadable':
+            return {
+                kind: 'cannot_resume',
+                reason: queue.reason,
+                statusCommand,
+            };
+    }
+}
+function onlyKeepsBlocked(actions) {
+    const controlActions = actions.filter((action) => action.kind !== 'flush_derived_plan_notifications' &&
+        action.kind !== 'log_interactive_blocked_recovery');
+    return controlActions.length > 0 && controlActions.every((action) => action.kind === 'keep_blocked');
+}
+function isOrdinaryDone(actions) {
+    return actions.length === 1 && actions[0]?.kind === 'done_noop';
+}
+function formatKeptBlockedReason(state) {
+    const blockedFrom = state.blockedFromPhase ? ` from ${state.blockedFromPhase}` : '';
+    const diagnostics = formatTerminalBlockDiagnostics(state);
+    return diagnostics
+        ? `Run is blocked${blockedFrom} and cannot be mechanically resumed. ${diagnostics} Inspect status and artifacts before adding guidance.`
+        : `Run is blocked${blockedFrom} and cannot be mechanically resumed. Inspect status and artifacts before adding guidance.`;
+}
+function formatContinueReason(actions) {
+    const actionKinds = actions.map((action) => action.kind).filter((kind) => kind !== 'log_interactive_blocked_recovery');
+    if (actionKinds.length === 0) {
+        return 'Run is in a resumable state.';
+    }
+    return `Resume planner selected ${actionKinds.join(', ')}.`;
+}
+function formatResumeCommand(runId) {
+    return `neal resume --run ${runId}`;
+}
+function formatMessageCommand(runId) {
+    return `neal resume --run ${runId} --message "..."`;
+}
+function formatStatusCommand(runId) {
+    return `neal status --run ${runId}`;
+}
+function formatTerminalBlockDiagnostics(state) {
+    const invalidPayloadPath = findCurrentInvalidSplitPlanPayloadArtifactPath(state);
+    const parts = [
+        latestRecoveryBlocker(state) ?? currentOrLatestBlockedCompletedScopeBlocker(state),
+        invalidPayloadPath ? `Invalid payload artifact: ${invalidPayloadPath}` : null,
+    ].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join(' ') : null;
+}
+function latestRecoveryBlocker(state) {
+    const active = state.interactiveBlockedRecovery;
+    if (active) {
+        const candidate = nonEmptyString(active.pendingDirective?.operatorGuidance) ?? nonEmptyString(active.blockedReason);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    for (const record of [...state.interactiveBlockedRecoveryHistory].reverse()) {
+        const candidate = nonEmptyString(record.blockedReason);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function nonEmptyString(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}
+function currentOrLatestBlockedCompletedScopeBlocker(state) {
+    const blockedScopes = state.completedScopes.filter((scope) => scope.result === 'blocked' && scope.blocker);
+    const currentScope = blockedScopes.find((scope) => scope.number === String(state.currentScopeNumber));
+    return currentScope?.blocker ?? blockedScopes.at(-1)?.blocker ?? null;
+}
+function findCurrentInvalidSplitPlanPayloadArtifactPath(state) {
+    const artifactPath = join(state.runDir, `SCOPE_${state.currentScopeNumber}_INVALID_DERIVED_PLAN.md`);
+    return existsSync(artifactPath) ? artifactPath : null;
+}

package/dist/neal/resume-planner.js

@@ -0,0 +1,265 @@
+import { flushDerivedPlanNotifications } from './orchestrator/notifications.js';
+import { recoverPendingReviewFromCleanCommittedScope } from './orchestrator/phases/coder.js';
+import { isResumableBlockedPhase } from './orchestrator/phases/recovery.js';
+import { persistBlockedScope } from './orchestrator/phases/shared.js';
+import { classifyUnexecutedDerivedPlanResumeState, getDerivedPlanView, getInteractiveRecoveryView, needsDerivedPlanNotificationFlush, } from './state-views.js';
+import { saveState } from './state.js';
+function getResumableBlockedSessionRole(phase) {
+    return phase === 'coder_plan' || phase === 'coder_plan_response' || phase === 'coder_plan_optional_response'
+        ? 'planner'
+        : 'coder';
+}
+export function planResumeActions(state) {
+    const actions = [];
+    let plannedState = state;
+    const statusAction = planStatusResumeAction(plannedState);
+    if (statusAction) {
+        actions.push(statusAction);
+        plannedState = applyPlannedStatusAction(plannedState, statusAction);
+    }
+    const derivedPlanResumeDisposition = classifyUnexecutedDerivedPlanResumeState(plannedState);
+    const derivedPlanAction = toDerivedPlanResumeAction(derivedPlanResumeDisposition);
+    if (derivedPlanAction) {
+        actions.push(derivedPlanAction);
+        plannedState = applyPlannedDerivedPlanAction(plannedState, derivedPlanAction);
+    }
+    if (needsDerivedPlanNotificationFlush(plannedState)) {
+        actions.push({ kind: 'flush_derived_plan_notifications' });
+    }
+    if (mayRecoverPendingReviewFromCleanCommittedScope(plannedState)) {
+        actions.push({ kind: 'recover_pending_review_from_clean_committed_scope' });
+    }
+    const interactiveRecovery = getInteractiveRecoveryView(plannedState);
+    if (interactiveRecovery?.active) {
+        if (interactiveRecovery.pendingOperatorGuidance) {
+            actions.push({
+                kind: 'process_pending_operator_guidance',
+                pendingTurnCount: interactiveRecovery.pendingTurnCount,
+            });
+        }
+        else if (interactiveRecovery.waitingForOperatorGuidance) {
+            actions.push({
+                kind: 'wait_for_operator_guidance',
+                sourcePhase: interactiveRecovery.sourcePhase,
+            });
+        }
+        actions.push({
+            kind: 'log_interactive_blocked_recovery',
+            sourcePhase: interactiveRecovery.sourcePhase,
+            blockedReason: interactiveRecovery.blockedReason,
+            recordedTurns: interactiveRecovery.turns.length,
+            lastHandledTurn: interactiveRecovery.handledTurn,
+        });
+    }
+    if (actions.length === 0 && plannedState.status === 'done') {
+        actions.push({ kind: 'done_noop' });
+    }
+    return actions;
+}
+export async function applyResumeActions(state, statePath, logger, actions) {
+    let nextState = state;
+    for (const action of actions) {
+        switch (action.kind) {
+            case 'restore_resumable_blocked_phase':
+                nextState = await restoreResumableBlockedPhase(nextState, statePath, logger, action);
+                break;
+            case 'normalize_stopped_status':
+                nextState = await normalizeStoppedStatus(nextState, statePath, logger, action);
+                break;
+            case 'promote_accepted_derived_plan':
+            case 'promote_pending_derived_plan_review':
+                nextState = await promoteUnexecutedDerivedPlan(nextState, statePath, logger, action);
+                break;
+            case 'block_rejected_abandoned_derived_plan':
+                nextState = await blockRejectedUnexecutedDerivedPlan(nextState, statePath, logger, action);
+                break;
+            case 'flush_derived_plan_notifications':
+                nextState = await flushDerivedPlanNotifications(nextState, statePath, logger);
+                break;
+            case 'recover_pending_review_from_clean_committed_scope':
+                nextState =
+                    (await recoverPendingReviewFromCleanCommittedScope(nextState, statePath, logger, 'run.recovered_pending_review_on_resume')) ?? nextState;
+                break;
+            case 'log_interactive_blocked_recovery':
+                await logger?.event('run.resumed_interactive_blocked_recovery', {
+                    statePath,
+                    sourcePhase: action.sourcePhase,
+                    blockedReason: action.blockedReason,
+                    recordedTurns: action.recordedTurns,
+                    lastHandledTurn: action.lastHandledTurn,
+                });
+                break;
+            case 'keep_blocked':
+            case 'wait_for_operator_guidance':
+            case 'process_pending_operator_guidance':
+            case 'done_noop':
+                break;
+        }
+    }
+    return nextState;
+}
+function planStatusResumeAction(state) {
+    if (state.status === 'blocked' && isResumableBlockedPhase(state.blockedFromPhase)) {
+        const sessionRole = getResumableBlockedSessionRole(state.blockedFromPhase);
+        const sessionHandle = sessionRole === 'planner' ? state.plannerSessionHandle : state.coderSessionHandle;
+        if (sessionHandle) {
+            return {
+                kind: 'restore_resumable_blocked_phase',
+                phase: state.blockedFromPhase,
+                sessionRole,
+                sessionHandle,
+            };
+        }
+    }
+    if (state.status === 'blocked' && state.phase === 'blocked') {
+        return {
+            kind: 'keep_blocked',
+            blockedFromPhase: state.blockedFromPhase,
+        };
+    }
+    if (state.status !== 'done' && state.status !== 'running' && state.phase !== 'blocked') {
+        return {
+            kind: 'normalize_stopped_status',
+            previousStatus: state.status,
+        };
+    }
+    return null;
+}
+function applyPlannedStatusAction(state, action) {
+    switch (action.kind) {
+        case 'restore_resumable_blocked_phase':
+            return {
+                ...state,
+                phase: action.phase,
+                status: 'running',
+            };
+        case 'normalize_stopped_status':
+            return {
+                ...state,
+                status: 'running',
+            };
+        default:
+            return state;
+    }
+}
+function toDerivedPlanResumeAction(disposition) {
+    switch (disposition.kind) {
+        case 'accepted':
+            return {
+                kind: 'promote_accepted_derived_plan',
+                phase: disposition.phase,
+            };
+        case 'pending_review':
+            return {
+                kind: 'promote_pending_derived_plan_review',
+                phase: disposition.phase,
+            };
+        case 'rejected':
+            return {
+                kind: 'block_rejected_abandoned_derived_plan',
+                blockedFromPhase: disposition.blockedFromPhase,
+                blocker: disposition.blocker,
+            };
+        case 'none':
+            return null;
+    }
+}
+function applyPlannedDerivedPlanAction(state, action) {
+    switch (action.kind) {
+        case 'promote_accepted_derived_plan':
+        case 'promote_pending_derived_plan_review':
+            return {
+                ...state,
+                phase: action.phase,
+                status: 'running',
+                blockedFromPhase: null,
+            };
+        case 'block_rejected_abandoned_derived_plan':
+            return {
+                ...state,
+                phase: 'blocked',
+                status: 'blocked',
+                blockedFromPhase: action.blockedFromPhase,
+            };
+        default:
+            return state;
+    }
+}
+function mayRecoverPendingReviewFromCleanCommittedScope(state) {
+    return (state.topLevelMode === 'execute' &&
+        state.phase === 'coder_scope' &&
+        Boolean(state.baseCommit) &&
+        state.finalCommit === null &&
+        state.createdCommits.length === 0);
+}
+async function restoreResumableBlockedPhase(state, statePath, logger, action) {
+    const nextState = await saveState(statePath, {
+        ...state,
+        phase: action.phase,
+        status: 'running',
+    });
+    await logger?.event('run.resumed_from_blocked', {
+        statePath,
+        blockedFromPhase: nextState.blockedFromPhase,
+        sessionRole: action.sessionRole,
+        sessionHandle: action.sessionHandle,
+    });
+    return nextState;
+}
+async function normalizeStoppedStatus(state, statePath, logger, action) {
+    const nextState = await saveState(statePath, {
+        ...state,
+        status: 'running',
+    });
+    await logger?.event('run.status_normalized_on_resume', {
+        statePath,
+        phase: nextState.phase,
+        previousStatus: action.previousStatus,
+        normalizedStatus: nextState.status,
+    });
+    return nextState;
+}
+async function promoteUnexecutedDerivedPlan(state, statePath, logger, action) {
+    const previousPhase = state.phase;
+    const previousStatus = state.status;
+    const derivedPlan = getDerivedPlanView(state);
+    const nextState = await saveState(statePath, {
+        ...state,
+        phase: action.phase,
+        status: 'running',
+        blockedFromPhase: null,
+    });
+    await logger?.event(action.kind === 'promote_accepted_derived_plan'
+        ? 'run.promoted_accepted_derived_plan_on_resume'
+        : 'run.promoted_pending_derived_plan_on_resume', {
+        statePath,
+        previousPhase,
+        previousStatus,
+        promotedPhase: nextState.phase,
+        derivedPlanPath: derivedPlan?.path ?? null,
+        derivedFromScopeNumber: derivedPlan?.parentScopeNumber ?? null,
+    });
+    return nextState;
+}
+async function blockRejectedUnexecutedDerivedPlan(state, statePath, logger, action) {
+    const previousPhase = state.phase;
+    const previousStatus = state.status;
+    const derivedPlan = getDerivedPlanView(state);
+    let nextState = await saveState(statePath, {
+        ...state,
+        phase: 'blocked',
+        status: 'blocked',
+        blockedFromPhase: action.blockedFromPhase,
+    });
+    nextState = await persistBlockedScope(nextState, statePath, action.blocker);
+    await logger?.event('run.blocked_rejected_derived_plan_on_resume', {
+        statePath,
+        previousPhase,
+        previousStatus,
+        blockedFromPhase: nextState.blockedFromPhase,
+        blocker: action.blocker,
+        derivedPlanPath: derivedPlan?.path ?? null,
+        derivedFromScopeNumber: derivedPlan?.parentScopeNumber ?? null,
+    });
+    return nextState;
+}