amicus 4.3.0 → 4.4.1

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