amicus 4.2.1 → 4.4.0

package/src/observe/watch-render.js

@@ -0,0 +1,168 @@
+// src/observe/watch-render.js
+'use strict';
+
+/**
+ * @module observe/watch-render
+ * Pure renderers + the poll loop for `amicus watch` (spec 5.1). Renderers are
+ * pure functions over the composed live doc (wave-progress.js precedent) so the
+ * table adds no testing burden beyond string assertions. The loop reads only
+ * the data layer: handlers.amicus_status (Surface C) each interval + the events
+ * tail (Surface B) for milestone lines. TTY -> in-place refresh table (ANSI
+ * erase-line + cursor-up, NO alternate screen — scrollback preserved);
+ * non-TTY/--plain -> milestone log lines; --json -> NDJSON.
+ */
+
+const { formatCost } = require('../utils/pricing');
+// Single source of truth for "what statuses are terminal" across the
+// observability layer (live-doc.js's markLive uses the SAME set to decide
+// when to stamp view:'live') — redefining it here would risk the two
+// modules drifting, which would make this loop spin forever on a run
+// live-doc already considers finished (or exit early on one still running).
+const { TERMINAL } = require('./live-doc');
+// Single source of truth for the wave status -> exit code mapping (same
+// drift risk as TERMINAL above) — mapExitCode's non-passthrough branch
+// delegates here instead of hand-rolling the complete/partial/else mapping.
+const { waveExitCode } = require('../utils/result-schema');
+
+const DASH = '—';
+const legCost = (leg) => (leg.usage && leg.usage.cost ? formatCost(leg.usage.cost) : DASH);
+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: '·' };
+
+/** The in-place refresh block for a composed wave/council/solo doc. */
+function renderTable(doc, width = 100) {
+  const cost = doc.usage && doc.usage.cost ? formatCost(doc.usage.cost) : DASH;
+  const head = `${doc.taskId || doc.runId}  ${doc.status}  ${doc.elapsed || ''}  ` +
+    (typeof doc.legsTotal === 'number' ? `legs ${doc.legsComplete}/${doc.legsTotal}  ` : '') +
+    `cost ${cost}`;
+  const lines = [head];
+  if (Array.isArray(doc.stages)) { // council stage checklist
+    lines.push(doc.stages.map((s) => `${STAGE_MARK[s.status] || STAGE_MARK.pending} ${s.name}`).join('  '));
+  }
+  for (const leg of (doc.legs || [])) {
+    const flag = leg.stalled ? ' ⏳stalled' : '';
+    lines.push(
+      `  ${String(leg.model || leg.taskId).padEnd(26)} ${String(leg.phase || leg.status).padEnd(11)} ` +
+      `${String(leg.messages || 0).toString().padStart(3)}msg ${legTokens(leg).padStart(11)} ${legCost(leg).padStart(9)} | ` +
+      `${truncate(leg.latestPreview, Math.max(10, width - 70))}${flag}`
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Non-TTY / --plain milestone lines + a periodic one-line rollup. */
+function renderPlainLines(events, doc) {
+  const lines = (events || []).map((e) => {
+    switch (e.event) {
+      case 'wave-started': return `[wave-started] ${e.id} models=${(e.models || []).join(',')}`;
+      case 'leg-started': return `[leg-started] ${e.legId} ${e.model}`;
+      case 'leg-fallback': return `[leg-fallback] ${e.legId} ${e.fromModel} -> ${e.toModel} (${e.reason})`;
+      case 'leg-terminal': return `[leg-terminal] ${e.legId} ${e.model} ${e.status}`;
+      case 'wave-terminal': return `[wave-terminal] ${e.id} ${e.status} exit=${e.exitCode}`;
+      case 'run-started': return `[run-started] ${e.id} bench=${(e.bench || []).join(',')}`;
+      case 'stage-started': return `[stage-started] ${e.stage}`;
+      case 'stage-terminal': return `[stage-terminal] ${e.stage} ${e.status}`;
+      case 'run-terminal': return `[run-terminal] ${e.id} ${e.status} exit=${e.exitCode}`;
+      default: return `[${e.event}] ${e.id || ''}`;
+    }
+  });
+  if (doc) {
+    const cost = doc.usage && doc.usage.cost ? formatCost(doc.usage.cost) : DASH;
+    lines.push(`… ${doc.status} ${typeof doc.legsTotal === 'number' ? `${doc.legsComplete}/${doc.legsTotal} legs ` : ''}cost ${cost}`);
+  }
+  return lines;
+}
+
+/** Exit mapping (spec 5.1). Council passes through its recorded exitCode. */
+function mapExitCode(doc) {
+  if (doc && typeof doc.exitCode === 'number') { return doc.exitCode; }
+  if (!doc) { return 1; }
+  return waveExitCode(doc.status);
+}
+
+/** Stable-stringify diff: emit the composed doc only when it changed. */
+function emitJsonChange(doc, prevText) {
+  const text = JSON.stringify(doc);
+  return text === prevText ? { emit: false } : { emit: true, text };
+}
+
+/**
+ * The watch poll loop. DI-injected clock/status/tail for testability.
+ * @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)));
+  const isTTY = deps.isTTY !== undefined ? deps.isTTY : process.stdout.isTTY;
+  const { createEventTail, EVENTS_FILE } = require('./events');
+  const { getSessionDir } = require('../session-manager');
+  const path = require('path');
+  const eventsFile = target.kind === 'council'
+    ? path.join(target.runDir, EVENTS_FILE)
+    : path.join(getSessionDir(project, target.id), EVENTS_FILE);
+  const tail = createEventTail(eventsFile);
+  let prevJson = null;
+  let prevRollup = null;
+  let lastLineCount = 0;
+
+  for (;;) {
+    const res = await statusFn(target.id, project);
+    let doc;
+    try { doc = JSON.parse(res.content[0].text); } catch { doc = null; }
+    const events = tail.poll();
+    const isTerminal = doc && TERMINAL.has(doc.status);
+    if (args.json) {
+      for (const e of events) { process.stdout.write(JSON.stringify(e) + '\n'); }
+      if (doc) { const c = emitJsonChange(doc, prevJson); if (c.emit) { process.stdout.write(c.text + '\n'); prevJson = c.text; } }
+    } else if (isTTY && !args.plain) {
+      if (lastLineCount) { process.stdout.write(`\x1b[${lastLineCount}A\x1b[0J`); }
+      const block = renderTable(doc || { status: 'unknown', legs: [] }, process.stdout.columns || 100);
+      process.stdout.write(block + '\n');
+      lastLineCount = block.split('\n').length;
+    } else {
+      // Milestone event lines: the tail only yields new events, so these are
+      // always fresh — print every tick, unthrottled.
+      for (const line of renderPlainLines(events, null)) { process.stdout.write(line + '\n'); }
+      // Rollup line: change-only (mirrors the --json path above), so a
+      // multi-minute --plain watch doesn't spam an identical line every
+      // interval. Always printed on the terminal tick so the final state
+      // is never silently swallowed.
+      if (doc) {
+        const rollup = renderPlainLines([], doc)[0];
+        if (rollup !== prevRollup || isTerminal) {
+          process.stdout.write(rollup + '\n');
+          prevRollup = rollup;
+        }
+      }
+    }
+    if (isTerminal) {
+      if (args.json) { process.stdout.write(JSON.stringify(doc) + '\n'); }
+      return mapExitCode(doc);
+    }
+    await sleep(intervalSec * 1000);
+  }
+}
+
+module.exports = { renderTable, renderPlainLines, mapExitCode, emitJsonChange, runWatchLoop, DASH };

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/continue.js

@@ -116,6 +116,26 @@ function createContinueSessionMetadata(taskId, project, options, oldTaskId) {
   return sessionDir;
 }
 
+/**
+ * Resolve a reopened session's usage, write it onto metadata, and append one
+ * attributed ledger row. Mirrors start.js's finalize (the only sites that
+ * dropped usage - BACKLOG.md:280). Best-effort ledger append; never throws.
+ * @returns {{usage: object|null}}
+ */
+function finalizeSpendForReopen({ taskId, model, mode, op, result, status, project, metadata }, ctx = {}) {
+  const { resolveUsage } = require('../utils/pricing');
+  const usage = result && result.usage ? resolveUsage({ model, usageTotals: result.usage }) : null;
+  if (usage) {
+    metadata.usage = usage; // buildRunResult surfaces metadata.usage into the --json doc for free
+    try {
+      const { appendSpend } = require('../utils/spend-ledger');
+      const gateway = metadata.gateway || (String(model).startsWith('openrouter/') ? 'openrouter' : 'direct');
+      appendSpend({ taskId, model, mode, usage, op, status, project, gateway }, ctx);
+    } catch { /* best-effort */ }
+  }
+  return { usage };
+}
+
 /**
  * Continue from a previous sidecar session - Spec Reference: §4.4, §8.5
  * @returns {Promise<number>} process exit code
@@ -246,6 +266,17 @@ async function continueSidecar(options) {
   } else {
     finalizeSession(sessionDir, summary, project, meta, { quietStdout: json, status: terminal.status });
   }
+  // v4.3: attribute continue spend (C9/E4). Reload meta, write usage + append a
+  // ledger row (status: statusFromResult, matching start.js — not terminal.status).
+  {
+    const { statusFromResult } = require('../utils/result-schema');
+    const reloaded = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    const { usage } = finalizeSpendForReopen({
+      taskId: newTaskId, model, mode: headless ? 'headless' : 'interactive',
+      op: 'continue', result, status: statusFromResult(result), project, metadata: reloaded,
+    });
+    if (usage) { writeFileAtomic(metaPath, JSON.stringify(reloaded, null, 2), { mode: 0o600 }); }
+  }
 
   if (json) {
     const { buildRunResult } = require('../utils/result-schema');
@@ -261,5 +292,6 @@ module.exports = {
   loadPreviousSession,
   buildContinuationContext,
   createContinueSessionMetadata,
+  finalizeSpendForReopen,
   continueSidecar
 };

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