amicus 4.2.1 → 4.4.0

package/src/headless.js

@@ -13,8 +13,14 @@ const { ensurePortAvailable } = require('./utils/server-setup');
 const { mapAgentToOpenCode } = require('./utils/agent-mapping');
 const { writeProgress } = require('./sidecar/progress');
 const { writeFileAtomic } = require('./utils/atomic-write');
-const { createMirrorState, mirrorMessages, logMessage, getPendingToolCalls } = require('./sidecar/conversation-mirror');
+const { createMirrorState, mirrorMessages, logMessage, getPendingToolCalls,
+  getLiveToolCalls, mirrorUsageOnly, allAssistantUsagePresent } = require('./sidecar/conversation-mirror');
 const { buildFoldMarker, trailingFoldMarkerRegex, generateFoldNonce } = require('./utils/fold-marker');
+// v4.4 (cost-council finding 3): `Number(process.env.X) || DEFAULT` cannot express
+// an explicit `0`, and `0` is the DOCUMENTED disable switch for every knob below
+// that uses this helper. See src/utils/env-num.js for why the older `||` knobs are
+// deliberately left alone.
+const { envNumber } = require('./utils/env-num');
 
 /**
  * Fold marker that the agent outputs when done.
@@ -73,6 +79,51 @@ const STABLE_IDLE_POLLS = Number(process.env.AMICUS_STABLE_IDLE_POLLS) || 30;
 const POLL_CALL_TIMEOUT_MS = Number(process.env.AMICUS_POLL_CALL_TIMEOUT_MS) || 30000; // per getMessages call (used by a later task)
 const MAX_CONSECUTIVE_POLL_FAILURES = Number(process.env.AMICUS_MAX_CONSECUTIVE_POLL_FAILURES) || 15; // ≈30s at 2s polls
 const TOOL_CALL_STALL_MS = Number(process.env.AMICUS_TOOL_CALL_STALL_MS) || 180000; // B53: wedged tool call w/ no progress
+/**
+ * v4.4 B1 — bounded post-loop usage reconciliation. The fold-marker (:~540) and
+ * SDK-idle (:~568) fast paths break WITHOUT requiring `info.time.completed`, but
+ * OpenCode stamps `info.tokens`/`info.cost` at message finalization — so those
+ * exits can win the race against the provider's usage payload and report a leg
+ * as free. Measured on real paid legs: $0.00759441096 lost by 155 ms and
+ * $0.00690565716 by 29 ms. 3 × 400 ms bounds the worst case at ~1.2 s of extra
+ * wall time on a leg that already finished, and the loop breaks early the moment
+ * every assistant message carries usage (the common case: one extra read).
+ * Set AMICUS_USAGE_SETTLE_POLLS to 0 to disable the re-poll entirely.
+ */
+const USAGE_SETTLE_POLLS = envNumber('AMICUS_USAGE_SETTLE_POLLS', 3);
+const USAGE_SETTLE_INTERVAL_MS = envNumber('AMICUS_USAGE_SETTLE_INTERVAL_MS', 400);
+/** Deliberately much tighter than POLL_CALL_TIMEOUT_MS: the leg is already
+ *  finished, so a hung settle read must not add 30 s × 3 to a run's wall time.
+ *  0 means "no extra timer" (withTimeout passes the promise through untouched). */
+const USAGE_SETTLE_CALL_TIMEOUT_MS = envNumber('AMICUS_USAGE_SETTLE_CALL_TIMEOUT_MS', 5000);
+/**
+ * v4.4 B4 part 1 — how long a completion signal may be DEFERRED while a tool
+ * call has not yet reached a terminal `state.status`.
+ *
+ * THE DEFECT THIS BOUNDS. `council-wsgate02/wsgate02-s1-3` was declared
+ * `complete` by the STABLE_IDLE_POLLS gate at 04:36:09.700 on **166 characters**
+ * of reasoning preamble, while its `task` tool call ran until 04:38:19.061 —
+ * 129 s later — and its session went on to bill $0.14279 of parent spend plus a
+ * $0.47105 child session. 166 characters were adjudicated as a peer review.
+ *
+ * WHY IT MUST BE BOUNDED. 9 of the 1,307 tool parts persisted in this machine's
+ * OpenCode database are stuck non-terminal forever: `time_updated` within
+ * milliseconds of `time_created`, all from killed sessions that never wrote a
+ * terminal status. A stale `running` can therefore outlive everything, so an
+ * unbounded wait is not an option.
+ *
+ * WHY 5 MINUTES. The measured duration of the real subagent call that exposed
+ * this is **190.6 s** (`task`, 04:35:08.427 → 04:38:19.061) — already longer
+ * than B53's 180 s TOOL_CALL_STALL_MS, so anything at that scale would kill a
+ * healthy `task` leg 10 s short of its answer. 300 s clears the measured case
+ * with margin and still lands far inside the 15-minute default `--timeout`.
+ * Set to 0 to disable the deferral entirely (pre-v4.4 behaviour).
+ *
+ * ON EXCEEDING IT the leg COMPLETES anyway — never fails — carrying
+ * `toolSettleTimedOut` on the result, the terminal progress record and the
+ * error log channel. Owner's standing ruling: fail LOUD, not fail CLOSED.
+ */
+const TOOL_SETTLE_GRACE_MS = envNumber('AMICUS_TOOL_SETTLE_GRACE_MS', 300000);
 
 /**
  * Race a promise against a timeout. Returns the promise's result, or rejects with
@@ -397,6 +448,15 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     const pollCallTimeoutMs = options.pollCallTimeoutMs || POLL_CALL_TIMEOUT_MS;
     const maxConsecutivePollFailures = options.maxConsecutivePollFailures || MAX_CONSECUTIVE_POLL_FAILURES;
     const toolCallStallMs = options.toolCallStallMs || TOOL_CALL_STALL_MS;
+    // `=== undefined` rather than `||`: 0 is a meaningful value (disable the
+    // v4.4 B1 settle re-poll entirely) and must survive injection.
+    const usageSettlePolls = options.usageSettlePolls === undefined
+      ? USAGE_SETTLE_POLLS : options.usageSettlePolls;
+    const usageSettleIntervalMs = options.usageSettleIntervalMs === undefined
+      ? USAGE_SETTLE_INTERVAL_MS : options.usageSettleIntervalMs;
+    // `=== undefined` rather than `||`: 0 is meaningful (disable the deferral).
+    const toolSettleGraceMs = options.toolSettleGraceMs === undefined
+      ? TOOL_SETTLE_GRACE_MS : options.toolSettleGraceMs;
     let consecutivePollFailures = 0;
     let pollFailureBail = false;
     let lastAssistantMsgId = null;
@@ -408,6 +468,61 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     let lastReasoningLength = 0; // B53: track reasoning-output growth to detect thinking
     let lastProgressAt = Date.now(); // B53: last poll where `progressed` was true
     let toolStalled = false; // B53: distinct from completed/timedOut/aborted — see resolveTerminalState
+    let lastSettledToolCount = 0; // B4: tool calls observed reaching a terminal status
+
+    // ---- v4.4 B4 part 1: the tool-settle deferral -----------------------------
+    // Recomputed once per poll (see the loop body) so every completion gate in a
+    // single poll reads ONE consistent answer.
+    let liveTools = [];      // POSITIVELY 'pending'/'running' — gates completion
+    let pendingTools = [];   // not-yet-terminal incl. unknown shape — feeds B53
+    let toolSettleDeferredSince = null; // ms timestamp of the first deferral, or null
+    let toolSettleTimedOut = false;     // the grace ceiling was exceeded
+    let unsettledAtCeiling = [];        // what was still live when it was exceeded
+
+    /**
+     * Should this poll's completion signal be DEFERRED because a tool call has
+     * not reached a terminal `state.status`?
+     *
+     * Keyed on the REAL SDK shape (src/sidecar/tool-part.js): terminal is
+     * `state.status === 'completed' | 'error'`. It is deliberately NOT keyed on a
+     * `tool_result` part — OpenCode emits no such part type (36 `tool_use` records
+     * and 0 `tool_result` records across the 35 recorded legs), so the diagnosis's
+     * proposed `pendingToolCalls` gate would have hung every tool-using leg.
+     *
+     * It reads `getLiveToolCalls`, NOT `getPendingToolCalls`: a leg is only ever
+     * held open on POSITIVE evidence that OpenCode is still working ('pending' /
+     * 'running'). A tool part carrying no `state` at all is unknown, not live, and
+     * must not defer anything — deferring on an absence of evidence is exactly how
+     * this gate would hang. B53 still owns that no-evidence case.
+     *
+     * @param {string} exitPath which completion gate is asking (for the logs)
+     * @returns {boolean} true = keep polling; false = complete now
+     */
+    const deferForUnsettledTools = (exitPath) => {
+      if (toolSettleTimedOut) { return false; }       // ceiling blown — never defer again
+      if (!(toolSettleGraceMs > 0)) { return false; } // 0 = disabled (escape hatch)
+      if (liveTools.length === 0) { return false; }
+      if (toolSettleDeferredSince === null) {
+        toolSettleDeferredSince = Date.now();
+        logger.info('Deferring leg completion — tool call(s) still executing', {
+          taskId, exitPath, live: liveTools.length,
+          tools: liveTools.map(t => `${t.name}:${t.status}`).join(','), toolSettleGraceMs,
+        });
+        return true;
+      }
+      if ((Date.now() - toolSettleDeferredSince) <= toolSettleGraceMs) { return true; }
+      // The ceiling. Complete the leg (keep whatever output it produced) and make
+      // the uncertainty impossible to miss — never fail it closed.
+      toolSettleTimedOut = true;
+      unsettledAtCeiling = liveTools.slice();
+      logger.error('Tool call(s) did not settle within the grace window — completing leg '
+        + 'anyway; its OpenCode session may STILL be working and BILLING', {
+        taskId, sessionId, exitPath, toolSettleGraceMs,
+        unsettled: unsettledAtCeiling.length,
+        tools: unsettledAtCeiling.map(t => `${t.name}@${t.firstSeenAt}`).join(','),
+      });
+      return false;
+    };
 
     while (!completed && (Date.now() - startTime) < timeoutMs) {
       watchdog.touch();
@@ -448,9 +563,25 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 
         const mr = mirrorMessages(messages, mirror);
         mr.appendLines.forEach(line => logMessage(conversationPath, line));
-        mr.progressUpdates.forEach(p => writeProgress(sessionDir, p.stage, p.extra));
+        // Surface A (spec §4.1): stamp raw usage on each 'receiving' flush from the
+        // PERSISTENT mirror.usageByMsg Map (accumulated across polls) — NOT
+        // mr.usageByMsg, which doesn't exist on mirrorMessages()'s per-poll delta.
+        // Cost resolution happens at read time (Task 9); the writer stays cheap.
+        const { sumPerMessageUsage } = require('./utils/pricing');
+        mr.progressUpdates.forEach(p => writeProgress(
+          sessionDir, p.stage,
+          p.stage === 'receiving' ? { ...p.extra, usage: sumPerMessageUsage(mirror.usageByMsg) } : p.extra,
+        ));
         const currentAssistantMsgId = mr.currentAssistantMsgId;
         const assistantFinished = mr.assistantFinished;
+        // v4.4 B4 part 1: evaluate tool liveness ONCE per poll, before any
+        // completion gate reads it. Clearing the deferral here (rather than
+        // inside deferForUnsettledTools) matters: the gates only run when a
+        // completion signal fires, so a leg that resumes working after a
+        // deferral would otherwise keep B53 suppressed on a stale timestamp.
+        pendingTools = getPendingToolCalls(mirror);
+        liveTools = getLiveToolCalls(mirror);
+        if (liveTools.length === 0) { toolSettleDeferredSince = null; }
         if (mr.sessionError) {
           sessionError = mr.sessionError;
           logger.error('Session error detected in assistant message', { sessionId, message: mr.sessionError });
@@ -469,7 +600,11 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // marker on its own line mid-output (echoing a prior sidecar, these
         // instructions, or scraped content) — only the exact nonced marker,
         // with nothing but blank lines after it, is a completion signal.
-        if (findTrailingFoldMarker(mirror.output, foldNonce) !== -1) {
+        // v4.4 B4: a fold marker WITHOUT info.time.completed means OpenCode has
+        // not finalized the message, so a tool call may still be live and billing
+        // (this is the same window B1's usage race lives in). Defer, bounded.
+        if (findTrailingFoldMarker(mirror.output, foldNonce) !== -1
+            && !deferForUnsettledTools('fold-marker')) {
           completed = true;
           break;
         }
@@ -506,7 +641,7 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
               'getSessionStatus'
             );
             const s = (statusData && statusData.type) ? statusData : (statusData && statusData[sessionId]);
-            if (s && s.type === 'idle') {
+            if (s && s.type === 'idle' && !deferForUnsettledTools('sdk-idle')) {
               logger.debug('Session reported idle by SDK — completing', { sessionId });
               completed = true;
               break;
@@ -535,9 +670,14 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // the stall clock resets instead of falsely firing "Tool call stalled".
         const reasoningActivity = mirror.reasoningOutput.length > lastReasoningLength;
         lastReasoningLength = mirror.reasoningOutput.length;
+        // v4.4 B4: a tool call REACHING a terminal status is real activity. Before
+        // the shape fix this could never be observed (pending never cleared), so a
+        // multi-tool leg's stall clock only reset on text growth.
+        const settleActivity = mirror.settledToolCallIds.size > lastSettledToolCount;
+        lastSettledToolCount = mirror.settledToolCallIds.size;
 
         const progressed = outputGrew || toolActivity || resultActivity || messageActivity
-          || newAssistant || reasoningActivity;
+          || newAssistant || reasoningActivity || settleActivity;
         if (progressed) { lastProgressAt = Date.now(); }
 
         // B53: a wedged tool call (tool_use emitted, result never arrives) otherwise
@@ -547,9 +687,19 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         // (text/tool/result/message/new-assistant) has been observed for the stall
         // window — this cannot false-positive during active streaming (progress
         // resets the clock every poll) and cannot fire without a wedged tool.
-        const pendingToolCalls = getPendingToolCalls(mirror);
-        if (pendingToolCalls.length > 0 && (Date.now() - lastProgressAt) > toolCallStallMs) {
-          const stalled = pendingToolCalls[0];
+        //
+        // v4.4 B4: SKIPPED while a tool-settle deferral is active. B53 was written
+        // against `pendingToolCalls`, which could never clear (no tool_result part
+        // exists), so its 180 s window was never calibrated against real tool
+        // durations — the measured `task` call that exposed this defect ran 190.6 s,
+        // so B53 would kill a healthy subagent leg 10 s short of its answer, and
+        // kill it CLOSED. Once a completion signal has fired, the bounded settle
+        // grace owns that decision and ends in a LOUD completion instead. B53's
+        // actual target — a wedge with NO output, where the idle gate never engages
+        // and therefore no deferral is ever active — is untouched.
+        if (pendingTools.length > 0 && toolSettleDeferredSince === null
+            && (Date.now() - lastProgressAt) > toolCallStallMs) {
+          const stalled = pendingTools[0];
           const pendingSeconds = Math.round((Date.now() - Date.parse(stalled.firstSeenAt)) / 1000);
           sessionError = `Tool call stalled: ${stalled.name} pending ${pendingSeconds}s with no result or output`;
           logger.error('Tool call stalled — no progress within threshold', {
@@ -572,7 +722,20 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
           if (currentAssistantMsgId !== null && mirror.output.length > 0) {
             stablePolls++;
             const threshold = assistantFinished ? stableFinishedPolls : stableIdlePolls;
-            if (stablePolls >= threshold) {
+            // v4.4 B4 part 1 — THE MEASURED DEFECT SITE. This is the gate that
+            // declared `wsgate02-s1-3` complete on 166 characters of preamble 129 s
+            // before its `task` tool finished. Deferred (bounded) when a tool call
+            // is still live.
+            //
+            // The `assistantFinished` branch is deliberately NOT deferred:
+            // OpenCode finalizes an assistant message only AFTER its tool calls
+            // end, so `time.completed` structurally implies settled. VERIFIED on
+            // the defect leg itself — task end 04:38:19.061, message
+            // time.completed 04:38:19.301 — and on both recorded multi-tool legs,
+            // whose last tool ended 62.3 s and 14.8 s before the leg completed.
+            // Gating it would add pure hang risk for no truth gained.
+            if (stablePolls >= threshold
+                && !(!assistantFinished && deferForUnsettledTools('stable-idle'))) {
               logger.debug('Session appears complete (idle)', { stablePolls, assistantFinished });
               completed = true;
               break;
@@ -636,16 +799,132 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
 
     watchdog.cancel();
     if (uninstallSignals) { uninstallSignals(); }
-    if (!externalServer) { await server.close(); }
 
-    // Log summary of tool calls for debugging
+    // ---- v4.4 B1: bounded post-loop usage reconciliation ----------------------
+    // MUST run before server.close() — the client needs a live server — and MUST
+    // NOT re-mirror text: mirrorMessages() would append the already-captured
+    // assistant output to conversation.jsonl a second time, so this uses the
+    // usage-only pass (src/sidecar/conversation-mirror.js mirrorUsageOnly).
+    //
+    // Strictly best-effort: every failure mode leaves the leg's completion
+    // verdict, summary and error exactly as the loop decided them. B2 is the
+    // safety net underneath — when the re-poll still sees nothing, the leg
+    // resolves to `unknown`, never a fabricated $0.
+    //
+    // Skipped when there is nothing to settle: an aborted leg (the caller pulled
+    // the plug), a leg that bailed on consecutive poll failures (the server is
+    // gone — three more reads would only burn the settle timeout), and a leg that
+    // errored with no output at all (no assistant message was ever billed).
+    // Deliberately NOT restricted to `completed`: a timed-out or tool-stalled leg
+    // spent real money too, and its usage is just as worth capturing.
+    const canSettleUsage = !aborted && !pollFailureBail && !(sessionError && !mirror.output);
+    if (canSettleUsage && usageSettlePolls > 0) {
+      for (let i = 0; i < usageSettlePolls; i++) {
+        // v4.4 (cost-council finding 2): the boundary covers the WHOLE loop body,
+        // not just the network read. It previously wrapped only `withTimeout(...)`,
+        // leaving `mirrorUsageOnly` and `allAssistantUsagePresent` — which inspect
+        // an untrusted snapshot shape — outside it. A throw there escaped
+        // runHeadless entirely and DISCARDED a leg whose answer was already
+        // captured and already paid for: the most expensive possible outcome for
+        // a path whose entire job is a nice-to-have usage top-up. "Best-effort"
+        // has to mean the effort, not just its first statement.
+        let done = false;
+        try {
+          const settled = await withTimeout(
+            getMessages(client, sessionId, ...dirArgs),
+            Math.min(pollCallTimeoutMs, USAGE_SETTLE_CALL_TIMEOUT_MS),
+            'getMessages(usage-settle)',
+          );
+          mirrorUsageOnly(settled, mirror);
+          done = allAssistantUsagePresent(settled);
+          if (!done && i < usageSettlePolls - 1) {
+            await new Promise(resolve => setTimeout(resolve, usageSettleIntervalMs));
+          }
+        } catch (settleErr) {
+          // Same disposition as the pre-existing network-failure branch: stop
+          // settling, keep every dollar already mirrored, and leave the loop's
+          // completion verdict, summary and error untouched. B2 remains the net
+          // underneath — no observation resolves to `unknown`, never a fake $0.
+          logger.debug('usage-settle re-poll failed (best-effort, leg unaffected)', {
+            taskId, attempt: i + 1, error: settleErr.message,
+          });
+          break;
+        }
+        if (done) { break; }
+      }
+    }
+
+    // Log summary of tool calls for debugging.
+    // v4.4 B4: this used to filter on `t.name === 'Task'` and was DEAD twice over —
+    // the mirror read `part.name` (the real shape has `part.tool`) so every name
+    // was undefined, and OpenCode's tool is named `task` in lowercase anyway.
+    const { isSubagentToolCall } = require('./sidecar/tool-part');
+    const subagentToolCalls = mirror.toolCalls.filter(isSubagentToolCall);
+
+    // ---- v4.4.1 CA-1: enumerate CHILD (subagent) session spend ---------------
+    // MUST run before server.close() — the walk needs a live server. A `task`
+    // call spawns a child OpenCode session that OpenCode bills separately and
+    // does NOT roll into this session's cost; amicus never looked, so $0.492506
+    // across the four recorded paid runs was invisible to every total the
+    // product prints. Safe to do at finalization only because dcb0792 stopped a
+    // `task` part going terminal while its child session is still live — before
+    // that, walking here would have captured a partial child cost and traded a
+    // silent zero for a silent floor.
+    //
+    // Run for EVERY leg, not only ones whose tool calls looked like `task`: the
+    // name-string proxy (src/sidecar/tool-part.js) was verified 1:1 on a
+    // 37-session corpus and nowhere else, so a child created by some other
+    // mechanism would be a silent under-count wearing a costExact badge — the
+    // exact defect the flag exists to kill. Skipped only when there is nothing
+    // to ask (same predicate as the usage settle: the server is gone, or the
+    // caller pulled the plug), in which case the leg falls back to the proxy and
+    // honestly reports its subtree as unknown.
+    let subtree = null;
+    if (canSettleUsage) {
+      try {
+        const { collectSubtreeUsage, subtreeIsUnknown } = require('./sidecar/child-sessions');
+        const walked = await collectSubtreeUsage(client, sessionId, {
+          directory,
+          callTimeoutMs: Math.min(pollCallTimeoutMs, USAGE_SETTLE_CALL_TIMEOUT_MS),
+          logger,
+        });
+        subtree = {
+          sessions: walked.sessions.length,
+          tokens: walked.tokens,
+          costReported: walked.costReported,
+          // The honesty verdict is decided HERE, where both observations live —
+          // the walk's own completeness and the `task`-call evidence. See
+          // subtreeIsUnknown for why a failed walk with no evidence of a
+          // subagent must NOT flag (an older server would otherwise mark every
+          // leg of every run inexact forever).
+          unknown: subtreeIsUnknown({
+            walkComplete: walked.complete,
+            sessionsFound: walked.sessions.length,
+            subagentCalls: subagentToolCalls.length,
+          }),
+        };
+        if (walked.sessions.length > 0) {
+          logger.info('Child session spend attributed to this leg', {
+            taskId, sessions: walked.sessions.map((s) => s.id),
+            costReported: walked.costReported, subtreeUnknown: subtree.unknown,
+          });
+        }
+      } catch (subtreeErr) {
+        // Cannot happen by construction (the collector swallows its own
+        // failures), but a throw here must never cost a leg its answer.
+        subtree = null;
+        logger.debug('subtree enumeration failed (best-effort)', { taskId, error: subtreeErr.message });
+      }
+    }
+
+    if (!externalServer) { await server.close(); }
     if (mirror.toolCalls.length > 0) {
       logger.info('Tool calls summary', {
         totalToolCalls: mirror.toolCalls.length,
-        taskToolCalls: mirror.toolCalls.filter(t => t.name === 'Task').length,
-        subagentTypes: mirror.toolCalls
-          .filter(t => t.name === 'Task' && t.input?.subagent_type)
-          .map(t => ({ type: t.input.subagent_type, model: t.input.model || 'inherited' }))
+        taskToolCalls: subagentToolCalls.length,
+        subagentTypes: subagentToolCalls
+          .filter(t => t.input && (t.input.subagent_type || t.input.description))
+          .map(t => ({ type: t.input.subagent_type || t.input.description, model: (t.input && t.input.model) || 'inherited' }))
       });
     }
 
@@ -658,6 +937,58 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
     const { sumPerMessageUsage } = require('./utils/pricing');
     const usage = sumPerMessageUsage(mirror.usageByMsg);
 
+    // ---- v4.4 B3: one TERMINAL progress record carrying the settled usage ----
+    // progress.json's `usage` block was previously stamped only on 'receiving'
+    // flushes, which fire on text/tool/reasoning GROWTH — always strictly before
+    // OpenCode's finalization stamp — and writeProgress rebuilds the file from
+    // scratch, so it could not preserve an earlier snapshot either. Net effect on
+    // real runs: 31 of 35 legs ended with an all-zero usage snapshot while their
+    // metadata.json held thousands of real tokens. That snapshot is what the LIVE
+    // workspace GUI reads (src/observe/live-doc.js enrichLegUsage → resolveUsage),
+    // so every completed leg rendered as free.
+    //
+    // `messagesReceived` is deliberately omitted: readProgress() derives `messages`
+    // from conversation.jsonl's assistant entries and only falls back to this field
+    // when there are none, so re-stating it here would add nothing and could only
+    // disagree with the file it is meant to summarize.
+    //
+    // v4.4 B4: when the settle grace was exceeded the leg completed with tool
+    // calls still live, so its reported cost is a FLOOR and its session may still
+    // be billing. That must travel with the leg, not just sit in a log line — the
+    // live GUI reads this file (src/observe/live-doc.js). `unsettledToolCalls` is
+    // a COUNT here (progress.json is a compact snapshot); the full list is on the
+    // returned result for the caller's metadata.
+    const settleFlags = toolSettleTimedOut
+      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling.length }
+      : {};
+    // v4.4 B4 (Task 2) + v4.4.1 CA-1: a leg that made a SUBAGENT call has spend
+    // in a CHILD OpenCode session that is billed separately and is NOT rolled
+    // into the parent session's cost. `subtree` carries what the walk MEASURED;
+    // `subtreeUnknown` is what it could not. The proxy count survives as the
+    // fallback for the case where the walk could not run at all (see the
+    // enumeration block above) — src/sidecar/tool-part.js isSubagentToolCall
+    // has the 1:1 evidence for it.
+    const subtreeFlags = subagentToolCalls.length > 0
+      ? { subagentToolCalls: subagentToolCalls.length }
+      : {};
+    const subtreeResult = subtree ? { subtree } : {};
+    // The live workspace reads progress.json directly (src/observe/live-doc.js
+    // enrichLegUsage), so the attribution has to travel on BOTH channels or the
+    // GUI's cost-by-seat silently disagrees with run.json.
+    const subtreeProgress = subtree
+      ? { ...(subtree.sessions > 0
+        ? { subtree: { sessions: subtree.sessions, tokens: subtree.tokens, costReported: subtree.costReported } }
+        : {}),
+      ...(subtree.unknown ? { subtreeUnknown: true } : {}) }
+      : (subagentToolCalls.length > 0 ? { subtreeUnknown: true } : {});
+    try { writeProgress(sessionDir, 'complete', { usage: { ...usage, ...subtreeProgress }, ...settleFlags }); }
+    catch (progressErr) {
+      logger.debug('terminal progress write failed (best-effort)', { taskId, error: progressErr.message });
+    }
+    const settleResult = toolSettleTimedOut
+      ? { toolSettleTimedOut: true, unsettledToolCalls: unsettledAtCeiling }
+      : {};
+
     if (sessionError && (!mirror.output || pollFailureBail || toolStalled)) {
       return {
         summary: mirror.output ? extractSummary(mirror.output, foldNonce) : '',
@@ -667,6 +998,9 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
         taskId,
         toolCalls: mirror.toolCalls,
         usage,
+        ...settleResult,
+        ...subtreeFlags,
+        ...subtreeResult,
         error: sessionError
       };
     }
@@ -679,6 +1013,9 @@ async function runHeadless(model, systemPrompt, userMessage, taskId, project, ti
       taskId,
       toolCalls: mirror.toolCalls, // Include tool calls in result for verification
       usage,
+      ...settleResult,
+      ...subtreeFlags,
+      ...subtreeResult,
       exitCode: 0
     };
 
@@ -800,4 +1137,8 @@ module.exports = {
   POLL_CALL_TIMEOUT_MS,
   MAX_CONSECUTIVE_POLL_FAILURES,
   TOOL_CALL_STALL_MS,
+  USAGE_SETTLE_POLLS,
+  USAGE_SETTLE_INTERVAL_MS,
+  USAGE_SETTLE_CALL_TIMEOUT_MS,
+  TOOL_SETTLE_GRACE_MS,
 };

package/src/mcp-council-awareness.js

@@ -15,7 +15,14 @@
 const fs = require('fs');
 const path = require('path');
 const runState = require('./council/run-state');
+// The pointer-containment fence. Lives in a dependency-free leaf module
+// (src/utils/path-fence.js) precisely so any surface can require it —
+// requiring it here adds no cycle and keeps ONE implementation of the check
+// shared with the v4.4 workspace reads.
+const { containsOnDisk } = require('./utils/path-fence');
 const { RUNNING_VERSION } = require('./utils/version-info');
+const { enrichLegUsage, markLive, rollupWaveUsage } = require('./observe/live-doc');
+const { buildLegRows } = require('./observe/council-legs');
 
 /**
  * Every wave a stage launched: the primary `waveId` plus the recorded
@@ -58,6 +65,65 @@ function countWaveLegs(project, waveId) {
   return { total: legs.length, complete };
 }
 
+/**
+ * Leg ids recorded on a sub-wave's metadata.json, or [] when the wave record
+ * is absent/malformed. A small sibling to countWaveLegs — kept separate so
+ * that helper's {total, complete} contract (other callers depend on it) isn't
+ * overloaded into returning ids too.
+ * @returns {string[]}
+ */
+function waveLegIds(project, waveId) {
+  const { getSessionDir } = require('./session-manager');
+  let legs;
+  try {
+    legs = JSON.parse(fs.readFileSync(
+      path.join(getSessionDir(project, waveId), 'metadata.json'), 'utf-8')).legs;
+  } catch { return []; }
+  return Array.isArray(legs) ? legs : [];
+}
+
+/**
+ * Read-time cost-by-seat for one leg (A8: progress.json only, never a ledger).
+ * Tolerates a leg with no progress.usage yet — contributes nothing (N3).
+ */
+function legUsage(project, legId) {
+  const { getSessionDir } = require('./session-manager');
+  const { readProgress } = require('./sidecar/progress');
+  let model = null;
+  try {
+    model = JSON.parse(fs.readFileSync(
+      path.join(getSessionDir(project, legId), 'metadata.json'), 'utf-8')).model || null;
+  } catch { /* leg metadata not written yet */ }
+  let progressUsage;
+  try { progressUsage = readProgress(getSessionDir(project, legId)).usage; }
+  catch { /* no progress.json yet */ }
+  return enrichLegUsage({ model }, progressUsage);
+}
+
+/**
+ * readPointer PLUS the containment check the pointer file itself cannot
+ * provide. runState.readPointer validates `council-<id>.json`'s {runId, runDir}
+ * JSON only for truthiness (run-state.js:133-139), so a tampered or stale
+ * pointer can point runDir anywhere on disk — and the two callers below do not
+ * merely READ from it, they runState.checkpoint() INTO it (crash detection and
+ * abort), which makes an unfenced pointer a write primitive at an
+ * attacker-chosen path. A real runDir is always nested inside the project:
+ * src/mcp-council-run.js:109 rejects an outDir outside it at creation time, so
+ * nothing legitimate is refused here.
+ *
+ * Fails to null — the SAME "not a council run" signal an absent/corrupt pointer
+ * already produces, so amicus_status / amicus_abort keep their existing
+ * "Session <id> not found in project <cwd>" error contract (mcp-server.js:586,
+ * :1005) and `amicus abort` keeps falling through to its own not-found path.
+ * No new error shape, and — because the fence runs before readRun — no read or
+ * write ever reaches the escaping directory.
+ * @returns {{runId: string, runDir: string}|null}
+ */
+function readFencedPointer(project, taskId) {
+  const ptr = runState.readPointer(project, taskId);
+  return ptr && containsOnDisk(project, ptr.runDir) ? ptr : null;
+}
+
 function elapsedOf(run) {
   const end = run.completedAt || new Date().toISOString();
   const ms = Math.max(0, new Date(end).getTime() - new Date(run.createdAt || end).getTime());
@@ -66,7 +132,7 @@ function elapsedOf(run) {
 
 /** Status payload for a council runId, or null when the id is not a council run. */
 function buildCouncilStatusPayload(project, taskId) {
-  const ptr = runState.readPointer(project, taskId);
+  const ptr = readFencedPointer(project, taskId);
   if (!ptr) { return null; }
   const run = runState.readRun(ptr.runDir);
   if (!run) { return null; }
@@ -94,11 +160,24 @@ function buildCouncilStatusPayload(project, taskId) {
   // Sum across every sub-wave the active stage launched: a lens stage1 has no
   // seat wave at all, and a critic solo runs beside one. Stays null until at
   // least one sub-wave record exists on disk.
+  // Cost-by-seat rides the same loop, read-time from progress.json only (A8) —
+  // usageLegs stays empty (no `usage` on the payload) until a leg has actually
+  // flushed usage; a leg with none yet contributes nothing (N3). allLegIds
+  // collects every leg id seen regardless of usage — the row builder below
+  // needs just-started legs too (DE-ROT F01: the naive `payload.legs =
+  // usageLegs` would silently drop them).
+  const usageLegs = [];
+  const allLegIds = [];
   for (const waveId of active && active.project ? subWaveIds(active) : []) {
     const c = countWaveLegs(active.project, waveId);
     if (!c) { continue; }
     legsTotal = (legsTotal || 0) + c.total;
     legsComplete = (legsComplete || 0) + c.complete;
+    for (const legId of waveLegIds(active.project, waveId)) {
+      allLegIds.push(legId);
+      const enriched = legUsage(active.project, legId);
+      if (enriched.usage) { usageLegs.push(enriched); }
+    }
   }
   const payload = {
     taskId: run.runId, type: 'council-run', runId: run.runId, runDir: ptr.runDir,
@@ -107,8 +186,18 @@ function buildCouncilStatusPayload(project, taskId) {
     exitCode: run.exitCode !== undefined ? run.exitCode : null,
     version: RUNNING_VERSION,
   };
+  if (usageLegs.length) { payload.usage = rollupWaveUsage(usageLegs); }
+  if (allLegIds.length) {
+    // F34/F36: bench/critic/lenses are the alias-valued fields legRole needs
+    // (roleFor's rule); stageName lets it treat the chair stage as its own
+    // case rather than matching on alias (see council-legs.js's legRole doc).
+    const runCtx = { bench: run.bench, critic: run.critic, lenses: run.lenses, stageName: active.name };
+    const built = buildLegRows(active.project, allLegIds, runCtx);
+    payload.legs = built.rows;
+    if (built.stalled) { payload.stalled = true; payload.stalledForSeconds = built.stalledForSeconds; }
+  }
   if (run.error) { payload.reason = `${run.error.code}: ${run.error.message}`; }
-  return payload;
+  return markLive(payload);
 }
 
 /** amicus_list entries for every council pointer in the project. */
@@ -116,6 +205,12 @@ function listCouncilRuns(project) {
   const { sanitizePreview } = require('./sidecar/progress-fields');
   const out = [];
   for (const ptr of runState.listPointers(project)) {
+    // Same fence as readFencedPointer, applied per enumerated pointer
+    // (listPointers parses the files itself and is no stricter about runDir).
+    // Skipping is the right failure mode here: an escaping pointer degrades
+    // exactly like the unreadable-run.json case below, so one tampered pointer
+    // can never blank the rest of the list.
+    if (!containsOnDisk(project, ptr.runDir)) { continue; }
     const run = runState.readRun(ptr.runDir);
     if (!run) { continue; }
     let briefing = '';
@@ -159,7 +254,7 @@ function cascadeWave(project, waveId) {
  * @returns {null|{notFound?: true}|{alreadyTerminal: true, status}|{aborted: true, cascaded: number}}
  */
 function abortCouncilRun(project, taskId) {
-  const ptr = runState.readPointer(project, taskId);
+  const ptr = readFencedPointer(project, taskId);
   if (!ptr) { return null; }
   const run = runState.readRun(ptr.runDir);
   if (!run) { return null; }