ai-maestro 1.0.0

package/src/orchestration/fallback-chain-lock.mjs

@@ -0,0 +1,217 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+import { CONFIG } from '../config.mjs';
+import { redactObject } from '../format.mjs';
+
+export const FALLBACK_CHAIN_LOCK_FILE = path.join('locks', 'fallback-chain-global.lock.json');
+
+let activeLockHandle = null;
+
+function lockPath(projectRoot = process.cwd()) {
+  return path.join(projectRoot, CONFIG.maestroPath, FALLBACK_CHAIN_LOCK_FILE);
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+async function readLock(filePath) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, 'utf-8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    if (error instanceof SyntaxError) {
+      return { corrupted: true, error: error.message };
+    }
+    throw error;
+  }
+}
+
+function makeLock({ command = 'run-task --failover', taskId = null } = {}) {
+  return redactObject({
+    schemaVersion: 1,
+    lockType: 'fallback-chain-global',
+    pid: process.pid,
+    command,
+    taskId: taskId == null ? null : String(taskId),
+    acquiredAt: new Date().toISOString(),
+    lockId: process.pid + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10)
+  });
+}
+
+async function createExclusive(filePath, lock) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const handle = await fs.open(filePath, 'wx');
+  try {
+    await handle.writeFile(JSON.stringify(lock, null, 2) + '\n', { encoding: 'utf8' });
+  } finally {
+    await handle.close();
+  }
+  return lock;
+}
+
+async function createRecoveryClaim(filePath) {
+  const claimPath = filePath + '.recovery';
+  const claim = redactObject({
+    schemaVersion: 1,
+    lockType: 'fallback-chain-global-recovery',
+    pid: process.pid,
+    acquiredAt: new Date().toISOString(),
+    claimId: process.pid + '-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10)
+  });
+  const handle = await fs.open(claimPath, 'wx');
+  try {
+    await handle.writeFile(JSON.stringify(claim, null, 2) + '\n', { encoding: 'utf8' });
+  } finally {
+    await handle.close();
+  }
+  return { claimPath, claim };
+}
+
+async function releaseRecoveryClaim(claimHandle) {
+  if (!claimHandle) return;
+  try {
+    await fs.unlink(claimHandle.claimPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+export async function acquireFallbackChainLock(options = {}) {
+  if (activeLockHandle) {
+    return {
+      acquired: false,
+      outcome: 'recursive_acquisition_blocked',
+      activeLock: activeLockHandle.lock
+    };
+  }
+  const filePath = options.filePath || lockPath(options.projectRoot);
+  const lock = makeLock(options);
+  try {
+    const created = await createExclusive(filePath, lock);
+    activeLockHandle = { filePath, lock: created };
+    return { acquired: true, outcome: 'acquired', lockHandle: activeLockHandle };
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+
+  const existing = await readLock(filePath);
+  if (!existing || existing.corrupted) {
+    return {
+      acquired: false,
+      outcome: existing && existing.corrupted ? 'lock_corrupted' : 'held_by_unknown',
+      activeLock: existing
+    };
+  }
+  if (isPidAlive(existing.pid)) {
+    return { acquired: false, outcome: 'held_by_active', activeLock: existing };
+  }
+
+  let claimHandle = null;
+  try {
+    claimHandle = await createRecoveryClaim(filePath);
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      return { acquired: false, outcome: 'recovery_in_progress', activeLock: existing };
+    }
+    throw error;
+  }
+
+  try {
+    const current = await readLock(filePath);
+    if (!current || current.corrupted) {
+      return {
+        acquired: false,
+        outcome: current && current.corrupted ? 'lock_corrupted' : 'held_by_unknown',
+        activeLock: current
+      };
+    }
+    if (isPidAlive(current.pid)) {
+      return { acquired: false, outcome: 'held_by_active', activeLock: current };
+    }
+    await fs.unlink(filePath);
+    if (typeof options.afterOrphanLockUnlinked === 'function') {
+      await options.afterOrphanLockUnlinked({ filePath, previousLock: current, lock });
+    }
+    let recovered;
+    try {
+      recovered = await createExclusive(filePath, lock);
+    } catch (error) {
+      if (error.code === 'EEXIST') {
+        const activeLock = await readLock(filePath);
+        return {
+          acquired: false,
+          outcome: 'lost_recovery_race',
+          recoveredFromPid: current.pid || null,
+          activeLock: activeLock || current
+        };
+      }
+      throw error;
+    }
+    activeLockHandle = { filePath, lock: recovered, recoveredFromPid: current.pid || null };
+    return {
+      acquired: true,
+      outcome: 'recovered_and_acquired',
+      recoveredFromPid: current.pid || null,
+      activeLock: current,
+      lockHandle: activeLockHandle
+    };
+  } finally {
+    await releaseRecoveryClaim(claimHandle);
+  }
+}
+
+export async function releaseFallbackChainLock(lockHandle) {
+  if (!lockHandle) return false;
+  const filePath = lockHandle.filePath;
+  try {
+    const current = await readLock(filePath);
+    if (current && current.pid === lockHandle.lock.pid && current.lockId === lockHandle.lock.lockId) {
+      await fs.unlink(filePath);
+      return true;
+    }
+    return false;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  } finally {
+    if (activeLockHandle && activeLockHandle.lock.lockId === lockHandle.lock.lockId) {
+      activeLockHandle = null;
+    }
+  }
+}
+
+export async function withFallbackChainLock(fn, options = {}) {
+  const lock = await acquireFallbackChainLock(options);
+  if (!lock.acquired) {
+    return lock;
+  }
+  try {
+    const result = await fn(lock);
+    return { ...result, lockOutcome: lock.outcome, recoveredFromPid: lock.recoveredFromPid || null };
+  } finally {
+    await releaseFallbackChainLock(lock.lockHandle);
+  }
+}
+
+export async function inspectFallbackChainLock(options = {}) {
+  const filePath = options.filePath || lockPath(options.projectRoot);
+  const lock = await readLock(filePath);
+  return {
+    exists: !!lock,
+    lock,
+    heldByActive: !!(lock && !lock.corrupted && isPidAlive(lock.pid)),
+    corrupted: !!(lock && lock.corrupted)
+  };
+}
+
+export const fallbackChainLockPaths = {
+  lockPath
+};

package/src/orchestration/fallback-chain-trail.mjs

@@ -0,0 +1,218 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+import { CONFIG } from '../config.mjs';
+import { redactCredentials, redactObject } from '../format.mjs';
+import { stampSchemaVersion } from '../schema.mjs';
+import { EVIDENCE_SUMMARY_LIMIT } from './failure-evidence.mjs';
+
+export const FALLBACK_CHAIN_EVENTS_FILE = 'FALLBACK_CHAIN_EVENTS.jsonl';
+
+export const FALLBACK_CHAIN_TERMINAL_EVENTS = new Set([
+  'fallback_chain_completed',
+  'fallback_chain_exhausted',
+  'fallback_blocked_by_workspace',
+  'fallback_blocked_by_budget',
+  'fallback_needs_human'
+]);
+
+const REQUIRED_EVENT_FIELDS = [
+  'eventId',
+  'timestamp',
+  'taskId',
+  'orchestrationId',
+  'fallbackChainId',
+  'runId',
+  'attemptId',
+  'attemptNumber',
+  'engineId',
+  'healthTargetId',
+  'failureClass',
+  'decision',
+  'reason',
+  'budgetBefore',
+  'budgetAfter',
+  'workspaceSafety',
+  'previousAttemptId',
+  'selectedCandidate',
+  'rejectedCandidates',
+  'schemaVersion'
+];
+
+function trailPath(projectRoot = process.cwd()) {
+  return path.join(projectRoot, CONFIG.maestroPath, FALLBACK_CHAIN_EVENTS_FILE);
+}
+
+function makeEventId(eventType) {
+  return 'fallback-chain-' + process.pid + '-' + Date.now().toString(36) + '-' + eventType + '-' + Math.random().toString(36).slice(2, 8);
+}
+
+function normalizeText(value) {
+  const redacted = redactCredentials(value == null ? '' : String(value));
+  return redacted.length > EVIDENCE_SUMMARY_LIMIT ? redacted.slice(0, EVIDENCE_SUMMARY_LIMIT) : redacted;
+}
+
+function normalizeReason(reason) {
+  return Array.isArray(reason) ? reason.map(normalizeText) : [normalizeText(reason)].filter(Boolean);
+}
+
+function scrubEvent(input = {}) {
+  const event = {
+    eventId: input.eventId || makeEventId(input.eventType || 'event'),
+    eventType: input.eventType || 'fallback_event',
+    timestamp: input.timestamp || new Date().toISOString(),
+    taskId: input.taskId == null ? null : Number(input.taskId),
+    orchestrationId: input.orchestrationId == null ? null : String(input.orchestrationId),
+    fallbackChainId: input.fallbackChainId == null ? null : String(input.fallbackChainId),
+    runId: input.runId == null ? null : String(input.runId),
+    attemptId: input.attemptId == null ? null : String(input.attemptId),
+    attemptNumber: Number.isInteger(input.attemptNumber) ? input.attemptNumber : null,
+    engineId: input.engineId == null ? null : String(input.engineId),
+    healthTargetId: input.healthTargetId == null ? null : String(input.healthTargetId),
+    failureClass: input.failureClass == null ? null : String(input.failureClass),
+    decision: input.decision == null ? null : String(input.decision),
+    reason: normalizeReason(input.reason),
+    budgetBefore: input.budgetBefore || null,
+    budgetAfter: input.budgetAfter || null,
+    workspaceSafety: input.workspaceSafety || { workspaceChanged: null },
+    previousAttemptId: input.previousAttemptId == null ? null : String(input.previousAttemptId),
+    selectedCandidate: input.selectedCandidate || null,
+    rejectedCandidates: Array.isArray(input.rejectedCandidates) ? input.rejectedCandidates : [],
+    deadline: input.deadline == null ? null : String(input.deadline),
+    visitedEngineIds: Array.isArray(input.visitedEngineIds) ? input.visitedEngineIds.map(String) : [],
+    visitedHealthTargets: Array.isArray(input.visitedHealthTargets) ? input.visitedHealthTargets.map(String) : [],
+    originatingRunId: input.originatingRunId == null ? null : String(input.originatingRunId),
+    terminalOutcome: input.terminalOutcome == null ? null : String(input.terminalOutcome),
+    reasonChain: Array.isArray(input.reasonChain) ? input.reasonChain.map(normalizeText) : []
+  };
+  for (const forbidden of ['prompt', 'stdout', 'stderr', 'fullStdout', 'fullStderr', 'headers', 'authorization', 'cookie']) {
+    delete event[forbidden];
+  }
+  return redactObject(stampSchemaVersion(event));
+}
+
+export function validateFallbackChainEvent(event) {
+  const errors = [];
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    return { ok: false, errors: ['event must be an object'] };
+  }
+  for (const field of REQUIRED_EVENT_FIELDS) {
+    if (!(field in event)) errors.push(field + ' is required');
+  }
+  if (typeof event.eventType !== 'string') errors.push('eventType is required');
+  if (event.schemaVersion !== 1) errors.push('schemaVersion must be 1');
+  return { ok: errors.length === 0, errors };
+}
+
+export async function appendFallbackChainEvent(input = {}, options = {}) {
+  const filePath = options.filePath || trailPath(options.projectRoot);
+  const event = scrubEvent(input);
+  const result = validateFallbackChainEvent(event);
+  if (!result.ok) {
+    throw new Error('Invalid fallback chain event: ' + result.errors.join('; '));
+  }
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.appendFile(filePath, JSON.stringify(event) + '\n', { encoding: 'utf8' });
+  return event;
+}
+
+export async function readFallbackChainEvents(options = {}) {
+  const filePath = options.filePath || trailPath(options.projectRoot);
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export function groupChainsById(events = []) {
+  const groups = new Map();
+  for (const event of events) {
+    if (!event || !event.fallbackChainId) continue;
+    const key = String(event.fallbackChainId);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(event);
+  }
+  for (const group of groups.values()) {
+    group.sort((a, b) => String(a.timestamp || '').localeCompare(String(b.timestamp || '')));
+  }
+  return groups;
+}
+
+export function replayFallbackChain(events = []) {
+  const ordered = [...events].sort((a, b) => String(a.timestamp || '').localeCompare(String(b.timestamp || '')));
+  const visitedEngineIds = new Set();
+  const visitedHealthTargets = new Set();
+  const reasonChain = [];
+  let latest = null;
+  let attemptNumber = 0;
+  let previousAttemptId = null;
+  let fallbackChainId = null;
+  let originatingRunId = null;
+  let deadline = null;
+  let selectedCandidate = null;
+  let inProgressAttempt = null;
+
+  for (const event of ordered) {
+    latest = event;
+    fallbackChainId = fallbackChainId || event.fallbackChainId || null;
+    originatingRunId = originatingRunId || event.originatingRunId || event.fallbackChainId || null;
+    deadline = deadline || event.deadline || null;
+    if (Number.isInteger(event.attemptNumber)) {
+      attemptNumber = Math.max(attemptNumber, event.attemptNumber);
+    }
+    if (event.previousAttemptId != null) previousAttemptId = event.attemptId || event.runId || event.previousAttemptId;
+    if (event.engineId) visitedEngineIds.add(String(event.engineId));
+    if (event.healthTargetId) visitedHealthTargets.add(String(event.healthTargetId));
+    for (const engineId of event.visitedEngineIds || []) visitedEngineIds.add(String(engineId));
+    for (const targetId of event.visitedHealthTargets || []) visitedHealthTargets.add(String(targetId));
+    for (const reason of event.reason || []) reasonChain.push(normalizeText(reason));
+    if (event.selectedCandidate) selectedCandidate = event.selectedCandidate;
+    if (event.eventType === 'fallback_attempt_started') {
+      selectedCandidate = null;
+      inProgressAttempt = event;
+    }
+    if (event.eventType === 'fallback_attempt_finished') {
+      inProgressAttempt = null;
+      previousAttemptId = event.attemptId || event.runId || previousAttemptId;
+    }
+  }
+
+  const terminal = !!(latest && FALLBACK_CHAIN_TERMINAL_EVENTS.has(latest.eventType));
+  return {
+    fallbackChainId,
+    originatingRunId,
+    taskId: latest ? latest.taskId : null,
+    latestEvent: latest,
+    terminal,
+    attemptNumber,
+    previousAttemptId,
+    deadline,
+    visitedEngineIds: [...visitedEngineIds],
+    visitedHealthTargets: [...visitedHealthTargets],
+    reasonChain,
+    selectedCandidate,
+    inProgressAttempt,
+    events: ordered
+  };
+}
+
+export async function findLatestFallbackChainForTask(taskId, options = {}) {
+  const events = await readFallbackChainEvents(options);
+  const taskEvents = events.filter(event => String(event.taskId) === String(taskId));
+  const groups = groupChainsById(taskEvents);
+  let latest = null;
+  for (const eventsForChain of groups.values()) {
+    const replayed = replayFallbackChain(eventsForChain);
+    if (!latest || String(replayed.latestEvent.timestamp || '').localeCompare(String(latest.latestEvent.timestamp || '')) > 0) {
+      latest = replayed;
+    }
+  }
+  return latest;
+}
+
+export const fallbackChainTrailPaths = {
+  trailPath
+};

package/src/orchestration/fallback-executor.mjs

@@ -0,0 +1,146 @@
+// src/orchestration/fallback-executor.mjs
+
+export function planFallback(input) {
+  const { failure, context, budget, policy } = input;
+  const { category, retryable } = failure;
+  const { attemptNumber, maxAttempts } = context;
+
+  // needs_human is a statement about the underlying problem, not about how
+  // many attempts/budget remain — the failure itself says a human must
+  // decide, so this is checked before maxAttempts/policy and is always
+  // "allowed" (asking a human is never an unsafe action to permit).
+  if (category === 'needs_human') {
+    return {
+      action: 'ask_human',
+      successorEngine: null,
+      successorRole: null,
+      reason: ['Failure category "needs_human" always asks a human, regardless of attempts/budget.'],
+      allowed: true,
+      requiresHuman: true,
+    };
+  }
+
+  let action = 'none';
+  let successorEngine = null;
+  let successorRole = null;
+  const reason = [];
+  let allowed = true; // Overall flag if the current plan is allowed
+  let requiresHuman = false;
+
+  // Rule: Max attempts exceeded - highest precedence block
+  if (attemptNumber >= maxAttempts) {
+    action = 'block';
+    allowed = false;
+    requiresHuman = true; // Human needs to know it's blocked
+    reason.push(`Max attempts (${maxAttempts}) exceeded.`);
+  }
+
+  // Rule: Policy forbids paid engines (only if not already hard-blocked)
+  if (allowed && policy && policy.allowPaid === false && budget && budget.isPaid) {
+    action = 'block';
+    allowed = false;
+    requiresHuman = true;
+    reason.push('Policy forbids paid engines.');
+  }
+
+  // Rule: Policy forbids direct OpenAI (only if not already hard-blocked)
+  if (allowed && policy && policy.allowDirectOpenAI === false && context && context.selectedEngine && context.selectedEngine.id === 'openai') {
+    action = 'block';
+    allowed = false;
+    requiresHuman = true;
+    reason.push('Policy forbids direct OpenAI calls.');
+  }
+
+  // Rule: Policy forbids direct Claude (only if not already hard-blocked)
+  if (allowed && policy && policy.allowDirectClaude === false && context && context.selectedEngine && context.selectedEngine.id === 'claude') {
+    action = 'block';
+    allowed = false;
+    requiresHuman = true;
+    reason.push('Policy forbids direct Claude calls.');
+  }
+
+
+  // If a hard block was applied due to max attempts or policy, prioritize asking human about the block
+  if (!allowed && action === 'block') {
+    // No further actions, just return the block.
+    return {
+      action,
+      successorEngine,
+      successorRole,
+      reason,
+      allowed,
+      requiresHuman,
+    };
+  }
+
+
+  // Fallback logic based on failure category (only if not already hard-blocked)
+  if (allowed) {
+    switch (category) {
+      case 'network_error':
+      case 'rate_limit':
+      case 'quota_exceeded':
+        if (retryable) {
+          action = 'retry';
+          reason.push(`Failure category "${category}" is retryable.`);
+        } else {
+          action = 'ask_human';
+          requiresHuman = true;
+          reason.push(`Failure category "${category}" is not retryable, asking human.`);
+        }
+        break;
+      case 'missing_tool':
+      case 'syntax_failure':
+      case 'test_failure':
+      case 'windows_shell_mismatch':
+      case 'unsupported_tool_call':
+        action = 'switch_engine'; // Or suggest a fix if context allows
+        reason.push(`Failure category "${category}" suggests switching engine or fixing.`);
+        break;
+      case 'nested_sandbox_process_failure':
+        action = 'verify';
+        reason.push('Worker validation was blocked by nested sandbox process creation; use allowlisted host validation if policy permits.');
+        break;
+      case 'authentication_error':
+      case 'policy_violation':
+      case 'budget_exceeded':
+      case 'needs_human': // This will be handled by the shouldAskHuman flag below
+        action = 'ask_human';
+        requiresHuman = true;
+        reason.push(`Failure category "${category}" requires human intervention.`);
+        break;
+      case 'unknown_failure':
+        if (retryable) {
+          action = 'retry';
+          reason.push('Unknown failure, attempting retry.');
+        } else {
+          action = 'ask_human';
+          requiresHuman = true;
+          reason.push('Unknown failure and not retryable, asking human.');
+        }
+        break;
+      default:
+        action = 'ask_human';
+        requiresHuman = true;
+        reason.push(`No specific fallback plan for category "${category}", asking human.`);
+        break;
+    }
+  }
+
+  // Note: shouldAskHuman from the classifier is informational here, not an
+  // override — categories with a more specific action (e.g. missing_tool ->
+  // switch_engine) keep that action. Any category NOT explicitly handled by
+  // the switch above already falls through to the 'default' branch, which
+  // asks a human, so no separate blanket override is needed (and one would
+  // incorrectly stomp switch_engine/retry decisions for categories the
+  // classifier also flags as shouldAskHuman, like missing_tool).
+
+  return {
+    action,
+    successorEngine,
+    successorRole,
+    reason,
+    allowed,
+    requiresHuman,
+  };
+}

package/src/orchestration/fallback-graph.mjs

@@ -0,0 +1,106 @@
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { readJsonSafe } from '../files.mjs';
+import { FAILURE_CATEGORIES } from '../schema.mjs';
+import { isNestedSandboxProcessFailure } from './failure-classifier.mjs';
+
+const fallbackGraphPath = path.join(CONFIG.maestroPath, 'fallback-graph.json');
+
+const DEFAULT_RULE = { action: 'escalate-to-manager', maxAttempts: 0, reason: 'No rule configured for this failure category; escalate rather than guess.' };
+
+export function getFallbackGraphPath() {
+  return fallbackGraphPath;
+}
+
+export async function loadFallbackGraph() {
+  return readJsonSafe(fallbackGraphPath, { schemaVersion: 1, rules: {} });
+}
+
+// Deterministic, text/signal-based classification. This never calls a model
+// to decide "why did this fail" — see project principle "Claude pensa
+// somente quando necessário." `context` fields are all optional; provide
+// whichever are known for a given failure and this returns the first
+// matching category, defaulting to 'unknown_failure'.
+export function classifyFailure(context = {}) {
+  const {
+    preflightDecision,
+    missingCapabilities = [],
+    blockedBySafety,
+    syntaxValidationFailed,
+    testFailed,
+    lowConfidence,
+    exitCode,
+    stderr = '',
+    stdout = ''
+  } = context;
+
+  const text = String(stderr) + '\n' + String(stdout);
+
+  if (isNestedSandboxProcessFailure(text)) return 'nested_sandbox_process_failure';
+  if (blockedBySafety) return 'policy_violation';
+
+  if (preflightDecision === 'NEEDS_CAPABILITY') {
+    const toolKeys = new Set(['shell', 'filesystemWrite', 'browser', 'vision', 'testExecution']);
+    const missingTool = missingCapabilities.some(key => toolKeys.has(key));
+    return missingTool ? 'missing_tool' : 'insufficient_capability';
+  }
+  if (preflightDecision === 'NEEDS_CONTEXT') return 'context_too_small';
+  if (preflightDecision === 'UNAVAILABLE') return 'provider_unavailable';
+
+  if (syntaxValidationFailed) return 'syntax_failure';
+  if (testFailed) return 'test_failure';
+  if (lowConfidence) return 'low_confidence';
+
+  if (/rate[\s-]?limit|too many requests|\b429\b/i.test(text)) return 'rate_limit';
+  if (/quota|insufficient[_\s]?(credit|balance)|out of credits/i.test(text)) return 'quota_exceeded';
+  if (/ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET|network error|fetch failed/i.test(text)) return 'network_error';
+  if (/\b401\b|unauthorized|invalid api key|authentication failed/i.test(text)) return 'authentication_error';
+  if (/\b5\d\d\b|service unavailable|bad gateway|provider (is )?down/i.test(text)) return 'provider_unavailable';
+  if (/unsupported call|invalid[_\s]?output|malformed (json|output)/i.test(text)) return 'invalid_output';
+
+  if (typeof exitCode === 'number' && exitCode !== 0) return 'unknown_failure';
+
+  return 'unknown_failure';
+}
+
+export async function resolveFallbackRule(category) {
+  const graph = await loadFallbackGraph();
+  const rules = graph.rules || {};
+  return rules[category] || DEFAULT_RULE;
+}
+
+// Turns an action string from fallback-graph.json into a concrete hint for
+// whatever calls engine-selector.mjs next. This is intentionally data, not
+// behavior — the delegation manager / task runner decides what to actually
+// do with the hint.
+const ACTION_HINTS = {
+  'try-equivalent-provider': { excludeCurrentEngine: true, requireSameCapabilityClass: true },
+  'retry-then-successor': { retrySameEngineFirst: true, thenExcludeCurrentEngine: true },
+  'switch-provider': { excludeCurrentEngine: true, excludeSameProvider: true },
+  'block-engine': { excludeCurrentEngine: true, blockEnginePermanently: true },
+  'require-capability': { excludeCurrentEngine: true, requireMissingTools: true },
+  'escalate-capability': { excludeCurrentEngine: true, requireHigherCapability: true },
+  'escalate-context': { excludeCurrentEngine: true, requireLargerContext: true },
+  'call-verifier': { callVerifierFirst: true },
+  'escalate-to-manager': { escalateToManager: true }
+};
+
+export async function planFallback(context = {}) {
+  const category = context.category || classifyFailure(context);
+  const rule = await resolveFallbackRule(category);
+  const hint = ACTION_HINTS[rule.action] || {};
+  return {
+    category,
+    action: rule.action,
+    maxAttempts: typeof rule.maxAttempts === 'number' ? rule.maxAttempts : 0,
+    retryDelayMs: rule.retryDelayMs || 0,
+    reason: rule.reason || '',
+    hint
+  };
+}
+
+export function isKnownFailureCategory(category) {
+  return FAILURE_CATEGORIES.has(category);
+}
+
+export { FAILURE_CATEGORIES };