amicus 4.2.1 → 4.4.0

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-budget.js

@@ -0,0 +1,71 @@
+// src/sidecar/fanout-budget.js
+'use strict';
+
+/**
+ * @module sidecar/fanout-budget
+ * runFanout's pre-flight spend gate (§1b), extracted from src/sidecar/fanout.js —
+ * which sits three lines under the 300-line size gate and had no room for the
+ * v4.4 reservation seam. Behaviour of the extracted half is unchanged; the
+ * reservation is the only addition.
+ *
+ * WHY THE RESERVATION EXISTS (v4.4 cost-council finding 1). `checkBudget`
+ * compares the wave's pre-flight ESTIMATE against a `maxCost` NUMBER that the
+ * caller read at some earlier moment. The council driver launches Stage-1's seat
+ * wave and critic wave concurrently under a single `Promise.all`, and each
+ * launcher read `remainingBudget()` before EITHER wave's legs had been recorded
+ * — so both observed the full, unreduced allowance and both could pass a ceiling
+ * that only one of them fits under. The read is not the claim.
+ *
+ * `options.reserveBudget(estimate) -> boolean` closes that: it is a SYNCHRONOUS
+ * read-and-claim against the allowance not already claimed by a sibling wave
+ * that is mid-launch. Being synchronous is the whole guarantee — the event loop
+ * cannot interleave two callers inside it, so the second caller necessarily sees
+ * the first caller's claim. See src/council/run-budget.js for the ledger.
+ *
+ * It is OPT-IN: every non-council caller (the `amicus fanout` CLI, `amicus run`)
+ * omits it and gets the byte-identical pre-v4.4 gate.
+ */
+
+/**
+ * @param {Array<{modelInput,model,pricing}>} okLegs legs that actually routed
+ * @param {object} options runFanout options (maxCost, maxCostPerMtok, noCostGate,
+ *   promptMeta/prompt, and the optional `reserveBudget` claim function)
+ * @returns {{ok:true, estimate?:number}|{ok:false, message:string, hint:string}}
+ */
+function preflightBudget(okLegs, options) {
+  // `--no-cost-gate` is a WHOLE-RUN opt-out of BOTH guards (an intentional
+  // o3-class council), so it must also skip the reservation — otherwise the
+  // council would still serialize its allowance for a ceiling it has disowned.
+  if (options.noCostGate) { return { ok: true }; }
+
+  const { checkBudget, formatBudgetError } = require('./budget');
+  const { loadConfig } = require('../utils/config');
+  const cfg = loadConfig() || {};
+  const maxCostPerMtok = options.maxCostPerMtok !== undefined ? options.maxCostPerMtok : cfg.maxCostPerMtok;
+  const promptChars = (options.promptMeta && options.promptMeta.chars)
+    || (options.prompt ? options.prompt.length : 0);
+  const maxCost = options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost;
+
+  const budget = checkBudget(okLegs, { maxCostPerMtok, maxCost, promptChars });
+  if (!budget.ok) {
+    return { ok: false, message: 'Error: budget gate refused the wave', hint: formatBudgetError(budget) };
+  }
+
+  // Claim AFTER the hard per-$/Mtok threshold has passed: a wave that is going
+  // to be refused for an over-priced model must not consume allowance on its
+  // way out and starve a sibling that would have fit.
+  const estimate = budget.breakdown.totalEstCost;
+  if (typeof options.reserveBudget === 'function' && !options.reserveBudget(estimate)) {
+    return {
+      ok: false,
+      message: 'Error: budget gate refused the wave',
+      hint: `Budget gate: estimated total $${estimate.toFixed(4)} does not fit the --max-cost `
+        + 'allowance still unclaimed by concurrently launching waves (estimate, not guaranteed).\n'
+        + 'The run continues with the waves that did launch. Override: --max-cost <$> to raise the '
+        + 'ceiling, or --no-cost-gate to disable both guards.',
+    };
+  }
+  return { ok: true, estimate };
+}
+
+module.exports = { preflightBudget };

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 };

package/src/sidecar/fanout-leg.js

@@ -4,7 +4,10 @@
 /**
  * @module fanout-leg
  * Per-leg helpers extracted from fanout.js to keep both files ≤300 lines.
- * Exports: legStatusFromResult, writeLegPatch, runLeg
+ * Exports: legStatusFromResult, writeLegPatch, runLeg, runSingleAttempt,
+ * buildRoutingFailureLeg (+ runLegWithFallback/recordAttemptSpend/
+ * sumAttemptUsage, re-exported from ./fanout-leg-fallback — split out to keep
+ * THIS file under the size gate; see that module for the substitution loop).
  */
 
 const fs = require('fs');
@@ -61,29 +64,40 @@ function buildRoutingFailureLeg({ leg, legId, waveId, quiet }) {
 }
 
 /**
- * Run one leg end-to-end: session record → runHeadless (shared server) →
- * leg finalize. Never throws — always resolves to a run document.
+ * Run ONE leg attempt end-to-end: session record -> runHeadless (shared
+ * server) -> leg finalize. Faithful extraction of the pre-fallback `runLeg`
+ * body — same setup, same never-throws try/finally, same leg-started/
+ * leg-terminal emits (with `follow` + the M4 own-try/catch), same `directory`
+ * threading into runHeadless. Never throws — always resolves to a run
+ * document. Does NOT append spend (the caller owns that: `runLeg` appends
+ * once; `runLegWithFallback` appends per attempt via recordAttemptSpend).
+ * Adds `.reason` (alias of buildRunResult's `.error`) and `.legId` so the
+ * fallback loop reads a stable shape without re-deriving them.
  */
-async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce, directory }) {
+async function runSingleAttempt({ leg, legId, waveId, project, directory, follow, systemPrompt, userMessage, timeoutMs, agent, client, server, summaryLength, reasoning, quiet, foldNonce }) {
   const { IdleWatchdog } = require('../utils/idle-watchdog');
   const { markAborted } = require('../utils/session-abort');
   const { runHeadless } = require('../headless');
   const { SessionPaths, saveInitialContext } = require('./session-utils');
-  const { buildRunResult } = require('../utils/result-schema');
+  const { buildRunResult, durationBetween } = require('../utils/result-schema');
   const { createSessionMetadata } = require('./start');
+  const { emitLegStarted, emitLegTerminal } = require('../observe/events');
+  const { getSessionDir } = require('../session-manager');
 
-  // Setup + run under ONE try so ANY throw (session record creation, initial
-  // context write, watchdog arm, or the poll loop itself) becomes an error run
-  // document — the wave still aggregates and writes wave.json. This function
-  // must NEVER throw / reject for a leg error (fanout.js relies on this in its
-  // Promise.all so one leg cannot sink the whole wave).
   let legDir = null;
   let watchdog = null;
   let result;
+  // Captured inside the try below so a getSessionDir throw (invalid taskId)
+  // still becomes an error run document like every other setup failure; used
+  // again AFTER the try/finally closes to emit leg-terminal (M4: that emit is
+  // unguarded by the try, so it must never depend on something that could throw).
+  let waveDir = null;
   try {
     legDir = createSessionMetadata(legId, project, {
       model: leg.model, prompt: userMessage, noUi: true, agent: agent || 'build',
     });
+    waveDir = getSessionDir(project, waveId);
+    emitLegStarted(waveDir, waveId, legId, leg.model, leg.modelInput, follow);
     writeLegPatch(legDir, { parentWave: waveId, modelInput: leg.modelInput });
     saveInitialContext(legDir, systemPrompt, userMessage);
 
@@ -118,15 +132,25 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
   const status = legStatusFromResult(result);
   const summary = result.summary || null;
   const { resolveUsage } = require('../utils/pricing');
-  const usage = result && result.usage ? resolveUsage({ model: leg.model, usageTotals: result.usage }) : null;
-  // B24: cross-run spend ledger — one row per leg (mirrors start.js's single-run
-  // append). Best-effort; never let ledger bookkeeping affect the leg's own result.
-  if (usage) {
-    try {
-      const { appendSpend } = require('../utils/spend-ledger');
-      appendSpend({ taskId: legId, waveId, model: leg.model, mode: 'leg', usage });
-    } catch { /* best-effort */ }
-  }
+  // v4.4 Task 2 (B4) + v4.4.1 CA-1: a leg that made a SUBAGENT (`task`) call has
+  // spend in a child OpenCode session that is billed separately and is NOT
+  // rolled into the parent session's cost. runHeadless now WALKS those sessions
+  // (src/sidecar/child-sessions.js), so `subtreeUnknown` narrows from "this leg
+  // called `task`, therefore assume the worst" to what it should always have
+  // meant: the walk could not account for the subtree.
+  //
+  // The walk is authoritative when it ran — including in the direction that
+  // CLEARS the flag, which the name-string proxy could never do (backlog CA-5:
+  // a tool merely NAMED `task` that spawns nothing used to make an exact run
+  // report itself inexact). The proxy survives only as the fallback for a leg
+  // where the walk could not run at all.
+  const walked = result && result.subtree;
+  const subtreeUnknown = walked
+    ? !!walked.unknown
+    : !!(result && result.subagentToolCalls > 0);
+  const usage = result && result.usage
+    ? resolveUsage({ model: leg.model, usageTotals: result.usage, subtreeUnknown, subtree: walked || undefined })
+    : null;
   // If setup threw before the session dir existed, there is nothing on disk to
   // finalize — still resolve to an error run document so the wave aggregates.
   const legPatch = {
@@ -134,24 +158,54 @@ async function runLeg({ leg, legId, waveId, project, systemPrompt, userMessage,
     reason: result.error || undefined,
     completedAt: new Date().toISOString(),
     usage: usage || undefined,
+    // v4.4 B4 part 1: the leg completed with tool calls still live, so its
+    // OpenCode session may have kept working (and billing) afterwards. Travels
+    // with the leg so it is readable long after the run's stderr is gone.
+    toolSettleTimedOut: (result && result.toolSettleTimedOut) || undefined,
   };
   let finalMeta = legPatch;
   if (legDir) {
-    if (summary) {
-      fs.writeFileSync(SessionPaths.summaryFile(legDir), summary, { mode: 0o600 });
-    }
+    if (summary) { fs.writeFileSync(SessionPaths.summaryFile(legDir), summary, { mode: 0o600 }); }
     finalMeta = writeLegPatch(legDir, legPatch);
   }
-  const effectiveResult = finalMeta.status === 'aborted'
-    ? { ...result, aborted: true }
-    : result;
+  if (waveDir) {
+    try {
+      emitLegTerminal(waveDir, waveId, legId, {
+        model: leg.model, status: finalMeta.status,
+        durationMs: durationBetween(finalMeta.createdAt, finalMeta.completedAt),
+        usage: usage || null,
+      }, follow);
+    } catch { /* best-effort: a missing duration/emit never fails the leg */ }
+  }
+  const effectiveResult = finalMeta.status === 'aborted' ? { ...result, aborted: true } : result;
   if (!quiet) {
     process.stderr.write(`[fanout] leg ${legId} (${leg.modelInput}): ${finalMeta.status}\n`);
   }
-  return buildRunResult({
+  const doc = buildRunResult({
     taskId: legId, metadata: finalMeta, result: effectiveResult, summary,
     modelInput: leg.modelInput, sessionDir: legDir, waveId, usage,
   });
+  doc.reason = doc.error || null; // classifier alias (buildRunResult stores it as .error)
+  doc.legId = legId;
+  return doc;
+}
+
+/**
+ * Run one leg end-to-end. Thin wrapper: fallback OFF (the default) is a
+ * single `runSingleAttempt` + exactly one spend row (`attempt:0`, byte-
+ * identical to the pre-fallback appendSpend row); fallback ON delegates to
+ * `runLegWithFallback` (./fanout-leg-fallback). Never throws.
+ */
+async function runLeg(args) {
+  const { leg, legId, waveId, project, fallback } = args;
+  const { runLegWithFallback, recordAttemptSpend } = require('./fanout-leg-fallback');
+  if (fallback && fallback.enabled) { return runLegWithFallback(args); }
+  const doc = await runSingleAttempt(args);
+  recordAttemptSpend({ doc, leg, currentModel: leg.model, legId, waveId, project, attempt: 0, originalModel: leg.model }, {});
+  return doc;
 }
 
-module.exports = { legStatusFromResult, writeLegPatch, runLeg, buildRoutingFailureLeg };
+module.exports = {
+  legStatusFromResult, writeLegPatch, runLeg, buildRoutingFailureLeg, runSingleAttempt,
+  ...require('./fanout-leg-fallback'),
+};