amicus 4.2.0 → 4.3.0

package/src/observe/on-complete.js

@@ -0,0 +1,117 @@
+// src/observe/on-complete.js
+'use strict';
+
+/**
+ * @module observe/on-complete
+ * CLI --on-complete exec hook (spec 5.3). The command is user-authored on the
+ * command line of THIS invocation — the same trust level as typing it into the
+ * shell. Amicus never sources hook commands from config/briefings/model output
+ * (D8 withdrawn) and never interpolates anything into the command string. The
+ * payload rides via ENVIRONMENT only, ids/paths only — never model-generated
+ * text — so untrusted previews can never enter a user's shell pipeline. The
+ * hook can never change the run's exit code, docs, or events. CLI-only: MCP
+ * never gets exec (Task 15 gives MCP a notify-only hook).
+ */
+
+const HOOK_TIMEOUT_MS = Number(process.env.AMICUS_HOOK_TIMEOUT_MS) || 60000;
+
+/** ids/paths ONLY (spec 5.3). Every value is a string; cost/paths default ''. */
+function buildHookEnv(info) {
+  return {
+    AMICUS_TASK_ID: String(info.taskId || ''),
+    AMICUS_TYPE: String(info.type || ''),
+    AMICUS_STATUS: String(info.status || ''),
+    AMICUS_EXIT_CODE: String(info.exitCode !== null && info.exitCode !== undefined ? info.exitCode : ''),
+    AMICUS_RESULT_FILE: String(info.resultFile || ''),
+    AMICUS_EVENTS_FILE: String(info.eventsFile || ''),
+    AMICUS_COST: String(info.cost || ''),
+    AMICUS_PROJECT: String(info.project || ''),
+  };
+}
+
+/**
+ * Fire the exec hook once at terminal state. Never throws/rejects; a non-zero
+ * exit or timeout is a warning only — the run's exit code/docs/events are
+ * never touched by this function.
+ */
+function runOnComplete(cmd, info, deps = {}) {
+  const spawn = deps.spawn || require('child_process').spawn;
+  const logger = deps.logger || require('../utils/logger').logger;
+  const timeoutMs = deps.timeoutMs || HOOK_TIMEOUT_MS;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, {
+        shell: true, cwd: info.project || process.cwd(),
+        env: { ...process.env, ...buildHookEnv(info) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      logger.warn('on-complete hook failed to spawn (run unaffected)', { error: e.message });
+      return resolve();
+    }
+    let done = false;
+    const finish = () => { if (!done) { done = true; clearTimeout(timer); resolve(); } };
+    const timer = setTimeout(() => {
+      logger.warn('on-complete hook timed out — killing (run unaffected)', { timeoutMs });
+      try { child.kill(); } catch { /* already gone */ }
+      finish();
+    }, timeoutMs);
+    if (child.stdout) { child.stdout.on('data', (d) => process.stderr.write(d)); }
+    if (child.stderr) { child.stderr.on('data', (d) => process.stderr.write(d)); }
+    child.on('error', (e) => { logger.warn('on-complete hook error (run unaffected)', { error: e.message }); finish(); });
+    child.on('close', (code) => {
+      if (code && code !== 0) { logger.warn('on-complete hook exited non-zero (run unaffected)', { code }); }
+      finish();
+    });
+  });
+}
+
+/**
+ * Thin fire helper for fanout's two terminal sites (normal finalize + the
+ * all-legs-failed short-circuit). No-ops on a falsy/non-string cmd so call
+ * sites stay one line with no guard of their own.
+ */
+async function fireWaveOnComplete(cmd, wave, { waveId, waveDir, wavePath, exitCode, project }, deps) {
+  if (!cmd || typeof cmd !== 'string') { return; }
+  try {
+    const path = require('path');
+    const { formatCost } = require('../utils/pricing');
+    const { EVENTS_FILE } = require('./events');
+    await runOnComplete(cmd, {
+      taskId: waveId, type: 'wave', status: wave.status, exitCode,
+      resultFile: wavePath, eventsFile: path.join(waveDir, EVENTS_FILE),
+      cost: wave.usage && wave.usage.cost ? formatCost(wave.usage.cost) : '',
+      project,
+    }, deps);
+  } catch (e) {
+    const logger = (deps && deps.logger) || require('../utils/logger').logger;
+    logger.warn('on-complete hook assembly failed (run unaffected)', { error: e.message });
+  }
+}
+
+/**
+ * Thin fire helper for council run.js's single finalize choke point. No-ops
+ * on a falsy/non-string cmd so the call site stays one line.
+ */
+async function fireCouncilOnComplete(cmd, run, { runId, runDir, exitCode, project }, deps) {
+  if (!cmd || typeof cmd !== 'string') { return; }
+  try {
+    const path = require('path');
+    const { formatCost } = require('../utils/pricing');
+    const { EVENTS_FILE } = require('./events');
+    await runOnComplete(cmd, {
+      taskId: runId, type: 'council-run', status: run.status, exitCode,
+      resultFile: path.join(runDir, 'run.json'), eventsFile: path.join(runDir, EVENTS_FILE),
+      cost: run.usage && run.usage.cost ? formatCost(run.usage.cost) : '',
+      project,
+    }, deps);
+  } catch (e) {
+    const logger = (deps && deps.logger) || require('../utils/logger').logger;
+    logger.warn('on-complete hook assembly failed (run unaffected)', { error: e.message });
+  }
+}
+
+module.exports = {
+  buildHookEnv, runOnComplete, fireWaveOnComplete, fireCouncilOnComplete, HOOK_TIMEOUT_MS,
+};

package/src/observe/watch-render.js

@@ -0,0 +1,149 @@
+// src/observe/watch-render.js
+'use strict';
+
+/**
+ * @module observe/watch-render
+ * Pure renderers + the poll loop for `amicus watch` (spec 5.1). Renderers are
+ * pure functions over the composed live doc (wave-progress.js precedent) so the
+ * table adds no testing burden beyond string assertions. The loop reads only
+ * the data layer: handlers.amicus_status (Surface C) each interval + the events
+ * tail (Surface B) for milestone lines. TTY -> in-place refresh table (ANSI
+ * erase-line + cursor-up, NO alternate screen — scrollback preserved);
+ * non-TTY/--plain -> milestone log lines; --json -> NDJSON.
+ */
+
+const { formatCost } = require('../utils/pricing');
+// Single source of truth for "what statuses are terminal" across the
+// observability layer (live-doc.js's markLive uses the SAME set to decide
+// when to stamp view:'live') — redefining it here would risk the two
+// modules drifting, which would make this loop spin forever on a run
+// live-doc already considers finished (or exit early on one still running).
+const { TERMINAL } = require('./live-doc');
+// Single source of truth for the wave status -> exit code mapping (same
+// drift risk as TERMINAL above) — mapExitCode's non-passthrough branch
+// delegates here instead of hand-rolling the complete/partial/else mapping.
+const { waveExitCode } = require('../utils/result-schema');
+
+const DASH = '—';
+const legCost = (leg) => (leg.usage && leg.usage.cost ? formatCost(leg.usage.cost) : DASH);
+const legTokens = (leg) => (leg.usage && leg.usage.tokens ? `${leg.usage.tokens.input || 0}/${leg.usage.tokens.output || 0}` : DASH);
+const truncate = (s, n) => { const t = String(s || ''); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+
+const STAGE_MARK = { complete: '✓', running: '▶', pending: '·' };
+
+/** The in-place refresh block for a composed wave/council/solo doc. */
+function renderTable(doc, width = 100) {
+  const cost = doc.usage && doc.usage.cost ? formatCost(doc.usage.cost) : DASH;
+  const head = `${doc.taskId || doc.runId}  ${doc.status}  ${doc.elapsed || ''}  ` +
+    (typeof doc.legsTotal === 'number' ? `legs ${doc.legsComplete}/${doc.legsTotal}  ` : '') +
+    `cost ${cost}`;
+  const lines = [head];
+  if (Array.isArray(doc.stages)) { // council stage checklist
+    lines.push(doc.stages.map((s) => `${STAGE_MARK[s.status] || STAGE_MARK.pending} ${s.name}`).join('  '));
+  }
+  for (const leg of (doc.legs || [])) {
+    const flag = leg.stalled ? ' ⏳stalled' : '';
+    lines.push(
+      `  ${String(leg.model || leg.taskId).padEnd(26)} ${String(leg.phase || leg.status).padEnd(11)} ` +
+      `${String(leg.messages || 0).toString().padStart(3)}msg ${legTokens(leg).padStart(11)} ${legCost(leg).padStart(9)} | ` +
+      `${truncate(leg.latestPreview, Math.max(10, width - 70))}${flag}`
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Non-TTY / --plain milestone lines + a periodic one-line rollup. */
+function renderPlainLines(events, doc) {
+  const lines = (events || []).map((e) => {
+    switch (e.event) {
+      case 'wave-started': return `[wave-started] ${e.id} models=${(e.models || []).join(',')}`;
+      case 'leg-started': return `[leg-started] ${e.legId} ${e.model}`;
+      case 'leg-fallback': return `[leg-fallback] ${e.legId} ${e.fromModel} -> ${e.toModel} (${e.reason})`;
+      case 'leg-terminal': return `[leg-terminal] ${e.legId} ${e.model} ${e.status}`;
+      case 'wave-terminal': return `[wave-terminal] ${e.id} ${e.status} exit=${e.exitCode}`;
+      case 'run-started': return `[run-started] ${e.id} bench=${(e.bench || []).join(',')}`;
+      case 'stage-started': return `[stage-started] ${e.stage}`;
+      case 'stage-terminal': return `[stage-terminal] ${e.stage} ${e.status}`;
+      case 'run-terminal': return `[run-terminal] ${e.id} ${e.status} exit=${e.exitCode}`;
+      default: return `[${e.event}] ${e.id || ''}`;
+    }
+  });
+  if (doc) {
+    const cost = doc.usage && doc.usage.cost ? formatCost(doc.usage.cost) : DASH;
+    lines.push(`… ${doc.status} ${typeof doc.legsTotal === 'number' ? `${doc.legsComplete}/${doc.legsTotal} legs ` : ''}cost ${cost}`);
+  }
+  return lines;
+}
+
+/** Exit mapping (spec 5.1). Council passes through its recorded exitCode. */
+function mapExitCode(doc) {
+  if (doc && typeof doc.exitCode === 'number') { return doc.exitCode; }
+  if (!doc) { return 1; }
+  return waveExitCode(doc.status);
+}
+
+/** Stable-stringify diff: emit the composed doc only when it changed. */
+function emitJsonChange(doc, prevText) {
+  const text = JSON.stringify(doc);
+  return text === prevText ? { emit: false } : { emit: true, text };
+}
+
+/**
+ * The watch poll loop. DI-injected clock/status/tail for testability.
+ * @returns {Promise<number>} exit code
+ */
+async function runWatchLoop(target, args, project, deps = {}) {
+  const intervalSec = Math.max(0.5, Number(args.interval) || 2);
+  const statusFn = deps.statusFn || ((id, p) => require('../mcp-server').handlers.amicus_status({ taskId: id }, p));
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const isTTY = deps.isTTY !== undefined ? deps.isTTY : process.stdout.isTTY;
+  const { createEventTail, EVENTS_FILE } = require('./events');
+  const { getSessionDir } = require('../session-manager');
+  const path = require('path');
+  const eventsFile = target.kind === 'council'
+    ? path.join(target.runDir, EVENTS_FILE)
+    : path.join(getSessionDir(project, target.id), EVENTS_FILE);
+  const tail = createEventTail(eventsFile);
+  let prevJson = null;
+  let prevRollup = null;
+  let lastLineCount = 0;
+
+  for (;;) {
+    const res = await statusFn(target.id, project);
+    let doc;
+    try { doc = JSON.parse(res.content[0].text); } catch { doc = null; }
+    const events = tail.poll();
+    const isTerminal = doc && TERMINAL.has(doc.status);
+    if (args.json) {
+      for (const e of events) { process.stdout.write(JSON.stringify(e) + '\n'); }
+      if (doc) { const c = emitJsonChange(doc, prevJson); if (c.emit) { process.stdout.write(c.text + '\n'); prevJson = c.text; } }
+    } else if (isTTY && !args.plain) {
+      if (lastLineCount) { process.stdout.write(`\x1b[${lastLineCount}A\x1b[0J`); }
+      const block = renderTable(doc || { status: 'unknown', legs: [] }, process.stdout.columns || 100);
+      process.stdout.write(block + '\n');
+      lastLineCount = block.split('\n').length;
+    } else {
+      // Milestone event lines: the tail only yields new events, so these are
+      // always fresh — print every tick, unthrottled.
+      for (const line of renderPlainLines(events, null)) { process.stdout.write(line + '\n'); }
+      // Rollup line: change-only (mirrors the --json path above), so a
+      // multi-minute --plain watch doesn't spam an identical line every
+      // interval. Always printed on the terminal tick so the final state
+      // is never silently swallowed.
+      if (doc) {
+        const rollup = renderPlainLines([], doc)[0];
+        if (rollup !== prevRollup || isTerminal) {
+          process.stdout.write(rollup + '\n');
+          prevRollup = rollup;
+        }
+      }
+    }
+    if (isTerminal) {
+      if (args.json) { process.stdout.write(JSON.stringify(doc) + '\n'); }
+      return mapExitCode(doc);
+    }
+    await sleep(intervalSec * 1000);
+  }
+}
+
+module.exports = { renderTable, renderPlainLines, mapExitCode, emitJsonChange, runWatchLoop, DASH };

package/src/sidecar/continue.js

@@ -116,6 +116,26 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
   return sessionDir;
 }
 
+/**
+ * Resolve a reopened session's usage, write it onto metadata, and append one
+ * attributed ledger row. Mirrors start.js's finalize (the only sites that
+ * dropped usage - BACKLOG.md:280). Best-effort ledger append; never throws.
+ * @returns {{usage: object|null}}
+ */
+function finalizeSpendForReopen({ taskId, model, mode, op, result, status, project, metadata }, ctx = {}) {
+  const { resolveUsage } = require('../utils/pricing');
+  const usage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
+  if (usage) {
+    metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
+      appendSpend({ taskId, model, mode, usage, op, status, project, gateway }, ctx);
+    } catch { /* best-effort */ }
+  }
+  return { usage };
+}
+
 /**
  * Continue from a previous sidecar session - Spec Reference: §4.4, §8.5
  * @returns {Promise<number>} process exit code
@@ -246,6 +266,17 @@ async function continueSidecar(options) {
   } else {
     finalizeSession(sessionDir, summary, project, meta, { quietStdout: json, status: terminal.status });
   }
+  // v4.3: attribute continue spend (C9/E4). Reload meta, write usage + append a
+  // ledger row (status: statusFromResult, matching start.js — not terminal.status).
+  {
+    const { statusFromResult } = require('../utils/result-schema');
+    const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    const { usage } = finalizeSpendForReopen({
+      taskId: newTaskId, model, mode: headless ? 'headless' : 'interactive',
+      op: 'continue', result, status: statusFromResult(result), project, metadata: reloaded,
+    });
+    if (usage) { writeFileAtomic(metaPath, JSON.stringify(reloaded, null, 2), { mode: 0o600 }); }
+  }
 
   if (json) {
     const { buildRunResult } = require('../utils/result-schema');
@@ -261,5 +292,6 @@ module.exports = {
   loadPreviousSession,
   buildContinuationContext,
   createContinueSessionMetadata,
+  finalizeSpendForReopen,
   continueSidecar
 };

package/src/sidecar/fallback-chains.js

@@ -0,0 +1,65 @@
+// src/sidecar/fallback-chains.js
+'use strict';
+
+/**
+ * @module fallback-chains
+ * Opt-in cheaper-model fallback chains (spec 6.2, resolved Q2). Default OFF;
+ * per-run --fallback/--no-fallback overrides config. Explicit chains win;
+ * otherwise a default chain is DERIVED from model-tiers by walking DOWN the
+ * failed model's vendor tiers (frontier -> balanced -> economy), keeping only
+ * entries CHEAPER than the failed model. Gateway-only + unknown vendors get
+ * no default chain (the leg fails as today). Chain entries may be aliases or
+ * full ids, including openrouter/... (so "same model, other gateway" is
+ * expressible).
+ */
+
+const { resolveTier, TIER_ORDER } = require('../utils/model-tiers');
+
+const DEFAULT_MAX_SUBSTITUTIONS = 2;
+
+/** Merge user config `fallbacks` with the per-run flag (flag wins). */
+function resolveFallbackConfig({ flagFallback, config } = {}) {
+  const fb = (config && config.fallbacks) || {};
+  let enabled = fb.enabled === true;
+  if (flagFallback === true) { enabled = true; }
+  if (flagFallback === false) { enabled = false; }
+  return {
+    enabled,
+    maxSubstitutions: Number.isInteger(fb.maxSubstitutions) ? fb.maxSubstitutions : DEFAULT_MAX_SUBSTITUTIONS,
+    chains: fb.chains || {},
+  };
+}
+
+/** Vendor segment for tier lookup; a bare alias returns itself (config key). */
+function vendorOf(model) {
+  let id = String(model || '');
+  if (id.startsWith('openrouter/')) { id = id.slice('openrouter/'.length); }
+  const slash = id.indexOf('/');
+  return slash > 0 ? id.slice(0, slash) : id;
+}
+
+/** Explicit chain, else the tier-walk default. A substitute must be cheaper. */
+function deriveChain(model, { config, catalog } = {}) {
+  const chains = (config && config.chains) || {};
+  // explicit chain keyed by the bare alias OR the vendor
+  const key = chains[model] ? model : (chains[vendorOf(model)] ? vendorOf(model) : null);
+  if (key) { return chains[key].slice(); }
+
+  // tier-walk default: frontier -> balanced -> economy (most -> least capable)
+  const vendor = vendorOf(model);
+  const ordered = [];
+  for (const tier of [...TIER_ORDER].reverse()) {
+    const id = resolveTier(vendor, tier, catalog || []);
+    if (id && !ordered.includes(id)) { ordered.push(id); } // do NOT drop the failed model here
+  }
+  // Keep only tiers CHEAPER than the failed model (strictly after its position
+  // in the most->least-capable ladder). This drops the failed model AND
+  // everything more capable — a substitute must be cheaper (spec 6.2). If the
+  // failed model is not a current tier pick (e.g. a slightly-stale id), fall
+  // back to the full vendor ladder minus the exact model (best-effort;
+  // bounded misclassification cost).
+  const failedIdx = ordered.indexOf(model);
+  return failedIdx === -1 ? ordered.filter((id) => id !== model) : ordered.slice(failedIdx + 1);
+}
+
+module.exports = { resolveFallbackConfig, deriveChain, vendorOf, DEFAULT_MAX_SUBSTITUTIONS };

package/src/sidecar/fanout-leg-fallback.js

@@ -0,0 +1,189 @@
+// src/sidecar/fanout-leg-fallback.js
+'use strict';
+
+/**
+ * @module fanout-leg-fallback
+ * Cheaper-model fallback substitution (spec 6.2), split out of fanout-leg.js
+ * to keep both files ≤300 lines (mirrors the fanout.js/fanout-validate.js
+ * split). Owns the substitution loop + its two bookkeeping helpers.
+ * `runSingleAttempt` is lazy-required from ./fanout-leg (function-scoped, to
+ * avoid a load-time circular require — fanout-leg.js requires this module for
+ * its thin runLeg wrapper).
+ */
+
+const fs = require('fs');
+const { logger } = require('../utils/logger');
+const { classifyLegError, isRetryable } = require('../utils/error-classify');
+const { deriveChain } = require('./fallback-chains');
+
+/**
+ * Append ONE attributed ledger row for a single attempt (spec 6.2/7.1). At
+ * `attempt:0` this is byte-identical to today's pre-fallback appendSpend row
+ * (same fields, sourced from `leg.attempt`/`leg.substitutedFor`/
+ * `leg.retryOfWaveId`, all undefined -> omitted for a plain leg). A
+ * substitution (`attempt` param > 0, the LOOP's attempt index) overrides
+ * `row.attempt`/`row.substitutedFor` with the substitution's own values.
+ * Best-effort — never throws, never affects the leg. `deps.spendDir` (tests)
+ * routes the write to a scratch dir; production leaves it undefined.
+ */
+function recordAttemptSpend({ doc, leg, currentModel, legId, waveId, project, attempt, originalModel, routeGateway }, deps = {}) {
+  const usage = doc && doc.usage;
+  if (!usage) { return; }
+  try {
+    const { appendSpend } = deps.spendLedger || require('../utils/spend-ledger');
+    // Resolved legs carry the router's gateway on `leg.gateway` (attempt 0);
+    // a substitution carries the substitute's resolved gateway on
+    // `routeGateway` (threaded in by the loop, incl. v4.2 'local').
+    const gateway = routeGateway || (leg && leg.gateway) ||
+      (String(currentModel).startsWith('openrouter/') ? 'openrouter' : 'direct');
+    const row = {
+      taskId: legId, waveId, model: currentModel, mode: 'leg', usage,
+      op: 'leg', status: doc.status, gateway,
+      councilRunId: leg && leg.councilRunId, councilName: leg && leg.councilName,
+      project, attempt: leg && leg.attempt, substitutedFor: leg && leg.substitutedFor,
+      retryOfWaveId: leg && leg.retryOfWaveId,
+    };
+    if (attempt > 0) { row.attempt = attempt; row.substitutedFor = originalModel; }
+    appendSpend(row, deps.spendDir ? { dir: deps.spendDir } : undefined);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Fold token totals + cost amount across a leg's attempts[]. A single-attempt
+ * leg returns that attempt's usage verbatim (no behavior change for non-fallback
+ * legs). Multi-attempt sums tokens.* and cost.amount, tagging source 'mixed'
+ * when attempts' sources differ — matching formatCost's `~` behavior so a summed
+ * cost never reads as authoritative.
+ */
+function sumAttemptUsage(attempts) {
+  const withUsage = (attempts || []).filter(a => a.usage && a.usage.tokens);
+  if (withUsage.length === 0) { return null; }
+  if (withUsage.length === 1) { return withUsage[0].usage; }
+  const tokens = {};
+  let amount = 0;
+  let anyCost = false;
+  const sources = new Set();
+  for (const a of withUsage) {
+    for (const [k, v] of Object.entries(a.usage.tokens || {})) {
+      tokens[k] = (tokens[k] || 0) + (v || 0);
+    }
+    if (a.usage.cost && typeof a.usage.cost.amount === 'number') {
+      amount += a.usage.cost.amount;
+      anyCost = true;
+      if (a.usage.cost.source) { sources.add(a.usage.cost.source); }
+    }
+  }
+  const cost = anyCost
+    ? { amount, currency: 'USD', source: sources.size > 1 ? 'mixed' : (sources.values().next().value || 'reported') }
+    : null;
+  return { tokens, cost };
+}
+
+/**
+ * Per-$/Mtok hard-cap check for ONE fallback substitute candidate (spec
+ * §6.2). Minimal inline version of budget.js's checkBudget threshold, applied
+ * to a single model instead of a leg list. Unpriced (direct-provider,
+ * pricing:null) candidates are never treated as over-cap — unknown cost is
+ * not exceeded cost.
+ */
+function isOverBudgetSubstitute(modelId, maxCostPerMtok) {
+  const { lookupPricing } = require('../utils/pricing');
+  const { DEFAULT_MAX_COST_PER_MTOK } = require('./budget');
+  const pricing = lookupPricing(modelId);
+  if (!pricing) { return false; }
+  const cap = (typeof maxCostPerMtok === 'number' && maxCostPerMtok > 0) ? maxCostPerMtok : DEFAULT_MAX_COST_PER_MTOK;
+  return Math.max(pricing.prompt * 1e6, pricing.completion * 1e6) > cap;
+}
+
+/**
+ * runLeg with opt-in cheaper-model substitution (spec 6.2). Runs the primary;
+ * on a classified rate-limit/overload failure with chain + budget remaining,
+ * substitutes the next chain model in the SAME leg dir under the SAME legId
+ * (conversation appends; metadata.model tracks the current model, modelInput
+ * stays the original). Best-effort bookkeeping (attempts/events/ledger) never
+ * fails the leg.
+ */
+async function runLegWithFallback(args, deps = {}) {
+  const { leg, legId, waveId, project, fallback, catalog } = args;
+  const runOnce = deps.runOnce || ((a) => require('./fanout-leg').runSingleAttempt(a, deps));
+  const resolveRoute = deps.resolveRoute ||
+    ((r) => require('../utils/route-launch').resolveRouteForLaunch(r));
+  const { getSessionDir } = require('../session-manager');
+  const { appendEvent } = require('../observe/events');
+  const waveDir = getSessionDir(project, waveId);
+  // In production the wave dir already exists (fanout.js creates it before
+  // any leg launches); this is a defensive no-op there and only matters for
+  // a direct/unit-test caller of runLegWithFallback. appendEvent itself never
+  // creates directories (spec: best-effort, no side effects beyond the file).
+  try { fs.mkdirSync(waveDir, { recursive: true, mode: 0o700 }); } catch { /* best-effort */ }
+
+  const chain = deriveChain(leg.model, { config: { chains: fallback.chains }, catalog });
+  const attempts = [];
+  let currentModel = leg.model;
+  let currentGateway = leg.gateway;
+  let reasonClass = null;
+  let attempt = 0;    // count of actual runs beyond the primary (bounded by maxSubstitutions)
+  let chainIdx = 0;    // chain cursor: candidates tried OR skipped-for-budget, monotonic
+  let last;
+
+  for (;;) {
+    const startedAt = new Date().toISOString();
+    // `model` is threaded BOTH at the top level (test/injected runOnce fakes
+    // destructure it directly, e.g. `async ({ model }) => ...`) and nested
+    // under `leg.model` (the real runSingleAttempt only reads the latter).
+    last = await runOnce({ ...args, leg: { ...leg, model: currentModel }, model: currentModel,
+      attempt, substitutedFor: attempt > 0 ? leg.model : undefined });
+    attempts.push({ model: currentModel, status: last.status, usage: last.usage || null,
+      startedAt, completedAt: new Date().toISOString(), reason: last.reason || last.error || null });
+
+    // record this attempt's spend (one row per attempt — spec 6.2)
+    recordAttemptSpend({ doc: last, leg, currentModel, legId, waveId, project, attempt,
+      originalModel: leg.model, routeGateway: currentGateway }, deps);
+
+    if (last.status === 'complete') { break; }
+    // runSingleAttempt exposes the failure text on both `.reason` (its own
+    // alias) and `.error` (the buildRunResult field); an injected runOnce may
+    // set only one — read either.
+    const cls = classifyLegError(last.reason || last.error);
+    if (!fallback.enabled || !isRetryable(cls) || attempt >= fallback.maxSubstitutions || chainIdx >= chain.length) { break; }
+
+    // Walk the chain forward from chainIdx: an over-cap candidate is skipped
+    // (spec §6.2 per-$/Mtok guard) and the walk tries the NEXT entry; a
+    // route-resolution failure stops the whole loop outright (spec 8).
+    let substituteId = null;
+    let acceptedGateway = null;
+    let routeFailed = false;
+    while (chainIdx < chain.length) {
+      const next = chain[chainIdx];
+      chainIdx += 1;
+      let route;
+      try { route = await resolveRoute({ model: next, gatewayMode: undefined, source: 'fallback', allowSelection: false, validateModel: false }); }
+      catch { route = { kind: 'error' }; }
+      // RouteResult is keyed by `.kind` ('resolved'|'selection_required'|'error') — no `.ok` field.
+      if (!route || route.kind !== 'resolved') { routeFailed = true; break; }
+      const candidateId = route.executableId || route.model || next;
+      if (isOverBudgetSubstitute(candidateId, args.maxCostPerMtok)) {
+        logger.warn('Fallback substitute over the per-$/Mtok cap — trying the next chain entry', { legId, candidate: candidateId });
+        continue;
+      }
+      substituteId = candidateId;
+      acceptedGateway = route.gateway;
+      break;
+    }
+    if (routeFailed || !substituteId) { break; }
+
+    reasonClass = cls;
+    appendEvent(waveDir, { event: 'leg-fallback', id: waveId, legId,
+      fromModel: currentModel, toModel: substituteId, reason: cls, attempt: attempt + 1 });
+    currentModel = substituteId;
+    currentGateway = acceptedGateway;
+    attempt += 1;
+  }
+
+  const finalUsage = sumAttemptUsage(attempts);
+  const doc = { ...last, legId, model: currentModel, modelInput: leg.modelInput, usage: finalUsage, attempts };
+  if (attempt > 0) { doc.fallback = { from: leg.model, reason: reasonClass, attempts: attempt }; }
+  return doc;
+}
+
+module.exports = { runLegWithFallback, recordAttemptSpend, sumAttemptUsage };