@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/result-normalizer.js

@@ -224,6 +224,21 @@ export class AgentAbortedError extends Error {
   }
 }
 
+function copyDispatchId(source, target) {
+  try {
+    if (!source || !target || typeof source.dispatchId !== 'string') return target;
+    Object.defineProperty(target, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: source.dispatchId,
+    });
+  } catch {
+    // Error replacement must preserve the original control flow even if a
+    // third-party target is unexpectedly frozen.
+  }
+  return target;
+}
+
 /**
  * STRAT-DEDUP-AGENTRUN-V3: `runAndNormalize` is now a thin wrapper around the
  * Python connector tier exposed through `stratum_agent_run`. Events arrive as
@@ -236,6 +251,75 @@ export class AgentAbortedError extends Error {
  * call-sites do not all need to be edited in a single sweep. New required opt:
  * `opts.stratum` — the StratumMcpClient instance.
  */
+/**
+ * Sum two usage records into one, for a step whose work took more than one
+ * agent call (e.g. a COMP-POLICY-CHECK revision replacing the primary draft).
+ * Token/cost fields add; `model` keeps the later run's value when it has one.
+ * Either side may be null.
+ *
+ * @param {object|null} a
+ * @param {object|null} b
+ * @returns {object|null}
+ */
+export function mergeUsage(a, b) {
+  if (!a) return b ?? null;
+  if (!b) return a;
+  return {
+    input_tokens: (a.input_tokens ?? 0) + (b.input_tokens ?? 0),
+    output_tokens: (a.output_tokens ?? 0) + (b.output_tokens ?? 0),
+    cache_creation_input_tokens: (a.cache_creation_input_tokens ?? 0) + (b.cache_creation_input_tokens ?? 0),
+    cache_read_input_tokens: (a.cache_read_input_tokens ?? 0) + (b.cache_read_input_tokens ?? 0),
+    cost_usd: (a.cost_usd ?? 0) + (b.cost_usd ?? 0),
+    model: b.model ?? a.model ?? null,
+  };
+}
+
+function hasReportedUsage(usage) {
+  if (!usage || typeof usage !== 'object') return false;
+  return [
+    usage.tokens, usage.input_tokens, usage.output_tokens,
+    usage.cache_read, usage.cache_read_input_tokens,
+    usage.cache_creation, usage.cache_creation_input_tokens,
+    usage.cost_usd, usage.usd, usage.ms, usage.duration_ms,
+  ].some((value) => typeof value === 'number' && Number.isFinite(value) && value !== 0);
+}
+
+function usageRecordFromRaw(usage, telemetry, dispatchId, fallback = {}, split = null) {
+  if (!hasReportedUsage(usage)) return null;
+  // STRAT-USAGE-SPLIT: prefer the connector-reported split over reconstruction
+  // (the reconstruction cannot tell input from output; it filed the aggregate
+  // as output on every record before surface 16).
+  const input = split?.input ?? usage.input_tokens ?? 0;
+  const output = split?.output
+    ?? usage.output_tokens
+    ?? (typeof usage.tokens === 'number' ? Math.max(0, usage.tokens - input) : 0);
+  const record = {
+    dispatch_id: dispatchId ?? randomUUID(),
+    model: telemetry?.model ?? usage.model ?? fallback.model ?? 'unknown',
+    ...(telemetry?.effort ?? fallback.effort
+      ? { effort: telemetry?.effort ?? fallback.effort }
+      : {}),
+    duration_ms: telemetry?.durationMs ?? usage.duration_ms ?? usage.ms ?? fallback.duration_ms ?? 0,
+    input_tokens: input,
+    output_tokens: output,
+    ...(typeof (split?.cacheRead ?? usage.cache_read ?? usage.cache_read_input_tokens) === 'number'
+      ? { cache_read: split?.cacheRead ?? usage.cache_read ?? usage.cache_read_input_tokens }
+      : {}),
+    ...(typeof (split?.cacheCreation ?? usage.cache_creation ?? usage.cache_creation_input_tokens) === 'number'
+      ? { cache_creation: split?.cacheCreation ?? usage.cache_creation ?? usage.cache_creation_input_tokens }
+      : {}),
+  };
+  const cost = usage.cost_usd ?? usage.usd;
+  const usdSource = ['reported', 'estimated'].includes(usage.usd_source)
+    ? usage.usd_source
+    : (['reported', 'estimated'].includes(fallback.usd_source) ? fallback.usd_source : null);
+  if (typeof cost === 'number' && Number.isFinite(cost) && cost > 0 && usdSource) {
+    record.cost_usd = cost;
+    record.usd_source = usdSource;
+  }
+  return record;
+}
+
 export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, opts = {}) {
   const progress = opts.progress;
   const streamWriter = opts.streamWriter;
@@ -252,17 +336,45 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
 
   const stepId = stepDispatch.step_id ?? 'unknown';
   const agentType = stepDispatch.agent ?? 'claude';
+  // COMP-AGENT-LANES: when the caller (a parallel fanout item) supplies a lane
+  // envelope, stamp it on every relayed stream write so the cockpit can route
+  // this run's output to its worker lane. Absent the opt, writes stay
+  // byte-identical (single-step runs unchanged).
+  const laneStamp = (opts.lane && typeof opts.lane === 'object') ? { lane: opts.lane } : {};
   // D6: the engine ships only the bare provider literal (stepDispatch.agent), so
   // the full profile string (with tool restrictions + model tier) is supplied
   // compose-side via opts.profile, keyed off the compose-owned sidecar. It
   // overrides the bare literal for capability resolution; the provider is
   // unchanged. Absent → bare literal (no restrictions), preserving old behavior.
   const cfg = resolveAgentConfig(opts.profile || agentType);
-  // A read-only profile (no Edit/Write/Bash) also maps to a read-only sandbox so
-  // the restriction binds at the engine's connector, not just at this invocation.
-  const readOnlyProfile = Array.isArray(cfg.disallowedTools)
-    && ['Edit', 'Write'].every((tool) => cfg.disallowedTools.includes(tool));
-  const sandboxMode = readOnlyProfile ? 'read-only' : undefined;
+  const callerTelemetry = opts.telemetry && typeof opts.telemetry === 'object'
+    ? opts.telemetry
+    : {};
+  const primaryTelemetry = {};
+  for (const field of ['project_cwd', 'site', 'build_id', 'feature_code']) {
+    if (callerTelemetry[field] !== undefined) primaryTelemetry[field] = callerTelemetry[field];
+  }
+  primaryTelemetry.step_id = stepId;
+  if (typeof stepDispatch.attempt === 'number' && Number.isFinite(stepDispatch.attempt)) {
+    primaryTelemetry.attempt = stepDispatch.attempt;
+  }
+  primaryTelemetry.effort_intended = cfg.effort ?? null;
+  // Claude profiles bind through SDK tool filters. Codex has an OS sandbox;
+  // write permission must be explicitly requested by the implementation caller.
+  const sandboxMode = cfg.provider === 'codex'
+    ? (opts.sandboxMode ?? 'read-only')
+    : undefined;
+  const executionOptions = {
+    modelID: cfg.modelID ?? undefined,
+    ...(cfg.provider === 'claude' ? {
+      allowedTools: cfg.allowedTools ?? undefined,
+      disallowedTools: cfg.disallowedTools ?? undefined,
+      thinking: cfg.thinking ?? undefined,
+    } : {}),
+    effort: cfg.effort ?? undefined,
+    sandboxMode,
+    cwd: opts.cwd ?? undefined,
+  };
 
   const outputFields = stepDispatch.output_fields;
   const hasSchema = outputFields && typeof outputFields === 'object' && Object.keys(outputFields).length > 0;
@@ -298,6 +410,7 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
     cost_usd: 0,
     model: null,
   };
+  let primaryUsdSource = null;
 
   let timedOut = false;
   let userInterruptAction = null;
@@ -306,21 +419,19 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   // the run mid-stream by returning a truthy reason from a tool event.
   let abortReason = null;
 
-  // V2/V3: CONTROLLED claude executions (consumer items, review fanout) run via
-  // the compose-LOCAL connector — the only seam that can enforce claude tool
-  // restrictions AND be interrupted (the sync engine agent_run can do neither;
-  // its background mode is codex+read-only-only). Abort replaces cancelAgentRun
-  // as the stop mechanism, and the connector streams real tool events so the
-  // stuck detector / timeout actually stop a runaway agent.
+  // Both local SDK and MCP executions own a cancellable handle. The MCP
+  // client translates this signal to an acknowledged foreground cancellation.
   const useLocalClaude = opts.localExecution === true && cfg.provider === 'claude';
-  const abortController = useLocalClaude ? new AbortController() : null;
-  const stopRun = () => {
-    if (abortController) {
-      try { abortController.abort(); } catch { /* already aborted */ }
-    } else {
-      stratum.cancelAgentRun(correlationId).catch(() => {});
-    }
+  const primaryFailure = (source, target) => {
+    const record = usageRecordFromRaw(source?.usage, source?.telemetry, source?.dispatchId, {
+      model: cfg.modelID, effort: cfg.effort, duration_ms: Date.now() - startTime,
+      usd_source: source?.usdSource ?? (useLocalClaude ? 'reported' : undefined),
+    }, source?.split);
+    if (record) target.usages = [record];
+    return copyDispatchId(source, target);
   };
+  const abortController = new AbortController();
+  const stopRun = () => abortController.abort();
 
   // Subscribe BEFORE calling agentRun — events fire during the call.
   const unsub = stratum.onEvent(correlationId, subStepId, (env) => {
@@ -333,14 +444,14 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
       case 'agent_relay':
         if (m.role === 'assistant' && typeof m.text === 'string' && m.text.length > 0) {
           textParts.push(m.text);
-          if (streamWriter) streamWriter.write({ type: 'assistant', content: m.text });
+          if (streamWriter) streamWriter.write({ type: 'assistant', content: m.text, ...laneStamp });
         }
         break;
       case 'tool_use_summary': {
         const tool = m.tool;
         if (tool) {
           if (streamWriter) {
-            streamWriter.write({ type: 'tool_use', tool, input: m.input ?? {} });
+            streamWriter.write({ type: 'tool_use', tool, input: m.input ?? {}, ...laneStamp });
           }
           if (onToolUse) onToolUse({ tool, input: m.input ?? {}, timestamp: Date.now() });
           if (progress) {
@@ -350,7 +461,7 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         }
         if (m.summary) {
           if (streamWriter) {
-            streamWriter.write({ type: 'tool_use_summary', summary: m.summary, output: m.output ?? '' });
+            streamWriter.write({ type: 'tool_use_summary', summary: m.summary, output: m.output ?? '', ...laneStamp });
           }
           if (progress) progress.toolSummary(m.summary);
         }
@@ -369,6 +480,9 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         const stepCost = m.cost_usd != null
           ? m.cost_usd
           : calculateCost(m.model, inTok, outTok, ccit, crit);
+        primaryUsdSource = m.cost_usd != null && primaryUsdSource !== 'estimated'
+          ? 'reported'
+          : 'estimated';
         usageTotals.cost_usd += stepCost;
         if (streamWriter) {
           streamWriter.write({
@@ -379,6 +493,7 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
             cache_read_input_tokens: crit,
             cost_usd: stepCost,
             model: m.model ?? null,
+            ...laneStamp,
           });
         }
         break;
@@ -420,7 +535,7 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   // abort a spinning run.
   const localOnToolUse = ({ tool, input }) => {
     if (onToolUse) onToolUse({ tool, input, timestamp: Date.now() });
-    if (streamWriter) streamWriter.write({ type: 'tool_use', tool, input: input ?? {} });
+    if (streamWriter) streamWriter.write({ type: 'tool_use', tool, input: input ?? {}, ...laneStamp });
     if (progress) progress.toolUse(tool, input?.command ?? input?.pattern ?? input?.file_path ?? '');
     if (opts.onAgentEvent && !abortReason) {
       const env = { schema_version: '0.2.6', kind: 'tool_use_summary', metadata: { tool, input: input ?? {}, summary: '', output: '' } };
@@ -429,156 +544,316 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
     }
   };
 
-  let runResult;
+  // Keep the deadline and interrupt controls active through review repair.
   try {
-    if (useLocalClaude) {
-      // Test seam: an installed factory shim exposes an SDK-shaped query adapter
-      // so the goldens drive the local path without spawning a real claude.
-      // Gated on NODE_ENV=test so production always uses the real SDK.
-      const localQuery = opts.localQuery
-        ?? (process.env.NODE_ENV === 'test' && stratum ? stratum._localQuery : undefined);
-      runResult = await runLocalClaudeAgent(actualPrompt, {
-        cwd:             opts.cwd ?? undefined,
-        model:           cfg.modelID ?? undefined,
-        allowedTools:    cfg.allowedTools ?? undefined,
-        disallowedTools: cfg.disallowedTools ?? undefined,
-        thinking:        cfg.thinking ?? undefined,
-        abortController,
-        onToolUse:       localOnToolUse,
-        ...(localQuery ? { query: localQuery } : {}),
-      });
-    } else {
-      runResult = await stratum.agentRun(agentType, actualPrompt, {
-        modelID:          cfg.modelID ?? undefined,
-        allowedTools:     cfg.allowedTools ?? undefined,
-        disallowedTools:  cfg.disallowedTools ?? undefined,
-        thinking:         cfg.thinking ?? undefined,
-        effort:           cfg.effort ?? undefined,
-        sandboxMode,
-        cwd:              opts.cwd ?? undefined,
-        correlationId,
-      });
+    let runResult;
+    let primaryDispatchId = null;
+    let repairDispatchId = null;
+    try {
+      if (useLocalClaude) {
+        // Test seam: an installed factory shim exposes an SDK-shaped query adapter
+        // so the goldens drive the local path without spawning a real claude.
+        // Gated on NODE_ENV=test so production always uses the real SDK.
+        const localQuery = opts.localQuery
+          ?? (process.env.NODE_ENV === 'test' && stratum ? stratum._localQuery : undefined);
+        runResult = await runLocalClaudeAgent(actualPrompt, {
+          cwd:             opts.cwd ?? undefined,
+          model:           cfg.modelID ?? undefined,
+          allowedTools:    cfg.allowedTools ?? undefined,
+          disallowedTools: cfg.disallowedTools ?? undefined,
+          thinking:        cfg.thinking ?? undefined,
+          effort:          cfg.effort ?? undefined,
+          abortController,
+          onToolUse:       localOnToolUse,
+          // COMP-AGENT-LANES: only a lane-carrying run (parallel fanout item)
+          // relays local assistant text to the stream — engine-path parity for
+          // the lanes UI. Lane-less local runs keep their historical shape (no
+          // assistant stream writes).
+          ...(laneStamp.lane && streamWriter ? {
+            onAssistantText: (text) => {
+              streamWriter.write({ type: 'assistant', content: text, ...laneStamp });
+            },
+          } : {}),
+          telemetry:       primaryTelemetry,
+          ...(localQuery ? { query: localQuery } : {}),
+        });
+      } else {
+        runResult = await stratum.agentRun(agentType, actualPrompt, {
+          ...executionOptions,
+          signal: abortController.signal,
+          correlationId,
+          telemetry:        primaryTelemetry,
+        });
+      }
+      primaryDispatchId = typeof runResult?.dispatchId === 'string'
+        ? runResult.dispatchId
+        : null;
+    } catch (err) {
+      if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(err?.code)) throw primaryFailure(err, err);
+      // F3/G3: preserve any billable usage the failed run reported (the local
+      // connector attaches it on a non-success result / usage-bearing rejection) so
+      // the consumer failure envelope can still debit the engine/GSD ledgers. G3:
+      // the timeout/abort throws happen here too — attach the usage to THOSE errors
+      // (not only the generic AgentError) so timeout/stuck attempts are billed.
+      // The local Claude SDK's price is provider-reported on failures too; label it
+      // here so the receipt funnel does not drop it as unlabelled raw usd.
+      const errUsage = (err && typeof err === 'object' && err.usage)
+        ? (useLocalClaude && err.usage.usd_source === undefined ? { ...err.usage, usd_source: 'reported' } : err.usage)
+        : null;
+      if (timedOut) {
+        const e = new AgentTimeoutError(stepId, Date.now() - startTime);
+        if (errUsage) e.usage = errUsage;
+        throw primaryFailure(err, e);
+      }
+      if (userInterruptAction) {
+        const e = new UserInterruptError(stepId, userInterruptAction);
+        if (errUsage) e.usage = errUsage;
+        throw primaryFailure(err, e);
+      }
+      if (abortReason) {
+        const e = new AgentAbortedError(stepId, abortReason);
+        if (errUsage) e.usage = errUsage;
+        throw primaryFailure(err, e);
+      }
+      const agentError = new AgentError(err?.message ?? 'Agent run failed');
+      if (errUsage) agentError.usage = errUsage;
+      throw primaryFailure(err, agentError);
     }
-  } catch (err) {
-    // F3/G3: preserve any billable usage the failed run reported (the local
-    // connector attaches it on a non-success result / usage-bearing rejection) so
-    // the consumer failure envelope can still debit the engine/GSD ledgers. G3:
-    // the timeout/abort throws happen here too — attach the usage to THOSE errors
-    // (not only the generic AgentError) so timeout/stuck attempts are billed.
-    const errUsage = (err && typeof err === 'object' && err.usage) ? err.usage : null;
+
+    // H2: when the underlying run RESOLVES late (rather than rejecting) after a
+    // timeout/abort fired, its billable usage is on runResult.usage. Copy it onto
+    // the thrown error — the same single channel the rejection path (G3) uses — so
+    // the consumer timeout envelope / stuck-ledger accounting still bill the attempt.
+    // Throwing here means usageTotals is never returned, so this is the ONLY channel
+    // (no double count).
+    const lateUsage = (runResult && typeof runResult === 'object' && runResult.usage && typeof runResult.usage === 'object')
+      ? runResult.usage
+      : null;
     if (timedOut) {
       const e = new AgentTimeoutError(stepId, Date.now() - startTime);
-      if (errUsage) e.usage = errUsage;
-      throw e;
+      if (lateUsage) e.usage = lateUsage;
+      throw primaryFailure(runResult, e);
+    }
+    if (userInterruptAction) {
+      const e = new UserInterruptError(stepId, userInterruptAction);
+      if (lateUsage) e.usage = lateUsage;
+      throw primaryFailure(runResult, e);
     }
-    if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
     if (abortReason) {
       const e = new AgentAbortedError(stepId, abortReason);
-      if (errUsage) e.usage = errUsage;
-      throw e;
+      if (lateUsage) e.usage = lateUsage;
+      throw primaryFailure(runResult, e);
     }
-    const agentError = new AgentError(err?.message ?? 'Agent run failed');
-    if (errUsage) agentError.usage = errUsage;
-    throw agentError;
-  } finally {
-    if (timeoutHandle) clearTimeout(timeoutHandle);
-    if (onInterrupt && progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
-    unsub();
-  }
 
-  // H2: when the underlying run RESOLVES late (rather than rejecting) after a
-  // timeout/abort fired, its billable usage is on runResult.usage. Copy it onto
-  // the thrown error — the same single channel the rejection path (G3) uses — so
-  // the consumer timeout envelope / stuck-ledger accounting still bill the attempt.
-  // Throwing here means usageTotals is never returned, so this is the ONLY channel
-  // (no double count).
-  const lateUsage = (runResult && typeof runResult === 'object' && runResult.usage && typeof runResult.usage === 'object')
-    ? runResult.usage
-    : null;
-  if (timedOut) {
-    const e = new AgentTimeoutError(stepId, Date.now() - startTime);
-    if (lateUsage) e.usage = lateUsage;
-    throw e;
-  }
-  if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
-  if (abortReason) {
-    const e = new AgentAbortedError(stepId, abortReason);
-    if (lateUsage) e.usage = lateUsage;
-    throw e;
-  }
+    // D2(b): the TS agent_run path returns a synchronous `complete` envelope with
+    // aggregate usage ({usd?, tokens, ms}) and streams NO step_usage progress
+    // events — without folding it in, budget accounting debits nothing on the TS
+    // route. The python / factory-shim path streams step_usage events (usageTotals
+    // already populated), so adopt runResult.usage only when the event stream
+    // contributed nothing (avoids double counting).
+    const runUsage = runResult && typeof runResult === 'object' ? runResult.usage : null;
+    const runSplit = runResult && typeof runResult === 'object' && runResult.split && typeof runResult.split === 'object'
+      ? runResult.split
+      : null;
+    const usageFromEvents = usageTotals.input_tokens || usageTotals.output_tokens || usageTotals.cost_usd;
+    if (runUsage && typeof runUsage === 'object' && !usageFromEvents) {
+      // STRAT-USAGE-SPLIT: the TS envelope now carries the true input/output
+      // detail beside its Budget-shaped usage. Adopt it; only a split-less
+      // (pre-surface-16) envelope falls back to the aggregate, which is filed
+      // as output for continuity — mislabeled, but the legacy column it always
+      // occupied. That path retires with surface 15.
+      if (runSplit) {
+        usageTotals.input_tokens += runSplit.input ?? 0;
+        usageTotals.output_tokens += runSplit.output ?? 0;
+        if (typeof runSplit.cacheRead === 'number') {
+          usageTotals.cache_read_input_tokens = (usageTotals.cache_read_input_tokens ?? 0) + runSplit.cacheRead;
+        }
+        if (typeof runSplit.cacheCreation === 'number') {
+          usageTotals.cache_creation_input_tokens = (usageTotals.cache_creation_input_tokens ?? 0) + runSplit.cacheCreation;
+        }
+      } else if (typeof runUsage.tokens === 'number') {
+        usageTotals.output_tokens += runUsage.tokens;
+      }
+      if (typeof runUsage.usd === 'number') usageTotals.cost_usd += runUsage.usd;
+      if (typeof runUsage.ms === 'number') usageTotals.duration_ms = (usageTotals.duration_ms ?? 0) + runUsage.ms;
+      if (!usageTotals.model && runResult.telemetry?.model) usageTotals.model = runResult.telemetry.model;
+    }
 
-  // D2(b): the TS agent_run path returns a synchronous `complete` envelope with
-  // aggregate usage ({usd?, tokens, ms}) and streams NO step_usage progress
-  // events — without folding it in, budget accounting debits nothing on the TS
-  // route. The python / factory-shim path streams step_usage events (usageTotals
-  // already populated), so adopt runResult.usage only when the event stream
-  // contributed nothing (avoids double counting).
-  const runUsage = runResult && typeof runResult === 'object' ? runResult.usage : null;
-  const usageFromEvents = usageTotals.input_tokens || usageTotals.output_tokens || usageTotals.cost_usd;
-  if (runUsage && typeof runUsage === 'object' && !usageFromEvents) {
-    if (typeof runUsage.tokens === 'number') usageTotals.output_tokens += runUsage.tokens;
-    if (typeof runUsage.usd === 'number') usageTotals.cost_usd += runUsage.usd;
-    if (typeof runUsage.ms === 'number') usageTotals.duration_ms = (usageTotals.duration_ms ?? 0) + runUsage.ms;
-    if (!usageTotals.model && runResult.telemetry?.model) usageTotals.model = runResult.telemetry.model;
-  }
+    const usages = [];
+    const primaryFromEvents = usageFromEvents || primaryUsdSource !== null;
+    if (primaryFromEvents) {
+      const primary = {
+        dispatch_id: primaryDispatchId ?? randomUUID(),
+        model: usageTotals.model ?? runResult?.telemetry?.model ?? cfg.modelID ?? 'unknown',
+        ...(runResult?.telemetry?.effort ?? cfg.effort
+          ? { effort: runResult?.telemetry?.effort ?? cfg.effort }
+          : {}),
+        duration_ms: runResult?.telemetry?.durationMs ?? usageTotals.duration_ms ?? (Date.now() - startTime),
+        input_tokens: usageTotals.input_tokens,
+        output_tokens: usageTotals.output_tokens,
+        ...(usageTotals.cache_read_input_tokens
+          ? { cache_read: usageTotals.cache_read_input_tokens }
+          : {}),
+        ...(usageTotals.cache_creation_input_tokens
+          ? { cache_creation: usageTotals.cache_creation_input_tokens }
+          : {}),
+        ...(usageTotals.cost_usd > 0
+          ? { cost_usd: usageTotals.cost_usd, usd_source: primaryUsdSource ?? 'estimated' }
+          : { usd_source: primaryUsdSource ?? 'estimated' }),
+      };
+      usages.push(primary);
+    } else {
+      const primary = usageRecordFromRaw(runUsage, runResult?.telemetry, primaryDispatchId, {
+        model: cfg.modelID,
+        effort: cfg.effort,
+        duration_ms: Date.now() - startTime,
+        usd_source: runResult?.usdSource ?? (useLocalClaude ? 'reported' : undefined),
+      }, runSplit);
+      if (primary) usages.push(primary);
+    }
 
-  const text = (runResult && typeof runResult.text === 'string' && runResult.text.length > 0)
-    ? runResult.text
-    : textParts.join('');
+    const text = (runResult && typeof runResult.text === 'string' && runResult.text.length > 0)
+      ? runResult.text
+      : textParts.join('');
 
-  if (progress) {
-    progress.debug(`normalizer: textParts=${textParts.length}, text length=${text.length}`);
-    if (text.length > 0) progress.debug(`text preview: ${text.slice(0, 300)}`);
-  } else if (process.env.COMPOSE_DEBUG) {
-    process.stderr.write(`  [normalizer] textParts=${textParts.length}, text length=${text.length}\n`);
-  }
+    if (progress) {
+      progress.debug(`normalizer: textParts=${textParts.length}, text length=${text.length}`);
+      if (text.length > 0) progress.debug(`text preview: ${text.slice(0, 300)}`);
+    } else if (process.env.COMPOSE_DEBUG) {
+      process.stderr.write(`  [normalizer] textParts=${textParts.length}, text length=${text.length}\n`);
+    }
 
-  // review_mode hook — MUST be before the !hasSchema early return (MF-3 in blueprint).
-  // Parallel lens steps often have empty output_fields (hasSchema=false), but review
-  // normalization must still run. The Stratum server validates the post-normalize result
-  // via `ensure` expressions after stratum_step_done — not against raw text.
-  if (opts.reviewMode === true) {
-    const reviewAgentType = agentType; // already resolved from stepDispatch.agent at line 178
-    const reviewModelId = usageTotals.model ?? cfg.modelID ?? null;
-    const repairFn = stratum
-      ? async (repairPrompt) => {
-          const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
-            modelID: cfg.modelID ?? undefined,
-            cwd: opts.cwd ?? undefined,
-          });
-          return repairResult?.text ?? '';
-        }
-      : undefined;
-    const reviewResult = await normalizeReviewResult(text, {
-      agentType: reviewAgentType,
-      modelId: reviewModelId,
-      confidenceGate: opts.confidenceGate ?? 7,
-      lens: opts.lens ?? 'general',
-      repairFn,
-    });
-    return { text, result: reviewResult, usage: usageTotals };
-  }
+    // review_mode hook — MUST be before the !hasSchema early return (MF-3 in blueprint).
+    // Parallel lens steps often have empty output_fields (hasSchema=false), but review
+    // normalization must still run. The Stratum server validates the post-normalize result
+    // via `ensure` expressions after stratum_step_done — not against raw text.
+    if (opts.reviewMode === true) {
+      const reviewAgentType = agentType; // already resolved from stepDispatch.agent at line 178
+      const reviewModelId = usageTotals.model ?? cfg.modelID ?? null;
+      // The repair dispatch is only CREDITED (dispatchIds.repair) when its output
+      // actually replaced the primary parse — a failed or unparseable repair still
+      // bills its usage but must not absorb the step's settlement.
+      let repairUsed = false;
+      let repairFailure = null;
+      let repairResultForControl = null;
+      const foldRepairUsage = (usage) => {
+        if (!usage || typeof usage !== 'object') return;
+        if (typeof usage.tokens === 'number') usageTotals.output_tokens += usage.tokens;
+        if (typeof usage.usd === 'number') usageTotals.cost_usd += usage.usd;
+      };
+      const repairFn = stratum
+        ? async (repairPrompt) => {
+            try {
+              const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
+                ...executionOptions,
+                signal: abortController.signal,
+                telemetry: { ...primaryTelemetry, site: 'review-repair' },
+              });
+              repairResultForControl = repairResult;
+              repairDispatchId = typeof repairResult?.dispatchId === 'string'
+                ? repairResult.dispatchId
+                : null;
+              foldRepairUsage(repairResult?.usage);
+              const record = usageRecordFromRaw(
+                repairResult?.usage,
+                repairResult?.telemetry,
+                repairDispatchId,
+                { model: cfg.modelID, effort: cfg.effort, usd_source: repairResult?.usdSource },
+                repairResult?.split && typeof repairResult.split === 'object' ? repairResult.split : null,
+              );
+              if (record) usages.push(record);
+              return repairResult?.text ?? '';
+            } catch (error) {
+              repairFailure = error;
+              repairDispatchId = typeof error?.dispatchId === 'string'
+                ? error.dispatchId
+                : null;
+              foldRepairUsage(error?.usage);
+              const record = usageRecordFromRaw(
+                error?.usage,
+                error?.telemetry,
+                repairDispatchId,
+                { model: cfg.modelID, effort: cfg.effort, usd_source: error?.usdSource },
+                error?.split,
+              );
+              if (record) usages.push(record);
+              throw error;
+            }
+          }
+        : undefined;
+      const reviewResult = await normalizeReviewResult(text, {
+        agentType: reviewAgentType,
+        modelId: reviewModelId,
+        confidenceGate: opts.confidenceGate ?? 7,
+        lens: opts.lens ?? 'general',
+        repairFn,
+        onRepairUsed: () => { repairUsed = true; },
+      });
+      // The tolerant text parser can recover ordinary repair failures, but it
+      // must never turn a cancelled or still-running repair into a clean review.
+      if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(repairFailure?.code)) {
+        repairFailure.usages = usages;
+        throw repairFailure;
+      }
+      const controlSource = repairFailure ?? repairResultForControl;
+      const controlError = timedOut
+        ? new AgentTimeoutError(stepId, Date.now() - startTime)
+        : userInterruptAction
+          ? new UserInterruptError(stepId, userInterruptAction)
+          : abortReason ? new AgentAbortedError(stepId, abortReason) : null;
+      if (controlError) {
+        if (controlSource?.usage) controlError.usage = controlSource.usage;
+        controlError.usages = usages;
+        throw copyDispatchId(controlSource, controlError);
+      }
+      return {
+        text,
+        result: reviewResult,
+        usage: usageTotals,
+        usages,
+        dispatchIds: { primary: primaryDispatchId, repair: repairUsed ? repairDispatchId : null },
+      };
+    }
 
-  if (!hasStructuredOutput) {
-    return { text, result: null, usage: usageTotals };
-  }
+    if (!hasStructuredOutput) {
+      return {
+        text,
+        result: null,
+        usage: usageTotals,
+        usages,
+        dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
+      };
+    }
 
-  const result = extractJson(text);
-  if (result === null) {
-    if (progress) {
-      progress.warn('Could not extract JSON from agent output, using fallback');
-    } else {
-      process.stderr.write('    ⚠ Could not extract JSON from agent output, using fallback\n');
+    const result = extractJson(text);
+    if (result === null) {
+      if (progress) {
+        progress.warn('Could not extract JSON from agent output, using fallback');
+      } else {
+        process.stderr.write('    ⚠ Could not extract JSON from agent output, using fallback\n');
+      }
+      const summary = text.slice(0, 200).replace(/\n/g, ' ').trim();
+      const normalizationFailure = summary || 'Could not extract structured output';
+      return {
+        text,
+        result: { summary: normalizationFailure },
+        usage: usageTotals,
+        usages,
+        normalizationFailure,
+        dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
+      };
     }
-    const summary = text.slice(0, 200).replace(/\n/g, ' ').trim();
-    const normalizationFailure = summary || 'Could not extract structured output';
+
     return {
       text,
-      result: { summary: normalizationFailure },
+      result,
       usage: usageTotals,
-      normalizationFailure,
+      usages,
+      dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
     };
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (onInterrupt && progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
+    unsub();
   }
-
-  return { text, result, usage: usageTotals };
 }