amicus 4.4.0 → 4.4.1

package/src/sidecar/fanout-wave-io.js

@@ -0,0 +1,75 @@
+// src/sidecar/fanout-wave-io.js
+'use strict';
+
+/**
+ * @module fanout-wave-io
+ * On-disk lifecycle of a WAVE document, split out of fanout.js to keep that
+ * file under the 300-line gate (v4.4.1 Task 0.5, which needed room for the
+ * external-server seam). Pure move — same writes, same order, same atomicity:
+ *
+ *   writeWaveMetadata  metadata.json read-merge-write, abort-wins
+ *   writeWaveDoc       wave.json, atomic (tmp + rename)
+ *   finishWave         the terminal path every completed wave funnels through:
+ *                      persist → checkpoint metadata → emit wave-terminal →
+ *                      fire --on-complete → print
+ *
+ * `finishWave` had two byte-identical copies in fanout.js (the all-legs-failed-
+ * to-route short circuit and the normal aggregation); they are one function here
+ * so a future change to the terminal contract cannot land on only one of them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { writeFileAtomic } = require('../utils/atomic-write');
+
+/**
+ * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
+ * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
+ * to a softer status (same precedence rule as writeLegPatch — a signal/abort
+ * marker must never lose a write race against an in-flight init/finalize).
+ */
+function writeWaveMetadata(waveDir, patch) {
+  const metaPath = path.join(waveDir, 'metadata.json');
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
+  }
+  const safePatch = { ...patch };
+  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
+    delete safePatch.status;
+  }
+  const merged = { ...existing, ...safePatch };
+  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+  return merged;
+}
+
+/**
+ * Persist a wave document atomically (tmp + rename).
+ * @returns {string} the wave.json path
+ */
+function writeWaveDoc(waveDir, wave) {
+  const wavePath = path.join(waveDir, 'wave.json');
+  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
+  return wavePath;
+}
+
+/**
+ * Terminal path for a wave that produced leg documents: persist wave.json,
+ * checkpoint metadata.json, emit wave-terminal, fire --on-complete, print.
+ * @param {{wave: object, waveDir: string, waveId: string, project: string,
+ *   exitCode: number, completedAt: string, follow: object|null, emit: Function,
+ *   onComplete?: string, onCompleteDeps?: object}} args
+ * @returns {Promise<{wave: object, exitCode: number}>}
+ */
+async function finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit, onComplete, onCompleteDeps }) {
+  const { emitWaveTerminal } = require('../observe/events');
+  const wavePath = writeWaveDoc(waveDir, wave);
+  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
+  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
+  await require('../observe/on-complete').fireWaveOnComplete(onComplete, wave,
+    { waveId, waveDir, wavePath, exitCode, project }, onCompleteDeps);
+  emit(wave);
+  return { wave, exitCode };
+}
+
+module.exports = { writeWaveMetadata, writeWaveDoc, finishWave };

package/src/sidecar/fanout.js

@@ -16,7 +16,10 @@ const { logger } = require('../utils/logger');
 const { runLeg, buildRoutingFailureLeg } = require('./fanout-leg');
 const { parseModelsList, DEFAULT_MAX_LEGS, validateFanoutModels } = require('./fanout-validate');
 const { ERROR_CODES } = require('../utils/error-doc');
-const { writeFileAtomic } = require('../utils/atomic-write');
+// Wave-document persistence lives in ./fanout-wave-io (size-gate split, v4.4.1
+// Task 0.5). writeWaveMetadata is re-exported below — fanout-retry.js and the
+// fanout tests import it from here.
+const { writeWaveMetadata, writeWaveDoc, finishWave } = require('./fanout-wave-io');
 
 /**
  * Derive leg task IDs: <waveId>-1 .. <waveId>-N (matches TASK_ID_PATTERN).
@@ -28,27 +31,6 @@ function deriveLegIds(waveId, count) {
   return Array.from({ length: count }, (_, i) => `${waveId}-${i + 1}`);
 }
 
-/**
- * Write/merge wave metadata (preserves fields an MCP pre-spawn handler wrote).
- * Abort-wins: once existing status is 'aborted', a patch cannot demote it back
- * to a softer status (same precedence rule as writeLegPatch — a signal/abort
- * marker must never lose a write race against an in-flight init/finalize).
- */
-function writeWaveMetadata(waveDir, patch) {
-  const metaPath = path.join(waveDir, 'metadata.json');
-  let existing = {};
-  if (fs.existsSync(metaPath)) {
-    try { existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8')); } catch { /* corrupt → rewrite */ }
-  }
-  const safePatch = { ...patch };
-  if (existing.status === 'aborted' && safePatch.status && safePatch.status !== 'aborted') {
-    delete safePatch.status;
-  }
-  const merged = { ...existing, ...safePatch };
-  writeFileAtomic(metaPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
-  return merged;
-}
-
 /**
  * Run a fan-out wave. Spec §4.3.
  * @param {object} options - models, prompt, promptMeta, waveId?, project, agent?,
@@ -59,7 +41,11 @@ function writeWaveMetadata(waveDir, patch) {
  *   with routing.prefer, applied per leg), json?, client?, quiet? (suppress
  *   stdout — tests), councilRunId? / councilName? (v4.3 §7.2: stamped onto legs),
  *   fallback? / catalog? (v4.3 Task 18 §6.2: opt-in substitution; off/absent unchanged),
- *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical)
+ *   retryContexts? / retryOfWaveId? (v4.3 Task 19: --retry-failed relaunch seam; absent -> byte-identical),
+ *   server? + serverClient? (v4.4.1 Task 0.5: an ALREADY-STARTED OpenCode server
+ *     to run this wave's legs on. Both or neither. When supplied this wave never
+ *     starts a server and never closes one — see the seam comment in step 4.
+ *     NOT `client`, which is the client TYPE string on this function.)
  * @returns {Promise<{wave: object, exitCode: number}>} Never rejects for leg errors.
  */
 async function runFanout(options) {
@@ -70,9 +56,9 @@ async function runFanout(options) {
   const { buildContext } = require('./context-builder');
   const { buildPrompts } = require('../prompt-builder');
   const { generateFoldNonce } = require('../utils/fold-marker');
-  const { installSignalAbort, markAborted } = require('../utils/session-abort');
+  const { installWaveAbort } = require('./fanout-signals');
   const { getSessionDir } = require('../session-manager');
-  const { emitWaveStarted, emitWaveTerminal } = require('../observe/events');
+  const { emitWaveStarted } = require('../observe/events'); // wave-terminal is emitted by finishWave
 
   const project = options.project || process.cwd();
   const createdAt = new Date().toISOString();
@@ -88,9 +74,17 @@ async function runFanout(options) {
       console.log(formatWaveHuman(doc));
     }
   };
-  const errorWave = (waveId, message) => {
+  // v4.4.1 Task 0.5: a wave that dies BEFORE its legs still owes the run a
+  // wave.json. Backlog C1 covered the pre-`try` throw; a server that never
+  // started was its uncovered sibling — run v441plan01's four dead seats left a
+  // `reason` in metadata.json, no wave.json, and stage1 recorded 'complete'.
+  // waveDir is optional (only the post-creation caller has one).
+  const errorWave = (waveId, message, waveDir) => {
     const doc = buildWaveResult({ waveId: waveId || null, legs: [], promptMeta: options.promptMeta || null, createdAt, completedAt: new Date().toISOString(), status: 'error' });
     doc.error = message;
+    doc.reason = message; // classifier alias, same as fanout-leg.js's run docs
+    // best-effort: an unwritable wave dir must not mask the real error
+    if (waveDir) { try { writeWaveDoc(waveDir, doc); } catch { /* ignore */ } }
     emit(doc);
     return { wave: doc, exitCode: 1 };
   };
@@ -162,14 +156,9 @@ async function runFanout(options) {
     const wave = buildWaveResult({
       waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt, notices,
     });
-    const wavePath = path.join(waveDir, 'wave.json');
-    writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
-    writeWaveMetadata(waveDir, { status: wave.status, completedAt });
-    const routingExitCode = waveExitCode(wave.status);
-    emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode: routingExitCode }, follow);
-    await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode: routingExitCode, project }, options.onCompleteDeps);
-    emit(wave);
-    return { wave, exitCode: routingExitCode };
+    return finishWave({ wave, waveDir, waveId, project, completedAt, follow, emit,
+      exitCode: waveExitCode(wave.status),
+      onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
   }
 
   // 3. Context + prompts built ONCE (model-independent)
@@ -198,37 +187,41 @@ async function runFanout(options) {
     mcp: options.mcp, mcpConfig: options.mcpConfig, clientType: options.client,
     noMcp: options.noMcp, excludeMcp: options.excludeMcp,
   });
+  // ⚠️ v4.4.1 Task 0.5 — the external-server seam runHeadless has carried since
+  // v4.0 (src/headless.js:245): a caller that already owns a server passes it in
+  // and we must NOT close it. Added here because a council run launches its
+  // Stage-1 seat wave and its critic solo under ONE Promise.all (run-stages.js:83)
+  // and two concurrent startOpenCodeServer calls race on OpenCode's SQLite —
+  // run v441plan01 lost four of five seats in 736ms to `database is locked`.
+  // NAME DIVERGENCE, deliberate: runHeadless spells the pair client+server, but
+  // runFanout's `options.client` is ALREADY the client TYPE string (buildMcpConfig
+  // above, buildContext, buildPrompts, cli-handlers-run.js `client: args.client`),
+  // so the SDK client is `options.serverClient`. Both or neither: a half-injection
+  // falls back to owning a server rather than running clientless.
+  const externalServer = !!(options.server && options.serverClient);
   let client, server;
-  try {
-    ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
-  } catch (err) {
-    writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
-    return errorWave(waveId, `Failed to start server: ${err.message}`);
+  if (externalServer) {
+    ({ serverClient: client, server } = options);
+    logger.debug('Using external server (shared server mode)', { waveId, url: server.url });
+  } else {
+    try {
+      ({ client, server } = await startOpenCodeServer(mcpServers, { models: validated.serverModels || okLegs.map(l => l.model) }));
+    } catch (err) {
+      writeWaveMetadata(waveDir, { status: 'error', reason: err.message, completedAt: new Date().toISOString() });
+      return errorWave(waveId, `Failed to start server: ${err.message}`, waveDir);
+    }
   }
-  if (server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
+  // Only an OWNED server's pid belongs in this wave's metadata: mcp-server.js's
+  // wave abort SIGTERMs `metadata.goPid` as "the orchestrator + its OWNED
+  // OpenCode server", which on an injected server would kill every sibling wave.
+  if (!externalServer && server.goPid) { writeWaveMetadata(waveDir, { goPid: server.goPid }); }
 
-  // 5. Signal abort: mark wave + all legs aborted, close the server, then let
-  // NORMAL control flow finalize — legs see their abort marker within one poll
-  // (~2s) and settle, so step 7 still writes wave.json and emits a parseable
-  // aborted document. An unref'd force-exit watchdog backstops a wedged leg.
+  // 5. Signal abort (./fanout-signals owns the handler — size gate): mark wave +
+  // all legs aborted, close an OWNED server, then let NORMAL control flow
+  // finalize, so step 7 still writes wave.json and emits a parseable aborted
+  // document. An unref'd force-exit watchdog backstops a wedged leg.
   const legDirs = legIds.map(id => getSessionDir(project, id));
-  let signalled = null;
-  const uninstallSignals = installSignalAbort({
-    onAbort: (signal) => {
-      const code = signal === 'SIGINT' ? 130 : 143;
-      if (signalled) { process.exit(code); } // second signal: exit NOW
-      signalled = signal;
-      logger.warn('Signal received — aborting wave', { waveId, signal });
-      markAborted(waveDir, signal);
-      for (const dir of legDirs) { markAborted(dir, signal); }
-      // close() is async (B06 escalation); this handler stays sync, so
-      // fire-and-forget with a rejection guard. The 10s exit watchdog below
-      // comfortably outlives the ~2s escalation grace inside close().
-      try { server.close().catch(() => {}); } catch { /* best-effort */ }
-      const { armExitWatchdog } = require('../utils/lifecycle');
-      armExitWatchdog(code, 10000, { log: (m, meta) => logger.debug(m, meta) });
-    },
-  });
+  const waveAbort = installWaveAbort({ waveId, waveDir, legDirs, server, externalServer });
 
   // 6. Launch all ROUTABLE legs concurrently (runLeg never rejects). A leg that
   // failed to route (leg.ok === false) resolves to an error run doc in its own
@@ -262,26 +255,24 @@ async function runFanout(options) {
     }));
   } finally {
     heartbeat.stop();
-    uninstallSignals();
-    try { await server.close(); } catch { /* already closed on signal */ }
+    waveAbort.uninstall();
+    // ⚠️ close site 2 of 2 (`grep -n "server.close()" src/sidecar/fanout.js`).
+    // An injected server outlives this wave by design — the owner closes it once.
+    if (!externalServer) { try { await server.close(); } catch { /* already closed on signal */ } }
   }
 
   // 7. Aggregate, persist (atomic: tmp + rename), finalize, emit
   const completedAt = new Date().toISOString();
+  const signalled = waveAbort.signal();
   const wave = buildWaveResult({
     waveId, legs: legDocs, promptMeta: options.promptMeta || null, createdAt, completedAt,
     status: signalled ? 'aborted' : null, notices,
   });
-  const wavePath = path.join(waveDir, 'wave.json');
-  writeFileAtomic(wavePath, JSON.stringify(wave, null, 2), { mode: 0o600 });
-  writeWaveMetadata(waveDir, { status: wave.status, completedAt });
   const exitCode = signalled
     ? (signalled === 'SIGINT' ? 130 : 143)
     : waveExitCode(wave.status);
-  emitWaveTerminal(waveDir, waveId, { status: wave.status, counts: wave.counts, usage: wave.usage, exitCode }, follow);
-  await require('../observe/on-complete').fireWaveOnComplete(options.onComplete, wave, { waveId, waveDir, wavePath, exitCode, project }, options.onCompleteDeps);
-  emit(wave);
-  return { wave, exitCode };
+  return finishWave({ wave, waveDir, waveId, project, exitCode, completedAt, follow, emit,
+    onComplete: options.onComplete, onCompleteDeps: options.onCompleteDeps });
 }
 
 module.exports = {

package/src/sidecar/progress-fields.js

@@ -10,6 +10,23 @@
 /** Coarse stages surfaced to agents. */
 const COARSE_STAGES = ['starting', 'generating', 'folding', 'terminal'];
 
+/**
+ * The stages src/headless.js can write on its ONE terminal progress record.
+ *
+ * ⚠️ v4.4.1 LC-3: this list must stay byte-identical to resolveTerminalState's
+ * status vocabulary (src/sidecar/session-finalize.js), because headless.js
+ * derives the terminal stage straight from that function. A drift pin in
+ * tests/sidecar/progress-fields.test.js asserts it.
+ *
+ * Before LC-3 the terminal record hardcoded 'complete' on every path, so this
+ * set had exactly one member and deriveStage could match the literal. Widening
+ * the writer without widening this set would have been the WORSE bug: an
+ * aborted/errored/timed-out leg would fall through to 'starting' and a finished
+ * leg would read as barely begun for the whole window before metadata.json
+ * lands.
+ */
+const TERMINAL_PROGRESS_STAGES = new Set(['complete', 'error', 'timed-out', 'aborted']);
+
 /**
  * Collapse whitespace and defang fence/tag characters so the preview can be
  * embedded in a one-line JSON status without opening a code fence or tag
@@ -42,8 +59,10 @@ function latestAssistantPreview(entries) {
  * Map (metadata.status, progress.stage) to the coarse agent-facing stage.
  *  - terminal metadata status -> 'terminal'
  *  - progress 'receiving' -> 'generating'
- *  - progress 'complete' while metadata still says running -> 'folding'
- *    (mirror stopped; summary/conflict finalize in flight)
+ *  - a TERMINAL progress stage while metadata still says running -> 'folding'
+ *    (mirror stopped; summary/conflict finalize in flight). v4.4.1 LC-3: that is
+ *    any of TERMINAL_PROGRESS_STAGES, not just 'complete' — an aborted or
+ *    errored leg is every bit as "done streaming, finalizing" as a clean one.
  *  - anything else -> 'starting'
  * @param {string|undefined} metadataStatus @param {string|undefined} progressStage
  * @returns {string}
@@ -53,8 +72,11 @@ function deriveStage(metadataStatus, progressStage) {
     return 'terminal';
   }
   if (progressStage === 'receiving') { return 'generating'; }
-  if (progressStage === 'complete') { return 'folding'; }
+  if (TERMINAL_PROGRESS_STAGES.has(progressStage)) { return 'folding'; }
   return 'starting';
 }
 
-module.exports = { sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES };
+module.exports = {
+  sanitizePreview, latestAssistantPreview, deriveStage, COARSE_STAGES,
+  TERMINAL_PROGRESS_STAGES,
+};

package/src/sidecar/progress.js

@@ -19,7 +19,14 @@ const STAGE_LABELS = {
   session_created: 'Session created',
   prompt_sent: 'Briefing delivered, waiting for response...',
   receiving: 'Generating response...',
-  complete: 'Complete'
+  complete: 'Complete',
+  // v4.4.1 LC-3: the terminal record is no longer always 'complete' — headless.js
+  // derives it from resolveTerminalState, so these three are now reachable. Without
+  // a label, readProgress's `latest` (which falls back to stageLabel when the leg
+  // has no assistant messages yet) would read the raw id: "aborted", not "Aborted".
+  aborted: 'Aborted',
+  error: 'Failed',
+  'timed-out': 'Timed out'
 };
 
 /**

package/src/sidecar/session-utils.js

@@ -229,13 +229,14 @@ async function executeMode(options) {
  *   has no single default `config.model`, so this registers ALL of them in provider.models
  *   instead. Additive alongside the single-model `options.model` path used by owned-server
  *   callers (start/continue); see opencode-client.js's buildServerOptions.
+ * @param {number} [options.retryDelayMs] - Test seam: collapse the lock-race backoff.
  * @returns {Promise<{client: object, server: object}>}
  * @throws {Error} If server fails to start or health check fails
  */
 async function startOpenCodeServer(mcpConfig, options = {}) {
   const { checkHealth, startServer } = require('../opencode-client');
   const { ensureNodeModulesBinInPath } = require('../utils/path-setup');
-  const { ensurePortAvailable } = require('../utils/server-setup');
+  const { ensurePortAvailable, retryOnLockRace } = require('../utils/server-setup');
   const { waitForServer } = require('../headless');
 
   ensureNodeModulesBinInPath();
@@ -253,20 +254,28 @@ async function startOpenCodeServer(mcpConfig, options = {}) {
   if (options.systemPrompt) { serverOptions.systemPrompt = options.systemPrompt; }
   if (options.agentName) { serverOptions.agentName = options.agentName; }
 
-  const { client, server } = await startServer(serverOptions);
-  logger.debug('OpenCode server started', { url: server.url });
-
-  const ready = await waitForServer(client, checkHealth);
-  if (!ready) {
-    // Fire-and-forget: today close() is sync (Promise.resolve wraps a
-    // non-promise harmlessly); once close() becomes async (bounded
-    // kill-escalation poll) this guard prevents an unhandled rejection
-    // from racing the throw below.
-    Promise.resolve(server.close()).catch(() => {});
-    throw new Error('OpenCode server failed to become ready');
-  }
+  // v4.4.1 Task 0.5: a LOCK-CLASS start failure is retried (5 attempts,
+  // 250/500/1000/2000ms — widened from 3/750ms by Step 10.5, see server-setup).
+  // The per-run shared server removes the races a single amicus process creates;
+  // this covers the ones it cannot — two amicus processes, or a CLI run beside a
+  // live MCP server, sharing one OpenCode SQLite database. Nothing else retries:
+  // see isLockClassStartFailure in ../utils/server-setup.
+  return retryOnLockRace(async () => {
+    const { client, server } = await startServer(serverOptions);
+    logger.debug('OpenCode server started', { url: server.url });
+
+    const ready = await waitForServer(client, checkHealth);
+    if (!ready) {
+      // Fire-and-forget: today close() is sync (Promise.resolve wraps a
+      // non-promise harmlessly); once close() becomes async (bounded
+      // kill-escalation poll) this guard prevents an unhandled rejection
+      // from racing the throw below.
+      Promise.resolve(server.close()).catch(() => {});
+      throw new Error('OpenCode server failed to become ready');
+    }
 
-  return { client, server };
+    return { client, server };
+  }, { retryDelayMs: options.retryDelayMs });
 }
 
 module.exports = {

package/src/spend-query.js

@@ -60,25 +60,32 @@ function rowKey(row, dimension) {
 }
 
 /**
- * Group rows into {key, amount, tokens, runs, unpricedRows, sourceMix},
- * most-expensive first.
+ * Group rows into {key, amount, tokens, runs, unpricedRows,
+ * unattributedSubtreeRows, sourceMix}, most-expensive first.
  *
  * v4.4: `amount` deliberately stays a plain number — the published
  * spend.schema.json pins `groups[].amount` to `type: "number"` — so
  * `unpricedRows` is how a group says "this figure omits N rows we cannot
  * price". Without it, a group of entirely unpriced rows was indistinguishable
  * from a group that genuinely cost $0 (diagnosis §8).
+ *
+ * v4.4.1 CA-2: `unattributedSubtreeRows` is the SECOND way a figure can be a
+ * floor, and `unpricedRows` structurally cannot see it — such a row IS priced,
+ * lands in the `r` source bucket, and contributes its own cost to `amount`; what
+ * is missing is the child session it spawned. The two counters are incremented
+ * BESIDE each other, never instead of: a row can be both.
  */
 function groupRows(rows, dimension) {
   const map = new Map();
   for (const r of rows) {
     const key = rowKey(r, dimension);
-    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
+    if (!map.has(key)) { map.set(key, { key, amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, sourceMix: { reported: 0, estimated: 0, unknown: 0 } }); }
     const b = map.get(key);
     b.runs += 1;
     addTokens(b.tokens, r.tokens);
     const cost = r.cost || {};
     if (typeof cost.amount === 'number') { b.amount += cost.amount; } else { b.unpricedRows += 1; }
+    if (r.subtreeUnknown) { b.unattributedSubtreeRows += 1; }
     const src = (cost.source === 'reported' || cost.source === 'estimated') ? cost.source : 'unknown';
     b.sourceMix[src] += 1;
   }
@@ -96,7 +103,7 @@ function groupRows(rows, dimension) {
  * a row); computeWasted intentionally drops it instead.
  */
 function computeWasted(rows) {
-  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, byStatus: {} };
+  const out = { amount: 0, tokens: emptyTokens(), runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0, byStatus: {} };
   for (const r of rows) {
     if (r.status === 'complete' || !r.status) { continue; }
     out.runs += 1;
@@ -104,14 +111,19 @@ function computeWasted(rows) {
     // v4.4: null→0 here is arithmetic, not a claim. `unpricedRows` records how
     // many failed rows we could not price so "wasted $X" is never mistaken for
     // the whole loss (see groupRows for why `amount` stays a number).
+    // v4.4.1 CA-2: `unattributedSubtreeRows` is the other half of the same
+    // understatement — a failed leg that DID resolve its own cost but left a
+    // child session unpriced. Counted beside `unpricedRows`, never instead of.
     const priced = r.cost && typeof r.cost.amount === 'number';
     const amt = priced ? r.cost.amount : 0;
     if (!priced) { out.unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.unattributedSubtreeRows += 1; }
     out.amount += amt;
-    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0 }; }
+    if (!out.byStatus[r.status]) { out.byStatus[r.status] = { amount: 0, runs: 0, unpricedRows: 0, unattributedSubtreeRows: 0 }; }
     out.byStatus[r.status].amount += amt;
     out.byStatus[r.status].runs += 1;
     if (!priced) { out.byStatus[r.status].unpricedRows += 1; }
+    if (r.subtreeUnknown) { out.byStatus[r.status].unattributedSubtreeRows += 1; }
   }
   return out;
 }

package/src/utils/lifecycle.js

@@ -41,4 +41,40 @@ function armExitWatchdog(code = 0, ms = 1500, deps = {}) {
   return t;
 }
 
-module.exports = { isOneShotCommand, armExitWatchdog, ONE_SHOT_COMMANDS };
+/**
+ * An `exit` hook for armExitWatchdog that REAPS an OpenCode server this process
+ * is using but does not own, on its way out (v4.4.1 fix wave, finding F3).
+ *
+ * The force-exit path is the one place where "not ours to close" stops being the
+ * safe answer. A wave running on an injected server deliberately never closes it
+ * — the owner does, once, in its own finalize. But if the watchdog fires first
+ * the parent dies anyway, and the Go server survives it: an orphan still holding
+ * the OpenCode SQLite lock that the per-run shared server exists to stop
+ * contending on. Before the external-server seam, fanout's own close() covered
+ * this by accident; this restores it deliberately.
+ *
+ * SIGTERM only, and synchronous: process.exit cannot await server.close()'s
+ * escalation, so this sends the one signal that fits in the window and gets out
+ * of the way. Never signals this process, and never lets a dead/absent pid throw
+ * — the exit must happen regardless.
+ *
+ * @param {{goPid?: number|null}|null} server the injected server handle
+ * @param {{kill?: Function, exit?: Function}} [deps] test seams
+ * @returns {(code: number) => void}
+ */
+function exitReaping(server, deps = {}) {
+  return (code) => {
+    // Resolved at CALL time, not creation time: this hook is built the instant a
+    // signal lands and invoked up to 10s later, so binding process.kill/exit
+    // early would freeze whatever was installed at signal time.
+    const kill = deps.kill || ((p, sig) => process.kill(p, sig));
+    const exit = deps.exit || ((c) => process.exit(c));
+    const pid = server && server.goPid;
+    if (pid && pid !== process.pid) {
+      try { kill(pid, 'SIGTERM'); } catch { /* already gone: nothing to reap */ }
+    }
+    exit(code);
+  };
+}
+
+module.exports = { isOneShotCommand, armExitWatchdog, exitReaping, ONE_SHOT_COMMANDS };

package/src/utils/path-fence.js

@@ -7,7 +7,10 @@
  * for truthiness by src/council/run-state.js's readPointer, so nothing
  * upstream of this check guarantees it stays inside the project).
  *
- * It is a LEAF: `fs` + `path` and nothing else, no require cycle possible.
+ * It is a LEAF: `fs` + `path` at load time and nothing else, no require cycle
+ * possible. (SEC-3's debug-mode diagnostic requires src/utils/logger.js lazily,
+ * inside the flag branch — logger.js has zero requires of its own, so even that
+ * cannot introduce a cycle, and nothing is loaded at all with the flag unset.)
  * That was first needed inside the v4.4 workspace layer —
  * src/workspace/artifact-guard.js requires src/workspace/run-scan.js for
  * readPointer, so if run-scan.js also required artifact-guard.js for this
@@ -30,6 +33,39 @@
 const fs = require('fs');
 const path = require('path');
 
+/**
+ * ⚠️ SEC-3: isRealpathContained is a pure string-prefix comparison, and it is only SOUND
+ * if both arguments were already resolved through realpathSync. Nothing enforced that, so
+ * a caller who forgot got a silently WEAKER check rather than an error — a raw
+ * (unresolved) path containing a symlink can prefix-match a directory it does not
+ * physically live under.
+ *
+ * This is a DIAGNOSTIC, opt-in via `AMICUS_DEBUG_FENCE=1`, and it MUST NEVER THROW: the
+ * fence must never become the failure it exists to prevent. Every step is wrapped, and a
+ * non-existent path is a legitimate argument here (callers fence paths before probing
+ * them), so it is not reported. The logger is required lazily so this module keeps its
+ * `fs` + `path` load-time surface (see the header) for the 99.99% of calls that run with
+ * the flag unset.
+ * @param {string} dir already-stringified dirRealPath
+ * @param {string} target already-stringified targetRealPath
+ */
+function assertResolvedArgs(dir, target) {
+  try {
+    const { logger } = require('./logger');
+    for (const [name, p] of [['dirRealPath', dir], ['targetRealPath', target]]) {
+      if (!path.isAbsolute(p)) {
+        logger.warn('path-fence: argument is not absolute', { arg: name, value: p });
+        continue;
+      }
+      try {
+        if (fs.existsSync(p) && fs.realpathSync(p) !== p) {
+          logger.warn('path-fence: argument is not realpath-resolved', { arg: name, value: p });
+        }
+      } catch { /* unreadable / dangling: not this diagnostic's business */ }
+    }
+  } catch { /* a broken logger must never break the fence */ }
+}
+
 /**
  * True when `targetRealPath` is exactly `dirRealPath` or a proper descendant
  * of it. Both arguments MUST already be resolved through realpathSync — this
@@ -41,6 +77,8 @@ const path = require('path');
 function isRealpathContained(dirRealPath, targetRealPath) {
   const dir = String(dirRealPath);
   const target = String(targetRealPath);
+  // SEC-3: debug-mode contract check only — never a gate, never a throw (see above).
+  if (process.env.AMICUS_DEBUG_FENCE === '1') { assertResolvedArgs(dir, target); }
   if (target === dir) { return true; }
   // ⚠️ COUNCIL REVIEW R2 (A6): when dirRealPath IS a filesystem root, it already
   // ends in a separator ('/' on POSIX, 'C:\\' on Windows) — blindly appending

package/src/utils/pricing.js

@@ -63,24 +63,37 @@ function lookupPricing(modelId) {
 }
 
 /**
- * Did we actually OBSERVE any token usage for this leg? (v4.4 B2)
+ * Did we actually OBSERVE tokens THIS MODULE'S ESTIMATE CAN PRICE? (v4.4 B2,
+ * narrowed by v4.4.1 CA-7)
  *
  * This is the predicate that separates "the provider billed us for a $0 tier"
  * from "we never saw a usage payload at all" — a distinction the old
  * `pricing && tokens` guard could not make, because it only inspected the
- * PRICE. Accepts both the normalized totals shape (cacheRead/cacheWrite, as
- * produced by sumPerMessageUsage) and OpenCode's raw per-message shape
- * (`cache: {read, write}`), so callers holding either can ask one question.
+ * PRICE. It reads the normalized totals shape (input/output, as produced by
+ * sumPerMessageUsage) and OpenCode's raw per-message shape alike, because both
+ * carry `input`/`output` at the top level.
+ *
+ * ⚠️ CA-7: deliberately narrower than "did we see any token count at all". The
+ * estimate in resolveLegCost prices input/output ONLY, so accepting
+ * cacheRead/cacheWrite — and `reasoning`, which this predicate also used to
+ * accept and which the estimate likewise never prices — let a leg observed with
+ * none of input/output pass the observation gate and resolve to `estimated $0`:
+ * the same false-zero class the v4.4 observed-tokens fix exists to kill, in the
+ * one corner its predicate did not cover. Such a leg is now `unknown`, which is
+ * true, rather than free, which is not. Pricing cache or reasoning tokens
+ * properly needs catalog fields that may not exist; when they do, widen this and
+ * the estimate together, never one alone.
+ *
+ * Live-validated 2026-07-26: a real local leg reports `input: 25953, output: 3`,
+ * so the shipped v4.2 free-local `$0` promise (a local seat costs nothing but
+ * still reports real input/output) is untouched — tests/pricing-local.test.js
+ * is the standing guard on that.
  * @param {object|null|undefined} tokens
  * @returns {boolean}
  */
 function hasObservedTokens(tokens) {
   if (!tokens || typeof tokens !== 'object') { return false; }
-  const cache = tokens.cache && typeof tokens.cache === 'object' ? tokens.cache : {};
-  const cacheRead = tokens.cacheRead || cache.read || 0;
-  const cacheWrite = tokens.cacheWrite || cache.write || 0;
-  return (tokens.input || 0) > 0 || (tokens.output || 0) > 0
-    || (tokens.reasoning || 0) > 0 || cacheRead > 0 || cacheWrite > 0;
+  return (tokens.input || 0) > 0 || (tokens.output || 0) > 0;
 }
 
 /** @returns {{amount:number|null, currency:'USD', source:'reported'|'estimated'|'unknown'}} */
@@ -96,7 +109,10 @@ function resolveLegCost({ reportedCost, tokens, pricing }) {
   // The v4.2 §4.5 free-local-tier carve-out is DELIBERATELY preserved: a local
   // Ollama/LM Studio seat legitimately costs $0 but still reports tokens, so
   // hasObservedTokens() is true for it and it still resolves to `estimated $0`.
-  // Only a leg where we observed no tokens at all falls through to `unknown`.
+  // v4.4.1 CA-7: a leg with no input/output falls through to `unknown` even when
+  // it reported cache or reasoning tokens — those are real observations, but not
+  // ones THIS estimate can turn into a price, so calling the result $0 would be
+  // the same fabrication one corner over. See hasObservedTokens above.
   if (pricing && hasObservedTokens(tokens)) {
     const est = (tokens.input || 0) * pricing.prompt + (tokens.output || 0) * pricing.completion;
     if (est >= 0) { return { amount: est, currency: 'USD', source: 'estimated' }; }