amicus 4.3.0 → 4.4.0

package/src/observe/council-legs.js

@@ -0,0 +1,183 @@
+// src/observe/council-legs.js
+'use strict';
+
+/**
+ * @module observe/council-legs
+ * Per-leg row builder for the composed council live doc
+ * (buildCouncilStatusPayload in src/mcp-council-awareness.js). Split out of
+ * that file to stay under the 300-line gate (DE-ROT Task 0.5, closes F01:
+ * `usageLegs` was computed then discarded — no `legs[]` ever reached the
+ * payload, so the live Seats panel had no data source).
+ *
+ * One row per leg id, built UNCONDITIONALLY: unlike the usage rollup (gated
+ * on `enriched.usage` in buildCouncilStatusPayload), a live seats panel needs
+ * just-started legs — the ones with no usage yet — just as much as priced
+ * ones. Field names mirror the wave branch (src/mcp-server.js:592-608) so
+ * live-normalize.js (Task 14) has one vocabulary to map, not two.
+ *
+ * `modelInput` + `role` (F36/F34 correction): a live leg's `model` is the
+ * RESOLVED executable id (metadata.model), never the council ALIAS that
+ * run.json's bench/chair/critic/lenses and roleFor's rule are keyed on — so
+ * deriving role from `model` is a silent no-op (Role column permanently
+ * em-dash) and blind mode's labelOf(alias) lookup never matches (real model
+ * id leaks). The alias IS on disk per-leg, though: every council leg goes
+ * through src/sidecar/fanout-leg.js's runSingleAttempt, which calls
+ * `writeLegPatch(legDir, { parentWave, modelInput })` synchronously,
+ * immediately after leg creation (fanout-leg.js:101) — well before any
+ * status poll could reasonably observe it missing. So this module reads
+ * `modelInput` straight off the leg's own metadata.json, no run.json join
+ * needed for the alias itself.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readProgress, isStalled } = require('../sidecar/progress');
+const { enrichLegUsage, TERMINAL } = require('./live-doc');
+const { roleFor } = require('../council/run-stages');
+
+/**
+ * A leg's council role. The chair stage is the one case alias identity
+ * cannot resolve: run-chair.js's fallback chain (ch1/ch2 = run.chair's own
+ * alias, ch3 = a DIFFERENT ledger-promoted alias, ch4 = whichever succeeded)
+ * means a chair leg's modelInput does not reliably equal run.json's `chair`
+ * field while the chain is still in flight (that field is only checkpointed
+ * once the WHOLE chain resolves, src/council/run-chair.js:122) — so alias
+ * matching would miss ch3/ch4 mid-run. The stage that owns the leg is the
+ * authoritative signal instead (plan's F34 correction: "derive role from the
+ * stage that owns the leg"). Every other stage (stage1/stage2/debate-*)
+ * reuses roleFor (src/council/run-stages.js) keyed on modelInput — a
+ * model's seat/critic/lens identity is stable whether it's reviewing
+ * (stage1) or judging (stage2), and a repair/debate leg relaunches the SAME
+ * alias as its origin leg, so the identity carries through unchanged.
+ * @returns {string|null} null when modelInput is unknown (truthful — never a guess)
+ */
+function legRole({ bench, critic, lenses, stageName, modelInput }) {
+  if (!modelInput) { return null; }
+  if (stageName === 'chair') { return 'chair'; }
+  return roleFor({ models: bench, critic, lenses }, modelInput);
+}
+
+/**
+ * One composed row for a leg, plus the ms-since-activity behind its `stalled`
+ * flag (or null when not stalled/not yet measurable) so the caller can roll
+ * several legs' staleness into one run-level summary without re-parsing
+ * `lastActivityAt` back into a timestamp.
+ * @param {string} project
+ * @param {string} legId
+ * @param {{bench: string[], critic: string|null, lenses: string[]|null, stageName: string}} runCtx
+ * @returns {{row: object, stalledMs: number|null}}
+ */
+function buildLegRow(project, legId, runCtx) {
+  const { getSessionDir } = require('../session-manager');
+  const legDir = getSessionDir(project, legId);
+  let meta = {};
+  try { meta = JSON.parse(fs.readFileSync(path.join(legDir, 'metadata.json'), 'utf-8')); }
+  catch { /* leg metadata not written yet — just-started leg */ }
+  // 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;
+  const row = {
+    taskId: legId, model: meta.model || null, status: meta.status || 'unknown',
+    modelInput, role: legRole({ ...runCtx, modelInput }),
+  };
+  let stalledMs = null;
+  let p = null;
+  try {
+    p = readProgress(legDir);
+    row.messages = p.messages;
+    row.stage = p.stage;
+    row.latestPreview = p.latestPreview;
+    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. */ }
+
+  // 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
+  // failure (an unknown model, a corrupt catalog row) landed in the exact same
+  // catch as "progress.json doesn't exist yet" — an operator (or the workspace's
+  // cost-by-seat panel) could not tell "pricing lookup failed" from "hasn't
+  // billed yet"; both rendered as a permanently blank cost cell. `usageError`
+  // makes the failure mode truthful and distinguishable, additive to the row
+  // (N3's undefined-key discipline still holds: only set usage/usageError when
+  // there is something to say).
+  //
+  // v4.4 B3 (diagnosis §4/§7.3): for a TERMINAL leg, metadata.json's `usage`
+  // block wins over the progress.json snapshot. progress.json's usage is stamped
+  // ONLY on 'receiving' flushes — which fire on text/tool/reasoning GROWTH, i.e.
+  // always strictly before OpenCode's finalization stamp — so on real paid runs
+  // 31 of 35 legs ended with an all-zero snapshot while metadata.json held
+  // thousands of real tokens and a reported cost. Reading the snapshot for a
+  // finished leg made every completed seat look free in the live doc.
+  // headless.js now also writes a terminal 'complete' progress record carrying
+  // the settled usage, which fixes the DATA; this makes the READER prefer the
+  // authoritative source either way, including for every leg already on disk.
+  // A still-RUNNING leg keeps reading progress.json — metadata.usage does not
+  // exist until the leg finalizes, and read-time resolution is what keeps a live
+  // in-flight cost current (live-doc.js's stated design).
+  if (TERMINAL.has(row.status) && meta.usage && meta.usage.cost) {
+    row.usage = meta.usage;
+  } else if (p && p.usage) {
+    try {
+      const enriched = enrichLegUsage(row, p.usage);
+      if (enriched.usage) { row.usage = enriched.usage; }
+    } catch (err) {
+      row.usageError = err.message;
+    }
+  }
+  return { row, stalledMs };
+}
+
+/**
+ * Rows for every leg id, plus a run-level stall rollup. A council run fans
+ * legs across several parallel sub-waves at once (seat wave, chair chain,
+ * lens/critic solos), so — unlike the single-leg wave branch, which only
+ * ever flags its own row — a run-level banner needs one summary rather than
+ * making the caller inspect every row.
+ *
+ * The rollup means exactly what the workspace's dead-run banner claims ("no
+ * leg activity for Xm — the run may be dead"): the run is stalled only when
+ * EVERY still-running leg is stalled. A single stalled leg alongside another
+ * leg that is actively producing (message/cost climbing) must NOT set the
+ * flag — that was the old (max-based) bug, observed live: `glm` sat stalled
+ * for two minutes while `qwen-coder` was visibly working, and the banner
+ * fired anyway. A leg that has already finished (any non-'running' status)
+ * is terminal — it is excluded from the "every leg" population entirely: it
+ * can neither keep the run "healthy" by counting as active, nor drag it
+ * "dead" by counting as stalled. Per-leg `row.stalled` is untouched by this —
+ * it stays the accurate, per-row signal it already was.
+ *
+ * When the run genuinely is stalled, `stalledForSeconds` is the SHORTEST
+ * idle duration among the stalled running legs, not the longest: that is the
+ * honest answer to "how long has the whole run been quiet" — something was
+ * still happening as recently as the most-recently-active (but still
+ * over-threshold) leg's last activity.
+ * @param {string} project
+ * @param {string[]} legIds
+ * @param {{bench: string[], critic: string|null, lenses: string[]|null, stageName: string}} runCtx
+ *   run.json's alias-valued fields (bench/critic/lenses) + the active stage's
+ *   name, threaded through to legRole — this module never reads run.json itself.
+ * @returns {{rows: object[], stalled?: true, stalledForSeconds?: number}}
+ */
+function buildLegRows(project, legIds, runCtx) {
+  const rows = [];
+  let runningCount = 0;
+  const stalledRunningMs = [];
+  for (const legId of legIds) {
+    const { row, stalledMs } = buildLegRow(project, legId, runCtx);
+    rows.push(row);
+    if (row.status === 'running') {
+      runningCount += 1;
+      if (stalledMs !== null) { stalledRunningMs.push(stalledMs); }
+    }
+  }
+  const out = { rows };
+  if (runningCount > 0 && stalledRunningMs.length === runningCount) {
+    out.stalled = true;
+    out.stalledForSeconds = Math.floor(Math.min(...stalledRunningMs) / 1000);
+  }
+  return out;
+}
+
+module.exports = { buildLegRows };

package/src/observe/live-doc.js

@@ -17,11 +17,29 @@ const { resolveUsage, sumWaveUsage } = require('../utils/pricing');
 
 const TERMINAL = new Set(['complete', 'partial', 'error', 'crashed', 'aborted', 'timeout', 'idle-timeout']);
 
-/** Attach read-time-resolved usage to a leg from its raw progress usage. */
+/**
+ * Attach read-time-resolved usage to a leg from its raw progress usage.
+ *
+ * v4.4.1 CA-1: the terminal progress record carries the leg's enumerated CHILD
+ * (subagent) session spend as `usage.subtree` / `usage.subtreeUnknown`
+ * (src/headless.js). Those must be forwarded, not dropped: the live workspace
+ * and `amicus watch` read progress.json directly, so silently keeping only
+ * {tokens, cost} here would make the GUI's cost-by-seat and its wave rollup
+ * disagree with run.json by exactly the child-session amount — reintroducing
+ * the under-report one surface down from where it was fixed.
+ */
 function enrichLegUsage(leg, progressUsage) {
   if (!progressUsage || !progressUsage.tokens) { return leg; }
-  const resolved = resolveUsage({ model: leg.model, usageTotals: progressUsage });
-  return { ...leg, usage: { tokens: resolved.tokens, cost: resolved.cost } };
+  const resolved = resolveUsage({
+    model: leg.model,
+    usageTotals: progressUsage,
+    subtree: progressUsage.subtree,
+    subtreeUnknown: progressUsage.subtreeUnknown,
+  });
+  const usage = { tokens: resolved.tokens, cost: resolved.cost };
+  if (resolved.subtree) { usage.subtree = resolved.subtree; }
+  if (resolved.subtreeUnknown) { usage.subtreeUnknown = true; }
+  return { ...leg, usage };
 }
 
 /** Stamp view:'live' on a non-terminal composed doc; no-op when terminal. */

package/src/observe/watch-render.js

@@ -93,6 +93,25 @@ function emitJsonChange(doc, prevText) {
  * @returns {Promise<number>} exit code
  */
 async function runWatchLoop(target, args, project, deps = {}) {
+  // Pointer-containment fence, defence in depth. cli-handlers-watch.js's
+  // resolveWatchTarget already refuses a council pointer whose runDir escapes
+  // the project, but this loop is exported, takes `target` from its caller, and
+  // opens events.jsonl straight out of target.runDir below — so it re-checks
+  // rather than trusting the hand-off. Reuses the shared fence
+  // (src/utils/path-fence.js) and reports through the SAME failJson
+  // BAD_SESSION envelope handleWatch uses for an unresolvable id, so a --json
+  // caller still gets exactly one typed error doc.
+  if (target.kind === 'council') {
+    const { containsOnDisk } = require('../utils/path-fence');
+    if (!containsOnDisk(project, target.runDir)) {
+      const { failJson, ERROR_CODES } = require('../utils/error-doc');
+      return failJson(!!args.json, {
+        code: ERROR_CODES.BAD_SESSION,
+        message: `watch: run directory for '${target.id}' resolves outside project ${project}`,
+        hint: 'Pass --project if the run was launched elsewhere.',
+      });
+    }
+  }
   const intervalSec = Math.max(0.5, Number(args.interval) || 2);
   const statusFn = deps.statusFn || ((id, p) => require('../mcp-server').handlers.amicus_status({ taskId: id }, p));
   const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));

package/src/opencode-client.js

@@ -328,15 +328,27 @@ async function createChildSession(client, parentId) {
 }
 
 /**
- * Get child sessions for a parent session
+ * Get child (subagent) sessions for a parent session.
+ *
+ * ⚠️ v4.4.1 LC-7: this was the ONE per-session call that did not thread
+ * `directoryQuery(directory)`, unlike getMessages / createSession /
+ * abortSession. It went unnoticed because nothing called it — on a SHARED
+ * server (one server, many projects) an un-scoped call is the exact
+ * "session not found" failure mode issue #47 fixed everywhere else, and it
+ * would have broken child-session cost attribution on precisely the
+ * configuration that makes attribution matter. Fixed with CA-1, its first
+ * consumer (src/sidecar/child-sessions.js).
  *
  * @param {import('@opencode-ai/sdk').OpencodeClient} client - SDK client
  * @param {string} parentId - Parent session ID
+ * @param {string} [directory] - Optional project directory to scope the call to.
+ *   Omitting it keeps the call byte-for-byte identical to before.
  * @returns {Promise<Array>} Array of child sessions
  */
-async function getChildren(client, parentId) {
+async function getChildren(client, parentId, directory) {
   const result = await client.session.children({
-    path: { id: parentId }
+    path: { id: parentId },
+    ...directoryQuery(directory)
   });
 
   return result.data || [];

package/src/sidecar/child-sessions.js

@@ -0,0 +1,198 @@
+// 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, hasObservedTokens } = 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,
+    observed: hasObservedTokens(totals.tokens),
+  };
+}
+
+/**
+ * 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 };