@smartmemory/compose 0.3.5-beta → 0.3.7

package/lib/build.js

@@ -75,6 +75,7 @@ import {
   recoverAdvancedConsumerArtifacts,
   verifyConsumerRunRevision,
 } from './consumer-fanout.js';
+import { appendEvent as appendDispatchEvent, readEvents as readDispatchEvents } from './dispatch-ledger.js';
 
 // ---------------------------------------------------------------------------
 // COMP-ROADMAP-PLAN S8: gate the `ship` interception by mode.
@@ -563,6 +564,11 @@ function isStaleOrDuplicateConsumerReportError(error) {
     || /\bstep is not awaiting a client result\b/i.test(message);
 }
 
+function responseReissuesStep(response, stepId) {
+  if (response?.status !== 'ready' || !Array.isArray(response.ready)) return false;
+  return response.ready.some((ready) => ready?.id === stepId && ready?.previousFailure);
+}
+
 async function reportConsumerStepDone({
   descriptor,
   flowId,
@@ -809,6 +815,14 @@ export async function runConsumerIssuance({
       reviewMode: reviewOpts.reviewMode,
       confidenceGate: reviewOpts.confidenceGate,
       lens: reviewOpts.lens,
+      telemetry: {
+        site: context.gsd ? 'gsd' : 'consumer',
+        project_cwd: context.projectCwd ?? context.cwd,
+        build_id: context.build_id,
+        feature_code: context.featureCode,
+        step_id: descriptor.id,
+        ...(typeof descriptor.attempt === 'number' ? { attempt: descriptor.attempt } : {}),
+      },
       // V2/V3: the isolation:none review fanout is the safety-critical controlled
       // execution — a claude review item runs via the compose-local connector so
       // its read-only tool restrictions actually BIND (the engine's sync
@@ -841,6 +855,8 @@ export async function runConsumerIssuance({
       mainResult = {
         result: { outcome: 'failed', summary: `Timed out after ${Math.round(error.durationMs / 1000)}s` },
         normalizationFailure: error.message,
+        dispatchIds: { primary: error.dispatchId ?? null, repair: null },
+        settlementFailureClass: 'agent',
         // G3: a timed-out run still consumed billable usage — forward it so the
         // failure envelope debits the engine ledger (same mechanism as F3).
         ...(error && typeof error === 'object' && error.usage ? { usage: error.usage } : {}),
@@ -855,6 +871,8 @@ export async function runConsumerIssuance({
       mainResult = {
         result: { outcome: 'failed', summary: `Agent error: ${reason}` },
         normalizationFailure: reason,
+        dispatchIds: { primary: error?.dispatchId ?? null, repair: null },
+        settlementFailureClass: 'agent',
         // F3: a failed run still consumed billable usage — the connector attaches
         // it to the error. Forward it so the failure envelope (and compose's
         // cumulative ledger) debit the attempt instead of letting failures evade
@@ -936,6 +954,17 @@ export async function runConsumerIssuance({
   });
   if (report.skipped) return report.response;
   const { response } = report;
+  if (!context.gsd && typeof context?.settleDispatches === 'function') {
+    const isEnsureRetry = responseReissuesStep(response, descriptor.id);
+    context.settleDispatches({
+      stepId: descriptor.id,
+      dispatchIds: mainResult.dispatchIds,
+      accepted: !localFailure && !isEnsureRetry,
+      failureClass: mainResult.settlementFailureClass
+        ?? (normalizationFailure ? 'normalization' : (localFailure ? 'agent' : null)),
+      isEnsureRetry,
+    });
+  }
   if (typeof artifacts.hooks.afterStepDone === 'function') {
     await artifacts.hooks.afterStepDone({ descriptor, envelope, response });
   }
@@ -1215,6 +1244,266 @@ function writeActiveBuild(dataDir, state) {
   renameSync(tmp, target);
 }
 
+const BUILD_ACCUMULATOR_VERSION = 1;
+const BUILD_ACCUMULATOR_FIELDS = new Set([
+  'v',
+  'build_id',
+  'feature_code',
+  'last_terminal',
+  'review_iterations',
+  'escalations',
+  'files_changed',
+  'ship_files_changed',
+  'test_count',
+  'pass_rate',
+  'tokens_total',
+  'usd',
+]);
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+function assertFeatureCodeForAccumulator(featureCode) {
+  if (typeof featureCode !== 'string' || featureCode.length === 0 || /[/\\]/.test(featureCode)) {
+    throw new Error('Build accumulator feature code must be a non-empty path-safe string');
+  }
+}
+
+export function buildAccumulatorPath(projectCwd, featureCode) {
+  assertFeatureCodeForAccumulator(featureCode);
+  return join(projectCwd, '.compose', 'data', 'build-accumulator', `${featureCode}.json`);
+}
+
+function validateBuildAccumulator(value, expectedFeatureCode = null) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Build accumulator is corrupt: expected an object');
+  }
+  for (const key of Object.keys(value)) {
+    if (!BUILD_ACCUMULATOR_FIELDS.has(key)) {
+      throw new Error(`Build accumulator is corrupt: unknown field "${key}"`);
+    }
+  }
+  for (const key of BUILD_ACCUMULATOR_FIELDS) {
+    if (!Object.hasOwn(value, key)) {
+      throw new Error(`Build accumulator is corrupt: missing field "${key}"`);
+    }
+  }
+  if (value.v !== BUILD_ACCUMULATOR_VERSION) {
+    throw new Error(`Build accumulator is corrupt: unsupported version ${value.v}`);
+  }
+  if (typeof value.build_id !== 'string' || !UUID_RE.test(value.build_id)) {
+    throw new Error('Build accumulator is corrupt: build_id must be a UUID');
+  }
+  if (typeof value.feature_code !== 'string' || value.feature_code.length === 0) {
+    throw new Error('Build accumulator is corrupt: feature_code must be a non-empty string');
+  }
+  if (expectedFeatureCode !== null && value.feature_code !== expectedFeatureCode) {
+    throw new Error(
+      `Build accumulator feature identity mismatch: expected ${expectedFeatureCode}, found ${value.feature_code}`,
+    );
+  }
+  if (![null, 'failed', 'complete', 'aborted'].includes(value.last_terminal)) {
+    throw new Error('Build accumulator is corrupt: invalid last_terminal');
+  }
+  for (const key of ['review_iterations', 'escalations']) {
+    if (!Number.isInteger(value[key]) || value[key] < 0) {
+      throw new Error(`Build accumulator is corrupt: ${key} must be a non-negative integer`);
+    }
+  }
+  if (!Array.isArray(value.files_changed) || !value.files_changed.every((file) => typeof file === 'string')) {
+    throw new Error('Build accumulator is corrupt: files_changed must be a string array');
+  }
+  if (value.ship_files_changed !== null
+    && (!Array.isArray(value.ship_files_changed)
+      || !value.ship_files_changed.every((file) => typeof file === 'string'))) {
+    throw new Error('Build accumulator is corrupt: ship_files_changed must be null or a string array');
+  }
+  for (const key of ['test_count', 'pass_rate']) {
+    if (value[key] !== null && (typeof value[key] !== 'number' || !Number.isFinite(value[key]))) {
+      throw new Error(`Build accumulator is corrupt: ${key} must be null or a finite number`);
+    }
+  }
+  for (const key of ['tokens_total', 'usd']) {
+    if (typeof value[key] !== 'number' || !Number.isFinite(value[key]) || value[key] < 0) {
+      throw new Error(`Build accumulator is corrupt: ${key} must be a non-negative finite number`);
+    }
+  }
+  return value;
+}
+
+export function readBuildAccumulator(projectCwd, featureCode) {
+  const path = buildAccumulatorPath(projectCwd, featureCode);
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`Build accumulator is corrupt at ${path}: ${error.message}`);
+  }
+  return validateBuildAccumulator(parsed, featureCode);
+}
+
+export function writeBuildAccumulator(projectCwd, accumulator) {
+  validateBuildAccumulator(accumulator, accumulator?.feature_code ?? null);
+  const target = buildAccumulatorPath(projectCwd, accumulator.feature_code);
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(accumulator, null, 2));
+  renameSync(tmp, target);
+  return accumulator;
+}
+
+export function clearBuildAccumulator(projectCwd, featureCode) {
+  const path = buildAccumulatorPath(projectCwd, featureCode);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+export function newBuildAccumulatorRecord(featureCode) {
+  return {
+    v: BUILD_ACCUMULATOR_VERSION,
+    build_id: randomUUID(),
+    feature_code: featureCode,
+    last_terminal: null,
+    review_iterations: 0,
+    escalations: 0,
+    files_changed: [],
+    ship_files_changed: null,
+    test_count: null,
+    pass_rate: null,
+    tokens_total: 0,
+    usd: 0,
+  };
+}
+
+export function createBuildAccumulator(projectCwd, featureCode) {
+  return writeBuildAccumulator(projectCwd, newBuildAccumulatorRecord(featureCode));
+}
+
+export function updateBuildAccumulator(projectCwd, featureCode, mutate) {
+  const current = readBuildAccumulator(projectCwd, featureCode);
+  if (!current) {
+    throw new Error(`Build accumulator not found for ${featureCode}`);
+  }
+  const next = typeof mutate === 'function' ? mutate({ ...current }) : { ...current, ...mutate };
+  validateBuildAccumulator(next, featureCode);
+  return writeBuildAccumulator(projectCwd, next);
+}
+
+export function selectBuildAccumulator(projectCwd, featureCode, { fresh = false } = {}) {
+  const existing = readBuildAccumulator(projectCwd, featureCode);
+  if (fresh || !existing || ['complete', 'aborted'].includes(existing.last_terminal)) {
+    // Candidate only — NOTHING persists until the caller owns the attempt. A
+    // concurrent live build may refuse this invocation, and persisting here
+    // (e.g. on --fresh) would clobber the live build's sidecar mid-run.
+    return { accumulator: newBuildAccumulatorRecord(featureCode), isNew: true };
+  }
+  return { accumulator: existing, isNew: false };
+}
+
+function ledgerEstimateSource(source) {
+  if (source === 'escalated') return 'escalated';
+  if (source === 'cached') return 'cached';
+  if (source === 'front' || source === 'refined' || source === 'fresh') return 'fresh';
+  throw new Error(`Unsupported triage estimate source "${source}"`);
+}
+
+export function emitTriageEstimate(projectCwd, estimate) {
+  return appendDispatchEvent(projectCwd, {
+    kind: 'triage-estimate',
+    build_id: estimate.build_id,
+    feature_code: estimate.feature_code,
+    tier: estimate.triageTier ?? estimate.tier,
+    lane: estimate.lane,
+    profile: estimate.profile,
+    estimate_source: ledgerEstimateSource(estimate.estimateSource ?? estimate.estimate_source),
+    confidence: estimate.triageConfidence ?? estimate.confidence ?? null,
+  });
+}
+
+export function emitBuildActuals(projectCwd, accumulator, terminalStatus) {
+  validateBuildAccumulator(accumulator, accumulator?.feature_code ?? null);
+  const persisted = readBuildAccumulator(projectCwd, accumulator.feature_code);
+  if (!persisted || persisted.build_id !== accumulator.build_id) {
+    throw new Error(`Build accumulator identity mismatch while finalizing ${accumulator.feature_code}`);
+  }
+  // COMP-TRIAGE-6-4: the ledger row is the durable, ACRR-consumed artifact —
+  // append it FIRST, then do the best-effort accumulator marker/clear. The row
+  // fields are all read from `persisted` (none depends on last_terminal), so
+  // this is byte-identical on the happy path. Row-first makes the two writes
+  // effectively atomic for every terminalization path (fresh, --fresh, resume,
+  // fresh-over-failed): a crash between them can leave a stale marker/sidecar
+  // (harmless — rotated away on the next build) but can NEVER lose a row or
+  // strand a `last_terminal='failed'` marker with no row behind it. Since
+  // emitBuildActuals is the ONLY writer of `last_terminal='failed'`, no other
+  // path can produce that orphan either.
+  const authoritativeShip = Array.isArray(persisted.ship_files_changed);
+  const files = authoritativeShip
+    ? persisted.ship_files_changed
+    : persisted.files_changed;
+  const row = appendDispatchEvent(projectCwd, {
+    kind: 'build-actuals',
+    build_id: persisted.build_id,
+    feature_code: persisted.feature_code,
+    terminal_status: terminalStatus,
+    files_changed_count: new Set(files).size,
+    files_source: authoritativeShip ? 'ship' : 'accumulated',
+    review_iterations: persisted.review_iterations,
+    escalations: persisted.escalations,
+    tokens_total: persisted.tokens_total,
+    usd: persisted.usd,
+    test_count: persisted.test_count,
+    pass_rate: persisted.pass_rate,
+  });
+  if (terminalStatus === 'failed') {
+    updateBuildAccumulator(projectCwd, persisted.feature_code, (current) => ({
+      ...current,
+      last_terminal: 'failed',
+    }));
+  } else if (terminalStatus === 'complete' || terminalStatus === 'aborted') {
+    clearBuildAccumulator(projectCwd, persisted.feature_code);
+  }
+  return row;
+}
+
+export function settleDispatches(projectCwd, buildId, stepId, {
+  dispatchIds,
+  accepted,
+  failureClass = null,
+  isEnsureRetry = false,
+  gsd = false,
+} = {}) {
+  if (gsd) return [];
+  const primary = dispatchIds?.primary;
+  const repair = dispatchIds?.repair;
+  if (!primary && !repair) return [];
+  const rows = [];
+  const appendSettlement = (dispatchId, isAccepted, rejectedClass) => {
+    if (typeof dispatchId !== 'string' || dispatchId.length === 0) return;
+    rows.push(appendDispatchEvent(projectCwd, {
+      kind: 'settlement',
+      dispatch_id: dispatchId,
+      accepted: isAccepted,
+      ...(typeof buildId === 'string' && buildId.length > 0 ? { build_id: buildId } : {}),
+      ...(typeof stepId === 'string' && stepId.length > 0 ? { step_id: stepId } : {}),
+      ...(!isAccepted ? { failure_class: rejectedClass ?? 'agent' } : {}),
+    }));
+  };
+
+  if (repair) {
+    appendSettlement(primary, false, 'normalization');
+    appendSettlement(
+      repair,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  } else {
+    appendSettlement(
+      primary,
+      isEnsureRetry ? false : accepted === true,
+      isEnsureRetry ? 'ensure-retry' : failureClass,
+    );
+  }
+  return rows;
+}
+
 /**
  * Decide how a compose build invocation should start.
  *
@@ -1391,7 +1680,17 @@ function makeAskAgent(stratum, context, gateDispatch, gateExtras) {
       `${fileRef} this question concisely:\n\n` +
       `${question}\n\n` +
       `Keep your answer brief — 2-3 sentences max.`;
-    const text = await stratum.runAgentText('claude', qaPrompt, { cwd: context.cwd });
+    const text = await stratum.runAgentText('claude', qaPrompt, {
+      cwd: context.cwd,
+      telemetry: {
+        site: 'gate-qa',
+        project_cwd: context.projectCwd ?? context.cwd,
+        build_id: context.build_id,
+        feature_code: context.featureCode,
+        step_id: gateDispatch.step_id ?? gateDispatch.id,
+        ...(typeof gateDispatch.attempt === 'number' ? { attempt: gateDispatch.attempt } : {}),
+      },
+    });
     return text || '(no answer)';
   };
 }
@@ -1638,6 +1937,87 @@ export async function runBuild(featureCode, opts = {}) {
     return;
   }
 
+  const {
+    accumulator: selectedAccumulator,
+    isNew: isNewAccumulator,
+  } = selectBuildAccumulator(cwd, featureCode, { fresh: opts.fresh === true });
+  let build_id = selectedAccumulator.build_id;
+  // Tracks the record this attempt actually owns: the reused sidecar, the
+  // in-memory candidate (persisted at the ownership point after the start
+  // verdict), or the rotated record on a fresh-over-failed start.
+  let activeAccumulator = selectedAccumulator;
+  let accumulatorPersisted = !isNewAccumulator;
+  const buildStartedAt = new Date().toISOString();
+  let buildStatus = 'failed';
+  let attemptStarted = true;
+  let attemptFinalized = false;
+  // COMP-TRIAGE-6-4: function-scoped so finalizeBuildAttempt's ownership guard
+  // can read them (they are assigned/read from inside the main try below).
+  // accumulatorRotated flips true once a fresh-over-failed retry rotates to a
+  // new identity; isFreshStart defaults true until a resume verdict flips it.
+  let accumulatorRotated = false;
+  let isFreshStart = true;
+  let progress = null;
+  let stratum = null;
+  let streamWriter = null;
+  let signalHandler = null;
+  let runtimeResourcesFinalized = false;
+
+  const _priorBuildIdEnv = process.env.COMPOSE_BUILD_ID;
+  if (_priorBuildIdEnv !== undefined) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[build] COMPOSE_BUILD_ID was already set ("${_priorBuildIdEnv}") when runBuild started. ` +
+      `Overriding for this build; concurrent in-process builds will mis-stamp events.`
+    );
+  }
+  process.env.COMPOSE_BUILD_ID = build_id;
+  const _restoreBuildIdEnv = () => {
+    if (_priorBuildIdEnv === undefined) delete process.env.COMPOSE_BUILD_ID;
+    else process.env.COMPOSE_BUILD_ID = _priorBuildIdEnv;
+  };
+  const finalizeBuildAttempt = () => {
+    if (!attemptStarted || attemptFinalized) return;
+    const terminalStatus = buildStatus === 'complete'
+      ? 'complete'
+      : (buildStatus === 'killed' || buildStatus === 'aborted')
+        ? 'aborted'
+        : 'failed';
+    let accumulator = readBuildAccumulator(cwd, featureCode);
+    // A pre-ownership failure (e.g. missing lifecycle spec) dies before the
+    // candidate persists — write it now so the attempt still leaves a terminal
+    // actuals row. The build_id guard keeps a stale on-disk record from another
+    // identity from being finalized under this attempt's name.
+    if ((!accumulator || accumulator.build_id !== build_id) && !accumulatorPersisted) {
+      accumulator = writeBuildAccumulator(cwd, activeAccumulator);
+      accumulatorPersisted = true;
+    }
+    // A terminal complete/abort may already have cleared the sidecar if a nested
+    // terminalization path finalized first. The finalized flag is the primary
+    // guard; the missing-file/identity guard keeps cleanup idempotent.
+    //
+    // COMP-TRIAGE-6-4 ownership guard: a fresh (non-resume), not-yet-rotated
+    // attempt that reuses a prior record must not re-emit a terminal row that
+    // ALREADY EXISTS for this build_id. Without it, an attempt that dies before
+    // rotating to a fresh identity (rotateStaleAccumulatorForFreshStart) — e.g.
+    // the flow-audit probe throws while resolving the fresh/resume verdict —
+    // re-finalizes the reused failed record, double-counting in ACRR. The signal
+    // is the LEDGER itself, not the reused record's last_terminal: emitBuildActuals
+    // writes last_terminal and the row non-atomically, so a crash between them
+    // must cause neither a wrongful suppression (marker set, no row) nor a
+    // wrongful double-emit (row written, marker cleared). A genuine resume
+    // (isFreshStart=false) owns and continues the build (its second row under the
+    // same id is intended); a rotated/new identity owns a fresh, unemitted id.
+    const mayReemitReused = !isNewAccumulator && !accumulatorRotated && isFreshStart;
+    const alreadyEmitted = mayReemitReused
+      && readDispatchEvents(cwd, { kind: 'build-actuals' }).some((r) => r.build_id === build_id);
+    if (accumulator && accumulator.build_id === build_id && !alreadyEmitted) {
+      emitBuildActuals(cwd, accumulator, terminalStatus);
+    }
+    attemptFinalized = true;
+  };
+
+  try {
   // Single resolver — used at every site that previously hardcoded
   // `docs/features/<featureCode>/`. Callers must use this (not inline
   // string concatenation) so the bug-mode path stays in sync.
@@ -1660,29 +2040,6 @@ export async function runBuild(featureCode, opts = {}) {
     ? join(resolveFeaturesPath(cwd), code)
     : join(cwd, ...cfg.artifactRoot.split('/'), code);
 
-  // COMP-MCP-MIGRATION-1: per-build correlation ID stamped onto every audit
-  // row written during this run, so `executeShipStep`'s pre-stage scan can
-  // tell agent-emitted typed-tool events apart from anything else.
-  const build_id = randomUUID();
-  const buildStartedAt = new Date().toISOString();
-  const _priorBuildIdEnv = process.env.COMPOSE_BUILD_ID;
-  if (_priorBuildIdEnv !== undefined) {
-    // Concurrent in-process builds are not currently supported — env-based
-    // stamping cannot tell them apart. Warn loudly so the surrounding
-    // process tree picks it up; do not throw, since the prior env value
-    // may simply be inherited from the parent (CI, harness) and harmless.
-    // eslint-disable-next-line no-console
-    console.warn(
-      `[build] COMPOSE_BUILD_ID was already set ("${_priorBuildIdEnv}") when runBuild started. ` +
-      `Overriding for this build; concurrent in-process builds will mis-stamp events.`
-    );
-  }
-  process.env.COMPOSE_BUILD_ID = build_id;
-  const _restoreBuildIdEnv = () => {
-    if (_priorBuildIdEnv === undefined) delete process.env.COMPOSE_BUILD_ID;
-    else process.env.COMPOSE_BUILD_ID = _priorBuildIdEnv;
-  };
-
   const featureDir = resolveItemDir(featureCode);
 
   // Debug discipline (COMP-DEBUG-1)
@@ -1732,6 +2089,7 @@ export async function runBuild(featureCode, opts = {}) {
   // ---------------------------------------------------------------------------
   let buildProfile = null;
   let _buildTierLabel = '?'; // for skip_reason label in spec YAML mutation below
+  let triageEstimate = null;
   // Only modes that run feature triage do so — triage is feature-shaped (writes
   // feature.json, profile selection per complexity tiers). bug AND plan skip it.
   if (cfg.runsTriage && !opts.skipTriage && !opts.template) {
@@ -1746,6 +2104,15 @@ export async function runBuild(featureCode, opts = {}) {
       // Reuse cached profile
       buildProfile = cachedFeature.profile;
       _buildTierLabel = cachedFeature.complexity ?? '?';
+      triageEstimate = {
+        build_id,
+        feature_code: featureCode,
+        triageTier: cachedFeature.triageTier,
+        lane: cachedFeature.lane,
+        profile: cachedFeature.profile,
+        estimateSource: _escalated ? 'escalated' : 'cached',
+        triageConfidence: cachedFeature.triageConfidence ?? null,
+      };
       console.log(`[triage] Using ${_escalated ? 'escalated' : 'cached'} profile (tier ${_buildTierLabel}, lane ${cachedFeature.lane ?? '?'}): ${JSON.stringify(buildProfile)}`);
     } else {
       // COMP-TRIAGE-5 (E3 Estimate): derive the lane from the RAW REQUEST before
@@ -1763,10 +2130,21 @@ export async function runBuild(featureCode, opts = {}) {
       buildProfile = front.buildProfile;
       _buildTierLabel = front.tierLabel;
       cachedFeature = front.cachedFeature;
+      triageEstimate = {
+        build_id,
+        feature_code: featureCode,
+        triageTier: front.tier,
+        lane: front.lane,
+        profile: front.buildProfile,
+        estimateSource: 'fresh',
+        triageConfidence: front.confidence ?? null,
+      };
       console.log(`[triage] Front estimate lane=${front.lane} (tier ${front.tier}): ${front.rationale}`);
       console.log(`[triage] Profile: ${JSON.stringify(buildProfile)}`);
     }
   }
+  // Estimate emission is DEFERRED to the post-verdict ownership point: a
+  // refused/errored invocation must leave no orphan estimate (review r2).
 
   // Load lifecycle spec (template selection). The mode's defaultTemplate is the
   // fallback when no explicit --template is given (build → 'build', byte-identical
@@ -1883,10 +2261,10 @@ export async function runBuild(featureCode, opts = {}) {
   }
 
   // CLI progress renderer
-  const progress = new CliProgress();
+  progress = new CliProgress();
 
   // Stratum MCP client (test override permitted via opts.stratum)
-  const stratum = opts.stratum ?? new StratumMcpClient();
+  stratum = opts.stratum ?? new StratumMcpClient();
   if (!opts.stratum) await stratum.connect(resolveStratumMcpConnection(cwd));
 
   // Update feature.json status to IN_PROGRESS (only modes that track
@@ -1905,8 +2283,7 @@ export async function runBuild(featureCode, opts = {}) {
   }
 
   // Hoisted for finally-block visibility
-  let streamWriter = null;
-  let buildStatus = 'complete';
+  buildStatus = 'complete';
   let killedByGate = false;
   let terminalFailureReason = null;
   // I4: the last step the engine issued as `ready` (i.e. dispatched). When a flow
@@ -1924,17 +2301,25 @@ export async function runBuild(featureCode, opts = {}) {
   // and resets lenses_run, so the TRUE dirty lens (e.g. security) can be erased —
   // the gate persists from this, and only falls back to post-normalization findings.
   let lastReviewMergeDirtyLenses = [];
-  let signalHandler = null;
   let response;
   let stepHistory = [];
   const terminalHistoryWritten = { value: false };
   // COMP-OBS-COST: Accumulate token/cost totals across all steps (hoisted for finally-block)
   // On resume, seed from active-build.json to preserve pre-resume cost totals
-  const buildCostTotals = { input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+  const buildCostTotals = {
+    input_tokens: 0,
+    output_tokens: selectedAccumulator.tokens_total,
+    cost_usd: selectedAccumulator.usd,
+  };
   // COMP-MODEL-AB: capture structured test counts from the ship step so they can
   // be persisted to build-history.jsonl for the metrics consumer (experiment-metrics.js).
   // Null when ship didn't run (failed/killed builds) or testSummary was unparsed.
-  let shipStepTestData = null;
+  let shipStepTestData = selectedAccumulator.test_count === null
+    ? null
+    : {
+        test_count: selectedAccumulator.test_count,
+        pass_rate: selectedAccumulator.pass_rate ?? 0,
+      };
 
   // COMP-OBS-GATES: accumulate tier pass/fail results for this build.
   // Keys are tier IDs (T0–T4), values are true (passed), false (failed), or null (not yet run).
@@ -1949,17 +2334,37 @@ export async function runBuild(featureCode, opts = {}) {
   // Accumulate contract compliance signal: array of { passed: bool } per ensure check
   const contractCompliance = [];
 
-  const priorActive = readActiveBuild(dataDir);
-  if (priorActive && priorActive.featureCode === featureCode && priorActive.status === 'running') {
-    if (typeof priorActive.total_input_tokens === 'number') buildCostTotals.input_tokens = priorActive.total_input_tokens;
-    if (typeof priorActive.total_output_tokens === 'number') buildCostTotals.output_tokens = priorActive.total_output_tokens;
-    if (typeof priorActive.cumulative_cost_usd === 'number') buildCostTotals.cost_usd = priorActive.cumulative_cost_usd;
-  }
+  // COMP-TRIAGE-6-4: on a fresh-over-failed retry the reused accumulator still
+  // carries the prior FAILED attempt's identity and counters. Rotate to a fresh
+  // record BEFORE the fallible startFresh (its plan() call can throw): otherwise
+  // a throw drops to finalizeBuildAttempt, which reads the OLD record still on
+  // disk under the reused build_id and emits a DUPLICATE build-actuals failed
+  // row with stale counters (double-count in ACRR). Rotating first means the
+  // throw finalizes the NEW record (distinct build_id, zeroed counters) instead.
+  // Idempotent: guarded so the post-startFresh ownership block cannot re-rotate.
+  // accumulatorRotated / isFreshStart are declared at function scope above so
+  // finalizeBuildAttempt's ownership guard can read them.
+  const rotateStaleAccumulatorForFreshStart = () => {
+    if (isNewAccumulator || accumulatorRotated) return;
+    activeAccumulator = createBuildAccumulator(cwd, featureCode);
+    accumulatorPersisted = true;
+    build_id = activeAccumulator.build_id;
+    process.env.COMPOSE_BUILD_ID = build_id;
+    buildCostTotals.input_tokens = 0;
+    buildCostTotals.output_tokens = 0;
+    buildCostTotals.cost_usd = 0;
+    shipStepTestData = null;
+    if (triageEstimate) {
+      triageEstimate.build_id = build_id;
+      emitTriageEstimate(cwd, triageEstimate);
+    }
+    accumulatorRotated = true;
+  };
 
   try {
     // Check for active build (resume)
     const active = readActiveBuild(dataDir);
-    let isFreshStart = true;
+    isFreshStart = true;
 
     // COMP-CODEX-IMPL: implementer/reviewer roles. A FRESH start derives them from
     // the flag (--codex flips Claude-implements/Codex-reviews → Codex/Claude); the
@@ -2083,8 +2488,13 @@ export async function runBuild(featureCode, opts = {}) {
         if (explicitResume) {
           throw new Error(`Nothing to resume for ${featureCode} (no in-progress or failed build found)`);
         }
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
+        // COMP-TRIAGE-6-4: claim fresh-ownership intent BEFORE rotating, so if
+        // rotation itself throws the finalize guard still treats this as a fresh
+        // start (isFreshStart=true) and suppresses re-finalizing the reused
+        // failed row. Rotation then swaps to a fresh identity before startFresh.
         isFreshStart = true;
+        rotateStaleAccumulatorForFreshStart();
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
       }
       if (!isFreshStart) {
         const stepId = response.ready?.[0]?.id;
@@ -2116,14 +2526,34 @@ export async function runBuild(featureCode, opts = {}) {
       }
     } else if (verdict.action === 'fresh') {
       if (activeForDecision?.flowId) console.log(`${verdict.reason}. Starting fresh.`);
+      // COMP-TRIAGE-6-4: rotate a reused failed identity before the fallible
+      // startFresh so a plan() throw cannot re-finalize the prior attempt.
+      rotateStaleAccumulatorForFreshStart();
       response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles, cwd);
     } else {
+      // A refused invocation never owned the accumulator — the ALIVE build does.
+      // Disown before throwing so the widened finally cannot finalize the other
+      // build's attempt as failed (spurious terminal row).
+      attemptStarted = false;
       const reason = verdict.reason.includes(featureCode)
         ? verdict.reason
         : verdict.reason.replace('Build already running', `Build already running for ${featureCode}`);
       throw new Error(reason);
     }
 
+    // Ownership point — the verdict resolved to resume or fresh (refuse/error
+    // threw above without persisting anything). The fresh-over-failed identity
+    // rotation now happens BEFORE startFresh (COMP-TRIAGE-6-4,
+    // rotateStaleAccumulatorForFreshStart), so only the brand-new candidate is
+    // persisted here. A new candidate is unaffected by that bug: a startFresh
+    // throw hits finalizeBuildAttempt's write-and-emit fallback under a distinct
+    // candidate id, never a duplicate row.
+    if (isNewAccumulator) {
+      writeBuildAccumulator(cwd, activeAccumulator);
+      accumulatorPersisted = true;
+      if (triageEstimate) emitTriageEstimate(cwd, triageEstimate);
+    }
+
     // COMP-CODEX-IMPL: verify Codex can write inside a detached git worktree (the
     // execute step's isolation primitive) before any step dispatches. Runs on the
     // EFFECTIVE role — after resume restoration above — so a resumed Codex build is
@@ -2135,6 +2565,9 @@ export async function runBuild(featureCode, opts = {}) {
     if (implementerAgent === 'codex') {
       const probe = await preflightCodexWorktreeProbe({
         cwd: agentCwd,
+        projectCwd: cwd,
+        buildId: build_id,
+        featureCode,
         stratum,
         dataDir,
         ts: new Date().toISOString().replace(/[:.]/g, '-'),
@@ -2235,6 +2668,7 @@ export async function runBuild(featureCode, opts = {}) {
 
     const context = {
       cwd: agentCwd,
+      projectCwd: cwd,
       featureCode,
       featureDir: resolveItemDir(featureCode),
       contextDir: contextDirPath,
@@ -2254,8 +2688,66 @@ export async function runBuild(featureCode, opts = {}) {
       // self-review suppression. Restored from active-build state on resume (above).
       implementerAgent,
       reviewerAgent,
+      filesChanged: [...activeAccumulator.files_changed],
       ...(isBugMode ? { bug_code: featureCode } : {}),
     };
+    context.recordBuildUsage = (usage) => {
+      if (!usage || typeof usage !== 'object') return;
+      const componentTokens = (typeof usage.input_tokens === 'number' ? usage.input_tokens : 0)
+        + (typeof usage.output_tokens === 'number' ? usage.output_tokens : 0);
+      const tokens = componentTokens > 0
+        ? componentTokens
+        : (typeof usage.tokens_total === 'number'
+            ? usage.tokens_total
+            : (typeof usage.tokens === 'number' ? usage.tokens : 0));
+      const usd = typeof usage.cost_usd === 'number'
+        ? usage.cost_usd
+        : (typeof usage.usd === 'number' ? usage.usd : 0);
+      if (tokens === 0 && usd === 0) return;
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        tokens_total: accumulator.tokens_total + tokens,
+        usd: accumulator.usd + usd,
+      }));
+    };
+    context.recordFilesChanged = (paths, { authoritativeShip = false } = {}) => {
+      const normalized = Array.isArray(paths)
+        ? [...new Set(paths.filter((file) => typeof file === 'string' && file.length > 0))]
+        : [];
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        ...(authoritativeShip
+          ? { ship_files_changed: normalized }
+          : { files_changed: [...new Set([...accumulator.files_changed, ...normalized])] }),
+      }));
+    };
+    context.recordShipTestMetrics = (metrics) => {
+      if (!metrics || typeof metrics.test_count !== 'number') return;
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        test_count: metrics.test_count,
+        pass_rate: typeof metrics.pass_rate === 'number' ? metrics.pass_rate : 0,
+      }));
+    };
+    context.recordEscalation = () => {
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        escalations: accumulator.escalations + 1,
+      }));
+    };
+    context.recordReviewIteration = () => {
+      updateBuildAccumulator(cwd, featureCode, (accumulator) => ({
+        ...accumulator,
+        review_iterations: accumulator.review_iterations + 1,
+      }));
+    };
+    context.settleDispatches = ({ stepId, ...args } = {}) => settleDispatches(
+      cwd,
+      build_id,
+      stepId,
+      args,
+    );
+    context.onUsage = context.recordBuildUsage;
 
     let consumerArtifacts = null;
     const artifactsForRun = (runId, pins) => {
@@ -2507,7 +2999,13 @@ export async function runBuild(featureCode, opts = {}) {
           // capture, shipStepTestData stays null for all real builds and appendBuildHistory
           // never persists test_count/pass_rate. Must mirror the generic path exactly.
           const _interceptedTestMetrics = _extractShipTestMetrics(shipResult);
-          if (_interceptedTestMetrics !== null) shipStepTestData = _interceptedTestMetrics;
+          if (Array.isArray(shipResult.filesChanged)) {
+            context.recordFilesChanged(shipResult.filesChanged, { authoritativeShip: true });
+          }
+          if (_interceptedTestMetrics !== null) {
+            shipStepTestData = _interceptedTestMetrics;
+            context.recordShipTestMetrics(_interceptedTestMetrics);
+          }
           stepHistory.push({
             stepId: 'ship',
             artifact: shipResult.artifact,
@@ -2618,17 +3116,36 @@ export async function runBuild(featureCode, opts = {}) {
             `Fix step "${stepId}" — the previous attempt failed:\n` +
             `- ${failureReason}\n\nFix every issue, then return the step's expected result.`;
           try {
-            await runAndNormalize(undefined, fixPrompt, { ...stepDispatch, agent: fixAgent }, {
+            // The fixer's work is adjudicated by the retried step's own stepDone —
+            // no settlement here (its dispatch event still records the cost).
+            const fixResult = await runAndNormalize(undefined, fixPrompt, { ...stepDispatch, agent: fixAgent }, {
               progress,
               streamWriter,
               maxDurationMs: STEP_TIMEOUT_MS[stepId] ?? DEFAULT_TIMEOUT_MS,
               stratum,
               cwd: agentCwd,
               profile: resolveStepProfile(context.stepProfiles, stepId),
+              telemetry: {
+                site: 'review-repair',
+                project_cwd: cwd,
+                build_id,
+                feature_code: featureCode,
+                step_id: stepId,
+                ...(typeof readyStep.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+              },
             });
+            if (fixResult?.usage && typeof context.recordBuildUsage === 'function') {
+              try { context.recordBuildUsage(fixResult.usage); } catch { /* fail-open */ }
+            }
           } catch (err) {
-            if (!(err instanceof AgentTimeoutError)) throw err;
-            console.warn(`\n⚠ Fix agent timed out on "${stepId}"`);
+            if (err?.usage && typeof context.recordBuildUsage === 'function') {
+              try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+            }
+            if (err instanceof AgentTimeoutError) {
+              console.warn(`\n⚠ Fix agent timed out on "${stepId}"`);
+            } else {
+              throw err;
+            }
           }
           progress.retry('build', stepId, readyStep.agent ?? response.agent ?? 'claude');
         }
@@ -2678,6 +3195,14 @@ export async function runBuild(featureCode, opts = {}) {
             reviewMode: isReviewMain,
             confidenceGate: confGateMain,
             lens: response.inputs?.lens_name ?? response.lens_name ?? 'general',
+            telemetry: {
+              site: isReviewMain ? 'review' : 'build-step',
+              project_cwd: cwd,
+              build_id,
+              feature_code: featureCode,
+              step_id: stepId,
+              ...(typeof readyStep?.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+            },
             // D6/V4: apply this ordinary step's compose-side profile (e.g.
             // blueprint → claude::critical, review_merge → claude:orchestrator),
             // normalizing scoped subflow ready ids to the bare step id.
@@ -2687,16 +3212,37 @@ export async function runBuild(featureCode, opts = {}) {
           if (err instanceof UserInterruptError) {
             if (err.action === 'skip') {
               if (progress) progress.info(`  ⏭ Skipped step "${stepId}"`);
-              mainResult = { text: '', result: { outcome: 'skipped', summary: `Skipped by user` } };
+              mainResult = {
+                text: '',
+                result: { outcome: 'skipped', summary: 'Skipped by user' },
+                dispatchIds: { primary: err.dispatchId ?? null, repair: null },
+                settlementFailureClass: 'agent',
+              };
             } else {
               if (progress) progress.info(`  ↻ Retrying step "${stepId}"`);
-              mainResult = { text: '', result: { outcome: 'failed', summary: `Retry requested by user` } };
+              mainResult = {
+                text: '',
+                result: { outcome: 'failed', summary: 'Retry requested by user' },
+                dispatchIds: { primary: err.dispatchId ?? null, repair: null },
+                settlementFailureClass: 'agent',
+              };
             }
           } else if (err instanceof AgentTimeoutError) {
             console.warn(`\n⚠ Agent timed out on step "${stepId}" after ${Math.round(err.durationMs / 1000)}s`);
             streamWriter.write({ type: 'build_error', message: err.message, stepId });
-            mainResult = { text: '', result: { outcome: 'failed', summary: `Timed out after ${Math.round(err.durationMs / 1000)}s` } };
+            mainResult = {
+              text: '',
+              result: { outcome: 'failed', summary: `Timed out after ${Math.round(err.durationMs / 1000)}s` },
+              dispatchIds: { primary: err.dispatchId ?? null, repair: null },
+              settlementFailureClass: 'agent',
+              ...(err.usage ? { usage: err.usage } : {}),
+            };
           } else {
+            // Fatal rethrow bypasses the post-stepDone usage fold — bill the
+            // attempt's real cost to the accumulator before crashing.
+            if (err?.usage && typeof context.recordBuildUsage === 'function') {
+              try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+            }
             streamWriter.write({ type: 'build_error', message: err.message, stepId });
             throw err;
           }
@@ -2791,6 +3337,7 @@ export async function runBuild(featureCode, opts = {}) {
               const existing = new Set(context.filesChanged ?? []);
               for (const f of files) existing.add(f);
               context.filesChanged = [...existing];
+              context.recordFilesChanged(context.filesChanged);
             }
           } catch { /* git not available or no repo — skip */ }
         }
@@ -2804,7 +3351,14 @@ export async function runBuild(featureCode, opts = {}) {
         // so both paths produce identical shipStepTestData shapes.
         if (stepId === 'ship') {
           const _genericTestMetrics = _extractShipTestMetrics(result);
-          if (_genericTestMetrics !== null) shipStepTestData = _genericTestMetrics;
+          const genericShipFiles = result?.filesChanged ?? result?.files_changed;
+          if (Array.isArray(genericShipFiles)) {
+            context.recordFilesChanged(genericShipFiles, { authoritativeShip: true });
+          }
+          if (_genericTestMetrics !== null) {
+            shipStepTestData = _genericTestMetrics;
+            context.recordShipTestMetrics(_genericTestMetrics);
+          }
         }
 
         // Note: scope-step BuildProfile persistence has been replaced by pre-build triage.
@@ -2861,6 +3415,26 @@ export async function runBuild(featureCode, opts = {}) {
         response = await stratum.stepDone(
           flowId, stepId, stepDoneResult, readyStep?.dispatchToken,
         );
+        {
+          const isEnsureRetry = responseReissuesStep(response, stepId);
+          const failureClass = ownershipFailure
+            ? 'ownership'
+            : vocabularyFailure
+              ? 'vocabulary'
+              : normalizationFailure || (stepDispatch.has_out_contract && result == null)
+                ? 'normalization'
+                : mainResult.settlementFailureClass
+                  ?? (result?.outcome === 'failed' ? 'agent' : null);
+          context.settleDispatches({
+            stepId,
+            dispatchIds: mainResult.dispatchIds,
+            accepted: !isEnsureRetry && !blockingFailure && !normalizationFailure
+              && result?.outcome !== 'failed'
+              && (!stepDispatch.has_out_contract || result != null),
+            failureClass,
+            isEnsureRetry,
+          });
+        }
         syncStepHistory(dataDir, stepHistory);
 
         // COMP-FIX-HARD T6: record accepted hypothesis on diagnose success (bug mode only).
@@ -2934,7 +3508,19 @@ export async function runBuild(featureCode, opts = {}) {
 
         // COMP-FIX-HARD T10: post-retro_check escalation gate (bug mode only).
         if (stepId === 'retro_check' && context.mode === 'bug' && context.bug_code) {
-          await maybeRunEscalation(stratum, context, progress, streamWriter, attemptCounter, dataDir);
+          await maybeRunEscalation(
+            stratum,
+            {
+              ...context,
+              projectCwd: cwd,
+              step_id: stepId,
+              ...(typeof readyStep?.attempt === 'number' ? { attempt: readyStep.attempt } : {}),
+            },
+            progress,
+            streamWriter,
+            attemptCounter,
+            dataDir,
+          );
         }
 
         // Stream: step done — read retries/violations from active-build state
@@ -2947,6 +3533,7 @@ export async function runBuild(featureCode, opts = {}) {
             buildCostTotals.input_tokens += stepUsage.input_tokens ?? 0;
             buildCostTotals.output_tokens += stepUsage.output_tokens ?? 0;
             buildCostTotals.cost_usd += stepUsage.cost_usd ?? 0;
+            context.recordBuildUsage(stepUsage);
             streamWriter.writeUsage(stepId, stepUsage);
           }
 
@@ -3113,6 +3700,7 @@ export async function runBuild(featureCode, opts = {}) {
                     const files = new Set(context.filesChanged ?? []);
                     for (const file of changed.split('\n').filter(Boolean)) files.add(file);
                     context.filesChanged = [...files];
+                    context.recordFilesChanged(context.filesChanged);
                   }
                 } catch { /* best-effort build context projection */ }
               } catch (error) {
@@ -3219,6 +3807,7 @@ export async function runBuild(featureCode, opts = {}) {
             stepHistory.push({ stepId: gateStepId, artifact: null, summary: 'Review gate: clean', outcome: resolved.outcome });
             syncStepHistory(dataDir, stepHistory);
           } else {
+            context.recordReviewIteration();
             // Persist the dirty lens ids so the revised triage re-runs only those.
             // J2: prefer the PRE-normalization dirty lenses (normalization resets
             // lenses_run and stamps a missing finding lens as 'general', which would
@@ -3242,11 +3831,25 @@ export async function runBuild(featureCode, opts = {}) {
               + (reviewResult.summary ? `\nSummary: ${reviewResult.summary}\n` : '')
               + findings.map((f) => `- ${f.file ?? '?'}:${f.line ?? '?'} [${f.lens ?? f.severity ?? ''}] ${f.finding ?? f.summary ?? ''}`).join('\n');
             try {
-              await runAndNormalize(undefined, fixPrompt, { step_id: 'review_fix', agent: fixAgent, flow_id: flowId }, {
+              const gateFixResult = await runAndNormalize(undefined, fixPrompt, { step_id: 'review_fix', agent: fixAgent, flow_id: flowId }, {
                 progress, streamWriter, maxDurationMs: STEP_TIMEOUT_MS.review_merge ?? DEFAULT_TIMEOUT_MS,
                 stratum, cwd: agentCwd, profile: resolveStepProfile(effectiveProfiles, 'fix'),
+                telemetry: {
+                  site: 'review-repair',
+                  project_cwd: cwd,
+                  build_id,
+                  feature_code: featureCode,
+                  step_id: 'review_fix',
+                  ...(typeof gateDispatch.attempt === 'number' ? { attempt: gateDispatch.attempt } : {}),
+                },
               });
+              if (gateFixResult?.usage && typeof context.recordBuildUsage === 'function') {
+                try { context.recordBuildUsage(gateFixResult.usage); } catch { /* fail-open */ }
+              }
             } catch (err) {
+              if (err?.usage && typeof context.recordBuildUsage === 'function') {
+                try { context.recordBuildUsage(err.usage); } catch { /* fail-open */ }
+              }
               if (!(err instanceof AgentTimeoutError)) throw err;
               console.warn('\n⚠ Review fixer timed out');
             }
@@ -3691,6 +4294,13 @@ export async function runBuild(featureCode, opts = {}) {
     }
     throw err;
   } finally {
+    let actualsError = null;
+    try {
+      finalizeBuildAttempt();
+    } catch (error) {
+      actualsError = error;
+      attemptFinalized = true;
+    }
     // Close stream writer with appropriate status (idempotent — signal handler may have already closed)
     if (streamWriter) {
       streamWriter.close(buildStatus, buildCostTotals);
@@ -3701,9 +4311,31 @@ export async function runBuild(featureCode, opts = {}) {
     }
     progress.finish();
     await stratum.close();
-    // COMP-MCP-MIGRATION-1: restore COMPOSE_BUILD_ID env to its prior value
-    // (or unset) so subsequent processes / tests don't inherit a stale UUID.
-    _restoreBuildIdEnv();
+    runtimeResourcesFinalized = true;
+    if (actualsError) throw actualsError;
+  }
+  } finally {
+    try {
+      finalizeBuildAttempt();
+    } finally {
+      try {
+        if (!runtimeResourcesFinalized) {
+          if (streamWriter) streamWriter.close(buildStatus);
+          if (signalHandler) {
+            process.removeListener('SIGINT', signalHandler);
+            process.removeListener('SIGTERM', signalHandler);
+          }
+          progress?.finish();
+          if (stratum) await stratum.close();
+          runtimeResourcesFinalized = true;
+        }
+      } finally {
+        // COMP-MCP-MIGRATION-1: restore COMPOSE_BUILD_ID env to its prior value
+        // (or unset) so subsequent processes / tests don't inherit a stale UUID.
+        _restoreBuildIdEnv();
+        attemptStarted = false;
+      }
+    }
   }
 }
 
@@ -3812,6 +4444,49 @@ export function _extractShipTestMetrics(shipResult) {
   return { test_count: shipResult.test_count, pass_rate: shipResult.pass_rate ?? 0 };
 }
 
+/** The guarded namespace — must equal the verifier's and the hook's (R2). */
+const JUDGMENT_TREE = 'docs/judgment';
+
+/**
+ * Run a git command and return its non-empty output lines.
+ *
+ * Deliberately does NOT swallow failures: this feeds the pre-commit judgment
+ * gate, where an unreadable git state must fail CLOSED. The caller's catch turns
+ * a throw into "verification errored; refusing to commit".
+ */
+function gitLines(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf-8', timeout: 5000 })
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function judgmentCanonDriftError({ treeDrift, projectionDrift, recordDrift }) {
+  const tiers = [
+    ['Tree drift', treeDrift],
+    ['Projection drift', projectionDrift],
+    // R1: records are covered by drift detection, not claimed as enforced.
+    ['Record drift detection', recordDrift],
+  ];
+  const sections = tiers
+    .filter(([, drift]) => drift.length > 0)
+    .map(([label, drift]) => {
+      const paths = drift.map((item) => {
+        if (typeof item === 'string') return `  - ${item}`;
+        return `  - ${item.path} [${item.kind}]`;
+      });
+      return `${label}:\n${paths.join('\n')}`;
+    });
+  const err = new Error(
+    `Judgment canon drift detected; refusing to commit.\n${sections.join('\n')}`,
+  );
+  err.code = 'JUDGMENT_CANON_DRIFT';
+  err.treeDrift = treeDrift;
+  err.projectionDrift = projectionDrift;
+  err.recordDrift = recordDrift;
+  return err;
+}
+
 /**
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
@@ -3906,6 +4581,7 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         // the real feature dir even when opts.cwd differs from process.cwd().
         const _esc = await maybeEscalateLane({ featureCode, provider: _escProvider, featureDir: resolve(cwd, featureDir) });
         if (_esc.action === 'escalate') {
+          context.recordEscalation?.();
           console.warn(`[triage] Test gate failed on lane '${_esc.from}' — escalated to '${_esc.to}'. Re-run to execute the heavier phases.`);
         } else if (_esc.action === 'stop') {
           console.warn(`[triage] Test gate failed and escalation bound reached (lane '${_esc.lane}') — see escalation-checkpoint.md; human review needed.`);
@@ -4032,6 +4708,49 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       } catch { /* file might not exist or already staged */ }
     }
 
+    // COMP-CANON-GUARD S5 T5: this verifier is deliberately build-independent
+    // and runs after staging so pre-staged judgment edits cannot slip through.
+    // This is a hard pre-commit gate: unlike best-effort metadata collection,
+    // unexpected verifier failures are rethrown and block the commit because
+    // silently passing would allow an unverified canon to ship.
+    //
+    // Scope boundary (whole-branch review): the canon verified is the WORKSPACE's
+    // (`cwd`). For a cross-repo build (`agentCwd !== cwd`) the commit lands in
+    // another repo, and that repo's own judgment canon — if it has one — is not
+    // verified here. The staged-divergence check below does run in `agentCwd`,
+    // against the tree actually being committed.
+    try {
+      // The verifier reads the WORKING TREE; `git commit` ships the INDEX. A canon
+      // file staged and then restored in the worktree therefore verifies GREEN while
+      // forged bytes go into the commit — a false GREEN, which is the one failure
+      // mode this whole slice exists to prevent. So before trusting the verdict,
+      // require that every STAGED guarded path matches the bytes about to be
+      // verified. A guarded path modified but NOT staged is not this case: it is not
+      // being committed, and worktree drift is what the verifier already covers.
+      const stagedGuarded = new Set(gitLines(['diff', '--cached', '--name-only', '--', JUDGMENT_TREE], agentCwd));
+      const worktreeGuarded = gitLines(['diff', '--name-only', '--', JUDGMENT_TREE], agentCwd);
+      const divergent = worktreeGuarded.filter((p) => stagedGuarded.has(p));
+      if (divergent.length > 0) {
+        throw judgmentCanonDriftError({
+          treeDrift: divergent.map((path) => ({ path, kind: 'staged-differs-from-worktree' })),
+          projectionDrift: [],
+          recordDrift: [],
+        });
+      }
+
+      const { verifyJudgmentCanon } = await import('./judgment-verify.js');
+      const verification = await verifyJudgmentCanon(cwd);
+      if (!verification.ok) throw judgmentCanonDriftError(verification);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        err?.code === 'JUDGMENT_CANON_DRIFT'
+          ? `[ship] ${err.message}`
+          : `[ship] Judgment canon verification errored; refusing to commit: ${err.message}`,
+      );
+      throw err;
+    }
+
     // 4. Check if there's anything to commit
     const staged = execSync('git diff --cached --name-only', {
       cwd: agentCwd, encoding: 'utf-8', timeout: 5000,
@@ -4085,6 +4804,7 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     } catch { /* metadata best-effort — leave [] */ }
     // If we got nothing from show, fall back to the staged list (still best-effort).
     if (filesChanged.length === 0 && sha) filesChanged = stagedFiles;
+    context.recordFilesChanged?.(filesChanged, { authoritativeShip: true });
 
     // COMP-MCP-MIGRATION: write a commit-bound completion record via the
     // typed writer. The writer flips feature.status to COMPLETE atomically
@@ -4141,6 +4861,7 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       artifact: '',
       outcome: 'failed',
       summary: `Ship failed: ${err.message}`,
+      ...(typeof err?.code === 'string' ? { error_code: err.code } : {}),
     };
   }
 }
@@ -4417,5 +5138,9 @@ export async function abortBuild(dataDir, featureCode, cwd, opts = {}) {
 
   // Write terminal state (file retained per STRAT-COMP-4 contract)
   writeActiveBuild(dataDir, { ...active, status: 'aborted', completedAt: new Date().toISOString() });
+  const accumulator = readBuildAccumulator(cwd, active.featureCode);
+  if (accumulator) {
+    emitBuildActuals(cwd, accumulator, 'aborted');
+  }
   console.log('Build aborted.');
 }