@smartmemory/compose 0.3.5-beta → 0.3.7

package/lib/lane-gate.js

@@ -87,6 +87,7 @@ export async function applyFrontTriage({ featureCode, request, provider, cachedF
     triageTier: tier,
     lane,
     estimateSource,
+    triageConfidence: front.confidence,
     profile: buildProfile,
     triageTimestamp: new Date().toISOString(),
   };
@@ -109,6 +110,7 @@ export async function applyFrontTriage({ featureCode, request, provider, cachedF
     buildProfile,
     tier,
     lane,
+    confidence: front.confidence,
     tierLabel: fields.complexity,
     rationale: front.rationale,
     cachedFeature: updated,

package/lib/lifecycle-modes.js

@@ -136,6 +136,48 @@ export const LIFECYCLE_MODES = {
       defaultTemplate: 'plan',
     },
   },
+
+  // -------------------------------------------------------------------------
+  // JUDGMENT — the joint state machine (COMP-JUDGMENT-WRITER design Decision 2).
+  // Consumed ONLY by lib/judgment-writer.js through guardedTransition(mode:
+  // 'judgment'), which makes the Stratum guard the single lifecycle authority
+  // for joint transitions where capabilities.guard is on. The per-edge required
+  // ARTIFACTS (resolution packages, dissolution, reopen, re-dispose) are
+  // enforced by lib/judgment-write-guard.js before the guard is called —
+  // edgeEvidence stays empty because the evidence lives inside records, not in
+  // per-feature files. Never run by any CLI runner; the runner block is inert.
+  //
+  // KNOWN SUPERSET: buildPhaseGraph() unconditionally adds `resolved →
+  // complete` and `<non-terminal> → killed` edges to every registered graph
+  // (an adapter invariant this feature may not touch). Those five extra edges
+  // are UNREACHABLE through the judgment writer — the write-guard's edge→
+  // artifact table refuses them before any guard call — and the parity test
+  // pins the superset to exactly that auto-added set. Closing them at the
+  // guard itself is epic S4–S6 enforcement territory.
+  // -------------------------------------------------------------------------
+  judgment: {
+    transitions: {
+      open: ['under_test', 'superseded', 'dissolved'],
+      under_test: ['resolved', 'inconclusive', 'open', 'superseded', 'dissolved'],
+      resolved: ['open'],
+      inconclusive: ['under_test', 'open'],
+    },
+    skippable: [],
+    terminal: ['superseded', 'dissolved', 'complete', 'killed'],
+    genesis: 'open',
+    completablePhase: 'resolved',
+    phaseArtifacts: [],
+    edgeEvidence: {},
+    phaseOrder: ['open', 'under_test', 'resolved', 'inconclusive'],
+    runner: {
+      artifactRoot: 'docs/judgment/records/joints',
+      runsTriage: false,
+      tracksFeatureJson: false,
+      descriptionLoader: 'plan',
+      planInputs: 'plan',
+      defaultTemplate: 'plan',
+    },
+  },
 };
 
 /**

package/lib/local-claude-connector.js

@@ -17,8 +17,11 @@
  * and reports usage. The SDK `query` is injectable for tests.
  */
 
+import { randomUUID } from 'node:crypto';
 import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
 
+import { appendEvent, resolveDispatchLedgerCwd } from './dispatch-ledger.js';
+
 const SENSITIVE_ENV_VARS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CLAUDE_API_KEY', 'CLAUDECODE'];
 
 function isRecord(value) {
@@ -29,6 +32,77 @@ function nonneg(value) {
   return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
 }
 
+function reportedNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+function reportedString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function isBlockedDispatch(value) {
+  const candidates = [value?.status, value?.outcome, value?.code, value?.subtype];
+  return candidates.some((candidate) => {
+    const normalized = typeof candidate === 'string' ? candidate.toLowerCase() : '';
+    return normalized === 'blocked'
+      || normalized === 'budget_exhausted'
+      || normalized === 'budget-exhausted';
+  });
+}
+
+function attachDispatchId(value, dispatchId) {
+  if ((typeof value !== 'object' && typeof value !== 'function') || value === null) return;
+  try {
+    Object.defineProperty(value, 'dispatchId', {
+      configurable: true,
+      enumerable: false,
+      value: dispatchId,
+    });
+  } catch {
+    // Capture metadata must never replace the SDK's original behavior.
+  }
+}
+
+function recordDispatch(dispatchId, context, capture, outcome, elapsedMs, effortExecuted) {
+  try {
+    const event = {
+      kind: 'dispatch',
+      dispatch_id: dispatchId,
+      site: reportedString(context.site) ?? 'unattributed',
+      agent: 'claude',
+      outcome,
+      model: reportedString(capture.model),
+      effort_intended: reportedString(context.effort_intended),
+      // Executed effort is only recorded once a model run is confirmed — the SDK
+      // emitted a model identity (init or result). A transport/startup failure
+      // before any model spoke leaves effort_executed null, so the executed-effort
+      // curve is not polluted by tiers that were requested but never actually ran
+      // (mirrors the codex route, whose effort_executed comes from run telemetry).
+      effort_executed: capture.model ? reportedString(effortExecuted) : null,
+      tokens_in: reportedNumber(capture.inputTokens),
+      tokens_out: reportedNumber(capture.outputTokens),
+      tokens_total: capture.inputTokens !== null || capture.outputTokens !== null
+        ? (reportedNumber(capture.inputTokens) ?? 0) + (reportedNumber(capture.outputTokens) ?? 0)
+        : null,
+      usd: reportedNumber(capture.costUsd),
+      duration_ms: reportedNumber(capture.durationMs) ?? reportedNumber(elapsedMs),
+    };
+    for (const [field, value] of [
+      ['build_id', context.build_id],
+      ['feature_code', context.feature_code],
+      ['step_id', context.step_id],
+    ]) {
+      if (reportedString(value) !== null) event[field] = value;
+    }
+    if (typeof context.attempt === 'number' && Number.isFinite(context.attempt)) {
+      event.attempt = context.attempt;
+    }
+    appendEvent(resolveDispatchLedgerCwd(context.project_cwd), event);
+  } catch {
+    // Dispatch capture is fail-open by contract.
+  }
+}
+
 /**
  * Run a controlled claude agent locally.
  *
@@ -39,17 +113,26 @@ function nonneg(value) {
  * @param {string[]} [opts.allowedTools]     enforced tool allowlist (read-only review)
  * @param {string[]} [opts.disallowedTools]
  * @param {object}   [opts.thinking]
+ * @param {string}   [opts.effort]           reasoning-effort tier (low|medium|high|xhigh|max)
  * @param {AbortController} [opts.abortController]  abort → interrupt the run
  * @param {(ev:{tool:string,input:object})=>void} [opts.onToolUse]  per tool_use block
  * @param {NodeJS.ProcessEnv} [opts.env]
  * @param {Function} [opts.query]            SDK `query` seam for tests
+ * @param {object} [opts.telemetry]           Compose-only dispatch context
  * @returns {Promise<{text:string, usage:object, telemetry:object}>}
  */
 export async function runLocalClaudeAgent(prompt, opts = {}) {
   const query = opts.query ?? sdkQuery;
+  const { telemetry } = opts;
+  const telemetryContext = telemetry && typeof telemetry === 'object'
+    ? telemetry
+    : {};
   const env = { ...(opts.env ?? process.env) };
   for (const key of SENSITIVE_ENV_VARS) delete env[key];
 
+  // Only forward a non-empty effort so routes without a configured tier keep the
+  // SDK's default behavior; the applied value is what we record as effort_executed.
+  const appliedEffort = reportedString(opts.effort);
   const sdkOptions = {
     cwd: opts.cwd ?? process.cwd(),
     model: opts.model ?? process.env.CLAUDE_MODEL ?? 'claude-sonnet-4-6',
@@ -57,6 +140,7 @@ export async function runLocalClaudeAgent(prompt, opts = {}) {
     env,
     ...(opts.abortController ? { abortController: opts.abortController } : {}),
     ...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
+    ...(appliedEffort !== null ? { effort: appliedEffort } : {}),
   };
   // A read-only profile passes an explicit allowlist; without one, the agent
   // gets the full claude_code preset (unrestricted).
@@ -83,67 +167,128 @@ export async function runLocalClaudeAgent(prompt, opts = {}) {
   let inputTokens = 0;
   let outputTokens = 0;
   let costUsd = 0;
+  const capture = {
+    model: null,
+    inputTokens: null,
+    outputTokens: null,
+    costUsd: null,
+    durationMs: null,
+  };
+  let resultError = null;
+  let resultFailureOutcome = null;
+  const dispatchId = randomUUID();
+  const dispatchStartedAt = Date.now();
 
-  for await (const raw of query({ prompt, options: sdkOptions })) {
-    if (!isRecord(raw)) continue;
-    if (raw.type === 'system' && raw.subtype === 'init' && typeof raw.model === 'string') {
-      resolvedModel = raw.model;
-    }
-    if (raw.type === 'assistant' && isRecord(raw.message) && Array.isArray(raw.message.content)) {
-      for (const block of raw.message.content) {
-        if (!isRecord(block)) continue;
-        if (block.type === 'text' && typeof block.text === 'string') assistantText += block.text;
-        if (block.type === 'tool_use' && typeof block.name === 'string' && typeof opts.onToolUse === 'function') {
-          opts.onToolUse({ tool: block.name, input: isRecord(block.input) ? block.input : {} });
+  try {
+    for await (const raw of query({ prompt, options: sdkOptions })) {
+      if (!isRecord(raw)) continue;
+      if (raw.type === 'system' && raw.subtype === 'init' && typeof raw.model === 'string') {
+        resolvedModel = raw.model;
+        capture.model = raw.model;
+      }
+      if (raw.type === 'assistant' && isRecord(raw.message) && Array.isArray(raw.message.content)) {
+        for (const block of raw.message.content) {
+          if (!isRecord(block)) continue;
+          if (block.type === 'text' && typeof block.text === 'string') assistantText += block.text;
+          if (block.type === 'tool_use' && typeof block.name === 'string' && typeof opts.onToolUse === 'function') {
+            opts.onToolUse({ tool: block.name, input: isRecord(block.input) ? block.input : {} });
+          }
         }
       }
+      if (raw.type !== 'result') continue;
+      durationMs = nonneg(raw.duration_ms);
+      capture.durationMs = reportedNumber(raw.duration_ms);
+      capture.costUsd = reportedNumber(raw.total_cost_usd);
+      if (reportedString(raw.model) !== null) capture.model = raw.model;
+      if (isRecord(raw.usage)) {
+        capture.inputTokens = reportedNumber(raw.usage.input_tokens);
+        capture.outputTokens = reportedNumber(raw.usage.output_tokens);
+        capture.model = reportedString(raw.usage.model) ?? capture.model;
+      }
+      if (raw.subtype !== 'success') {
+        // F3: a failed run still consumed billable tokens/cost. Capture them from
+        // the error result (SDKResultError carries usage + total_cost_usd) and
+        // attach to the thrown Error — same usage shape as the success return — so
+        // the consumer failure path can debit the engine/GSD ledgers. Without this,
+        // repeated failures evade budget exhaustion.
+        const failCost = nonneg(raw.total_cost_usd);
+        const failIn = isRecord(raw.usage) ? nonneg(raw.usage.input_tokens) : 0;
+        const failOut = isRecord(raw.usage) ? nonneg(raw.usage.output_tokens) : 0;
+        const errors = Array.isArray(raw.errors) ? raw.errors.filter((v) => typeof v === 'string') : [];
+        const err = new Error(errors.join('; ') || `claude query failed: ${String(raw.subtype)}`);
+        err.usage = {
+          input_tokens: failIn,
+          output_tokens: failOut,
+          tokens: failIn + failOut,
+          cost_usd: failCost,
+          usd: failCost,
+          duration_ms: durationMs,
+          ms: durationMs,
+          model: resolvedModel,
+        };
+        err.costUsd = failCost;
+        resultError = err;
+        resultFailureOutcome = isBlockedDispatch(raw) ? 'blocked' : 'error';
+        throw err;
+      }
+      if (typeof raw.result === 'string') finalText = raw.result;
+      costUsd = nonneg(raw.total_cost_usd);
+      if (isRecord(raw.usage)) {
+        inputTokens = nonneg(raw.usage.input_tokens);
+        outputTokens = nonneg(raw.usage.output_tokens);
+      }
     }
-    if (raw.type !== 'result') continue;
-    durationMs = nonneg(raw.duration_ms);
-    if (raw.subtype !== 'success') {
-      // F3: a failed run still consumed billable tokens/cost. Capture them from
-      // the error result (SDKResultError carries usage + total_cost_usd) and
-      // attach to the thrown Error — same usage shape as the success return — so
-      // the consumer failure path can debit the engine/GSD ledgers. Without this,
-      // repeated failures evade budget exhaustion.
-      const failCost = nonneg(raw.total_cost_usd);
-      const failIn = isRecord(raw.usage) ? nonneg(raw.usage.input_tokens) : 0;
-      const failOut = isRecord(raw.usage) ? nonneg(raw.usage.output_tokens) : 0;
-      const errors = Array.isArray(raw.errors) ? raw.errors.filter((v) => typeof v === 'string') : [];
-      const err = new Error(errors.join('; ') || `claude query failed: ${String(raw.subtype)}`);
-      err.usage = {
-        input_tokens: failIn,
-        output_tokens: failOut,
-        tokens: failIn + failOut,
-        cost_usd: failCost,
-        usd: failCost,
+
+    const result = {
+      text: finalText ?? assistantText,
+      usage: {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        tokens: inputTokens + outputTokens,
+        cost_usd: costUsd,
+        usd: costUsd,
         duration_ms: durationMs,
         ms: durationMs,
         model: resolvedModel,
-      };
-      err.costUsd = failCost;
-      throw err;
-    }
-    if (typeof raw.result === 'string') finalText = raw.result;
-    costUsd = nonneg(raw.total_cost_usd);
-    if (isRecord(raw.usage)) {
-      inputTokens = nonneg(raw.usage.input_tokens);
-      outputTokens = nonneg(raw.usage.output_tokens);
+      },
+      telemetry: { durationMs, model: resolvedModel },
+    };
+    recordDispatch(
+      dispatchId,
+      telemetryContext,
+      capture,
+      'ok',
+      Date.now() - dispatchStartedAt,
+      appliedEffort,
+    );
+    attachDispatchId(result, dispatchId);
+    return result;
+  } catch (error) {
+    if (error !== resultError && error && typeof error === 'object') {
+      const errorUsage = isRecord(error.usage) ? error.usage : {};
+      const errorTelemetry = isRecord(error.telemetry) ? error.telemetry : {};
+      capture.model = reportedString(errorTelemetry.model)
+        ?? reportedString(errorUsage.model)
+        ?? capture.model;
+      capture.inputTokens = reportedNumber(errorUsage.input_tokens) ?? capture.inputTokens;
+      capture.outputTokens = reportedNumber(errorUsage.output_tokens) ?? capture.outputTokens;
+      capture.costUsd = reportedNumber(errorUsage.cost_usd)
+        ?? reportedNumber(errorUsage.usd)
+        ?? capture.costUsd;
+      capture.durationMs = reportedNumber(errorUsage.duration_ms)
+        ?? reportedNumber(errorUsage.ms)
+        ?? reportedNumber(errorTelemetry.durationMs)
+        ?? capture.durationMs;
     }
+    recordDispatch(
+      dispatchId,
+      telemetryContext,
+      capture,
+      resultFailureOutcome ?? (isBlockedDispatch(error) ? 'blocked' : 'error'),
+      Date.now() - dispatchStartedAt,
+      appliedEffort,
+    );
+    attachDispatchId(error, dispatchId);
+    throw error;
   }
-
-  return {
-    text: finalText ?? assistantText,
-    usage: {
-      input_tokens: inputTokens,
-      output_tokens: outputTokens,
-      tokens: inputTokens + outputTokens,
-      cost_usd: costUsd,
-      usd: costUsd,
-      duration_ms: durationMs,
-      ms: durationMs,
-      model: resolvedModel,
-    },
-    telemetry: { durationMs, model: resolvedModel },
-  };
 }

package/lib/mcp-enforcement.js

@@ -11,19 +11,20 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import {
+  isGuarded as registryIsGuarded,
+  toolsForPath as registryToolsForPath,
+  featureCodeForPath as registryFeatureCodeForPath,
+} from './canon-registry.js';
 
-const GUARDED_FILES = new Set(['ROADMAP.md', 'CHANGELOG.md']);
-
-const TOOLS_FOR_ROADMAP = ['add_roadmap_entry', 'set_feature_status', 'propose_followup'];
-const TOOLS_FOR_CHANGELOG = ['add_changelog_entry'];
-const TOOLS_FOR_FEATURE_JSON = [
-  'add_roadmap_entry',
-  'set_feature_status',
-  'link_artifact',
-  'link_features',
-  'record_completion',
-  'propose_followup',
-];
+// COMP-CANON-GUARD S1: the guarded-path/tool declarations that used to live here
+// as literal sets now live in lib/canon-registry.js — the single source of truth
+// shared with the write-time hook. This module is the 'ship' enforcement point;
+// it consumes ONLY the registry's ship subset, so its behavior is unchanged
+// (docs/judgment/** is a hook-only path and is invisible here, exactly as before
+// this refactor, when it was not declared at all). The contract test
+// (test/canon-registry-contract.test.js) pins that equivalence.
+const ENFORCEMENT_POINT = 'ship';
 
 /**
  * Read `enforcement.mcpForFeatureMgmt` and normalize to 'block' | 'log' | 'off'.
@@ -63,11 +64,7 @@ export function filterGuarded(dirtyFiles, featuresDir) {
  */
 export function isGuardedPath(path, featuresDir) {
   if (typeof path !== 'string') return false;
-  if (GUARDED_FILES.has(path)) return true;
-  // <featuresDir>/<CODE>/feature.json
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (!path.startsWith(prefix)) return false;
-  return path.endsWith('/feature.json');
+  return registryIsGuarded(path, { featuresDir, point: ENFORCEMENT_POINT });
 }
 
 /**
@@ -80,13 +77,7 @@ export function isGuardedPath(path, featuresDir) {
  * @returns {string[]}
  */
 export function expectedToolsForPath(path, featuresDir) {
-  if (path === 'ROADMAP.md') return [...TOOLS_FOR_ROADMAP];
-  if (path === 'CHANGELOG.md') return [...TOOLS_FOR_CHANGELOG];
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (path.startsWith(prefix) && path.endsWith('/feature.json')) {
-    return [...TOOLS_FOR_FEATURE_JSON];
-  }
-  return [];
+  return registryToolsForPath(path, { featuresDir, point: ENFORCEMENT_POINT });
 }
 
 /**
@@ -98,11 +89,7 @@ export function expectedToolsForPath(path, featuresDir) {
  * @returns {string|null}
  */
 export function featureCodeFromPath(path, featuresDir) {
-  const prefix = featuresDir.replace(/\/$/, '') + '/';
-  if (!path.startsWith(prefix) || !path.endsWith('/feature.json')) return null;
-  const middle = path.slice(prefix.length, -'/feature.json'.length);
-  if (!middle || middle.includes('/')) return null;
-  return middle;
+  return registryFeatureCodeForPath(path, { featuresDir });
 }
 
 /**
@@ -165,9 +152,8 @@ export function enforcementError(violations) {
   return err;
 }
 
-export const _internals = {
-  GUARDED_FILES,
-  TOOLS_FOR_ROADMAP,
-  TOOLS_FOR_CHANGELOG,
-  TOOLS_FOR_FEATURE_JSON,
-};
+// NOTE: the `_internals` export (guarded-file set + tool sets) was removed in
+// COMP-CANON-GUARD S1. Those declarations now live in lib/canon-registry.js —
+// the single source of truth — with no in-repo consumer of the old shim. Import
+// from canon-registry.js if you need the raw sets, so there is exactly ONE
+// declaration, not a copy here that can drift.

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
@@ -258,6 +273,18 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   // 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);
+  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;
   // 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)
@@ -430,6 +457,8 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   };
 
   let runResult;
+  let primaryDispatchId = null;
+  let repairDispatchId = null;
   try {
     if (useLocalClaude) {
       // Test seam: an installed factory shim exposes an SDK-shaped query adapter
@@ -443,8 +472,10 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         allowedTools:    cfg.allowedTools ?? undefined,
         disallowedTools: cfg.disallowedTools ?? undefined,
         thinking:        cfg.thinking ?? undefined,
+        effort:          cfg.effort ?? undefined,
         abortController,
         onToolUse:       localOnToolUse,
+        telemetry:       primaryTelemetry,
         ...(localQuery ? { query: localQuery } : {}),
       });
     } else {
@@ -457,8 +488,12 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
         sandboxMode,
         cwd:              opts.cwd ?? undefined,
         correlationId,
+        telemetry:        primaryTelemetry,
       });
     }
+    primaryDispatchId = typeof runResult?.dispatchId === 'string'
+      ? runResult.dispatchId
+      : null;
   } 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
@@ -469,17 +504,19 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
     if (timedOut) {
       const e = new AgentTimeoutError(stepId, Date.now() - startTime);
       if (errUsage) e.usage = errUsage;
-      throw e;
+      throw copyDispatchId(err, e);
+    }
+    if (userInterruptAction) {
+      throw copyDispatchId(err, new UserInterruptError(stepId, userInterruptAction));
     }
-    if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
     if (abortReason) {
       const e = new AgentAbortedError(stepId, abortReason);
       if (errUsage) e.usage = errUsage;
-      throw e;
+      throw copyDispatchId(err, e);
     }
     const agentError = new AgentError(err?.message ?? 'Agent run failed');
     if (errUsage) agentError.usage = errUsage;
-    throw agentError;
+    throw copyDispatchId(err, agentError);
   } finally {
     if (timeoutHandle) clearTimeout(timeoutHandle);
     if (onInterrupt && progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
@@ -498,13 +535,15 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   if (timedOut) {
     const e = new AgentTimeoutError(stepId, Date.now() - startTime);
     if (lateUsage) e.usage = lateUsage;
-    throw e;
+    throw copyDispatchId(runResult, e);
+  }
+  if (userInterruptAction) {
+    throw copyDispatchId(runResult, new UserInterruptError(stepId, userInterruptAction));
   }
-  if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
   if (abortReason) {
     const e = new AgentAbortedError(stepId, abortReason);
     if (lateUsage) e.usage = lateUsage;
-    throw e;
+    throw copyDispatchId(runResult, e);
   }
 
   // D2(b): the TS agent_run path returns a synchronous `complete` envelope with
@@ -540,13 +579,35 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
   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;
+    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) => {
-          const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
-            modelID: cfg.modelID ?? undefined,
-            cwd: opts.cwd ?? undefined,
-          });
-          return repairResult?.text ?? '';
+          try {
+            const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
+              modelID: cfg.modelID ?? undefined,
+              cwd: opts.cwd ?? undefined,
+              telemetry: { ...primaryTelemetry, site: 'review-repair' },
+            });
+            repairDispatchId = typeof repairResult?.dispatchId === 'string'
+              ? repairResult.dispatchId
+              : null;
+            foldRepairUsage(repairResult?.usage);
+            return repairResult?.text ?? '';
+          } catch (error) {
+            repairDispatchId = typeof error?.dispatchId === 'string'
+              ? error.dispatchId
+              : null;
+            foldRepairUsage(error?.usage);
+            throw error;
+          }
         }
       : undefined;
     const reviewResult = await normalizeReviewResult(text, {
@@ -555,12 +616,23 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
       confidenceGate: opts.confidenceGate ?? 7,
       lens: opts.lens ?? 'general',
       repairFn,
+      onRepairUsed: () => { repairUsed = true; },
     });
-    return { text, result: reviewResult, usage: usageTotals };
+    return {
+      text,
+      result: reviewResult,
+      usage: usageTotals,
+      dispatchIds: { primary: primaryDispatchId, repair: repairUsed ? repairDispatchId : null },
+    };
   }
 
   if (!hasStructuredOutput) {
-    return { text, result: null, usage: usageTotals };
+    return {
+      text,
+      result: null,
+      usage: usageTotals,
+      dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
+    };
   }
 
   const result = extractJson(text);
@@ -577,8 +649,14 @@ export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, o
       result: { summary: normalizationFailure },
       usage: usageTotals,
       normalizationFailure,
+      dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
     };
   }
 
-  return { text, result, usage: usageTotals };
+  return {
+    text,
+    result,
+    usage: usageTotals,
+    dispatchIds: { primary: primaryDispatchId, repair: repairDispatchId },
+  };
 }

package/lib/review-normalize.js

@@ -144,6 +144,7 @@ export async function normalizeReviewResult(rawText, {
   confidenceGate = 7,
   lens = 'general',
   repairFn,
+  onRepairUsed,
 } = {}) {
   // Step 1: Try direct JSON parse
   let parsed = parseReviewJson(rawText);
@@ -158,6 +159,9 @@ export async function normalizeReviewResult(rawText, {
 
     if (repairText) {
       parsed = parseReviewJson(repairText);
+      // Only a parseable repair actually replaces the primary output — the
+      // caller uses this to decide which dispatch gets credited.
+      if (parsed && typeof onRepairUsed === 'function') onRepairUsed();
     }
   }