amicus 4.4.0 → 4.4.1

package/src/headless.js

@@ -122,8 +122,22 @@ const USAGE_SETTLE_CALL_TIMEOUT_MS = envNumber('AMICUS_USAGE_SETTLE_CALL_TIMEOUT
  * ON EXCEEDING IT the leg COMPLETES anyway — never fails — carrying
  * `toolSettleTimedOut` on the result, the terminal progress record and the
  * error log channel. Owner's standing ruling: fail LOUD, not fail CLOSED.
+ *
+ * v4.4.1 LC-2 (owner ruling, 2026-07-26): the leg's completion and its partial
+ * output are unchanged, but its OpenCode session is now ABORTED at the ceiling
+ * (see the finalization block) so it stops billing for work nobody will read.
  */
 const TOOL_SETTLE_GRACE_MS = envNumber('AMICUS_TOOL_SETTLE_GRACE_MS', 300000);
+/**
+ * v4.4.1 LC-2 — how long the ceiling's abort call may take before we stop
+ * waiting on it. A hard constant rather than an env knob (the same disposition
+ * as src/sidecar/child-sessions.js's bounds): it exists to stop a pathological
+ * hang, not to be tuned. The leg is already complete and already paid for when
+ * this runs, so an unbounded wait here would hold a finished answer hostage to a
+ * best-effort cost optimization — exactly the trade A-8 forbids. Injectable via
+ * `options.toolSettleAbortTimeoutMs` so the bound itself is testable.
+ */
+const TOOL_SETTLE_ABORT_TIMEOUT_MS = 5000;
 
 /**
  * Race a promise against a timeout. Returns the promise's result, or rejects with
@@ -258,7 +272,18 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       if (options.mcp) {
         serverOptions.mcp = options.mcp;
       }
-      const result = await startServer(serverOptions);
+      // v4.4.1 fix wave (F5): this is the OTHER server-start site. It calls
+      // startServer directly rather than going through startOpenCodeServer, so
+      // the lock-class retry added for the concurrent-start race never covered
+      // it — a plain `amicus start` that lost the race still died on the first
+      // `database is locked`. "Two separate amicus processes contending" is half
+      // that retry's stated justification, and this is one of the two processes.
+      // Same bounded, narrow policy: 5 attempts (Step 10.5 widened it from 3),
+      // lock-class messages only, final failure rethrown unchanged into the
+      // degrade path below.
+      const { retryOnLockRace } = require('./utils/server-setup');
+      const result = await retryOnLockRace(() => startServer(serverOptions),
+        { retryDelayMs: options.retryDelayMs });
       client = result.client;
       server = result.server;
       logger.debug('Server started', { url: server.url });
@@ -457,6 +482,8 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // `=== undefined` rather than `||`: 0 is meaningful (disable the deferral).
     const toolSettleGraceMs = options.toolSettleGraceMs === undefined
       ? TOOL_SETTLE_GRACE_MS : options.toolSettleGraceMs;
+    const toolSettleAbortTimeoutMs = options.toolSettleAbortTimeoutMs === undefined
+      ? TOOL_SETTLE_ABORT_TIMEOUT_MS : options.toolSettleAbortTimeoutMs;
     let consecutivePollFailures = 0;
     let pollFailureBail = false;
     let lastAssistantMsgId = null;
@@ -478,6 +505,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let toolSettleDeferredSince = null; // ms timestamp of the first deferral, or null
     let toolSettleTimedOut = false;     // the grace ceiling was exceeded
     let unsettledAtCeiling = [];        // what was still live when it was exceeded
+    let toolSettleAborted = false;      // LC-2: the ceiling's abort landed (see finalization)
 
     /**
      * Should this poll's completion signal be DEFERRED because a tool call has
@@ -917,6 +945,54 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       }
     }
 
+    // ---- v4.4.1 LC-2: stop paying for a session nobody will read -------------
+    // OWNER RULING (2026-07-26). The leg is complete and runHeadless is returning,
+    // so nothing will ever read further session output — the outcome was already
+    // discarded by completing. Aborting here does not truncate an answer that
+    // would have been used; it stops paying for work nobody will read. The
+    // original objection ("stops the bleeding at the cost of truncating a
+    // possibly-healthy call") applied to aborting ON the completion route, where
+    // the call might still have mattered. Here it cannot.
+    //
+    // ORDER IS LOAD-BEARING, on BOTH sides:
+    //   AFTER the child-session walk above — aborting first risks losing the
+    //     subtree cost data v4.4.0 exists to capture, trading one silent
+    //     under-report for another.
+    //   BEFORE server.close() below — the abort is an SDK call and needs a live
+    //     server. It is not redundant with close(): on a SHARED server (every
+    //     council run) close() is never called here, and the session would go on
+    //     billing against a server that outlives this leg.
+    //
+    // A-8 APPLIES: "never lose the answer" outranks "never report inaccurate
+    // usage". This is an optimization layered on an already-successful,
+    // already-paid-for leg, so every failure — rejection, hang, or a missing
+    // session id — is logged and dropped. Nothing here may alter `completed`,
+    // `summary`, `usage` or `error`. `toolSettleAborted: false` is the honest
+    // record of "we tried and could not; it may still be billing".
+    if (toolSettleTimedOut && sessionId) {
+      try {
+        const { abortSession } = require('./opencode-client');
+        await withTimeout(
+          abortSession(client, sessionId, ...dirArgs),
+          toolSettleAbortTimeoutMs,
+          'abortSession(tool-settle)',
+        );
+        toolSettleAborted = true;
+        // Task 6 review X2: a LANDED abort is the good outcome of a condition
+        // that is already logged at `error` (the ceiling itself). Logging the
+        // remedy at `warn` reads as a second problem; `info` reads honestly.
+        // The FAILED abort below stays at `warn` — that one really is a problem
+        // ("it may still be billing").
+        logger.info('Aborted the OpenCode session after the tool-settle ceiling', {
+          taskId, sessionId, unsettled: unsettledAtCeiling.length,
+        });
+      } catch (abortErr) {
+        toolSettleAborted = false;
+        logger.warn('Could not abort the session after the tool-settle ceiling — it may '
+          + 'still be billing', { taskId, sessionId, error: abortErr.message });
+      }
+    }
+
     if (!externalServer) { await server.close(); }
     if (mirror.toolCalls.length > 0) {
       logger.info('Tool calls summary', {
@@ -958,8 +1034,13 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     // live GUI reads this file (src/observe/live-doc.js). `unsettledToolCalls` is
     // a COUNT here (progress.json is a compact snapshot); the full list is on the
     // returned result for the caller's metadata.
+    //
+    // v4.4.1 LC-2: `toolSettleAborted` rides alongside it — `true` = the session
+    // was told to stop, `false` = it may still be billing. Both are meaningful
+    // ONLY when the ceiling was hit, so neither appears on a clean leg.
     const settleFlags = toolSettleTimedOut
-      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling.length }
+      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling.length,
+        toolSettleAborted }
       : {};
     // v4.4 B4 (Task 2) + v4.4.1 CA-1: a leg that made a SUBAGENT call has spend
     // in a CHILD OpenCode session that is billed separately and is NOT rolled
@@ -981,15 +1062,46 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         : {}),
       ...(subtree.unknown ? { subtreeUnknown: true } : {}) }
       : (subagentToolCalls.length > 0 ? { subtreeUnknown: true } : {});
-    try { writeProgress(sessionDir, 'complete', { usage: { ...usage, ...subtreeProgress }, ...settleFlags }); }
+    // ---- v4.4.1 LC-3: the terminal stage is DERIVED, never hardcoded ---------
+    // This write sits above BOTH returns below, so EVERY terminal path reaches
+    // it — the external-abort break, the --timeout, the poll-failure bail, the
+    // tool-call wedge — and it used to stamp 'complete' on all of them. The live
+    // workspace reads progress.json directly (src/observe/live-doc.js
+    // enrichLegUsage), so an aborted or errored leg rendered with a green check
+    // until metadata.json landed. Fix the WRITER: src/observe/council-legs.js
+    // already prefers metadata.json for a terminal leg and is NOT the problem.
+    //
+    // resolveTerminalState is the codebase's single source of truth for the
+    // (completed, timedOut, aborted, error) → status mapping, and it is what
+    // start.js / continue.js / resume.js / finalizeHeadlessResult will run on
+    // THIS function's return value to stamp metadata.json. Deriving the stage
+    // from it — rather than re-deriving a second, hand-rolled expression here —
+    // is what guarantees progress.json's stage and metadata.json's status cannot
+    // disagree. It also covers the two cases a hand-rolled `aborted ? … :
+    // sessionError ? …` would get wrong: a TIMED-OUT leg (which would still have
+    // read 'complete'), and the F1 case where a session error arrived alongside
+    // usable output and the leg legitimately returns completed (which would have
+    // read a false 'error').
+    //
+    // `failedWithNoUsableOutput` is hoisted out of the `if` below so the stage
+    // and the returned shape are decided by ONE predicate and cannot drift.
+    const failedWithNoUsableOutput = !!(sessionError && (!mirror.output || pollFailureBail || toolStalled));
+    const { resolveTerminalState } = require('./sidecar/session-finalize');
+    const terminalStage = resolveTerminalState({
+      completed,
+      timedOut,
+      aborted,
+      error: failedWithNoUsableOutput ? sessionError : null,
+    }).status;
+    try { writeProgress(sessionDir, terminalStage, { usage: { ...usage, ...subtreeProgress }, ...settleFlags }); }
     catch (progressErr) {
       logger.debug('terminal progress write failed (best-effort)', { taskId, error: progressErr.message });
     }
     const settleResult = toolSettleTimedOut
-      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling }
+      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling, toolSettleAborted }
       : {};
 
-    if (sessionError && (!mirror.output || pollFailureBail || toolStalled)) {
+    if (failedWithNoUsableOutput) {
       return {
         summary: mirror.output ? extractSummary(mirror.output, foldNonce) : '',
         completed: false,
@@ -1036,7 +1148,64 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     }
     if (watchdog) { watchdog.cancel(); }
     if (uninstallSignals) { uninstallSignals(); }
-    if (!externalServer) { await server.close(); }
+    // ⚠️ v4.4.1 M2: guarded — this used to be a bare `await server.close()` sitting directly
+    // above A3's terminal-write block, OUTSIDE any try, in the one place a close failure is
+    // least affordable: the error handler. A rejection here would have skipped the terminal
+    // progress write below entirely AND replaced the original `error` (the one A3 exists to
+    // preserve) with this close failure instead. `close()` has already done its job of freeing
+    // the port by the time we get here; a failure to close cleanly is not this handler's
+    // problem to propagate, so it is logged and swallowed, same discipline as every other
+    // best-effort close in this file (see the signal handler above).
+    if (!externalServer) {
+      try { await server.close(); } catch (closeErr) {
+        logger.debug('server.close() failed in the outer exception handler (best-effort)', {
+          taskId, error: closeErr.message,
+        });
+      }
+    }
+    // ⚠️ v4.4.1 A3 — the last hole in LC-3's story. LC-3 made the SUCCESS path's terminal
+    // progress write derive its stage from resolveTerminalState instead of hardcoding 'complete',
+    // so an aborted/errored/timed-out leg stopped rendering with a green check. This path — the
+    // outer exception handler — wrote NO terminal progress record at all, so progress.json kept
+    // whatever non-terminal stage the last flush left on it (usually 'receiving') while the
+    // caller's finalizeHeadlessResult stamped metadata.json 'error' off the return value below.
+    // The live workspace and `amicus watch` read progress.json DIRECTLY (live-doc.js
+    // enrichLegUsage, council-legs.js), so a leg that exploded rendered as still-streaming
+    // forever: exactly the stale-state class LC-3 closed one path over.
+    //
+    // ⚠️ This runs INSIDE an error handler: it must never throw and must never mask the original
+    // error, so the whole thing sits in its own try and its failure is a debug line, exactly like
+    // the success path's write. The stage comes from the same single source of truth that path
+    // uses, so progress.json's stage and metadata.json's status still cannot disagree.
+    //
+    // ⚠️ The prior `usage` is READ BACK and re-attached deliberately. writeProgress REBUILDS
+    // progress.json from `{stage, stageLabel, updatedAt, ...extra}` — it does not merge — so a
+    // bare terminal write would silently delete whatever real spend the last 'receiving' flush had
+    // already recorded, trading a stale-stage bug for a cost-under-report on exactly the legs that
+    // failed. There are no settled totals on this path (that is what the exception cost us), so
+    // carrying the last known usage forward unchanged is the honest maximum.
+    //
+    // v4.4.1 M3 — scope of "the last known ones": `usage` ONLY. That same 'receiving' flush also
+    // wrote `p.extra` (e.g. `messagesReceived`), and that is deliberately left to drop here, not
+    // carried forward too — the same call LC-3's success-path terminal write already made (see
+    // that block's comment above): readProgress() derives `messages` from conversation.jsonl's
+    // assistant entries directly and only falls back to `messagesReceived` when there are none, so
+    // restating a stale count on an exception — where conversation.jsonl is the more truthful,
+    // already-mirrored source — could only disagree with the file it exists to summarize.
+    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('./sidecar/session-finalize');
+      const stage = resolveTerminalState({ error: error.message }).status;
+      writeProgress(sessionDir, stage, priorUsage ? { usage: priorUsage } : {});
+    } catch (progressErr) {
+      logger.debug('terminal progress write failed after exception (best-effort)', {
+        taskId, error: progressErr.message,
+      });
+    }
     const { emptyUsageTotals } = require('./utils/pricing');
     return {
       summary: '',

package/src/observe/council-legs.js

@@ -34,6 +34,7 @@ const path = require('path');
 const { readProgress, isStalled } = require('../sidecar/progress');
 const { enrichLegUsage, TERMINAL } = require('./live-doc');
 const { roleFor } = require('../council/run-stages');
+const { logger } = require('../utils/logger');
 
 /**
  * A leg's council role. The chair stage is the one case alias identity
@@ -54,6 +55,37 @@ const { roleFor } = require('../council/run-stages');
 function legRole({ bench, critic, lenses, stageName, modelInput }) {
   if (!modelInput) { return null; }
   if (stageName === 'chair') { return 'chair'; }
+  // ⚠️ v4.4.1 LC-4: roleFor's LENS branch does `o.models.indexOf(alias)`, so a
+  // run.json carrying truthy `lenses` with a missing or non-array `bench` throws
+  // a TypeError. This function runs on every status poll, so one malformed
+  // run.json took out three surfaces at once: `amicus status`, the amicus_status
+  // MCP tool, and `amicus watch`. It was unreachable only because
+  // src/council/run.js:72 happens to write `bench` and `lenses` together — an
+  // argument that rests entirely on one writer never changing.
+  //
+  // A role we cannot compute is `null` — the module's existing, documented
+  // degradation (an em-dash in the Role column), never a guess and never a
+  // throw. The non-lens branch never touches `models`, so it stays exact.
+  //
+  // ⚠️ v4.4.1 A2: the guard above was ASYMMETRIC — it validated `bench` and took `lenses` on
+  // trust, but roleFor's lens branch indexes BOTH (`o.lenses[o.models.indexOf(alias)]`). Neither
+  // remaining shape throws, because slug() coerces with String(), so both produced a confident
+  // LIE instead of a crash: `lenses: 'security'` with `bench: ['gpt']` indexes the STRING and
+  // yields `lens:s`, and a `lenses` array shorter than `bench` yields `lens:undefined`. The
+  // length pairing is a real, enforced invariant, not an assumption — cli-handlers-council-run.js:170
+  // refuses `--lenses` unless it has exactly one lens per seat — so a run.json that violates it is
+  // malformed, and the honest answer for a malformed pairing is the same `null` (an em-dash in the
+  // Role column) that LC-4 established, never a guess.
+  if (lenses && (!Array.isArray(bench) || !Array.isArray(lenses) || lenses.length !== bench.length)) {
+    logger.debug('leg role unresolved: run.json lenses/bench are not a matched pair', {
+      modelInput, stageName,
+      benchType: bench === null ? 'null' : typeof bench,
+      lensesType: lenses === null ? 'null' : typeof lenses,
+      benchLength: Array.isArray(bench) ? bench.length : null,
+      lensesLength: Array.isArray(lenses) ? lenses.length : null,
+    });
+    return null;
+  }
   return roleFor({ models: bench, critic, lenses }, modelInput);
 }
 
@@ -71,15 +103,30 @@ function buildLegRow(project, legId, runCtx) {
   const { getSessionDir } = require('../session-manager');
   const legDir = getSessionDir(project, legId);
   let meta = {};
+  // ⚠️ v4.4.1 LC-9: the catch stays ALL-OR-NOTHING on purpose (Appendix A-9) —
+  // it mirrors the wave branch, and a half-parsed metadata object is worse than
+  // an empty one. What was wrong was the SILENCE: a corrupt metadata.json, an
+  // EACCES on the leg dir, and "the file doesn't exist yet" were indistinguishable
+  // and left no trace anywhere, so a leg with corrupt metadata rendered as a
+  // just-started leg forever. `code` is what separates them — ENOENT is the
+  // ordinary just-started case, anything else is a real fault. Logging only; the
+  // branching is untouched.
   try { meta = JSON.parse(fs.readFileSync(path.join(legDir, 'metadata.json'), 'utf-8')); }
-  catch { /* leg metadata not written yet — just-started leg */ }
+  catch (metaErr) {
+    logger.debug('leg metadata.json unreadable — rendering the leg with base fields only', {
+      legId, code: metaErr.code || null, error: metaErr.message,
+    });
+  }
   // Truthful null, never metadata.model as a fallback: showing the resolved
   // id where the alias was expected is exactly the F36 bug (blind mode would
   // leak the real model id instead of degrading to an em-dash).
   const modelInput = meta.modelInput || null;
+  // LC-4: hoisted out of the object literal below so the guard inside legRole is
+  // the only thing standing between a malformed run.json and three live surfaces.
+  const role = legRole({ ...runCtx, modelInput });
   const row = {
     taskId: legId, model: meta.model || null, status: meta.status || 'unknown',
-    modelInput, role: legRole({ ...runCtx, modelInput }),
+    modelInput, role,
   };
   let stalledMs = null;
   let p = null;
@@ -91,7 +138,17 @@ function buildLegRow(project, legId, runCtx) {
     row.lastActivityAt = p.lastActivityAt;
     row.stalled = row.status === 'running' && isStalled(p.lastActivityMs);
     if (row.stalled) { stalledMs = p.lastActivityMs; }
-  } catch { /* no progress.json yet — a just-started leg; base fields only. */ }
+  } catch (progressErr) {
+    // ⚠️ v4.4.1 LC-9: same deal as the metadata catch above — all-or-nothing by
+    // design (A-9), silent by accident. readProgress swallows a malformed
+    // progress.json itself, so reaching here means the leg DIR could not be
+    // stat'd/read at all (EACCES, a vanished session dir) or readProgress threw
+    // on a shape it could not handle — neither of which is "hasn't started yet",
+    // and both of which previously left the row indistinguishable from one.
+    logger.debug('leg progress unreadable — rendering the leg with base fields only', {
+      legId, code: progressErr.code || null, error: progressErr.message,
+    });
+  }
 
   // council review C3: this is a SEPARATE try from readProgress's above, on
   // purpose. The old code wrapped both in one try, so a pricing-resolution

package/src/observe/live-doc.js

@@ -15,7 +15,24 @@
 
 const { resolveUsage, sumWaveUsage } = require('../utils/pricing');
 
-const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'idle-timeout']);
+// ⚠️ v4.4.1 A1: 'timeout' AND 'timed-out' — the codebase genuinely has two spellings for one
+// state, written by two different producers, and this set has to cover both.
+//   'timeout'   — src/utils/result-schema.js:23 statusFromResult, i.e. the LEG/wave-document and
+//                 `--json` run-document vocabulary. Correct, still emitted, stays.
+//   'timed-out' — src/sidecar/session-finalize.js:21 resolveTerminalState, i.e. what actually
+//                 lands in a session's metadata.json `status` and (since LC-3) progress.json's
+//                 terminal stage. It was MISSING here, and this set is the one every observability
+//                 reader consults, so three real consequences followed: `amicus watch <taskId>` on
+//                 a timed-out single session never exited (watch-render.js:138 polls until
+//                 TERMINAL.has(doc.status), and amicus_status stamps metadata.status straight onto
+//                 the doc — mcp-server.js:687); a timed-out leg skipped the "prefer metadata.usage
+//                 over the stale progress.json snapshot" branch in council-legs.js:162 and reported
+//                 an under-counted cost; and markLive kept stamping view:'live' on a finished
+//                 single-session doc.
+// NOTE this is deliberately NOT the same list as src/utils/result-schema.js:13 TERMINAL_STATUSES
+// (the leg set, no 'partial'). Two mirrors of THIS list exist — src/workspace/run-detail.js:26 and
+// electron/workspace-ui/live-model.js:14 — byte-identical, held by drift pins. Edit all three.
+const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'timed-out', 'idle-timeout']);
 
 /**
  * Attach read-time-resolved usage to a leg from its raw progress usage.

package/src/observe/watch-render.js

@@ -29,7 +29,10 @@ const legCost = (leg) => (leg.usage && leg.usage.cost ? formatCost(leg.usage.cos
 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: '·' };
+// `partial` (v4.4.1 F6): a stage that FINISHED but lost seats. Without its own
+// mark it fell through to `pending`, so a degraded Stage 1 rendered as if it had
+// not started — the opposite of reporting loudly.
+const STAGE_MARK = { complete: '✓', running: '▶', partial: '⚠', pending: '·' };
 
 /** The in-place refresh block for a composed wave/council/solo doc. */
 function renderTable(doc, width = 100) {

package/src/sidecar/child-sessions.js

@@ -42,7 +42,7 @@
 
 const { getChildren, getMessages } = require('../opencode-client');
 const { createMirrorState, mirrorUsageOnly } = require('./conversation-mirror');
-const { sumPerMessageUsage, hasObservedTokens } = require('../utils/pricing');
+const { sumPerMessageUsage } = require('../utils/pricing');
 
 /**
  * Bounds. Hard constants rather than env knobs: they exist to stop a pathological
@@ -88,7 +88,6 @@ function usageOfSession(messages) {
     // what they are. A session with neither tokens nor cost is not free either:
     // we saw nothing, and nothing is not zero.
     priced: totals.costReported > 0,
-    observed: hasObservedTokens(totals.tokens),
   };
 }
 

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