amicus 4.4.0 → 4.5.0

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

@@ -48,35 +48,83 @@ function recordAttemptSpend({ doc, leg, currentModel, legId, waveId, project, at
   } catch { /* best-effort */ }
 }
 
+/** Add up a list of token blocks, key by key. */
+function foldTokens(blocks) {
+  const tokens = {};
+  for (const t of blocks) {
+    for (const [k, v] of Object.entries(t || {})) { tokens[k] = (tokens[k] || 0) + (v || 0); }
+  }
+  return tokens;
+}
+
 /**
- * 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.
+ * Add up a list of resolved cost objects, tagging source 'mixed' when they
+ * differ — matching formatCost's `~` behavior so a summed cost never reads as
+ * authoritative. `none` is returned when not one of them carried a number,
+ * because a sum of nothing is not $0.
  */
-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 = {};
+function foldCosts(costs, none) {
   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;
+  for (const c of costs) {
+    if (c && typeof c.amount === 'number') {
+      amount += c.amount;
       anyCost = true;
-      if (a.usage.cost.source) { sources.add(a.usage.cost.source); }
+      if (c.source) { sources.add(c.source); }
     }
   }
-  const cost = anyCost
-    ? { amount, currency: 'USD', source: sources.size > 1 ? 'mixed' : (sources.values().next().value || 'reported') }
-    : null;
-  return { tokens, cost };
+  if (!anyCost) { return none; }
+  return { amount, currency: 'USD',
+    source: sources.size > 1 ? 'mixed' : (sources.values().next().value || 'reported') };
+}
+
+/**
+ * Fold a leg's attempts[] into ONE usage block. A single-attempt leg returns that
+ * attempt's usage verbatim (no behavior change for non-fallback legs).
+ *
+ * ⚠️ v4.4.1 A1. This used to `return { tokens, cost }` — silently DISCARDING every
+ * other key resolveUsage puts on a usage block. The casualty was `subtreeUnknown`:
+ * a leg that fell back to a substitute AND left an unattributable subagent subtree
+ * lost the flag here, `sumWaveUsage` never counted it in `subtreeUnknownLegs`, and
+ * run.json reported `costExact: true` for a total that was not — precisely the lie
+ * `costExact` exists to prevent, and reachable only on the fallback path. So the
+ * fold now starts from a merge of every attempt's usage and overwrites only the
+ * keys it has a real opinion about; anything added to the block later survives by
+ * default instead of being dropped by omission.
+ *
+ * HOW EACH KIND OF KEY FOLDS, and why:
+ *  - `tokens` / `cost` — SUMMED. They are per-attempt measurements of one leg's
+ *    total consumption; every attempt really was billed.
+ *  - `subtreeUnknown` — OR'd. It is a claim about EXACTNESS, not a quantity: if
+ *    even one attempt left a subtree it could not account for, the leg's total is
+ *    a floor, and that stays true no matter how exact the other attempts were.
+ *    Any other fold (last-wins, or requiring every attempt to agree) would let a
+ *    later clean attempt erase an earlier attempt's admitted gap.
+ *  - `subtree` — SUMMED, not last-wins. Two attempts can each have walked and
+ *    PRICED child sessions, and both spent real money; keeping only the last one's
+ *    measurement would re-open the same under-report one level down, which
+ *    sumWaveUsage's CA-1 docblock explicitly refuses to make.
+ *  - anything else — last attempt wins, which is what the merge already does.
+ */
+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 usages = withUsage.map(a => a.usage);
+  const out = Object.assign({}, ...usages);
+  out.tokens = foldTokens(usages.map(u => u.tokens));
+  out.cost = foldCosts(usages.map(u => u.cost), null);
+  const subtrees = usages.map(u => u.subtree).filter(Boolean);
+  if (subtrees.length > 0) {
+    out.subtree = {
+      sessions: subtrees.reduce((n, s) => n + (s.sessions || 0), 0),
+      tokens: foldTokens(subtrees.map(s => s.tokens)),
+      cost: foldCosts(subtrees.map(s => s.cost), { amount: null, currency: 'USD', source: 'unknown' }),
+    };
+  }
+  if (usages.some(u => u.subtreeUnknown)) { out.subtreeUnknown = true; }
+  return out;
 }
 
 /**

package/src/sidecar/fanout-leg.js

@@ -162,6 +162,12 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     // 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,
+    // v4.4.1 LC-2: whether the ceiling's abort landed. Deliberately NOT
+    // `|| undefined` like the flag above — a `false` here is the whole point
+    // ("we tried to stop it and could not; it may still be billing") and must
+    // survive onto disk. runHeadless sets it only when the ceiling was hit, so
+    // passing it through unchanged keeps a clean leg carrying neither field.
+    toolSettleAborted: result ? result.toolSettleAborted : undefined,
   };
   let finalMeta = legPatch;
   if (legDir) {

package/src/sidecar/fanout-signals.js

@@ -0,0 +1,61 @@
+// src/sidecar/fanout-signals.js
+'use strict';
+
+/**
+ * @module fanout-signals
+ * A fan-out wave's signal-abort handler, extracted from fanout.js for the
+ * 300-line size gate (v4.4.1 fix wave, finding F3 needed room in fanout.js).
+ * Pure move plus the force-exit reaper described below — same markers, same
+ * ordering, same watchdog window.
+ *
+ * The contract fanout.js relies on: mark the wave and every leg aborted, then
+ * let NORMAL control flow finalize. Legs see their abort marker within one poll
+ * (~2s) and settle, so the caller still writes wave.json and emits a parseable
+ * aborted document. The force-exit watchdog is only a backstop for a wedged leg.
+ */
+
+const { logger } = require('../utils/logger');
+const { installSignalAbort, markAborted } = require('../utils/session-abort');
+const { armExitWatchdog, exitReaping } = require('../utils/lifecycle');
+
+/** Force-exit backstop window; comfortably outlives close()'s ~2s escalation. */
+const WAVE_FORCE_EXIT_MS = 10000;
+
+/**
+ * @param {{waveId: string, waveDir: string, legDirs: string[], server: object,
+ *   externalServer: boolean}} args
+ * @returns {{uninstall: Function, signal: () => (string|null)}} `signal()` is a
+ *   GETTER — the handler mutates it between awaits, so a snapshot would miss it.
+ */
+function installWaveAbort({ waveId, waveDir, legDirs, server, externalServer }) {
+  let signalled = null;
+  const uninstall = installSignalAbort({
+    onAbort: (signal) => {
+      const code = signal === 'SIGINT' ? 130 : 143;
+      if (signalled) { process.exit(code); } // second signal: exit NOW
+      signalled = signal;
+      logger.warn('Signal received — aborting wave', { waveId, signal });
+      markAborted(waveDir, signal);
+      for (const dir of legDirs) { markAborted(dir, signal); }
+      // close() is async (B06 escalation); this handler stays sync, so
+      // fire-and-forget with a rejection guard.
+      // ⚠️ close site 1 of 2 — NEVER an injected server: it belongs to the
+      // council run, whose own signal handler tears it down in finalize().
+      // Closing it here would kill every sibling and later wave in the run.
+      if (!externalServer) { try { server.close().catch(() => {}); } catch { /* best-effort */ } }
+      // ⚠️ …but a FORCE exit must not orphan it either (F3). We no longer close
+      // an injected server above, so if this watchdog fires before the owner's
+      // finalize() runs, the OpenCode process outlives the parent — still
+      // holding the SQLite lock this whole task exists to stop contending on.
+      // exitReaping SIGTERMs its Go pid on the way out. An OWNED server needs
+      // no hook: close() above already signalled it.
+      armExitWatchdog(code, WAVE_FORCE_EXIT_MS, {
+        log: (m, meta) => logger.debug(m, meta),
+        ...(externalServer ? { exit: exitReaping(server) } : {}),
+      });
+    },
+  });
+  return { uninstall, signal: () => signalled };
+}
+
+module.exports = { installWaveAbort, WAVE_FORCE_EXIT_MS };

package/src/sidecar/fanout-wave-io.js

@@ -0,0 +1,75 @@
+// src/sidecar/fanout-wave-io.js
+'use strict';
+
+/**
+ * @module fanout-wave-io
+ * On-disk lifecycle of a WAVE document, split out of fanout.js to keep that
+ * file under the 300-line gate (v4.4.1 Task 0.5, which needed room for the
+ * external-server seam). Pure move — same writes, same order, same atomicity:
+ *
+ *   writeWaveMetadata  metadata.json read-merge-write, abort-wins
+ *   writeWaveDoc       wave.json, atomic (tmp + rename)
+ *   finishWave         the terminal path every completed wave funnels through:
+ *                      persist → checkpoint metadata → emit wave-terminal →
+ *                      fire --on-complete → print
+ *
+ * `finishWave` had two byte-identical copies in fanout.js (the all-legs-failed-
+ * to-route short circuit and the normal aggregation); they are one function here
+ * so a future change to the terminal contract cannot land on only one of them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomic } = require('../utils/atomic-write');
+
+/**
+ * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
+ * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
+ * to a softer status (same precedence rule as writeLegPatch — a signal/abort
+ * marker must never lose a write race against an in-flight init/finalize).
+ */
+function writeWaveMetadata(waveDir, patch) {
+  const metaPath = path.join(waveDir, 'metadata.json');
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
+  }
+  const safePatch = { ...patch };
+  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
+    delete safePatch.status;
+  }
+  const merged = { ...existing, ...safePatch };
+  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  return merged;
+}
+
+/**
+ * Persist a wave document atomically (tmp + rename).
+ * @returns {string} the wave.json path
+ */
+function writeWaveDoc(waveDir, wave) {
+  const wavePath = path.join(waveDir, 'wave.json');
+  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
+  return wavePath;
+}
+
+/**
+ * Terminal path for a wave that produced leg documents: persist wave.json,
+ * checkpoint metadata.json, emit wave-terminal, fire --on-complete, print.
+ * @param {{wave: object, waveDir: string, waveId: string, project: string,
+ *   exitCode: number, completedAt: string, follow: object|null, emit: Function,
+ *   onComplete?: string, onCompleteDeps?: object}} args
+ * @returns {Promise<{wave: object, exitCode: number}>}
+ */
+async function finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit, onComplete, onCompleteDeps }) {
+  const { emitWaveTerminal } = require('../observe/events');
+  const wavePath = writeWaveDoc(waveDir, wave);
+  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
+  await require('../observe/on-complete').fireWaveOnComplete(onComplete, wave,
+    { waveId, waveDir, wavePath, exitCode, project }, onCompleteDeps);
+  emit(wave);
+  return { wave, exitCode };
+}
+
+module.exports = { writeWaveMetadata, writeWaveDoc, finishWave };

package/src/sidecar/fanout.js

@@ -16,7 +16,10 @@ const { logger } = require('../utils/logger');
 const { runLeg, buildRoutingFailureLeg } = require('./fanout-leg');
 const { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels } = require('./fanout-validate');
 const { ERROR_CODES } = require('../utils/error-doc');
-const { writeFileAtomic } = require('../utils/atomic-write');
+// Wave-document persistence lives in ./fanout-wave-io (size-gate split, v4.4.1
+// Task 0.5). writeWaveMetadata is re-exported below — fanout-retry.js and the
+// fanout tests import it from here.
+const { writeWaveMetadata, writeWaveDoc, finishWave } = require('./fanout-wave-io');
 
 /**
  * Derive leg task IDs: <waveId>-1 .. <waveId>-N (matches TASK_ID_PATTERN).
@@ -28,27 +31,6 @@ function deriveLegIds(waveId, count) {
   return Array.from({ length: count }, (_, i) => `${waveId}-${i + 1}`);
 }
 
-/**
- * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
- * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
- * to a softer status (same precedence rule as writeLegPatch — a signal/abort
- * marker must never lose a write race against an in-flight init/finalize).
- */
-function writeWaveMetadata(waveDir, patch) {
-  const metaPath = path.join(waveDir, 'metadata.json');
-  let existing = {};
-  if (fs.existsSync(metaPath)) {
-    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
-  }
-  const safePatch = { ...patch };
-  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
-    delete safePatch.status;
-  }
-  const merged = { ...existing, ...safePatch };
-  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
-  return merged;
-}
-
 /**
  * Run a fan-out wave. Spec §4.3.
  * @param {object} options - models, prompt, promptMeta, waveId?, project, agent?,
@@ -59,7 +41,17 @@ function writeWaveMetadata(waveDir, patch) {
  *   with routing.prefer, applied per leg), json?, client?, quiet? (suppress
  *   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)
+ *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical),
+ *   pack? (v4.5 Task 13: {name,version,hash,source} record when launched via
+ *     --pack; absent/null -> omitted from wave metadata.json/wave.json, not stored as null.
+ *     v4.5 final-review F2: when absent, wave.json still inherits a pack the caller
+ *     pre-seeded onto this wave dir's metadata.json before calling runFanout — see
+ *     `metaPack` below. That is how an MCP-spawned child, which never receives
+ *     --pack itself, still ends up with the pack on its wave.json),
+ *   server? + serverClient? (v4.4.1 Task 0.5: an ALREADY-STARTED OpenCode server
+ *     to run this wave's legs on. Both or neither. When supplied this wave never
+ *     starts a server and never closes one — see the seam comment in step 4.
+ *     NOT `client`, which is the client TYPE string on this function.)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -70,9 +62,9 @@ async function runFanout(options) {
   const { buildContext } = require('./context-builder');
   const { buildPrompts } = require('../prompt-builder');
   const { generateFoldNonce } = require('../utils/fold-marker');
-  const { installSignalAbort, markAborted } = require('../utils/session-abort');
+  const { installWaveAbort } = require('./fanout-signals');
   const { getSessionDir } = require('../session-manager');
-  const { emitWaveStarted, emitWaveTerminal } = require('../observe/events');
+  const { emitWaveStarted } = require('../observe/events'); // wave-terminal is emitted by finishWave
 
   const project = options.project || process.cwd();
   const createdAt = new Date().toISOString();
@@ -88,9 +80,17 @@ async function runFanout(options) {
       console.log(formatWaveHuman(doc));
     }
   };
-  const errorWave = (waveId, message) => {
-    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, createdAt, completedAt: new Date().toISOString(), status: 'error' });
+  // v4.4.1 Task 0.5: a wave that dies BEFORE its legs still owes the run a
+  // wave.json. Backlog C1 covered the pre-`try` throw; a server that never
+  // started was its uncovered sibling — run v441plan01's four dead seats left a
+  // `reason` in metadata.json, no wave.json, and stage1 recorded 'complete'.
+  // waveDir is optional (only the post-creation caller has one).
+  const errorWave = (waveId, message, waveDir) => {
+    const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, pack: options.pack, createdAt, completedAt: new Date().toISOString(), status: 'error' });
     doc.error = message;
+    doc.reason = message; // classifier alias, same as fanout-leg.js's run docs
+    // best-effort: an unwritable wave dir must not mask the real error
+    if (waveDir) { try { writeWaveDoc(waveDir, doc); } catch { /* ignore */ } }
     emit(doc);
     return { wave: doc, exitCode: 1 };
   };
@@ -143,13 +143,24 @@ async function runFanout(options) {
   const waveDir = getSessionDir(project, waveId);
   fs.mkdirSync(waveDir, { recursive: true, mode: 0o700 });
   fs.writeFileSync(path.join(waveDir, 'briefing.md'), options.prompt, { mode: 0o600 });
-  writeWaveMetadata(waveDir, {
+  const waveMeta = writeWaveMetadata(waveDir, {
     taskId: waveId, type: 'wave', status: 'running', mode: 'headless',
     models: legs.map(l => (l.ok ? l.model : l.modelInput)), legs: legIds,
     briefing: String(options.prompt).slice(0, 200),
     promptMeta: options.promptMeta || null,
+    ...(options.pack ? { pack: options.pack } : {}), // v4.5 Task 13: absent-not-null.
     pid: process.pid, project, createdAt,
   });
+  // v4.5 final-review F2: an MCP-spawned child never gets --pack (single-
+  // resolution rule), but mcp-server.js pre-seeds THIS wave dir's
+  // metadata.json with the pack it already resolved in-process before
+  // spawning the child. writeWaveMetadata read-merges (fanout-wave-io.js),
+  // so its RETURN VALUE already carries that pre-seeded pack when
+  // options.pack is absent here — inherit from it below rather than
+  // re-reading the file (mirrors the inherit idiom in
+  // result-schema-rebuild.js:93, which reads meta.pack off a metadata.json
+  // it loaded for an unrelated reason).
+  const metaPack = waveMeta.pack;
   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
@@ -160,16 +171,11 @@ async function runFanout(options) {
     const legDocs = legs.map((leg, i) => buildRoutingFailureLeg({ leg, legId: legIds[i], waveId, quiet: options.quiet }));
     const completedAt = new Date().toISOString();
     const wave = buildWaveResult({
-      waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt, notices,
+      waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt, notices,
     });
-    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: routingExitCode };
+    return finishWave({ wave, waveDir, waveId, project, completedAt, follow, emit,
+      exitCode: waveExitCode(wave.status),
+      onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
   }
 
   // 3. Context + prompts built ONCE (model-independent)
@@ -198,37 +204,41 @@ async function runFanout(options) {
     mcp: options.mcp, mcpConfig: options.mcpConfig, clientType: options.client,
     noMcp: options.noMcp, excludeMcp: options.excludeMcp,
   });
+  // ⚠️ v4.4.1 Task 0.5 — the external-server seam runHeadless has carried since
+  // v4.0 (src/headless.js:245): a caller that already owns a server passes it in
+  // and we must NOT close it. Added here because a council run launches its
+  // Stage-1 seat wave and its critic solo under ONE Promise.all (run-stages.js:83)
+  // and two concurrent startOpenCodeServer calls race on OpenCode's SQLite —
+  // run v441plan01 lost four of five seats in 736ms to `database is locked`.
+  // NAME DIVERGENCE, deliberate: runHeadless spells the pair client+server, but
+  // runFanout's `options.client` is ALREADY the client TYPE string (buildMcpConfig
+  // above, buildContext, buildPrompts, cli-handlers-run.js `client: args.client`),
+  // so the SDK client is `options.serverClient`. Both or neither: a half-injection
+  // falls back to owning a server rather than running clientless.
+  const externalServer = !!(options.server && options.serverClient);
   let client, server;
-  try {
-    ({ 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}`);
+  if (externalServer) {
+    ({ serverClient: client, server } = options);
+    logger.debug('Using external server (shared server mode)', { waveId, url: server.url });
+  } else {
+    try {
+      ({ 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}`, waveDir);
+    }
   }
-  if (server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
+  // Only an OWNED server's pid belongs in this wave's metadata: mcp-server.js's
+  // wave abort SIGTERMs `metadata.goPid` as "the orchestrator + its OWNED
+  // OpenCode server", which on an injected server would kill every sibling wave.
+  if (!externalServer && server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
 
-  // 5. Signal abort: mark wave + all legs aborted, close the server, then let
-  // NORMAL control flow finalize — legs see their abort marker within one poll
-  // (~2s) and settle, so step 7 still writes wave.json and emits a parseable
-  // aborted document. An unref'd force-exit watchdog backstops a wedged leg.
+  // 5. Signal abort (./fanout-signals owns the handler — size gate): mark wave +
+  // all legs aborted, close an OWNED server, then let NORMAL control flow
+  // finalize, so step 7 still writes wave.json and emits a parseable aborted
+  // document. An unref'd force-exit watchdog backstops a wedged leg.
   const legDirs = legIds.map(id => getSessionDir(project, id));
-  let signalled = null;
-  const uninstallSignals = installSignalAbort({
-    onAbort: (signal) => {
-      const code = signal === 'SIGINT' ? 130 : 143;
-      if (signalled) { process.exit(code); } // second signal: exit NOW
-      signalled = signal;
-      logger.warn('Signal received — aborting wave', { waveId, signal });
-      markAborted(waveDir, signal);
-      for (const dir of legDirs) { markAborted(dir, signal); }
-      // close() is async (B06 escalation); this handler stays sync, so
-      // fire-and-forget with a rejection guard. The 10s exit watchdog below
-      // comfortably outlives the ~2s escalation grace inside close().
-      try { server.close().catch(() => {}); } catch { /* best-effort */ }
-      const { armExitWatchdog } = require('../utils/lifecycle');
-      armExitWatchdog(code, 10000, { log: (m, meta) => logger.debug(m, meta) });
-    },
-  });
+  const waveAbort = installWaveAbort({ waveId, waveDir, legDirs, server, externalServer });
 
   // 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
@@ -262,26 +272,24 @@ async function runFanout(options) {
     }));
   } finally {
     heartbeat.stop();
-    uninstallSignals();
-    try { await server.close(); } catch { /* already closed on signal */ }
+    waveAbort.uninstall();
+    // ⚠️ close site 2 of 2 (`grep -n "server.close()" src/sidecar/fanout.js`).
+    // An injected server outlives this wave by design — the owner closes it once.
+    if (!externalServer) { try { await server.close(); } catch { /* already closed on signal */ } }
   }
 
   // 7. Aggregate, persist (atomic: tmp + rename), finalize, emit
   const completedAt = new Date().toISOString();
+  const signalled = waveAbort.signal();
   const wave = buildWaveResult({
-    waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
+    waveId, legs: legDocs, promptMeta: options.promptMeta || null, pack: options.pack || metaPack, createdAt, completedAt,
     status: signalled ? 'aborted' : null, notices,
   });
-  const wavePath = path.join(waveDir, 'wave.json');
-  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
-  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
   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 };
+  return finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit,
+    onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
 }
 
 module.exports = {

package/src/sidecar/progress-fields.js

@@ -10,6 +10,23 @@
 /** Coarse stages surfaced to agents. */
 const COARSE_STAGES = ['starting', 'generating', 'folding', 'terminal'];
 
+/**
+ * The stages src/headless.js can write on its ONE terminal progress record.
+ *
+ * ⚠️ v4.4.1 LC-3: this list must stay byte-identical to resolveTerminalState's
+ * status vocabulary (src/sidecar/session-finalize.js), because headless.js
+ * derives the terminal stage straight from that function. A drift pin in
+ * tests/sidecar/progress-fields.test.js asserts it.
+ *
+ * Before LC-3 the terminal record hardcoded 'complete' on every path, so this
+ * set had exactly one member and deriveStage could match the literal. Widening
+ * the writer without widening this set would have been the WORSE bug: an
+ * aborted/errored/timed-out leg would fall through to 'starting' and a finished
+ * leg would read as barely begun for the whole window before metadata.json
+ * lands.
+ */
+const TERMINAL_PROGRESS_STAGES = new Set(['complete', 'error', 'timed-out', 'aborted']);
+
 /**
  * Collapse whitespace and defang fence/tag characters so the preview can be
  * embedded in a one-line JSON status without opening a code fence or tag
@@ -42,8 +59,10 @@ function latestAssistantPreview(entries) {
  * Map (metadata.status, progress.stage) to the coarse agent-facing stage.
  *  - terminal metadata status -> 'terminal'
  *  - progress 'receiving' -> 'generating'
- *  - progress 'complete' while metadata still says running -> 'folding'
- *    (mirror stopped; summary/conflict finalize in flight)
+ *  - a TERMINAL progress stage while metadata still says running -> 'folding'
+ *    (mirror stopped; summary/conflict finalize in flight). v4.4.1 LC-3: that is
+ *    any of TERMINAL_PROGRESS_STAGES, not just 'complete' — an aborted or
+ *    errored leg is every bit as "done streaming, finalizing" as a clean one.
  *  - anything else -> 'starting'
  * @param {string|undefined} metadataStatus @param {string|undefined} progressStage
  * @returns {string}
@@ -53,8 +72,11 @@ function deriveStage(metadataStatus, progressStage) {
     return 'terminal';
   }
   if (progressStage === 'receiving') { return 'generating'; }
-  if (progressStage === 'complete') { return 'folding'; }
+  if (TERMINAL_PROGRESS_STAGES.has(progressStage)) { return 'folding'; }
   return 'starting';
 }
 
-module.exports = { sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES };
+module.exports = {
+  sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES,
+  TERMINAL_PROGRESS_STAGES,
+};

package/src/sidecar/progress.js

@@ -19,7 +19,14 @@ const STAGE_LABELS = {
   session_created: 'Session created',
   prompt_sent: 'Briefing delivered, waiting for response...',
   receiving: 'Generating response...',
-  complete: 'Complete'
+  complete: 'Complete',
+  // v4.4.1 LC-3: the terminal record is no longer always 'complete' — headless.js
+  // derives it from resolveTerminalState, so these three are now reachable. Without
+  // a label, readProgress's `latest` (which falls back to stageLabel when the leg
+  // has no assistant messages yet) would read the raw id: "aborted", not "Aborted".
+  aborted: 'Aborted',
+  error: 'Failed',
+  'timed-out': 'Timed out'
 };
 
 /**
@@ -123,6 +130,39 @@ function writeProgress(sessionDir, stage, extra = {}) {
   writeFileAtomic(progressPath, JSON.stringify(data), { mode: 0o600 });
 }
 
+/**
+ * FR-1 (v4.5): stamp a TERMINAL stage into progress.json on a failure path,
+ * preserving previously recorded usage. Extracted from headless.js's A3 outer
+ * catch so the early-return paths and the exception path can never drift.
+ *
+ * writeProgress REBUILDS progress.json (no merge) — a bare terminal write would
+ * delete whatever real spend the last flush recorded, trading a stale-stage bug
+ * for a cost under-report on exactly the legs that failed. So the prior usage is
+ * read back and re-attached; `extra` fields beyond usage are deliberately
+ * dropped (readProgress derives message counts from conversation.jsonl).
+ *
+ * Runs on error paths: must never throw and never mask the original error.
+ *
+ * @param {string} sessionDir
+ * @param {string} errorMessage - the failure being recorded (stage derives from it)
+ * @returns {boolean} true if the terminal record was written
+ */
+function writeTerminalProgressSafe(sessionDir, errorMessage) {
+  try {
+    let priorUsage = null;
+    try {
+      const prior = JSON.parse(fs.readFileSync(path.join(sessionDir, 'progress.json'), 'utf-8'));
+      if (prior && prior.usage) { priorUsage = prior.usage; }
+    } catch { /* no readable prior record: write the terminal stage without usage */ }
+    const { resolveTerminalState } = require('./session-finalize');
+    const stage = resolveTerminalState({ error: errorMessage }).status;
+    writeProgress(sessionDir, stage, priorUsage ? { usage: priorUsage } : {});
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Read progress from a session's conversation.jsonl and progress.json files.
  *
@@ -235,6 +275,7 @@ function readProgress(sessionDir) {
 module.exports = {
   readProgress,
   writeProgress,
+  writeTerminalProgressSafe,
   extractLatest,
   computeLastActivity,
   STAGE_LABELS,