amicus 4.2.1 → 4.4.0

package/src/sidecar/fanout-retry.js

@@ -0,0 +1,208 @@
+// src/sidecar/fanout-retry.js
+'use strict';
+
+/**
+ * @module fanout-retry
+ * `fanout --retry-failed <waveId>` — relaunch ONLY the dead legs of a prior
+ * wave as a NEW linked wave, using each failed leg's own saved initial
+ * context for a byte-identical retry (spec 6.1). Split out of fanout.js
+ * (⚠️ DE-ROT B1): fanout.js is hard-gated at 300 lines and near the cap —
+ * inlining this ~120-line surface would blow it past the limit. Mirrors the
+ * fanout-leg-fallback.js extraction precedent (Task 18).
+ * `wave.json` is NEVER touched by this module — all linkage (retryOf /
+ * retriedBy / retry-started event / effective block) is additive, living in
+ * metadata.json (mutable via writeWaveMetadata) and the in-memory wave doc.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Terminal, non-complete leg statuses eligible for --retry-failed. */
+const ELIGIBLE_RETRY = new Set(['error', 'timeout', 'crashed', 'aborted', 'idle-timeout']);
+
+/**
+ * Parse an initial_context.md written by saveInitialContext (session-utils.js:69):
+ *   `# System Prompt\n\n<sys>\n\n# User Message (Task)\n\n<user>`
+ * Returns null for any file that does not match that exact framing (legacy legs
+ * or a hand-edited file) so the caller falls back to briefing.md at launch time.
+ * @returns {{systemPrompt: string, userMessage: string}|null}
+ */
+function parseInitialContext(ctx) {
+  const head = '# System Prompt\n\n';
+  const marker = '\n\n# User Message (Task)\n\n';
+  if (!ctx.startsWith(head)) { return null; }
+  const mi = ctx.indexOf(marker, head.length);
+  if (mi === -1) { return null; }
+  return { systemPrompt: ctx.slice(head.length, mi), userMessage: ctx.slice(mi + marker.length) };
+}
+
+/**
+ * Plan a --retry-failed relaunch (spec 6.1). Pure over disk: reads the original
+ * wave + leg metadata, selects terminal non-complete legs (optionally filtered
+ * by --models), and loads each leg's saved initial context for a byte-identical
+ * retry. Refuses while the original wave is still running.
+ * @returns {{eligible: Array<{legId, model, systemPrompt, userMessage, hadSavedContext}>, error?: string}}
+ */
+function buildRetryPlan(origWaveId, project, { models } = {}) {
+  const { getSessionDir } = require('../session-manager');
+  const { SessionPaths } = require('./session-utils');
+  const waveDir = getSessionDir(project, origWaveId);
+  let waveMeta;
+  try { waveMeta = JSON.parse(fs.readFileSync(path.join(waveDir, 'metadata.json'), 'utf-8')); }
+  catch { return { eligible: [], error: `wave ${origWaveId} not found` }; }
+  if (waveMeta.type !== 'wave') { return { eligible: [], error: `${origWaveId} is not a fan-out wave` }; }
+  if (waveMeta.status === 'running') { return { eligible: [], error: `wave ${origWaveId} is still running — wait for it to finish before retrying` }; }
+
+  const wanted = models && models.length ? new Set(models) : null;
+  const eligible = [];
+  for (const legId of (waveMeta.legs || [])) {
+    let m;
+    try { m = JSON.parse(fs.readFileSync(path.join(getSessionDir(project, legId), 'metadata.json'), 'utf-8')); }
+    catch { continue; }
+    if (!ELIGIBLE_RETRY.has(m.status)) { continue; }
+    const model = m.modelInput || m.model;
+    if (wanted && !wanted.has(model) && !wanted.has(m.model)) { continue; }
+    // load saved initial context (system + user) for a byte-identical retry
+    const legDir = getSessionDir(project, legId);
+    let systemPrompt = null;
+    let userMessage = null;
+    let hadSavedContext = false;
+    try {
+      const parsed = parseInitialContext(fs.readFileSync(SessionPaths.contextFile(legDir), 'utf-8'));
+      if (parsed) { ({ systemPrompt, userMessage } = parsed); hadSavedContext = true; }
+    } catch { /* legacy leg — fall back to briefing.md at launch time */ }
+    eligible.push({ legId, model, systemPrompt, userMessage, hadSavedContext });
+  }
+  return { eligible };
+}
+
+/**
+ * Launch a --retry-failed wave (spec 6.1). New linked wave, byte-identical
+ * relaunch of the original wave's failed legs. Additive linkage only:
+ *   - new wave metadata + doc gain `retryOf:<origWaveId>`
+ *   - each new leg metadata gains `retryOf:<origLegId>`
+ *   - the ORIGINAL wave metadata gains `retriedBy:[<newWaveId>,...]` (mutable,
+ *     abort-wins via writeWaveMetadata) — wave.json is NOT touched
+ *   - a `retry-started` event lands in the new wave dir
+ *   - the doc gains an `effective` block (per original failed slot: the
+ *     retry leg's latest status + usage)
+ * Linkage is gated on `runFanout` actually producing a wave: a pre-flight
+ * failure inside runFanout (wave:null, e.g. budget gate) must leave the
+ * original wave's metadata untouched — no false retriedBy record for a
+ * retry that never launched. runFanout suppresses its OWN stdout doc-print
+ * for a retry launch (its `options.retryOfWaveId` gate — see fanout.js),
+ * so this function owns printing the enriched doc (retryOf + effective),
+ * exactly once, respecting the caller's --json/--quiet.
+ * @param {object} [opts.runFanout] - injected for tests (defaults to runFanout)
+ * @returns {Promise<{wave: object|null, exitCode: number, errorDoc?: object}>}
+ */
+async function retryFailedWave(origWaveId, project, opts = {}) {
+  const { runFanout, deriveLegIds, writeWaveMetadata } = require('./fanout');
+  const { generateTaskId } = require('./start');
+  const { getSessionDir } = require('../session-manager');
+  const { appendEvent } = require('../observe/events');
+  const { writeFileAtomic } = require('../utils/atomic-write');
+  const { buildWaveResult } = require('../utils/result-schema');
+  const runFanoutImpl = opts.runFanout || runFanout;
+
+  const plan = buildRetryPlan(origWaveId, project, { models: opts.models });
+  if (plan.error) {
+    // no-console (repo lint gate): this module isn't on the CLI-output
+    // allowlist (unlike fanout.js) — write directly, matching failJson's
+    // established process.stdout/stderr.write pattern for JSON/human output.
+    if (!opts.quiet) { process.stderr.write(plan.error + '\n'); }
+    const { buildErrorDoc } = require('../utils/error-doc');
+    return { wave: null, errorDoc: buildErrorDoc({ code: 'BAD_ARGS', message: plan.error }), exitCode: 1 };
+  }
+  if (plan.eligible.length === 0) {
+    if (!opts.quiet) {
+      if (opts.json) {
+        // valid-JSON no-op doc (Finding 5) — reuses the wave schema so a
+        // --json caller's stdout stays machine-parseable either way.
+        const noopDoc = {
+          ...buildWaveResult({ waveId: origWaveId, legs: [], status: 'complete' }),
+          retryOf: origWaveId, effective: [], note: 'no failed legs',
+        };
+        process.stdout.write(JSON.stringify(noopDoc, null, 2) + '\n');
+      } else {
+        process.stdout.write(`No failed legs to retry in ${origWaveId} — nothing to do.\n`);
+      }
+    }
+    return { wave: null, exitCode: 0 };
+  }
+
+  const origWaveDir = getSessionDir(project, origWaveId);
+  let briefing = '';
+  try { briefing = fs.readFileSync(path.join(origWaveDir, 'briefing.md'), 'utf-8'); } catch { /* legacy — empty */ }
+
+  const newWaveId = generateTaskId();
+  const models = plan.eligible.map(e => e.model);
+  const retryContexts = plan.eligible.map(e => ({
+    origLegId: e.legId, systemPrompt: e.systemPrompt, userMessage: e.userMessage, hadSavedContext: e.hadSavedContext,
+  }));
+
+  // Launch the new wave. `retryContexts`/`retryOfWaveId` are additive options;
+  // runFanout uses each slot's saved system/user verbatim when present (Step 4b)
+  // and threads retryOfWaveId onto each leg so Task 1's append tags the rows.
+  // `models` MUST be the comma-separated STRING runFanout's own validator
+  // expects (parseModelsList/validateFanoutModels) — an array silently fails
+  // every leg pre-flight (BAD_ARGS), matching run-launch.js:41's precedent.
+  // Strip our own injection key so it is never forwarded.
+  const fanoutOpts = { ...opts, models: models.join(','), prompt: briefing, project, waveId: newWaveId, retryContexts, retryOfWaveId: origWaveId };
+  delete fanoutOpts.runFanout;
+  const { wave, exitCode } = await runFanoutImpl(fanoutOpts);
+
+  // No wave produced (pre-flight failure inside runFanout) — nothing
+  // launched, so no linkage may be recorded on the original wave.
+  if (!wave) { return { wave: null, exitCode }; }
+
+  // --- additive linkage (best-effort; a missing dir never throws) ---
+  const newWaveDir = getSessionDir(project, newWaveId);
+  writeWaveMetadata(newWaveDir, { retryOf: origWaveId });
+  wave.retryOf = origWaveId;
+
+  const newLegIds = deriveLegIds(newWaveId, plan.eligible.length);
+  newLegIds.forEach((newLegId, i) => {
+    const mp = path.join(getSessionDir(project, newLegId), 'metadata.json');
+    try {
+      const m = JSON.parse(fs.readFileSync(mp, 'utf-8'));
+      m.retryOf = retryContexts[i].origLegId;
+      writeFileAtomic(mp, JSON.stringify(m, null, 2), { mode: 0o600 });
+    } catch { /* leg dir absent (short-circuited wave) — best-effort */ }
+  });
+
+  // original wave gains retriedBy:[...] (dedup; abort-wins merge)
+  let origMeta = {};
+  try { origMeta = JSON.parse(fs.readFileSync(path.join(origWaveDir, 'metadata.json'), 'utf-8')); } catch { /* corrupt */ }
+  const retriedBy = Array.isArray(origMeta.retriedBy) ? origMeta.retriedBy.slice() : [];
+  if (!retriedBy.includes(newWaveId)) { retriedBy.push(newWaveId); }
+  writeWaveMetadata(origWaveDir, { retriedBy });
+
+  // milestone: retry-started into the NEW wave dir (never-throws appendEvent)
+  appendEvent(newWaveDir, { event: 'retry-started', id: newWaveId, retryOf: origWaveId, legIds: newLegIds });
+
+  // effective block: original failed slot -> the retry leg's latest status/usage
+  const legs = Array.isArray(wave.legs) ? wave.legs : [];
+  const effective = plan.eligible.map((e, i) => ({
+    origLegId: e.legId, model: e.model,
+    status: legs[i] ? legs[i].status : 'unknown',
+    usage: legs[i] ? (legs[i].usage || null) : null,
+  }));
+  wave.effective = effective;
+
+  // runFanout suppressed its own stdout print for this retry launch (its
+  // options.retryOfWaveId gate) — print the enriched doc (retryOf +
+  // effective now attached) ONCE, respecting --json/--quiet (Finding 3).
+  if (!opts.quiet) {
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(wave, null, 2) + '\n');
+    } else {
+      const { formatWaveHuman } = require('./fanout-output');
+      process.stdout.write(formatWaveHuman(wave) + '\n');
+    }
+  }
+
+  return { wave, exitCode };
+}
+
+module.exports = { ELIGIBLE_RETRY, parseInitialContext, buildRetryPlan, retryFailedWave };

package/src/sidecar/fanout-validate.js

@@ -1,6 +1,8 @@
 // src/sidecar/fanout-validate.js
 'use strict';
 
+const { logger } = require('../utils/logger');
+
 /**
  * @module fanout-validate
  * Fan-out --models parsing + per-leg gateway routing. Split out of fanout.js
@@ -32,10 +34,18 @@ function parseModelsList(modelsArg) {
  * exceeding the leg-count cap — remain wave-level fatal and are returned as
  * a top-level `{error, code}` (nothing to route yet at that point).
  * @param {string} modelsArg - Raw --models value
- * @param {{noValidateModel?: boolean, gatewayMode?: string}} [opts]
+ * @param {{noValidateModel?: boolean, gatewayMode?: string, fallback?: object,
+ *   catalog?: Array}} [opts] `fallback`/`catalog` (v4.3 Task 18, spec §6.2) are
+ *   additive: when `fallback.enabled`, every resolved primary's chain
+ *   candidates are pre-resolved so the shared server can register them (see
+ *   `serverModels` below); omitted/disabled callers are unaffected.
  * @returns {Promise<{legs: Array<{modelInput: string, ok: boolean, model?: string,
- *   pricing?: object, gateway?: string, provenance?: object, routeResult?: object}>}
- *   | {error: string, code: string}>}
+ *   pricing?: object, gateway?: string, provenance?: object, routeResult?: object}>,
+ *   serverModels?: string[]}
+ *   | {error: string, code: string}>} `serverModels` (additive) is the UNION of
+ *   every resolved primary + its fallback-chain candidates' executable ids —
+ *   present only when `opts.fallback.enabled`; the caller falls back to
+ *   `okLegs.map(l => l.model)` when absent (unchanged today).
  */
 async function validateFanoutModels(modelsArg, opts = {}) {
   const raw = parseModelsList(modelsArg);
@@ -75,7 +85,35 @@ async function validateFanoutModels(modelsArg, opts = {}) {
       legs.push({ modelInput, ok: false, routeResult });
     }
   }
-  return { legs };
+
+  // v4.3 Task 18 (spec §6.2 sole-input invariant): when fallback substitution
+  // is enabled, pre-resolve every resolved primary's chain candidates and
+  // register the UNION of primary + candidate executable ids on the shared
+  // server — a substitute that never runs must still be an allowed model if
+  // one IS selected mid-wave. An unresolvable candidate is DROPPED (logged),
+  // never a wave failure: registration is config, not spend.
+  let serverModels;
+  if (opts.fallback && opts.fallback.enabled) {
+    const { deriveChain } = require('./fallback-chains');
+    const ids = new Set(legs.filter(l => l.ok).map(l => l.model));
+    for (const leg of legs) {
+      if (!leg.ok) { continue; }
+      const chain = deriveChain(leg.model, { config: { chains: opts.fallback.chains }, catalog: opts.catalog });
+      for (const candidate of chain) {
+        let route;
+        try {
+          route = await resolveRouteForLaunch({ model: candidate, gatewayMode, source: 'fallback', allowSelection: false, validateModel });
+        } catch { route = { kind: 'error' }; }
+        if (route.kind === 'resolved') {
+          ids.add(route.executableId);
+        } else {
+          logger.warn('Fallback chain candidate failed to route — dropped from server registration', { primary: leg.model, candidate });
+        }
+      }
+    }
+    serverModels = [...ids];
+  }
+  return { legs, serverModels };
 }
 
 module.exports = { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels };

package/src/sidecar/fanout.js

@@ -57,7 +57,9 @@ function writeWaveMetadata(waveDir, patch) {
  *   contextTurns?, contextSince?, contextMaxTokens?, mcp?, mcpConfig?, noMcp?,
  *   excludeMcp?, noValidateModel?, gatewayMode? (#61 Task 7.3: --gateway merged
  *   with routing.prefer, applied per leg), json?, client?, quiet? (suppress
- *   stdout — tests)
+ *   stdout — tests), councilRunId? / councilName? (v4.3 §7.2: stamped onto legs),
+ *   fallback? / catalog? (v4.3 Task 18 §6.2: opt-in substitution; off/absent unchanged),
+ *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -70,11 +72,15 @@ async function runFanout(options) {
   const { generateFoldNonce } = require('../utils/fold-marker');
   const { installSignalAbort, markAborted } = require('../utils/session-abort');
   const { getSessionDir } = require('../session-manager');
+  const { emitWaveStarted, emitWaveTerminal } = require('../observe/events');
 
   const project = options.project || process.cwd();
   const createdAt = new Date().toISOString();
+  // v4.3 Task 13: live stderr mirror of this wave's own events, in-process
+  // (no tail). Off by default; every emit* call below threads it through.
+  const follow = options.follow ? require('../observe/follow').createFollowPrinter({ json: options.json }) : null;
   const emit = (doc) => {
-    if (options.quiet) { return; }
+    if (options.quiet || options.retryOfWaveId) { return; } // v4.3 T19 FW1#3: retry launches print via fanout-retry.js instead
     if (options.json) {
       console.log(JSON.stringify(doc, null, 2));
     } else {
@@ -108,30 +114,28 @@ async function runFanout(options) {
   const validated = await validateFanoutModels(options.models, {
     noValidateModel: options.noValidateModel,
     gatewayMode: options.gatewayMode,
+    fallback: options.fallback, // v4.3 Task 18 §6.2: serverModels union only when enabled
+    catalog: options.catalog,
   });
   if (validated.error) { return failPre(validated.code || 'BAD_ARGS', validated.error); }
   const legs = validated.legs;
+  // v4.3 §7.2: stamp council attribution onto every leg (fanout-leg.js's
+  // existing appendSpend reads it); no-op for every non-council caller.
+  if (options.councilRunId || options.councilName) {
+    legs.forEach(l => { l.councilRunId = options.councilRunId; l.councilName = options.councilName; });
+  }
   const okLegs = legs.filter(l => l.ok);
   // FIX 2 (#61 whole-branch review): a leg's migration notice has no CLI
-  // stderr to land on (fanout is one process resolving many legs, not one
-  // launch) — surface it on the wave doc instead, deduped in case two legs
-  // for the same vendor happen to both migrate (only the first ever fires
-  // since markMigrationNotified is one-shot per vendor, but dedupe defensively).
+  // stderr to land on — surface it on the wave doc instead, deduped in case
+  // two legs for the same vendor happen to both migrate.
   const notices = [...new Set(legs.map(l => l.notice).filter(Boolean))];
 
   // 1b. Budget gate (pre-creation; refuse before spending). Only legs that
   // will actually run cost anything — a leg that never routed never spends.
-  if (!options.noCostGate) {
-    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 budget = checkBudget(okLegs, { maxCostPerMtok, maxCost: options.maxCost !== null && options.maxCost !== undefined ? options.maxCost : cfg.maxCost, promptChars });
-    if (!budget.ok) {
-      return failPre(ERROR_CODES.BUDGET_EXCEEDED, 'Error: budget gate refused the wave', formatBudgetError(budget));
-    }
-  }
+  // Lives in ./fanout-budget so the v4.4 concurrency reservation seam has room;
+  // that module's docblock carries the why.
+  const preflight = require('./fanout-budget').preflightBudget(okLegs, options);
+  if (!preflight.ok) { return failPre(ERROR_CODES.BUDGET_EXCEEDED, preflight.message, preflight.hint); }
 
   // 2. Wave record
   const waveId = options.waveId || generateTaskId();
@@ -146,14 +150,12 @@ async function runFanout(options) {
     promptMeta: options.promptMeta || null,
     pid: process.pid, project, createdAt,
   });
+  emitWaveStarted(waveDir, waveId, legs.map(l => (l.ok ? l.model : l.modelInput)), legIds, follow);
 
   // 2b. All legs failed to route (#61 perf): no leg will ever touch the
-  // shared server, so starting one (and immediately tearing it down) is pure
-  // waste. Short-circuit straight to the same routing-failure wave the
-  // normal path would eventually produce — same per-leg docs
-  // (buildRoutingFailureLeg), same aggregation (buildWaveResult /
-  // waveStatusFromLegs via the default status param), same exit-code mapping
-  // (waveExitCode) — just without the server round-trip.
+  // shared server, so starting one (and tearing it down) is pure waste.
+  // Short-circuit to the same routing-failure wave the normal path would
+  // eventually produce — same per-leg docs, aggregation, and exit mapping.
   if (okLegs.length === 0) {
     const legDocs = legs.map((leg, i) => buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }));
     const completedAt = new Date().toISOString();
@@ -163,8 +165,11 @@ async function runFanout(options) {
     const wavePath = path.join(waveDir, 'wave.json');
     writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
     writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+    const routingExitCode = waveExitCode(wave.status);
+    emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode: routingExitCode }, follow);
+    await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode: routingExitCode, project }, options.onCompleteDeps);
     emit(wave);
-    return { wave, exitCode: waveExitCode(wave.status) };
+    return { wave, exitCode: routingExitCode };
   }
 
   // 3. Context + prompts built ONCE (model-independent)
@@ -195,7 +200,7 @@ async function runFanout(options) {
   });
   let client, server;
   try {
-    ({ client, server } = await startOpenCodeServer(mcpServers, { models: okLegs.map(l => l.model) }));
+    ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
   } catch (err) {
     writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
     return errorWave(waveId, `Failed to start server: ${err.message}`);
@@ -225,12 +230,10 @@ async function runFanout(options) {
     },
   });
 
-  // 6. Launch all ROUTABLE legs concurrently (runLeg never rejects). A leg
-  // that failed to route (leg.ok === false) never touches the shared server —
-  // it resolves immediately to an error run document (buildRoutingFailureLeg)
-  // in its own slot, so it fails only itself, never the sibling legs or the
-  // whole wave (#61 Task 7.3).
-  const heartbeat = options.quiet
+  // 6. Launch all ROUTABLE legs concurrently (runLeg never rejects). A leg that
+  // failed to route (leg.ok === false) resolves to an error run doc in its own
+  // slot (buildRoutingFailureLeg), failing only itself, never the wave (#61).
+  const heartbeat = (options.quiet || options.follow)
     ? { stop() {} }
     : createWaveHeartbeat(
         legs.map((leg, i) => ({ label: leg.modelInput || leg.model, dir: legDirs[i] })),
@@ -240,15 +243,23 @@ async function runFanout(options) {
   const reasoning = options.thinking ? { effort: options.thinking } : undefined;
   let legDocs;
   try {
-    legDocs = await Promise.all(legs.map((leg, i) => (leg.ok
-      ? runLeg({
-          leg, legId: legIds[i], waveId, project, systemPrompt, userMessage,
-          timeoutMs, agent: options.agent, client, server,
-          summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
-          foldNonce, directory: options.directory,
-        })
-      : Promise.resolve(buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }))
-    )));
+    // retryContexts/retryOfWaveId (v4.3 Task 19): absent on a normal wave, so
+    // every leg below falls back to the wave-wide prompt — byte-identical.
+    legDocs = await Promise.all(legs.map((leg, i) => {
+      if (!leg.ok) { return Promise.resolve(buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet })); }
+      const rc = options.retryContexts && options.retryContexts[i];
+      const saved = rc && rc.hadSavedContext;
+      return runLeg({
+        leg: options.retryOfWaveId ? { ...leg, retryOfWaveId: options.retryOfWaveId } : leg,
+        legId: legIds[i], waveId, project,
+        systemPrompt: saved ? rc.systemPrompt : systemPrompt,
+        userMessage: saved ? rc.userMessage : userMessage,
+        timeoutMs, agent: options.agent, client, server,
+        summaryLength: options.summaryLength, reasoning, quiet: options.quiet,
+        foldNonce, directory: options.directory, follow,
+        fallback: options.fallback, catalog: options.catalog,
+      });
+    }));
   } finally {
     heartbeat.stop();
     uninstallSignals();
@@ -264,10 +275,12 @@ async function runFanout(options) {
   const wavePath = path.join(waveDir, 'wave.json');
   writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
   writeWaveMetadata(waveDir, { status: wave.status, completedAt });
-  emit(wave);
   const exitCode = signalled
     ? (signalled === 'SIGINT' ? 130 : 143)
     : waveExitCode(wave.status);
+  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
+  await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode, project }, options.onCompleteDeps);
+  emit(wave);
   return { wave, exitCode };
 }
 

package/src/sidecar/progress.js

@@ -113,6 +113,8 @@ function isStalled(lastActivityMs) {
 function writeProgress(sessionDir, stage, extra = {}) {
   const progressPath = path.join(sessionDir, 'progress.json');
   const data = {
+    schemaVersion: 1,
+    type: 'progress',
     stage,
     stageLabel: STAGE_LABELS[stage] || stage,
     updatedAt: new Date().toISOString(),
@@ -224,6 +226,9 @@ function readProgress(sessionDir) {
   if (stage !== undefined) {
     result.stage = stage;
   }
+  if (progress && progress.usage) {
+    result.usage = progress.usage;
+  }
   return result;
 }
 

package/src/sidecar/resume.js

@@ -248,6 +248,18 @@ async function resumeSidecar(options) {
     } else {
       finalizeSession(sessionDir, summary, project, updatedMetadata, { quietStdout: json, status: terminal.status });
     }
+    // v4.3: attribute resume spend (C9/E4). Reload metadata, write usage + append
+    // a ledger row (status: statusFromResult, matching start.js — not terminal.status).
+    {
+      const { finalizeSpendForReopen } = require('./continue');
+      const { statusFromResult } = require('../utils/result-schema');
+      const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+      const { usage } = finalizeSpendForReopen({
+        taskId, model: metadata.model, mode: headless ? 'headless' : 'interactive',
+        op: 'resume', 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');

package/src/sidecar/start.js

@@ -257,7 +257,19 @@ async function startSidecar(options) {
     // this run's own success must never hinge on ledger bookkeeping either way.
     try {
       const { appendSpend } = require('../utils/spend-ledger');
-      appendSpend({ taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive', usage: runUsage });
+      const { statusFromResult } = require('../utils/result-schema');
+      appendSpend({
+        taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive', usage: runUsage,
+        op: 'start', status: statusFromResult(result), project: effectiveProject,
+        // ⚠️ DE-ROT: `metadata` is NOT in scope at startSidecar's finalize site — the objects
+        // there are `meta` (createSessionMetadata result) and `m`; `metadata` is a local only
+        // inside createSessionMetadata. Reading `metadata.gateway` throws a ReferenceError the
+        // best-effort catch swallows → EVERY start-mode spend row silently dropped + start-json.test.js
+        // goes red. Use an in-scope value (spec-complete for direct/openrouter):
+        gateway: String(model).startsWith('openrouter/') ? 'openrouter' : 'direct',
+        // (To also attribute v4.2 'local': thread the resolved route gateway — dropped today at
+        // cli-handlers-run.js:47 — into createSessionMetadata and read `meta.gateway`, as continue.js:111 does.)
+      });
     } catch { /* best-effort */ }
   }