ai-maestro 1.0.0

package/src/orchestration/attempt-chain-runtime.mjs

@@ -0,0 +1,627 @@
+import { getEngine } from '../engines/registry.mjs';
+import { redactObject } from '../format.mjs';
+import { getTaskById, updateTaskStatus } from '../tasks.mjs';
+import { runTask, withAccountingLock } from '../task-commands.mjs';
+import { countRunsForTask } from './runtime-gate.mjs';
+import { classifyFailureEvidence, HEALTH_AFFECTING_FAILURE_CLASSES } from './failure-evidence.mjs';
+import { deriveHealthTargetId, recordHealthFailure, recordHealthSuccess } from './provider-health.mjs';
+import { listEngineRecords } from './capability-registry.mjs';
+import { loadBudget } from './budget-manager.mjs';
+import { planProviderFallback } from './provider-router.mjs';
+import {
+  appendFallbackChainEvent,
+  findLatestFallbackChainForTask,
+  replayFallbackChain
+} from './fallback-chain-trail.mjs';
+import {
+  acquireFallbackChainLock,
+  releaseFallbackChainLock
+} from './fallback-chain-lock.mjs';
+
+export const DEFAULT_FALLBACK_CHAIN_DEADLINE_MS = 600000;
+
+const SUCCESS_STATUSES = new Set(['completed', 'completed_with_warnings']);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function terminal(eventType, status, fields = {}) {
+  return {
+    status,
+    terminalEventType: eventType,
+    ...fields
+  };
+}
+
+function asSet(values) {
+  return values instanceof Set ? values : new Set((Array.isArray(values) ? values : []).map(item => String(item)));
+}
+
+function normalizeEngineIdCandidate(value) {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+  }
+  if (value && typeof value === 'object' && value.id != null) {
+    const trimmed = String(value.id).trim();
+    return trimmed ? trimmed : null;
+  }
+  return null;
+}
+
+function normalizeRunEngineId(run, fallbackEngineId = null) {
+  const explicit = normalizeEngineIdCandidate(fallbackEngineId);
+  if (explicit) return explicit;
+  const selected = normalizeEngineIdCandidate(run && run.selectedEngine);
+  if (selected) return selected;
+  const runtimeSelected = normalizeEngineIdCandidate(run && run.runtimeGate && run.runtimeGate.selectedEngine);
+  if (runtimeSelected) return runtimeSelected;
+  return null;
+}
+
+function mapGateFailureClass(run) {
+  const gate = run && run.runtimeGate ? run.runtimeGate : {};
+  if (gate.decision === 'NEEDS_HUMAN') return 'human_decision';
+  if (gate.blockCategory === 'budget') return 'unknown';
+  const preflightDecision = gate.preflightDecision || (gate.preflight && gate.preflight.decision);
+  if (preflightDecision === 'UNAVAILABLE') return 'provider_unavailable';
+  if (preflightDecision === 'NEEDS_CAPABILITY' || preflightDecision === 'NEEDS_CONTEXT') return 'model_unavailable';
+  if (preflightDecision === 'DECLINE') return 'human_decision';
+  const category = gate.fallback && gate.fallback.category;
+  if (category === 'provider_unavailable') return 'provider_unavailable';
+  if (category === 'rate_limit') return 'rate_limit';
+  if (category === 'quota') return 'quota';
+  if (category === 'auth_failure' || category === 'authentication') return 'authentication';
+  if (category === 'context_too_small' || category === 'missing_tool' || category === 'insufficient_capability') return 'model_unavailable';
+  return 'unknown';
+}
+
+function classifyRunEvidence(run, task) {
+  if (!run) {
+    return { outcome: 'failure', failureClass: 'unknown', reason: 'runTask returned no run', evidenceSummary: '' };
+  }
+  if (run.blockedByGate === true) {
+    return {
+      outcome: 'failure',
+      failureClass: mapGateFailureClass(run),
+      retryable: false,
+      affectsHealth: false,
+      evidenceSource: 'runtimeGate',
+      evidenceSummary: 'blockedByGate=true',
+      reason: 'pre-execution runtime gate decision'
+    };
+  }
+  if (SUCCESS_STATUSES.has(run.status)) {
+    return {
+      outcome: 'success',
+      failureClass: null,
+      retryable: false,
+      affectsHealth: false,
+      evidenceSource: 'status',
+      evidenceSummary: 'status=' + run.status,
+      reason: 'task completed'
+    };
+  }
+  if (run.blockedBySafety === true) {
+    return { outcome: 'failure', failureClass: 'safety_block', retryable: false, affectsHealth: false, evidenceSource: 'blockedBySafety', evidenceSummary: 'blockedBySafety=true', reason: 'safety blocked the attempt' };
+  }
+  const deliverable = run.deliverableVerification || {};
+  if ((deliverable.failures || []).length > 0 || (deliverable.missingEvidence || []).length > 0) {
+    return { outcome: 'failure', failureClass: 'deliverable_rejection', retryable: false, affectsHealth: false, evidenceSource: 'deliverableVerification', evidenceSummary: 'deliverable verification rejected the attempt', reason: 'deliverable verification failed' };
+  }
+  if (run.status === 'needs_human') {
+    return { outcome: 'failure', failureClass: 'human_decision', retryable: false, affectsHealth: false, evidenceSource: 'status', evidenceSummary: 'status=needs_human', reason: 'attempt requires human decision' };
+  }
+  return classifyFailureEvidence({
+    source: 'run',
+    taskDescription: task ? task.description : '',
+    acceptanceCriteria: task ? task.acceptance : [],
+    exitCode: run.exitCode,
+    signal: run.signal,
+    timedOut: run.timedOut,
+    stdout: run.stdout,
+    stderr: run.stderr,
+    fullStdout: run.fullStdout,
+    fullStderr: run.fullStderr,
+    retryAfterMs: run.retryAfterMs
+  });
+}
+
+function workspaceSafetyFromRun(run) {
+  return {
+    workspaceChanged: run ? run.workspaceChanged === true : true,
+    changedFiles: run && Array.isArray(run.changedFiles) ? run.changedFiles : [],
+    createdFiles: run && Array.isArray(run.createdFiles) ? run.createdFiles : [],
+    deletedFiles: run && Array.isArray(run.deletedFiles) ? run.deletedFiles : [],
+    outOfScopeChanges: run && Array.isArray(run.outOfScopeChanges) ? run.outOfScopeChanges : []
+  };
+}
+
+function workspaceIsSafe(run) {
+  const safety = workspaceSafetyFromRun(run);
+  return safety.workspaceChanged === false &&
+    safety.outOfScopeChanges.length === 0 &&
+    safety.deletedFiles.length === 0;
+}
+
+async function engineMetadata(engineId, deps) {
+  if (!engineId) return {};
+  try {
+    const records = await (deps.listEngineRecords || listEngineRecords)({ enabledOnly: false });
+    const record = records.find(item => String(item.id) === String(engineId));
+    return record ? { provider: record.provider || null, model: record.model || null, record } : {};
+  } catch (error) {
+    return {};
+  }
+}
+
+async function updateHealthAfterRun({ run, taskId, engineId, healthTargetId, failureClassification, deps }) {
+  if (!run || run.blockedByGate === true || !healthTargetId) {
+    return null;
+  }
+  const metadata = await engineMetadata(engineId, deps);
+  if (failureClassification.outcome === 'success') {
+    return (deps.recordHealthSuccess || recordHealthSuccess)({
+      healthTargetId,
+      taskId,
+      runId: run.runId,
+      orchestrationId: run.orchestrationId || null,
+      metadata
+    });
+  }
+  if (HEALTH_AFFECTING_FAILURE_CLASSES.has(failureClassification.failureClass)) {
+    return (deps.recordHealthFailure || recordHealthFailure)({
+      healthTargetId,
+      taskId,
+      runId: run.runId,
+      orchestrationId: run.orchestrationId || null,
+      failureClass: failureClassification.failureClass,
+      evidenceSource: failureClassification.evidenceSource || null,
+      evidenceSummary: failureClassification.evidenceSummary || '',
+      retryAfterMs: failureClassification.retryAfterMs,
+      metadata
+    });
+  }
+  return null;
+}
+
+async function setTaskStatus(taskId, status, deps) {
+  const update = deps.updateTaskStatus || updateTaskStatus;
+  const lock = deps.withAccountingLock || withAccountingLock;
+  return lock(() => update(taskId, status));
+}
+
+function eventBase(state, fields = {}) {
+  return {
+    taskId: Number(state.taskId),
+    orchestrationId: fields.orchestrationId || null,
+    fallbackChainId: state.fallbackChainId,
+    originatingRunId: state.originatingRunId,
+    deadline: state.deadline,
+    previousAttemptId: state.previousAttemptId,
+    attemptNumber: state.attemptNumber,
+    visitedEngineIds: [...state.visitedEngineIds],
+    visitedHealthTargets: [...state.visitedHealthTargets],
+    reasonChain: [...state.reasonChain],
+    ...fields
+  };
+}
+
+async function appendEvent(state, fields, deps) {
+  const append = deps.appendFallbackChainEvent || appendFallbackChainEvent;
+  return append(eventBase(state, fields), { projectRoot: deps.projectRoot });
+}
+
+function makeBudgetState(runsSoFar, budget) {
+  return {
+    runsSoFar,
+    maxRunsPerTask: budget.maxRunsPerTask,
+    maxAttempts: budget.maxRunsPerTask,
+    budget
+  };
+}
+
+async function planNext({ task, state, failureClassification, budgetState, deps }) {
+  const route = deps.planProviderFallback || planProviderFallback;
+  return route({
+    task,
+    failureClassification,
+    visitedEngineIds: state.visitedEngineIds,
+    visitedHealthTargets: state.visitedHealthTargets,
+    budgetState,
+    deadline: state.deadline,
+    timestamp: nowIso(),
+    allowPaid: state.budget.allowPaid === true,
+    preferFree: state.budget.preferFree !== false,
+    dependencies: deps.routerDependencies || {}
+  });
+}
+
+async function resolveEngineForAttempt(engineId, deps) {
+  if (!engineId) return undefined;
+  const resolve = deps.resolveEngine || getEngine;
+  return resolve(engineId);
+}
+
+async function executeAttempt({ taskId, task, engineId, state, options, deps }) {
+  if (state.attemptNumber > 0) {
+    await setTaskStatus(taskId, 'pending', deps);
+  }
+  const runsBefore = await (deps.countRunsForTask || countRunsForTask)(taskId);
+  const runOptions = {
+    force: options.force === true,
+    suppressOutput: true,
+    quiet: true,
+    verbose: options.verbose === true,
+    debug: options.debug === true
+  };
+  if (engineId) {
+    runOptions.engine = await resolveEngineForAttempt(engineId, deps);
+  }
+  const runResult = await (deps.runTask || runTask)(taskId, runOptions);
+  const run = runResult && runResult.run ? runResult.run : null;
+  if (!run || !run.runId) {
+    return terminal('fallback_needs_human', 'needs_human', {
+      reason: ['runTask returned no run; cannot correlate fallback attempt'],
+      runResult
+    });
+  }
+
+  if (!state.fallbackChainId) {
+    state.fallbackChainId = run.runId;
+    state.originatingRunId = run.runId;
+    state.deadline = options.deadline || new Date(Date.now() + (options.deadlineMs || DEFAULT_FALLBACK_CHAIN_DEADLINE_MS)).toISOString();
+  }
+
+  state.attemptNumber += 1;
+  const attemptNumber = state.attemptNumber;
+  const previousAttemptId = state.previousAttemptId;
+  const actualEngineId = normalizeRunEngineId(run, engineId);
+  const healthTargetId = actualEngineId ? deriveHealthTargetId({ id: actualEngineId }) : null;
+  if (actualEngineId) state.visitedEngineIds.add(actualEngineId);
+  if (healthTargetId) state.visitedHealthTargets.add(healthTargetId);
+
+  if (attemptNumber === 1) {
+    await appendEvent(state, {
+      eventType: 'fallback_chain_started',
+      runId: run.runId,
+      attemptId: run.runId,
+      attemptNumber,
+      previousAttemptId,
+      engineId: actualEngineId,
+      healthTargetId,
+      decision: 'started',
+      reason: ['fallback chain started from returned run'],
+      budgetBefore: { runsSoFar: runsBefore },
+      workspaceSafety: workspaceSafetyFromRun(run)
+    }, deps);
+  }
+  await appendEvent(state, {
+    eventType: 'fallback_attempt_started',
+    runId: run.runId,
+    attemptId: run.runId,
+    attemptNumber,
+    previousAttemptId,
+    engineId: actualEngineId,
+    healthTargetId,
+    decision: 'attempt_started',
+    reason: ['attempt correlated by returned run.runId'],
+    budgetBefore: { runsSoFar: runsBefore },
+    workspaceSafety: workspaceSafetyFromRun(run)
+  }, deps);
+
+  const failureClassification = classifyRunEvidence(run, task);
+  await updateHealthAfterRun({ run, taskId, engineId: actualEngineId, healthTargetId, failureClassification, deps });
+  const runsAfter = await (deps.countRunsForTask || countRunsForTask)(taskId);
+  state.previousAttemptId = run.runId;
+  state.reasonChain.push(failureClassification.reason || failureClassification.failureClass || 'attempt classified');
+
+  await appendEvent(state, {
+    eventType: 'fallback_attempt_finished',
+    runId: run.runId,
+    attemptId: run.runId,
+    attemptNumber,
+    previousAttemptId,
+    engineId: actualEngineId,
+    healthTargetId,
+    failureClass: failureClassification.failureClass,
+    decision: failureClassification.outcome === 'success' ? 'success' : 'failed',
+    reason: [failureClassification.reason || 'attempt finished'],
+    budgetBefore: { runsSoFar: runsBefore },
+    budgetAfter: { runsSoFar: runsAfter },
+    workspaceSafety: workspaceSafetyFromRun(run)
+  }, deps);
+
+  return {
+    run,
+    runResult,
+    actualEngineId,
+    healthTargetId,
+    failureClassification,
+    runsBefore,
+    runsAfter,
+    attemptNumber
+  };
+}
+
+async function finishChain(state, eventType, status, fields, deps) {
+  await appendEvent(state, {
+    eventType,
+    runId: fields.runId || state.previousAttemptId,
+    attemptId: fields.runId || state.previousAttemptId,
+    engineId: fields.engineId || null,
+    healthTargetId: fields.healthTargetId || null,
+    failureClass: fields.failureClass || null,
+    decision: fields.decision || eventType,
+    reason: fields.reason || [],
+    selectedCandidate: fields.selectedCandidate || null,
+    rejectedCandidates: fields.rejectedCandidates || [],
+    budgetBefore: fields.budgetBefore || null,
+    budgetAfter: fields.budgetAfter || null,
+    workspaceSafety: fields.workspaceSafety || { workspaceChanged: null },
+    terminalOutcome: eventType
+  }, deps);
+  if (status === 'needs_human' || status === 'blocked') {
+    await setTaskStatus(state.taskId, status, deps);
+  }
+  return terminal(eventType, status, {
+    fallbackChainId: state.fallbackChainId,
+    originatingRunId: state.originatingRunId,
+    attemptNumber: state.attemptNumber,
+    previousAttemptId: state.previousAttemptId,
+    visitedEngineIds: [...state.visitedEngineIds],
+    visitedHealthTargets: [...state.visitedHealthTargets],
+    reason: fields.reason || [],
+    selectedCandidate: fields.selectedCandidate || null,
+    rejectedCandidates: fields.rejectedCandidates || []
+  });
+}
+
+async function continueFromAttempt({ task, state, attempt, deps }) {
+  if (attempt.failureClassification.outcome === 'success') {
+    return finishChain(state, 'fallback_chain_completed', 'completed', {
+      runId: attempt.run.runId,
+      engineId: attempt.actualEngineId,
+      healthTargetId: attempt.healthTargetId,
+      decision: 'success',
+      reason: ['attempt succeeded'],
+      budgetAfter: { runsSoFar: attempt.runsAfter },
+      workspaceSafety: workspaceSafetyFromRun(attempt.run)
+    }, deps);
+  }
+
+  if (attempt.run.blockedByGate === true && attempt.run.runtimeGate && attempt.run.runtimeGate.decision !== 'FALLBACK') {
+    const budgetBlocked = attempt.run.runtimeGate.blockCategory === 'budget';
+    return finishChain(state, budgetBlocked ? 'fallback_blocked_by_budget' : 'fallback_needs_human', budgetBlocked ? 'blocked' : 'needs_human', {
+      runId: attempt.run.runId,
+      engineId: attempt.actualEngineId,
+      healthTargetId: attempt.healthTargetId,
+      failureClass: attempt.failureClassification.failureClass,
+      decision: budgetBlocked ? 'budget_blocked' : 'needs_human',
+      reason: attempt.run.runtimeGate.reason || ['runtime gate did not authorize fallback'],
+      budgetAfter: { runsSoFar: attempt.runsAfter },
+      workspaceSafety: workspaceSafetyFromRun(attempt.run)
+    }, deps);
+  }
+
+  if (!workspaceIsSafe(attempt.run)) {
+    return finishChain(state, 'fallback_blocked_by_workspace', 'needs_human', {
+      runId: attempt.run.runId,
+      engineId: attempt.actualEngineId,
+      healthTargetId: attempt.healthTargetId,
+      failureClass: attempt.failureClassification.failureClass,
+      decision: 'workspace_unsafe',
+      reason: ['workspace changed or could not be proven safe after failed attempt'],
+      budgetAfter: { runsSoFar: attempt.runsAfter },
+      workspaceSafety: workspaceSafetyFromRun(attempt.run)
+    }, deps);
+  }
+
+  const budgetState = makeBudgetState(attempt.runsAfter, state.budget);
+  const plan = await planNext({ task, state, failureClassification: attempt.failureClassification, budgetState, deps });
+  for (const rejected of plan.rejectedCandidates || []) {
+    await appendEvent(state, {
+      eventType: 'fallback_candidate_rejected',
+      runId: attempt.run.runId,
+      attemptId: attempt.run.runId,
+      engineId: rejected.engineId || null,
+      healthTargetId: rejected.healthTargetId || null,
+      failureClass: attempt.failureClassification.failureClass,
+      decision: 'rejected',
+      reason: [rejected.reason || 'candidate rejected'],
+      rejectedCandidates: [rejected],
+      budgetAfter: { runsSoFar: attempt.runsAfter },
+      workspaceSafety: workspaceSafetyFromRun(attempt.run)
+    }, deps);
+  }
+  if (plan.action !== 'switch_engine' || !plan.candidateEngineId) {
+    const eventType = plan.terminalReason === 'fallback_blocked_by_budget'
+      ? 'fallback_blocked_by_budget'
+      : plan.terminalReason === 'fallback_exhausted'
+        ? 'fallback_chain_exhausted'
+        : 'fallback_needs_human';
+    return finishChain(state, eventType, eventType === 'fallback_needs_human' ? 'needs_human' : 'blocked', {
+      runId: attempt.run.runId,
+      engineId: attempt.actualEngineId,
+      healthTargetId: attempt.healthTargetId,
+      failureClass: attempt.failureClassification.failureClass,
+      decision: plan.action,
+      reason: plan.reason,
+      rejectedCandidates: plan.rejectedCandidates || [],
+      budgetAfter: { runsSoFar: attempt.runsAfter },
+      workspaceSafety: workspaceSafetyFromRun(attempt.run)
+    }, deps);
+  }
+
+  const selectedCandidate = {
+    engineId: plan.candidateEngineId,
+    healthTargetId: plan.candidateEngineId,
+    reason: plan.reason
+  };
+  await appendEvent(state, {
+    eventType: 'fallback_candidate_selected',
+    runId: attempt.run.runId,
+    attemptId: attempt.run.runId,
+    engineId: plan.candidateEngineId,
+    healthTargetId: plan.candidateEngineId,
+    failureClass: attempt.failureClassification.failureClass,
+    decision: 'switch_engine',
+    reason: plan.reason,
+    selectedCandidate,
+    rejectedCandidates: plan.rejectedCandidates || [],
+    budgetAfter: { runsSoFar: attempt.runsAfter },
+    workspaceSafety: workspaceSafetyFromRun(attempt.run)
+  }, deps);
+  return { status: 'continue', nextEngineId: plan.candidateEngineId };
+}
+
+function createNewState(taskId, budget) {
+  return {
+    taskId: Number(taskId),
+    fallbackChainId: null,
+    originatingRunId: null,
+    attemptNumber: 0,
+    previousAttemptId: null,
+    deadline: null,
+    visitedEngineIds: new Set(),
+    visitedHealthTargets: new Set(),
+    reasonChain: [],
+    budget
+  };
+}
+
+function stateFromReplay(taskId, replayed, budget) {
+  return {
+    taskId: Number(taskId),
+    fallbackChainId: replayed.fallbackChainId,
+    originatingRunId: replayed.originatingRunId || replayed.fallbackChainId,
+    attemptNumber: replayed.attemptNumber,
+    previousAttemptId: replayed.previousAttemptId,
+    deadline: replayed.deadline,
+    visitedEngineIds: asSet(replayed.visitedEngineIds),
+    visitedHealthTargets: asSet(replayed.visitedHealthTargets),
+    reasonChain: replayed.reasonChain || [],
+    budget
+  };
+}
+
+export async function dryRunFailoverPlan(taskId, options = {}) {
+  const deps = options.dependencies || {};
+  const task = await (deps.getTaskById || getTaskById)(taskId);
+  if (!task) {
+    return { dryRun: true, status: 'blocked', reason: ['task not found'], taskId: Number(taskId) };
+  }
+  const budget = await (deps.loadBudget || loadBudget)();
+  const runsSoFar = await (deps.countRunsForTask || countRunsForTask)(taskId);
+  const currentEngineId = options.currentEngineId || task.engine || null;
+  const visitedEngineIds = currentEngineId ? [currentEngineId] : [];
+  const failureClassification = {
+    outcome: 'failure',
+    failureClass: options.simulateFailure || 'network',
+    reason: 'dry-run simulated failure'
+  };
+  const plan = await (deps.planProviderFallback || planProviderFallback)({
+    task,
+    failureClassification,
+    visitedEngineIds,
+    visitedHealthTargets: visitedEngineIds,
+    budgetState: makeBudgetState(runsSoFar, budget),
+    deadline: options.deadline || new Date(Date.now() + (options.deadlineMs || DEFAULT_FALLBACK_CHAIN_DEADLINE_MS)).toISOString(),
+    dependencies: deps.routerDependencies || {}
+  });
+  return redactObject({
+    dryRun: true,
+    taskId: Number(taskId),
+    runTaskCalled: false,
+    chainLockAcquired: false,
+    failureClassification,
+    plan
+  });
+}
+
+export async function runTaskWithFailover(taskId, options = {}) {
+  if (options.dryRun === true) {
+    return dryRunFailoverPlan(taskId, options);
+  }
+  const deps = options.dependencies || {};
+  const acquire = deps.acquireFallbackChainLock || acquireFallbackChainLock;
+  const release = deps.releaseFallbackChainLock || releaseFallbackChainLock;
+  const lock = await acquire({ command: 'run-task ' + taskId + ' --failover', taskId, projectRoot: deps.projectRoot });
+  if (!lock.acquired) {
+    return {
+      status: 'blocked',
+      terminalEventType: 'fallback_chain_lock_unavailable',
+      lockOutcome: lock.outcome,
+      activeLock: lock.activeLock || null,
+      reason: ['another fallback chain is already in progress']
+    };
+  }
+
+  try {
+    const task = await (deps.getTaskById || getTaskById)(taskId);
+    if (!task) {
+      return { status: 'blocked', terminalEventType: 'fallback_needs_human', reason: ['task not found'], lockOutcome: lock.outcome };
+    }
+    const latestChain = await (deps.findLatestFallbackChainForTask || findLatestFallbackChainForTask)(taskId, { projectRoot: deps.projectRoot });
+    if (latestChain && !latestChain.terminal && options.resume !== true) {
+      return {
+        status: 'blocked',
+        terminalEventType: 'fallback_active_chain_exists',
+        fallbackChainId: latestChain.fallbackChainId,
+        reason: ['incomplete fallback chain exists; rerun with --resume']
+      };
+    }
+    if (options.resume === true) {
+      if (!latestChain) {
+        return { status: 'blocked', terminalEventType: 'fallback_resume_missing', reason: ['no fallback chain exists to resume'] };
+      }
+      if (latestChain.terminal) {
+        return { status: 'blocked', terminalEventType: 'fallback_resume_terminal', fallbackChainId: latestChain.fallbackChainId, reason: ['terminal fallback chain cannot be resumed'] };
+      }
+      const budget = await (deps.loadBudget || loadBudget)();
+      const replayedState = stateFromReplay(taskId, latestChain, budget);
+      if (latestChain.inProgressAttempt) {
+        return finishChain(replayedState, 'fallback_needs_human', 'needs_human', {
+          runId: latestChain.inProgressAttempt.runId,
+          engineId: latestChain.inProgressAttempt.engineId,
+          healthTargetId: latestChain.inProgressAttempt.healthTargetId,
+          decision: 'resume_blocked',
+          reason: ['resume found an attempt that was in progress; human reconciliation required']
+        }, deps);
+      }
+      const selected = latestChain.selectedCandidate && latestChain.selectedCandidate.engineId;
+      if (selected) {
+        let nextEngine = selected;
+        while (nextEngine) {
+          const attempt = await executeAttempt({ taskId, task, engineId: nextEngine, state: replayedState, options, deps });
+          if (attempt.terminalEventType) return attempt;
+          const next = await continueFromAttempt({ task, state: replayedState, attempt, deps });
+          if (next.status !== 'continue') return next;
+          nextEngine = next.nextEngineId;
+        }
+      }
+      return finishChain(replayedState, 'fallback_needs_human', 'needs_human', {
+        decision: 'resume_blocked',
+        reason: ['resume could not identify a safe next candidate from the trail']
+      }, deps);
+    }
+
+    const budget = await (deps.loadBudget || loadBudget)();
+    const state = createNewState(taskId, budget);
+    let nextEngineId = null;
+    while (true) {
+      const attempt = await executeAttempt({ taskId, task, engineId: nextEngineId, state, options, deps });
+      if (attempt.terminalEventType) return attempt;
+      const next = await continueFromAttempt({ task, state, attempt, deps });
+      if (next.status !== 'continue') return next;
+      nextEngineId = next.nextEngineId;
+    }
+  } finally {
+    await release(lock.lockHandle);
+  }
+}
+
+export function replayFallbackState(events = [], budget = {}) {
+  return stateFromReplay((events[0] && events[0].taskId) || 0, replayFallbackChain(events), budget);
+}