amicus 4.3.0 → 4.4.1

package/src/sidecar/child-sessions.js

@@ -0,0 +1,197 @@
+// src/sidecar/child-sessions.js
+'use strict';
+
+/**
+ * @module sidecar/child-sessions
+ * v4.4.1 CA-1 (B4) — enumerate a leg's CHILD (subagent) sessions and total
+ * their spend, so it can be attributed to the parent leg instead of vanishing.
+ *
+ * THE DEFECT. A leg that calls the `task` tool spawns a child OpenCode session.
+ * OpenCode bills it separately and does NOT roll it into the parent session's
+ * cost, and amicus never enumerated it — so it was invisible to every total the
+ * product prints. Measured across the four recorded paid runs: **$0.492506**
+ * ($0.021460 in `council-wsgate01`, $0.471046 in `council-wsgate02`).
+ * `wsgate01` is the honest limit case: all 7 legs `source: 'reported'`,
+ * `unpricedLegs: 0`, and the run still 7.1% short — 100% of that gap was one
+ * `explore` child session.
+ *
+ * WHY IT IS SAFE TO DO THIS NOW. Both blockers named in
+ * `cost-pipeline-fix-report.md` §5.4/§5.7 are closed. The client capability was
+ * already there (`getChildren`, src/opencode-client.js — only `directory`
+ * scoping was missing, backlog LC-7, fixed with this change), and the
+ * premature-completion fix (`dcb0792`) means a `task` part goes terminal only
+ * once its child session ends, so enumerating at finalization can no longer
+ * capture a partial child cost and trade a silent zero for a silent floor.
+ *
+ * THE HONESTY RULE. Never fabricate a number. `complete: false` is returned
+ * whenever any part of the walk could not be carried out — an API failure, a
+ * bound, or a child whose spend cannot be stated — and the caller turns that
+ * into the leg's existing `subtreeUnknown` flag rather than into a zero. There
+ * is deliberately no fourth honesty concept here: what this module produces is
+ * either an attributable amount or the flag that already exists for "the
+ * subtree is not knowable".
+ *
+ * A child's price comes from the SAME field the parent's does: the assistant
+ * messages' `info.cost`. It is never estimated from a catalog — the SDK's
+ * Session record carries no model id, so estimating one would mean guessing
+ * which route billed it, and a guess is exactly what this module exists to
+ * avoid. A child that shows real tokens but reports no cost is therefore
+ * `priced: false` and makes the subtree incomplete (the B2 rule, one level
+ * down): work happened, and we cannot state what it cost.
+ */
+
+const { getChildren, getMessages } = require('../opencode-client');
+const { createMirrorState, mirrorUsageOnly } = require('./conversation-mirror');
+const { sumPerMessageUsage } = require('../utils/pricing');
+
+/**
+ * Bounds. Hard constants rather than env knobs: they exist to stop a pathological
+ * walk, not to be tuned. Real subagent trees observed in the corpus are one child
+ * deep and one wide; 4/64 is orders of magnitude of headroom, and exceeding either
+ * is reported as INCOMPLETE rather than silently truncated.
+ */
+const SUBTREE_MAX_DEPTH = 4;
+const SUBTREE_MAX_SESSIONS = 64;
+
+/** Resolve, or reject after `ms`. `ms <= 0` passes the promise through untouched. */
+function withDeadline(promise, ms) {
+  if (!ms || ms <= 0) { return promise; }
+  let timer;
+  return Promise.race([
+    promise.then((v) => { clearTimeout(timer); return v; },
+      (e) => { clearTimeout(timer); throw e; }),
+    new Promise((_r, reject) => { timer = setTimeout(() => reject(new Error('subtree call timed out')), ms); }),
+  ]);
+}
+
+function emptyTokens() {
+  return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+/**
+ * Total one child session's own usage from its assistant messages — the same
+ * capture path the parent leg uses (mirrorUsageOnly keys the latest snapshot per
+ * message id, so a re-read can never double-count).
+ * @returns {{tokens: object, costReported: number, priced: boolean}}
+ */
+function usageOfSession(messages) {
+  const state = createMirrorState();
+  mirrorUsageOnly(messages, state);
+  const totals = sumPerMessageUsage(state.usageByMsg);
+  return {
+    tokens: totals.tokens,
+    costReported: totals.costReported,
+    // "We can state this session's spend." Only a billed amount states it.
+    // Tokens with no cost are the child-level form of the B2 lie (`0 × catalog
+    // = estimated $0`) and cannot be priced here at all, because the SDK's
+    // Session record carries no model id — so they read as unknown, which is
+    // 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,
+  };
+}
+
+/**
+ * Walk `rootSessionId`'s child sessions (breadth-first, bounded, cycle-proof)
+ * and total their spend.
+ *
+ * @param {import('@opencode-ai/sdk').OpencodeClient} client
+ * @param {string} rootSessionId the LEG's own session id (never itself counted)
+ * @param {object} [opts]
+ * @param {string} [opts.directory] project dir; threaded into every call (#47/LC-7)
+ * @param {number} [opts.callTimeoutMs] per-call deadline; 0/absent = no extra timer
+ * @param {object} [opts.logger] optional logger for best-effort debug lines
+ * @returns {Promise<{sessions: Array<{id: string, tokens: object, costReported: number, priced: boolean}>,
+ *   tokens: object, costReported: number, complete: boolean}>}
+ */
+async function collectSubtreeUsage(client, rootSessionId, opts = {}) {
+  const { directory, callTimeoutMs, logger } = opts;
+  const dirArgs = directory === undefined ? [] : [directory];
+  const tokens = emptyTokens();
+  const sessions = [];
+  const visited = new Set([rootSessionId]);
+  let costReported = 0;
+  let complete = true;
+  let frontier = [rootSessionId];
+
+  for (let depth = 0; depth < SUBTREE_MAX_DEPTH && frontier.length > 0; depth++) {
+    const next = [];
+    for (const parentId of frontier) {
+      let kids;
+      try {
+        kids = await withDeadline(getChildren(client, parentId, ...dirArgs), callTimeoutMs);
+      } catch (err) {
+        // Could not enumerate: the subtree is unknown, not empty.
+        complete = false;
+        if (logger) { logger.debug('subtree: getChildren failed', { parentId, error: err.message }); }
+        continue;
+      }
+      for (const kid of Array.isArray(kids) ? kids : []) {
+        const id = kid && kid.id;
+        if (!id || visited.has(id)) { continue; }
+        if (visited.size > SUBTREE_MAX_SESSIONS) { complete = false; break; }
+        visited.add(id);
+
+        let messages;
+        try {
+          messages = await withDeadline(getMessages(client, id, ...dirArgs), callTimeoutMs);
+        } catch (err) {
+          complete = false;
+          if (logger) { logger.debug('subtree: getMessages failed', { sessionId: id, error: err.message }); }
+          continue;
+        }
+        const u = usageOfSession(messages);
+        sessions.push({ id, tokens: u.tokens, costReported: u.costReported, priced: u.priced });
+        if (u.priced) {
+          costReported += u.costReported;
+          for (const k of Object.keys(tokens)) { tokens[k] += u.tokens[k] || 0; }
+        } else {
+          // The child exists and we read it, but its spend is not stateable.
+          complete = false;
+        }
+        next.push(id);
+      }
+    }
+    // The frontier is non-empty at the last permitted depth only if there may be
+    // another level we are choosing not to walk — say so rather than imply the
+    // walk finished.
+    if (depth === SUBTREE_MAX_DEPTH - 1 && next.length > 0) { complete = false; }
+    frontier = next;
+  }
+
+  return { sessions, tokens, costReported, complete };
+}
+
+/**
+ * Is this leg's subtree spend UNKNOWN, given everything we observed?
+ *
+ * Split out as a pure predicate because the calibration is the whole argument,
+ * and getting it wrong in either direction is a real defect:
+ *
+ *  - Too eager and the flag cries wolf. An OpenCode server that does not serve
+ *    `/session/{id}/children` fails EVERY walk, and a naive `!walkComplete`
+ *    would then mark every leg of every run inexact forever — which is not
+ *    honesty, it is noise that trains the reader to ignore the one run where it
+ *    matters.
+ *  - Too lax and it is the silent under-count the flag exists to kill.
+ *
+ * So it keys on EVIDENCE. A failed walk with no evidence of a subagent at all
+ * (no child found, no `task` call recorded) asserts nothing and flags nothing —
+ * exactly the pre-CA-1 behaviour. Any positive evidence of a subtree that the
+ * walk did not fully account for flags it.
+ *
+ * @param {{walkComplete: boolean, sessionsFound: number, subagentCalls: number}} obs
+ * @returns {boolean}
+ */
+function subtreeIsUnknown({ walkComplete, sessionsFound, subagentCalls }) {
+  const found = sessionsFound > 0;
+  const expected = subagentCalls > 0;
+  // A clean walk still cannot be believed when it contradicts the other
+  // observation: a leg that demonstrably called `task` and yet has no child
+  // session means one of the two readings is wrong, and "there was nothing" is
+  // not the reading this evidence supports.
+  if (walkComplete) { return expected && !found; }
+  return found || expected;
+}
+
+module.exports = { collectSubtreeUsage, subtreeIsUnknown, SUBTREE_MAX_DEPTH, SUBTREE_MAX_SESSIONS };

package/src/sidecar/conversation-mirror.js

@@ -17,6 +17,9 @@
 // bump in the headless idle detector.
 const MAX_TOOL_CALLS = 2000;
 
+const toolPart = require('./tool-part');
+const { isToolPart, toolPartName, toolPartInput, toolPartStatus, isToolPartSettled } = toolPart;
+
 /** Fresh cursor for a session's mirror. */
 function createMirrorState() {
   return {
@@ -24,7 +27,8 @@ function createMirrorState() {
     toolCalls: [],              // [{id,name,input}] — capped at MAX_TOOL_CALLS (most-recent-N)
     seenToolCallIds: new Set(), // stable dedup identity for tool calls (survives the cap)
     seenToolResultIds: new Set(),
-    pendingToolCalls: new Map(), // id -> {id,name,firstSeenAt} — tool_use with no tool_result yet (B53)
+    settledToolCallIds: new Set(), // ids that reached a TERMINAL state.status (v4.4 B4 part 1)
+    pendingToolCalls: new Map(), // id -> {id,name,firstSeenAt} — tool call not yet TERMINAL (B53/B4)
     receivingReported: false,
     output: '',                 // accumulated assistant text
     seenReasoningParts: new Map(), // partId -> last captured reasoning length
@@ -34,16 +38,63 @@ function createMirrorState() {
 }
 
 /**
- * Unresolved tool calls: tool_use ids seen with no matching tool_result yet
- * (matched by `part.tool_use_id`). Used by the headless poll loop's stall
- * detector (B53) to fail fast on a wedged tool call instead of burning the
- * full timeout. Returns a fresh array each call; `state.pendingToolCalls`
- * is the live source of truth.
- * @param {object} state from createMirrorState()
- * @returns {Array<{id:string,name:string,firstSeenAt:string}>}
+ * Capture one assistant message's usage snapshot into `state.usageByMsg`.
+ * The poll loop re-reads ALL messages every poll, so the latest snapshot per
+ * message id wins (keyed Map, never additive) — see pricing.sumPerMessageUsage.
+ * @returns {boolean} true when this message carried a usage payload
  */
-function getPendingToolCalls(state) {
-  return Array.from(state.pendingToolCalls.values());
+function captureMsgUsage(msg, state) {
+  if (msg.info.tokens || typeof msg.info.cost === 'number') {
+    state.usageByMsg.set(msg.info.id, { tokens: msg.info.tokens, cost: msg.info.cost });
+    return true;
+  }
+  return false;
+}
+
+/**
+ * USAGE-ONLY mirror pass (v4.4 B1). Captures `info.tokens`/`info.cost` from a
+ * fresh getMessages() snapshot and NOTHING else — no appendLines, no
+ * `state.output` growth, no progress updates, no pending-tool bookkeeping.
+ *
+ * This exists because the headless poll loop's fast-path exits (trailing fold
+ * marker, SDK `idle`) break BEFORE OpenCode stamps usage at finalization, so a
+ * bounded post-loop re-read is required to see it. Calling the full
+ * mirrorMessages() there would append the already-mirrored assistant text to
+ * conversation.jsonl a second time; this function cannot, because it never
+ * touches seenTextParts/output at all.
+ * @param {Array} messages getMessages() snapshot
+ * @param {object} state from createMirrorState() (only usageByMsg is mutated)
+ * @returns {number} count of messages whose usage was captured
+ */
+function mirrorUsageOnly(messages, state) {
+  const list = Array.isArray(messages) ? messages : [];
+  let captured = 0;
+  for (const msg of list) {
+    if (!msg || !msg.info || msg.info.role !== 'assistant') { continue; }
+    if (captureMsgUsage(msg, state)) { captured += 1; }
+  }
+  return captured;
+}
+
+/**
+ * Does EVERY assistant message in this snapshot carry a usage payload we can
+ * act on — a billed cost, or genuinely observed tokens (v4.4 B1 early-break)?
+ *
+ * Keyed on `hasObservedTokens` rather than "tokens object exists" so an
+ * all-zero placeholder block does not satisfy the predicate — that is exactly
+ * the pre-finalization state the settle loop is waiting out. A legitimately
+ * free local seat still reports real token counts, so it satisfies this on the
+ * first re-read and never pays the full settle window.
+ * @param {Array} messages
+ * @returns {boolean} false when there are no assistant messages at all
+ */
+function allAssistantUsagePresent(messages) {
+  const { hasObservedTokens } = require('../utils/pricing');
+  const list = Array.isArray(messages) ? messages : [];
+  const assistants = list.filter((m) => m && m.info && m.info.role === 'assistant');
+  if (assistants.length === 0) { return false; }
+  return assistants.every((m) => (typeof m.info.cost === 'number' && m.info.cost > 0)
+    || hasObservedTokens(m.info.tokens));
 }
 
 /**
@@ -68,9 +119,7 @@ function mirrorMessages(messages, state, opts = {}) {
     // Track assistant message state
     if (role === 'assistant') {
       currentAssistantMsgId = msg.info.id;
-      if (msg.info.tokens || typeof msg.info.cost === 'number') {
-        state.usageByMsg.set(msg.info.id, { tokens: msg.info.tokens, cost: msg.info.cost });
-      }
+      captureMsgUsage(msg, state);
       // Check for errors — capture for result propagation
       if (msg.info.error) {
         sessionError = (msg.info.error.data && msg.info.error.data.message)
@@ -99,29 +148,49 @@ function mirrorMessages(messages, state, opts = {}) {
             progressUpdates.push({ stage: 'receiving', extra: { messagesReceived: 1 } });
           }
         }
-      } else if ((part.type === 'tool_use' || part.type === 'tool') && !state.seenToolCallIds.has(part.id)) {
-        const toolCall = { id: part.id, name: part.name, input: part.input };
-        state.seenToolCallIds.add(part.id);
-        state.toolCalls.push(toolCall);
-        // Bound growth: keep the most recent N tool-call payloads (BL-4). Dedup is the
-        // Set above, so dropping the oldest here never causes a re-append.
-        if (state.toolCalls.length > MAX_TOOL_CALLS) { state.toolCalls.shift(); }
-        appendLines.push({ role: 'assistant', type: 'tool_use', toolCall, timestamp: now() });
-
-        // Track as pending until a matching tool_result arrives (B53 stall detector).
-        // firstSeenAt is captured once here — never touched again for this id.
-        state.pendingToolCalls.set(part.id, { id: part.id, name: part.name, firstSeenAt: now() });
-
-        // Update progress on tool_use detection
-        progressUpdates.push({
-          stage: 'receiving',
-          extra: {
-            messagesReceived: state.toolCalls.length,
-            latestTool: part.name || undefined,
-            stageLabel: part.name ? `Calling tool: ${part.name}` : 'Executing tool call...',
-          },
-        });
-        state.receivingReported = true;
+      } else if (isToolPart(part)) {
+        // v4.4 B4 part 1: this branch runs on EVERY poll, not only first sight,
+        // because a tool call's `state.status` transitions in place — that
+        // transition is the only signal OpenCode gives that the call finished
+        // (there is no tool_result part). Appending stays first-sight-only.
+        const toolName = toolPartName(part);
+        const firstSight = !state.seenToolCallIds.has(part.id);
+        if (firstSight) {
+          const toolCall = { id: part.id, name: toolName, input: toolPartInput(part) };
+          state.seenToolCallIds.add(part.id);
+          state.toolCalls.push(toolCall);
+          // Bound growth: keep the most recent N tool-call payloads (BL-4). Dedup is the
+          // Set above, so dropping the oldest here never causes a re-append.
+          if (state.toolCalls.length > MAX_TOOL_CALLS) { state.toolCalls.shift(); }
+          appendLines.push({ role: 'assistant', type: 'tool_use', toolCall, timestamp: now() });
+
+          // Update progress on tool-call detection
+          progressUpdates.push({
+            stage: 'receiving',
+            extra: {
+              messagesReceived: state.toolCalls.length,
+              latestTool: toolName || undefined,
+              stageLabel: toolName ? `Calling tool: ${toolName}` : 'Executing tool call...',
+            },
+          });
+          state.receivingReported = true;
+        }
+        // Pending until the status is positively observed TERMINAL. firstSeenAt
+        // is captured once — never bumped while the call stays non-terminal, so
+        // B53's "pending for Ns" reason string stays honest.
+        if (isToolPartSettled(part)) {
+          state.pendingToolCalls.delete(part.id);
+          state.settledToolCallIds.add(part.id);
+        } else if (!state.settledToolCallIds.has(part.id)) {
+          const prior = state.pendingToolCalls.get(part.id);
+          state.pendingToolCalls.set(part.id, {
+            id: part.id, name: toolName,
+            // undefined = legacy shape, status unknown. Kept explicitly so
+            // getLiveToolCalls can tell "still running" from "no idea".
+            status: toolPartStatus(part),
+            firstSeenAt: prior ? prior.firstSeenAt : now(),
+          });
+        }
       } else if (part.type === 'tool_result') {
         // Dedup: append only on first sight (fixes latent double-log bug in headless poll loop)
         if (!state.seenToolResultIds.has(partId)) {
@@ -199,4 +268,9 @@ function logMessage(conversationPath, message) {
   fs.appendFileSync(conversationPath, JSON.stringify(message) + '\n', { mode: 0o600 });
 }
 
-module.exports = { createMirrorState, mirrorMessages, logMessage, getPendingToolCalls };
+module.exports = { createMirrorState, mirrorMessages, logMessage,
+  mirrorUsageOnly, allAssistantUsagePresent,
+  // Re-exported from ./tool-part so callers have ONE import surface for the
+  // mirror's tool-call model (that module exists separately to keep this file
+  // under the 300-line size gate).
+  ...toolPart };

package/src/sidecar/fanout-budget.js

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

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

@@ -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

@@ -132,7 +132,25 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
   const status = legStatusFromResult(result);
   const summary = result.summary || null;
   const { resolveUsage } = require('../utils/pricing');
-  const usage = result && result.usage ? resolveUsage({ model: leg.model, usageTotals: result.usage }) : null;
+  // v4.4 Task 2 (B4) + v4.4.1 CA-1: a leg that made a SUBAGENT (`task`) call has
+  // spend in a child OpenCode session that is billed separately and is NOT
+  // rolled into the parent session's cost. runHeadless now WALKS those sessions
+  // (src/sidecar/child-sessions.js), so `subtreeUnknown` narrows from "this leg
+  // called `task`, therefore assume the worst" to what it should always have
+  // meant: the walk could not account for the subtree.
+  //
+  // The walk is authoritative when it ran — including in the direction that
+  // CLEARS the flag, which the name-string proxy could never do (backlog CA-5:
+  // a tool merely NAMED `task` that spawns nothing used to make an exact run
+  // report itself inexact). The proxy survives only as the fallback for a leg
+  // where the walk could not run at all.
+  const walked = result && result.subtree;
+  const subtreeUnknown = walked
+    ? !!walked.unknown
+    : !!(result && result.subagentToolCalls > 0);
+  const usage = result && result.usage
+    ? resolveUsage({ model: leg.model, usageTotals: result.usage, subtreeUnknown, subtree: walked || undefined })
+    : null;
   // If setup threw before the session dir existed, there is nothing on disk to
   // finalize — still resolve to an error run document so the wave aggregates.
   const legPatch = {
@@ -140,6 +158,16 @@ async function runSingleAttempt({ leg, legId, waveId, project, directory, follow
     reason: result.error || undefined,
     completedAt: new Date().toISOString(),
     usage: usage || undefined,
+    // v4.4 B4 part 1: the leg completed with tool calls still live, so its
+    // OpenCode session may have kept working (and billing) afterwards. Travels
+    // with the leg so it is readable long after the run's stderr is gone.
+    toolSettleTimedOut: (result && result.toolSettleTimedOut) || undefined,
+    // 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) {