@smartmemory/compose 0.5.0 → 0.5.1

package/lib/build.js

@@ -9,7 +9,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync, symlinkSync } from 'node:fs';
-import { join, resolve, dirname, relative, posix } from 'node:path';
+import { join, resolve, dirname, basename, relative, posix } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync, execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
@@ -27,14 +27,14 @@ import { preflightCodexWorktreeProbe, codexProbeAbortMessage } from './codex-pre
 import { buildStepPrompt, buildGateContext, clearAmbientContextCache } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter, ServerUnreachableError } from './vision-writer.js';
-import { readFlowRound } from './flow-state.js';
+import { readFlowRound, readFlowSnapshot, readFlowSpend } from './flow-state.js';
 import { resolvePort } from './resolve-port.js';
 import { probeServer } from './server-probe.js';
 import { CliProgress } from './cli-progress.js';
 import { BuildStreamWriter } from './build-stream-writer.js';
 import { appendBuildHistory, projectHistorySteps, stepOutcomeToStatus } from './build-history.js';
 import { KNOWN_VERSIONS } from './build-stream-schema.js';
-import { resolveAgentConfig, parseAgentString } from './agent-string.js';
+import { resolveAgentConfig, parseAgentString, validateAgentString } from './agent-string.js';
 import { emitSections as emitPlanSections, appendTrailers as appendSectionTrailers, analyzeRollup, writeRollup } from './sections.js';
 import { SECTIONS_DIR } from './constants.js';
 import { rtkPrefix } from './rtk.js';
@@ -96,6 +96,9 @@ import {
   recoverAdvancedConsumerArtifacts,
   verifyConsumerRunRevision,
 } from './consumer-fanout.js';
+import { preflightPipelineProfiles as preflightProfiles, mergeRuntimeProfiles, validateWaveAdmission, resolveConsumerProfile, profilesDigest, PipelineProfileError } from './pipeline-profiles.js';
+import { decideGateFromOutput } from './output-gate.js';
+import { readCheckpointRef, worktreeBaseFor, squashOntoBase, removeCheckpointRef, WaveCheckpointError } from './wave-checkpoint.js';
 import { appendEvent as appendDispatchEvent, readEvents as readDispatchEvents } from './dispatch-ledger.js';
 import { appendEvent as appendFeatureEvent } from './feature-events.js';
 
@@ -773,6 +776,257 @@ async function reportConsumerStepDone({
   }
 }
 
+export function waveProfilesEnabled(profiles) {
+  return Object.entries(profiles ?? {}).some(([id, entry]) =>
+    id === '_consumer' || id === '_costCeiling' || (!id.startsWith('_') && typeof entry === 'object'));
+}
+
+/** One durable delivery spool for metadata and paid-call receipts. */
+export async function flushWaveReceipts(context, dispatchIds) {
+  const artifacts = context.artifacts;
+  for (const pending of artifacts?.journal.pendingUsageReceipts ?? []) {
+    if (pending.state === 'acknowledged' || dispatchIds && !dispatchIds.includes(pending.dispatchId)) continue;
+    if (context.buildCancel?.cancelled || typeof context.stratum?.usageReport !== 'function') {
+      throw new ConsumerArtifactError('WAVE_EVIDENCE_INCOMPLETE', 'Receipt retained locally; replication unavailable or cancelled');
+    }
+    try {
+      const ack = await context.stratum.usageReport(context.flowId, pending.receipt);
+      if (!['ok', 'accepted', 'duplicate'].includes(ack?.status)) throw new Error('Receipt acknowledgement missing');
+      artifacts.acknowledgeUsageReceipt({ dispatchId: pending.dispatchId, seq: ack.receipt?.seq ?? ack.seq });
+    } catch (error) {
+      await confirmCancellation(error, context);
+      throw new ConsumerArtifactError('WAVE_EVIDENCE_INCOMPLETE', `Receipt ${pending.dispatchId} retained locally: ${error.message}`);
+    }
+  }
+}
+
+export async function reportWaveEvidence(context, kind, token, detail, state) {
+  const dispatchId = `compose:${kind}:${context.flowId}:${token}${state ? `:${state}` : ''}`;
+  const receipt = { dispatchId, source: `compose:${kind}`, usage: {}, detail };
+  context.artifacts.recordPendingUsageReceipt({ dispatchId, receipt });
+  await flushWaveReceipts(context, [dispatchId]);
+  return dispatchId;
+}
+
+/** Validate the recorded full input, before a concurrency-truncated ready list runs. */
+export async function admitConsumerWave({ descriptor, descriptors = [descriptor], audit, localSpec,
+  profiles = {}, artifacts, stratum, flowId }) {
+  const policy = profiles._consumer?.[descriptor.step] ?? {};
+  if (!profiles[descriptor.step]?.tier_from && !profiles._consumer?.[descriptor.step]) return null;
+  audit ??= await stratum.audit(flowId);
+  const steps = localSpec.flows[localSpec.flows.entry]?.steps ?? [];
+  const step = steps.find(s => s.id === descriptor.step);
+  const state = audit?.steps?.[descriptor.step];
+  // Fresh engine fanouts omit the parent epoch but stamp every audit item with 0.
+  // Derive from that recorded item evidence; never admit an unrecorded epoch.
+  const epoch = state?.epoch ?? state?.fanout?.items?.[0]?.epoch;
+  const findings = [];
+  const add = message => findings.push({ code: 'WAVE_INPUT_INVALID', message });
+  let items;
+  let sourceProvenance;
+  try {
+    const reference = step?.fanout?.over;
+    const expression = typeof reference === 'string' && reference.match(/^\$\{([a-z][a-z0-9_-]*)((?:\.[A-Za-z_]\w*|\[\d+\])*)\}$/);
+    if (!expression || ['item', 'prev'].includes(expression[1])) throw new Error('Unsupported recorded fanout reference');
+    const root = expression[1];
+    const path = [...expression[2].matchAll(/\.([A-Za-z_]\w*)|\[(\d+)\]/g)].map(m => m[1] ?? Number(m[2]));
+    const access = (value, segments) => {
+      for (const key of segments) {
+        if (value === null || typeof value !== 'object' || !Object.hasOwn(value, key)
+          || ['__proto__', 'prototype', 'constructor'].includes(key)) return undefined;
+        value = value[key];
+      }
+      return value;
+    };
+    if (root === 'input' && path.length) {
+      const snapshot = readFlowSnapshot(flowId, { revisionDigest: artifacts.journal.revisionDigest });
+      items = access(snapshot.input, path);
+      sourceProvenance = { reference, inputDigest: profilesDigest(snapshot.input) };
+    } else if (path[0] === 'output') {
+      const source = audit.steps?.[root];
+      // Ordinary source steps also omit their initial epoch (the engine uses 0).
+      const sourceEpoch = source?.epoch ?? 0;
+      if (source?.status !== 'succeeded' || sourceEpoch !== epoch) throw new Error('Wave source is not current and succeeded');
+      items = access(source.output, path.slice(1));
+      sourceProvenance = { reference, step: root, epoch: sourceEpoch,
+        acceptedDispatchToken: source.acceptedDispatchToken, outputDigest: profilesDigest(source.output) };
+    } else {
+      // Engine carry expressions are bare names (${wave.tasks}), not ${carry.wave.tasks}.
+      const carry = Object.hasOwn(audit.carry ?? {}, root) ? audit.carry[root] : undefined;
+      items = access(carry?.value, path);
+      sourceProvenance = { reference, carry: carry ?? null };
+    }
+    if (!Array.isArray(items) || !Number.isInteger(epoch) || epoch < 0
+      || !Array.isArray(state?.fanout?.items) || items.length !== state.fanout.items.length) {
+      throw new Error('Recorded wave length/epoch differs from fanout');
+    }
+    for (const [index, item] of state.fanout.items.entries()) {
+      if ((item.epoch ?? state.epoch) !== epoch || item.index !== undefined && item.index !== index) {
+        throw new Error('Recorded fanout item index/epoch differs from wave');
+      }
+    }
+    for (const d of descriptors.filter(d => d.step === descriptor.step)) {
+      const recorded = state.fanout.items[d.itemIndex];
+      if (!recorded || !Number.isInteger(d.itemIndex) || d.itemIndex < 0
+        || !Number.isInteger(d.stage) || d.stage < 0 || d.stage >= step.fanout.steps.length
+        || recorded.generation !== d.generation
+        || d.epoch !== undefined && d.epoch !== epoch
+        || profilesDigest(d.item) !== profilesDigest(items[d.itemIndex])) throw new Error('Descriptor differs from recorded wave item');
+    }
+  } catch (error) { add(error.message); }
+  const profilesByStage = [];
+  if (!findings.length) for (const stage of step.fanout.steps) {
+    const result = validateWaveAdmission(profiles[step.id] ?? stage.agent ?? 'claude', items,
+      { provider: stage.agent?.startsWith('$.input')
+        ? resolveConsumerProfile(profiles[step.id], {}).provider : stage.agent ?? 'claude',
+        ownership: policy.ownership, independent: policy.independent });
+    findings.push(...result.findings);
+    profilesByStage.push(result.profiles.map(p => ({ ...p, profilesDigest: artifacts.journal.profilesDigest })));
+  }
+  if (findings.length) {
+    const failure = `${findings[0].code}: ${findings.map(f => `item ${(f.itemIndex ?? -1) + 1} ${f.message}`).join('; ')}`;
+    await reportWaveEvidence({ artifacts, stratum, flowId }, 'wave_admission',
+      `${descriptor.step}:${epoch ?? 'unknown'}`, { findings, failure, items: items ?? null });
+    return { failure, findings };
+  }
+  if (policy.checkpoint_gate) artifacts.initializeWave({ ref: `refs/heads/compose/wave/${flowId}`,
+    profilesDigest: artifacts.journal.profilesDigest });
+  if (artifacts.journal.wave?.checkpoints.some(c => c.state !== 'published' || !c.evidenceReceiptId)) {
+    throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint publication/evidence pending before admission');
+  }
+  const previous = artifacts.journal.waveAdmissions?.find(a => a.fanoutStepId === step.id && a.epoch === epoch);
+  const baseCommit = previous?.baseCommit ?? (artifacts.journal.wave
+    ? worktreeBaseFor({ journal: artifacts.journal, ref: readCheckpointRef({ cwd: artifacts.targetCwd, ref: artifacts.journal.wave.ref }) })
+    : execFileSync('git', ['rev-parse', 'HEAD'], { cwd: artifacts.targetCwd, encoding: 'utf8' }).trim());
+  artifacts.recordWaveAdmission({ fanoutStepId: step.id, epoch, inputDigest: profilesDigest(items),
+    sourceProvenance, baseCommit, items: items.map((item, itemIndex) => ({ itemIndex,
+      itemDigest: profilesDigest(item), filesOwned: item.files_owned ?? [],
+      profilesByStage: profilesByStage.map(stage => stage[itemIndex]) })) });
+  const bindings = {};
+  for (const d of descriptors.filter(d => d.step === descriptor.step)) {
+    bindings[d.dispatchToken] = artifacts.recordDispatchBinding({ dispatchToken: d.dispatchToken,
+      itemBinding: { item: items[d.itemIndex], itemDigest: profilesDigest(items[d.itemIndex]), epoch, sourceProvenance },
+      resolvedProfile: profilesByStage[d.stage][d.itemIndex] });
+  }
+  return { bindings };
+}
+
+/** recoverCheckpoint owns prepared-fsync -> CAS -> published, using the merge witness. */
+export async function publishConsumerCheckpoint(context, transaction) {
+  const artifacts = context.artifacts;
+  if (!artifacts?.journal.wave || !transaction) return;
+  artifacts.recoverCheckpoint(transaction);
+  await replicateCheckpoints(context);
+}
+
+function capturedWavePaths(artifacts) {
+  return [...new Set((artifacts.journal.wave?.checkpoints ?? []).flatMap(checkpoint =>
+    execFileSync('git', ['diff', '--name-only', '-z', '--no-renames', checkpoint.baselineTree, checkpoint.tree, '--'],
+      { cwd: artifacts.targetCwd, encoding: 'utf8' }).split('\0').filter(Boolean)))];
+}
+
+async function replicateCheckpoints(context) {
+  const artifacts = context.artifacts;
+  for (const checkpoint of artifacts?.journal.wave?.checkpoints ?? []) {
+    if (checkpoint.evidenceReceiptId) continue;
+    const { publishedAt, materializedTree, preparedAt, state, ...identity } = checkpoint;
+    const evidenceReceiptId = await reportWaveEvidence(context, 'checkpoint', checkpoint.gateToken, identity, 'published');
+    artifacts.markCheckpointPublished({ gateToken: checkpoint.gateToken, commit: checkpoint.commit, evidenceReceiptId });
+    context.streamWriter?.write({ type: 'wave_checkpoint', ...identity, flowId: context.flowId });
+  }
+  if (artifacts?.journal.wave) {
+    context.filesChanged = capturedWavePaths(artifacts);
+    context.recordFilesChanged?.(context.filesChanged);
+  }
+}
+
+/** Current audit only; a token's durable human hold survives a ceiling override. */
+export async function evaluateConfiguredGate(context, { localSpec, gateStepId, gateToken, audit, costCeilingUsd }) {
+  const profiles = context.pipelineProfiles ?? {};
+  const config = profiles[gateStepId]?.decide_from ? profiles[gateStepId] : null;
+  const budget = profiles._costCeiling?.gates.includes(gateStepId) ? profiles._costCeiling : null;
+  if (!config && !budget) return null;
+  audit ??= await context.stratum.audit(context.flowId);
+  let decision = null;
+  let ceiling;
+  if (budget) {
+    try {
+      if (!context.receiptsMode) throw new Error('Usage receipt surface unavailable');
+      await flushWaveReceipts(context);
+      const read = readFlowSpend(context.flowId, { revisionDigest: context.artifacts.journal.revisionDigest,
+        gateStepId, gateToken }, context.artifacts.journal.pendingUsageReceipts);
+      const limit = costCeilingUsd ?? read.input?.[budget.input] ?? budget.default;
+      if (!Number.isFinite(limit) || limit <= 0) throw new Error('Ceiling must be finite and positive');
+      ceiling = { spent: read.spent, ceiling: limit };
+      const control = { ceiling: limit, input: budget.input, override: costCeilingUsd ?? null };
+      await reportWaveEvidence(context, 'cost_ceiling', gateToken, control, profilesDigest(control));
+      if (read.spent > limit) decision = { outcome: null, reason: 'WAVE_COST_CEILING_EXCEEDED', ...ceiling };
+    } catch (error) {
+      decision = { outcome: null, reason: 'WAVE_COST_UNVERIFIED', message: error.message };
+    }
+  }
+  const held = context.artifacts.journal.pendingUsageReceipts?.find(p =>
+    p.dispatchId === `compose:gate_hold:${context.flowId}:${gateToken}`);
+  if (held) return { ...held.receipt.detail, outcome: null };
+  if (!decision && config) {
+    const steps = localSpec.flows[localSpec.flows.entry].steps;
+    const execute = steps.find(s => s.id === 'execute' && s.fanout?.dispatch === 'consumer')
+      ?? steps.find(s => profiles._consumer?.[s.id]?.independent)
+      ?? steps.find(s => profiles[s.id]?.tier_from)
+      ?? steps.find(s => profiles._consumer?.[s.id]) ?? steps.find(s => s.fanout?.dispatch === 'consumer');
+    const executeProfile = profiles[execute?.id] ?? execute?.fanout?.steps?.[0]?.agent ?? 'claude';
+    const executeProvider = resolveConsumerProfile(executeProfile, {}).provider;
+    // The engine omits `epoch` on a step that has never been revised (initial epoch
+    // = 0, the same convention admission applies at the wave seam); the gate's
+    // staleness fence compares integers, so materialise the convention here rather
+    // than reading a fresh run as stale (GATE_SOURCE_STALE on every first pass).
+    const states = Object.fromEntries(Object.entries(audit.steps ?? {}).map(([id, state]) =>
+      [id, state && typeof state === 'object' ? { ...state, epoch: state.epoch ?? 0 } : state]));
+    decision = decideGateFromOutput(config, states, { gateStepId, gateToken, ceiling, executeProfile, executeProvider });
+  }
+  if (!decision) return null;
+  if (!decision.outcome) {
+    // Queue first even if the cost-delivery barrier itself is unavailable.
+    try { await reportWaveEvidence(context, 'gate_hold', gateToken, decision); }
+    catch (error) { if (context.buildCancel?.cancelled) throw error; }
+  } else {
+    await reportWaveEvidence(context, 'gate_decision', gateToken, decision, 'proposed');
+    const fresh = await context.stratum.audit(context.flowId);
+    if (fresh.steps?.[gateStepId]?.gateToken !== gateToken
+      || [config.decide_from.step, ...(config.validators ?? []).map(v => v.review_step)].some(id =>
+        profilesDigest(fresh.steps?.[id] ?? null) !== profilesDigest(audit.steps?.[id] ?? null))) {
+      return { outcome: null, reason: 'GATE_SOURCE_STALE' };
+    }
+  }
+  return decision;
+}
+
+export function prepareWaveShip(context) {
+  const artifacts = context?.artifacts;
+  const wave = artifacts?.journal.wave;
+  if (!wave?.checkpoints.length) return;
+  const checkpoint = wave.checkpoints.at(-1);
+  if (checkpoint.state !== 'published' || !checkpoint.evidenceReceiptId) {
+    throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Ship requires acknowledged checkpoint evidence');
+  }
+  const head = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: artifacts.targetCwd, encoding: 'utf8' }).trim();
+  if (head !== wave.baseCommit) {
+    const shipped = artifacts.journal.pendingUsageReceipts?.find(p =>
+      p.receipt.source === 'compose:wave_ship' && p.receipt.detail.commit === head);
+    const parent = execFileSync('git', ['rev-parse', `${head}^`], { cwd: artifacts.targetCwd, encoding: 'utf8' }).trim();
+    if (!shipped || parent !== wave.baseCommit || shipped.receipt.detail.checkpointTree !== checkpoint.tree) {
+      throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'HEAD differs from base and recorded ship');
+    }
+    context.filesChanged = shipped.receipt.detail.filesChanged;
+    return { replay: shipped };
+  }
+  const tree = squashOntoBase({ cwd: artifacts.targetCwd, ref: wave.ref, base: wave.baseCommit });
+  if (tree !== checkpoint.tree) throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Ship tree differs from checkpoint');
+  context.filesChanged = [...new Set([...(context.filesChanged ?? []), ...capturedWavePaths(artifacts)])];
+  context.recordFilesChanged?.(context.filesChanged);
+  return tree;
+}
+
 export async function runConsumerIssuance({
   descriptor,
   flowId,
@@ -797,7 +1051,30 @@ export async function runConsumerIssuance({
   // sidecar), applied at invocation so e.g. an isolation:none review fanout runs
   // read-only. Absent → the descriptor's bare provider literal (no restrictions).
   profile = null,
+  admission = null,
 }) {
+  if (profile && typeof profile !== 'string') throw new Error('Consumer profile must be a resolved string; pass pipelineProfiles for item admission');
+  const configured = context.pipelineProfiles?.[descriptor.step]?.tier_from
+    || context.pipelineProfiles?._consumer?.[descriptor.step];
+  if (configured && !admission) admission = await admitConsumerWave({
+    descriptor, descriptors: [descriptor], audit: await stratum.audit(flowId),
+    localSpec, profiles: context.pipelineProfiles, artifacts, stratum, flowId,
+  });
+  const bound = admission?.bindings?.[descriptor.dispatchToken];
+  if (bound) profile = bound.resolvedProfile.profile;
+  const evidenceContext = { ...context, stratum, flowId, artifacts, buildCancel };
+  if (admission?.failure) {
+    const envelope = { failure: admission.failure };
+    const entry = artifacts.prepareArtifactFailure(descriptor, envelope,
+      new ConsumerArtifactError(admission.findings[0]?.code ?? 'WAVE_INPUT_INVALID', admission.failure));
+    await reportWaveEvidence(evidenceContext, 'wave_rejected', descriptor.dispatchToken,
+      { findings: admission.findings });
+    const report = await reportConsumerStepDone({ descriptor, flowId, envelope: entry.envelope,
+      stratum, artifacts, progress, streamWriter, buildCancel });
+    if (!report.skipped) artifacts.reconcileAudit(await stratum.audit(flowId),
+      { fanoutStepId: descriptor.step, itemIndex: descriptor.itemIndex });
+    return report.response;
+  }
   let recovery;
   try {
     recovery = artifacts.reconcileDescriptor(descriptor, audit);
@@ -829,6 +1106,8 @@ export async function runConsumerIssuance({
     throw new Error(`accepted consumer issuance ${descriptor.id} unexpectedly remained ready`);
   }
   if (recovery.action === 'report') {
+    const entry = artifacts.journal.issuances.find(e => e.dispatchToken === descriptor.dispatchToken);
+    if (entry?.findings?.length) await reportWaveEvidence(evidenceContext, 'ownership', descriptor.dispatchToken, { findings: entry.findings });
     const report = await reportConsumerStepDone({
       descriptor,
       flowId,
@@ -899,8 +1178,7 @@ export async function runConsumerIssuance({
   // D3: stable per-item key for the stuck detector's per-task bookkeeping. In
   // GSD mode this becomes the operator-facing stuck task id (stuck.json/pause.json/
   // stuck.md), so it MUST be the decompose task id (T01), matching the blackboard
-  // + milestone report. The engine's GSD consumer descriptor carries no `.item`,
-  // so the real runGsd call site threads the resolved id via context.gsdTaskId
+  // + milestone report. GSD threads descriptor.item.id via context.gsdTaskId
   // (same precedence as gsdTaskId below); build-mode fanout passes no gsdTaskId and
   // keeps the item-id/index key unchanged (byte-identical).
   const stuckTaskId = context?.gsdTaskId ?? descriptor.item?.id ?? `${descriptor.step ?? descriptor.id}:${descriptor.itemIndex}`;
@@ -961,6 +1239,12 @@ export async function runConsumerIssuance({
     lane,
   });
 
+  if (bound) {
+    streamWriter.write({ type: 'step_model', stepId: descriptor.id, flowId,
+      itemIndex: descriptor.itemIndex, ...bound.resolvedProfile });
+    await reportWaveEvidence(evidenceContext, 'item_model', descriptor.dispatchToken,
+      { intended: bound.resolvedProfile, itemBinding: bound.itemBinding }, 'proposed');
+  }
   let mainResult;
   try {
     mainResult = await runAndNormalize(null, prompt, dispatch, {
@@ -1062,6 +1346,9 @@ export async function runConsumerIssuance({
   const { result, normalizationFailure } = mainResult;
   // D2(b): forward the item's agent usage so GSD can debit the cumulative
   // budget ledger. Build mode passes no onUsage sink → byte-identical no-op.
+  if (context.pipelineProfiles?._costCeiling && !mainResult?.usage) {
+    await context.onUsage?.({ dispatch_id: mainResult.dispatchIds?.primary ?? descriptor.dispatchToken }, { stepId: descriptor.step, source: 'fanout' });
+  }
   if (typeof context?.onUsage === 'function' && mainResult?.usage) {
     await context.onUsage(usagePayload(mainResult.usage, mainResult.usages), {
       dispatchId: mainResult.dispatchIds?.primary,
@@ -1084,7 +1371,7 @@ export async function runConsumerIssuance({
     );
     if (gateFailure) localFailure = `pre_merge failed: ${JSON.stringify(gateFailure)}`;
   }
-  const envelope = localFailure
+  let envelope = localFailure
     ? { failure: String(localFailure) }
     : contract.hasOutContract
       ? result != null
@@ -1108,8 +1395,18 @@ export async function runConsumerIssuance({
     });
   }
   const preparedEntry = artifacts.prepareIssuance(descriptor, envelope, {
-    finalStage,
+    finalStage, ...(bound ?? {}),
+    ownership: context.pipelineProfiles?._consumer?.[descriptor.step]?.ownership,
   });
+  // Legacy injected artifact adapters predate returned envelopes. Configured
+  // admission/ownership requires the authoritative primitive result.
+  if (configured || bound || preparedEntry?.envelope) envelope = preparedEntry.envelope;
+  localFailure = envelope.failure ?? localFailure;
+  if (preparedEntry?.findings?.length) await reportWaveEvidence(evidenceContext, 'ownership',
+    descriptor.dispatchToken, { findings: preparedEntry.findings });
+  if (bound) await reportWaveEvidence(evidenceContext, 'item_model', descriptor.dispatchToken,
+    { intended: bound.resolvedProfile, observed: { normalizedUsageModel: mainResult.usage?.model ?? null,
+      connectorIdentityVerified: false } }, 'observed');
   // H3: record this item's timing + (final-stage) diff snapshot for the GSD
   // milestone report. `preparedEntry.diff` is the cumulative worktree diff the
   // artifacts journal already computed at final stage (null otherwise) — tapped
@@ -1156,7 +1453,7 @@ export async function runConsumerIssuance({
     stepId: descriptor.id,
     summary: result?.summary ?? `consumer item ${descriptor.itemIndex} stage ${descriptor.stage} reported`,
     retries: Math.max(0, (descriptor.attempt ?? 1) - 1),
-    violations: [],
+    violations: preparedEntry?.findings ?? [],
     flowId,
     consumer: true,
     // H6: matches the item's start stepId so the UI decrements the same task
@@ -1165,7 +1462,7 @@ export async function runConsumerIssuance({
     // COMP-AGENT-LANES (C4): terminal status is explicit at source — the UI
     // must not infer "complete" from the done event's existence.
     status: localFailure ? 'failed' : 'succeeded',
-    outcome: result?.outcome ?? (localFailure ? 'failed' : 'succeeded'),
+    outcome: localFailure ? 'failed' : (result?.outcome ?? 'succeeded'),
     itemIndex: descriptor.itemIndex,
     stage: descriptor.stage,
     generation: descriptor.generation,
@@ -1213,26 +1510,158 @@ function extractFilesChanged(response) {
  * @param {Array<{id?:string, files_owned?:string[]}>} tasks
  * @returns {string|null}
  */
+/**
+ * A local copy of a bundled preset whose sidecar carries EXECUTION configuration
+ * (object-form agent entries with tier_from, gate decide_from/validators,
+ * `_consumer`, `_costCeiling`) must keep that sidecar: without it the output-driven
+ * gate, per-item routing, ownership and the ceiling silently vanish and a blocking
+ * repair decision ships (slice 4 review r1 #1). A string-only sidecar carries tool
+ * restrictions and tiers, for which "missing → bare defaults" stays the documented
+ * behaviour — and a custom spec that merely shares a bundled basename (every build
+ * test fixture writes its own pipelines/build.stratum.yaml) is not a copy.
+ */
+export function sidecarCarriesExecutionConfig(profiles) {
+  if (!profiles || typeof profiles !== 'object') return false;
+  return Object.entries(profiles).some(([key, value]) =>
+    key === '_consumer' || key === '_costCeiling'
+    || (!key.startsWith('_') && value !== null && typeof value === 'object'));
+}
+
+export function requirePipelineSidecar(specPath) {
+  const localPath = resolve(specPath);
+  const name = basename(localPath).replace(/\.stratum\.ya?ml$/, '');
+  if (name === basename(localPath)) return;
+  const sidecarName = `${name}.profiles.json`;
+  if (existsSync(join(dirname(localPath), sidecarName))) return;
+
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const bundledSpecs = ['presets', 'pipelines'].flatMap(directory =>
+    ['yaml', 'yml'].map(ext => join(packageRoot, directory, `${name}.stratum.${ext}`)));
+  if (bundledSpecs.includes(localPath)) return;
+  for (const path of bundledSpecs) {
+    const bundledSidecar = join(dirname(path), sidecarName);
+    if (!existsSync(path) || !existsSync(bundledSidecar)) continue;
+    let bundledProfiles;
+    try { bundledProfiles = JSON.parse(readFileSync(bundledSidecar, 'utf-8')); } catch { continue; }
+    if (sidecarCarriesExecutionConfig(bundledProfiles)) {
+      throw Object.assign(new Error(
+        `PROFILE_SIDECAR_REQUIRED: ${specPath} has no adjacent ${sidecarName} but the bundled ${name} ships one that configures gates/routing/ownership — copy both files (see docs/team-presets.md)`,
+      ), { code: 'PROFILE_SIDECAR_REQUIRED' });
+    }
+  }
+}
+
 /**
  * D6: load the compose-owned profile sidecar next to a pipeline spec. The engine
  * accepts only the literal claude|codex agent, so the full profile strings that
  * carry tool restrictions + model tiers (claude:read-only-reviewer,
  * claude::critical, claude:orchestrator, ...) live in <spec>.profiles.json keyed
  * by step id and are applied compose-side at invocation. Absent → {} (bare
- * literals; no restrictions).
+ * literals; no restrictions), after runBuild enforces required bundled sidecars.
+ * Malformed or non-object sidecars fail closed.
  *
  * @param {string} specPath  path to the .stratum.yaml spec
  * @returns {Record<string,string>} step id → agent profile string
  */
 export function loadPipelineProfiles(specPath) {
+  const sidecar = String(specPath).replace(/\.stratum\.ya?ml$/, '.profiles.json');
+  if (sidecar === String(specPath)) return {};
   try {
-    const sidecar = String(specPath).replace(/\.stratum\.ya?ml$/, '.profiles.json');
-    if (sidecar === String(specPath) || !existsSync(sidecar)) return {};
     const parsed = JSON.parse(readFileSync(sidecar, 'utf-8'));
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('expected an object mapping step ids to profiles');
+    }
+    return parsed;
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw new Error(`Profile sidecar ${sidecar} is invalid: ${error.message}`);
+  }
+}
+
+/**
+ * Pure profile validation across all flows and fanout stages. Runtime references
+ * use the supplied role inputs (build defaults for the initial static check).
+ * No tier with modelID null means the documented connector default and is legal;
+ * an explicit tier with modelID null is unavailable and must fail closed.
+ * Metadata keys starting with '_' are ignored; stale step keys are errors.
+ */
+export function preflightPipelineProfiles(stepProfiles, specYaml, specName = '<spec>', inputs = {
+  implementer_agent: 'claude', reviewer_agent: 'codex',
+}) {
+  const rawProfiles = stepProfiles;
+  if (Array.isArray(rawProfiles._costCeiling?.gates) && rawProfiles._costCeiling.gates.includes('review_gate')) {
+    throw new PipelineProfileError('WAVE_COST_CEILING_RESERVED_GATE',
+      `Profile preflight failed for ${specName}: _costCeiling.gates cannot target reserved review_gate`);
+  }
+  stepProfiles = Object.fromEntries(Object.entries(stepProfiles).filter(([, entry]) => !entry?.decide_from).map(([id, entry]) => [id, entry?.default ?? entry]));
+  const rawSpec = typeof specYaml === 'string' ? YAML.parse(specYaml) : structuredClone(specYaml);
+  const spec = resolvePlanSpecValues(structuredClone(rawSpec), inputs);
+  const rawSteps = Object.values(rawSpec?.flows ?? {}).flatMap(flow => flow?.steps ?? []);
+  const rawById = new Map(rawSteps.map(step => [step.id, step]));
+  const steps = Object.values(spec?.flows ?? {}).flatMap(flow => flow?.steps ?? []);
+  const stepIds = new Set(steps.map(step => step.id));
+  const failures = [];
+  const resolved = {};
+  const check = (id, profile, { engineDispatch = false } = {}) => {
+    try {
+      if (typeof profile !== 'string' || !profile.trim()) {
+        throw new Error('profile must be a non-empty agent string');
+      }
+      validateAgentString(profile);
+      const { provider, template, tier, modelID } = resolveAgentConfig(profile);
+      if (tier && modelID === null) throw new Error(`tier "${tier}" has no model for provider "${provider}"`);
+      // Review r1 #3: an engine-dispatched fanout invokes its connector inside
+      // Stratum, so compose-side tiers/templates never reach the call — certifying
+      // a model here that the engine will not use is worse than not checking.
+      if (engineDispatch && (tier || template)) {
+        throw new Error(`profile "${profile}" carries a tier/template but the fanout is dispatch: engine, where compose profiles are not applied`);
+      }
+      resolved[id] = { profile, provider, tier, modelID };
+    } catch (error) {
+      failures.push(`step "${id}": ${error.message}`);
+    }
+  };
+  for (const id of Object.keys(stepProfiles)) {
+    if (!id.startsWith('_') && !stepIds.has(id)) failures.push(`step "${id}": not found in spec`);
+  }
+  for (const step of steps) {
+    const hasProfile = !step.id.startsWith('_') && Object.hasOwn(stepProfiles, step.id);
+    const stages = step.fanout?.steps ?? [];
+    const engineDispatch = step.fanout?.dispatch === 'engine';
+    if (Object.hasOwn(step, 'agent') || (hasProfile && stages.length === 0)) {
+      check(step.id, hasProfile ? stepProfiles[step.id] : step.agent);
+    }
+    // Review r1 #1: profiles (sidecar and runtime) are keyed by the FANOUT id and
+    // applied to every stage at invocation (resolvePlanSpecValues records the
+    // last stage's runtime profile under step.id). A multi-stage fanout whose raw
+    // stage agents differ therefore cannot be routed honestly — fail closed.
+    if (stages.length > 1) {
+      const rawStages = rawById.get(step.id)?.fanout?.steps ?? [];
+      const rawAgents = new Set(rawStages.map(stage => JSON.stringify(stage?.agent ?? null)));
+      const runtimeRef = rawStages.some(stage => typeof stage?.agent === 'string' && stage.agent.startsWith('$.input'));
+      // Bare literals with no profile run as written — nothing collapses.
+      if (rawAgents.size > 1 && (hasProfile || runtimeRef)) {
+        failures.push(`step "${step.id}": multi-stage fanout stages declare different agents (${[...rawAgents].join(', ')}); profiles are keyed by the fanout id and apply to every stage`);
+        continue;
+      }
+    }
+    for (const [index, stage] of stages.entries()) {
+      // Review r1 #2: a stage with no explicit agent inherits claude but still
+      // consumes the enclosing sidecar profile at invocation — check it too.
+      if (!Object.hasOwn(stage, 'agent') && !hasProfile) continue;
+      // Single-stage fanouts use the enclosing id, as invocation profile lookup does.
+      const id = stages.length === 1 ? step.id : `${step.id}/${index}`;
+      check(id, hasProfile ? stepProfiles[step.id] : stage.agent, { engineDispatch });
+    }
   }
+  if (failures.length) throw new Error(`Profile preflight failed for ${specName}: ${failures.join('; ')}`);
+  let checked;
+  try { checked = preflightProfiles(rawProfiles, spec); }
+  catch (error) { throw new Error(`Profile preflight failed for ${specName}: ${error.message}`, { cause: error }); }
+  // Keep the public legacy projection; runner-only pins are additive.
+  return Object.defineProperties({ ok: true, resolved }, {
+    normalized: { value: checked.normalized }, profilesDigest: { value: checked.profilesDigest },
+  });
 }
 
 /**
@@ -1285,7 +1714,8 @@ function usagePayload(usage, usages) {
 
 /** Send one surface-15 receipt per underlying model dispatch. */
 export async function reportUsageReceipts(context, usage, meta = {}) {
-  if (context?.buildCancel?.cancelled || !context?.receiptsMode || !context.flowId || typeof context.stratum?.usageReport !== 'function') {
+  if ((!context?.pipelineProfiles?._costCeiling && context?.buildCancel?.cancelled)
+    || !context?.receiptsMode || !context.flowId || typeof context.stratum?.usageReport !== 'function') {
     return [];
   }
   const entries = Array.isArray(usage)
@@ -1293,10 +1723,10 @@ export async function reportUsageReceipts(context, usage, meta = {}) {
     : (Array.isArray(usage?.usages) ? usage.usages : (usage ? [usage] : []));
   const responses = [];
   for (const entry of entries) {
-    if (context.buildCancel?.cancelled) break;
+    if (context.buildCancel?.cancelled && !context.pipelineProfiles?._costCeiling) break;
     if (!entry || typeof entry !== 'object') continue;
-    const engineUsage = toEngineUsage(entry);
-    if (!engineUsage) continue;
+    const engineUsage = toEngineUsage(entry) ?? (context.pipelineProfiles?._costCeiling ? {} : null);
+    if (!engineUsage && !context.pipelineProfiles?._costCeiling) continue;
     // Surface 15 requires explicit USD provenance. Normalized UsageRecords carry
     // `usd_source`; raw engine usage ({tokens, usd, ms}) does not. Preserve raw
     // token/time usage, but fail closed on an unlabelled dollar value instead of
@@ -1305,7 +1735,7 @@ export async function reportUsageReceipts(context, usage, meta = {}) {
       ? entry.usd_source
       : null;
     if (Object.hasOwn(engineUsage, 'usd') && !usdSource) delete engineUsage.usd;
-    if (Object.keys(engineUsage).length === 0) continue;
+    if (Object.keys(engineUsage).length === 0 && !context.pipelineProfiles?._costCeiling) continue;
     const input = entry.input_tokens;
     const output = entry.output_tokens;
     const receipt = {
@@ -1331,9 +1761,14 @@ export async function reportUsageReceipts(context, usage, meta = {}) {
           } }
         : {}),
       ...(Object.hasOwn(engineUsage, 'usd') ? { usdSource } : {}),
+      ...(context.pipelineProfiles?._costCeiling && (!usdSource || !Number.isFinite(entry.cost_usd ?? entry.usd))
+        ? { detail: { costUnknown: true } } : {}),
     };
     try {
-      responses.push(await context.stratum.usageReport(context.flowId, receipt));
+      if (context.pipelineProfiles?._costCeiling) {
+        context.artifacts.recordPendingUsageReceipt({ dispatchId: receipt.dispatchId, receipt });
+        await flushWaveReceipts(context, [receipt.dispatchId]);
+      } else responses.push(await context.stratum.usageReport(context.flowId, receipt));
     } catch (error) {
       if (await confirmCancellation(error, context)) break;
       console.warn(`[usage-receipt] failed for ${receipt.dispatchId}: ${error?.message ?? error}`);
@@ -2395,6 +2830,7 @@ export async function runBuild(featureCode, opts = {}) {
   let streamWriter = null;
   let signalHandler = null;
   let runtimeResourcesFinalized = false;
+  let suspended = false;
 
   const _priorBuildIdEnv = process.env.COMPOSE_BUILD_ID;
   if (_priorBuildIdEnv !== undefined) {
@@ -2410,7 +2846,7 @@ export async function runBuild(featureCode, opts = {}) {
     else process.env.COMPOSE_BUILD_ID = _priorBuildIdEnv;
   };
   const finalizeBuildAttempt = () => {
-    if (!attemptStarted || attemptFinalized) return;
+    if (!attemptStarted || attemptFinalized || (suspended && !buildCancel.cancelled)) return;
     if (buildCancel.teardown || buildCancel.cancelled) buildStatus = 'aborted';
     const terminalStatus = buildStatus === 'complete'
       ? 'complete'
@@ -2588,11 +3024,16 @@ export async function runBuild(featureCode, opts = {}) {
   if (!existsSync(specPath)) {
     throw new Error(`Lifecycle spec not found: ${specPath}`);
   }
+  requirePipelineSidecar(specPath);
   // D6: compose-owned per-step agent profiles (tool restrictions + model tiers)
   // for this pipeline. The engine ships only bare claude|codex; these restore
-  // the stripped profiles at invocation. Absent sidecar → {} (bare literals).
+  // the stripped profiles at invocation. Optional absent sidecar → {} (bare literals).
   const stepProfiles = loadPipelineProfiles(specPath);
   let specYaml = readFileSync(specPath, 'utf-8');
+  preflightPipelineProfiles(stepProfiles, specYaml, specPath);
+  if (opts.costCeilingUsd !== undefined && (!Number.isFinite(opts.costCeilingUsd) || opts.costCeilingUsd <= 0 || !stepProfiles._costCeiling)) {
+    throw new Error('costCeilingUsd requires a finite positive value and a configured _costCeiling');
+  }
 
   // COMP-PIPELINE-QUARANTINE: refuse a retired-dialect spec HERE, at the one
   // seam every template passes through (build, fix, plan, --quick, --template,
@@ -2863,6 +3304,28 @@ export async function runBuild(featureCode, opts = {}) {
       }
     }
     const roles = { implementerAgent, reviewerAgent };
+    // Resolve and validate runtime overrides BEFORE startFresh can create a flow.
+    // Recompute on resume when persisted roles replace this invocation's flags.
+    let pipelineProfiles;
+    let effectiveProfiles;
+    let profilePreflight;
+    const refreshProfilePreflight = () => {
+      const runtimeProfiles = {};
+      const inputs = { implementer_agent: implementerAgent, reviewer_agent: reviewerAgent };
+      resolvePlanSpecValues(structuredClone(localSpec), inputs, runtimeProfiles);
+      pipelineProfiles = stepProfiles;
+      for (const [id, override] of Object.entries(runtimeProfiles)) {
+        try { pipelineProfiles = mergeRuntimeProfiles(pipelineProfiles, { [id]: override }); }
+        catch (error) { throw new Error(`Profile preflight failed for ${specPath}: step "${id}": ${error.message}`, { cause: error }); }
+      }
+      // Pass the RAW local spec: the preflight resolves inputs itself and needs the
+      // unresolved stage agents to detect a multi-stage runtime-profile collapse.
+      profilePreflight = preflightPipelineProfiles(pipelineProfiles, localSpec, specPath, inputs);
+      effectiveProfiles = Object.fromEntries(Object.entries(pipelineProfiles)
+        .filter(([id, entry]) => !id.startsWith('_') && !entry?.decide_from)
+        .map(([id, entry]) => [id, entry?.default ?? entry]));
+    };
+    refreshProfilePreflight();
     // Restore persisted roles when (and only when) a resume actually happens.
     const restoreRolesFromActive = (src) => {
       if (mode !== 'feature' || !src || !src.implementerAgent) return;
@@ -2874,6 +3337,7 @@ export async function runBuild(featureCode, opts = {}) {
       }
       implementerAgent = src.implementerAgent;
       reviewerAgent = src.reviewerAgent ?? reviewerAgent;
+      refreshProfilePreflight();
     };
 
     const activeForDecision = active && active.featureCode === featureCode ? active : null;
@@ -2893,6 +3357,21 @@ export async function runBuild(featureCode, opts = {}) {
     if (probeFlowId && !opts.fresh && (opts.resumeFlowId || !flowTerminal)) {
       try {
         const audit = await stratum.audit(probeFlowId);
+        if (isTerminalFlow(audit?.status)) {
+          const terminalJournal = verifyConsumerRunRevision({ runId: probeFlowId, targetCwd: agentCwd,
+            artifactRoot: opts.consumerArtifactsRoot, specDigest: localSpecDigest,
+            profilesDigest: waveProfilesEnabled(pipelineProfiles) ? profilePreflight.profilesDigest : undefined });
+          recoverAdvancedConsumerArtifacts({ runId: probeFlowId, targetCwd: agentCwd,
+            artifactRoot: opts.consumerArtifactsRoot, audit });
+          if (terminalJournal?.wave) {
+            const artifacts = new ConsumerFanoutArtifacts({ runId: probeFlowId, targetCwd: agentCwd, artifactRoot: opts.consumerArtifactsRoot });
+            try { await replicateCheckpoints({ artifacts, stratum, flowId: probeFlowId, buildCancel }); }
+            catch (error) {
+              if (audit.status !== 'cancelled') throw error;
+              console.warn(`[wave-checkpoint] ${error.message}; local checkpoint preserved, replication incomplete`);
+            }
+          }
+        }
         if (audit?.status === 'cancelled') {
           // C42/C49: a resume probe is not necessarily the owning driver.
           const handle = lookupBuildCancel(probeFlowId);
@@ -2911,14 +3390,7 @@ export async function runBuild(featureCode, opts = {}) {
           });
         }
         flowTerminal = isTerminalFlow(audit?.status);
-        if (flowTerminal) {
-          recoverAdvancedConsumerArtifacts({
-            runId: probeFlowId,
-            targetCwd: agentCwd,
-            artifactRoot: opts.consumerArtifactsRoot,
-            audit,
-          });
-        }
+
       } catch (err) {
         if (isRecoverableFlowProbeError(err)) {
           // An unknown flow is only evidence the build is over when its driver is
@@ -2939,8 +3411,18 @@ export async function runBuild(featureCode, opts = {}) {
       sameMode,
     });
     isFreshStart = verdict.action === 'fresh';
+    if (isFreshStart && opts.fresh && activeForDecision?.flowId) {
+      if (pidAlive) throw new Error('Cannot remove a wave ref owned by a live driver');
+      const prior = new ConsumerFanoutArtifacts({ runId: activeForDecision.flowId,
+        targetCwd: agentCwd, artifactRoot: opts.consumerArtifactsRoot }).journal;
+      if (prior?.wave) {
+        const expected = prior.wave.checkpoints.at(-1)?.commit;
+        if (expected) removeCheckpointRef({ cwd: agentCwd, ref: prior.wave.ref, expected });
+      }
+    }
 
     if (verdict.action === 'resume') {
+      restoreRolesFromActive(activeForDecision);
       const resumeFlowId = verdict.flowId;
       console.log(`Resuming flow ${resumeFlowId} for ${featureCode}...`);
       response = await stratum.resume(resumeFlowId);
@@ -2954,6 +3436,7 @@ export async function runBuild(featureCode, opts = {}) {
         artifactRoot: opts.consumerArtifactsRoot,
         specDigest: localSpecDigest,
         resumeRevisionDigest: response?.revisionDigest,
+        profilesDigest: waveProfilesEnabled(pipelineProfiles) ? profilePreflight.profilesDigest : undefined,
       });
       try {
         recoverAdvancedConsumerArtifacts({
@@ -2963,7 +3446,7 @@ export async function runBuild(featureCode, opts = {}) {
           audit: await stratum.audit(resumeFlowId),
         });
       } catch (error) {
-        if (error instanceof ConsumerArtifactError) throw error;
+        if (error instanceof ConsumerArtifactError || error instanceof WaveCheckpointError) throw error;
         // Audit/cleanup projection is best-effort for ordinary non-consumer runs.
       }
       // A BARE programmatic resumeFlowId (no --resume flag) resumes the named
@@ -3169,19 +3652,7 @@ export async function runBuild(featureCode, opts = {}) {
       specPath: `pipelines/${templateName}.stratum.yaml`,
     });
 
-    // V4: merge the runtime profile map over the static sidecar (runtime wins).
-    // Tiers/templates carried by $.input.* agents (e.g. --implementer=claude::critical)
-    // are stripped to the bare provider at resolution for the engine; recover the
-    // full string here so the tier/capability profile still binds at invocation.
-    const runtimeProfiles = {};
-    try {
-      resolvePlanSpecValues(
-        YAML.parse(readFileSync(specPath, 'utf-8')),
-        { implementer_agent: implementerAgent, reviewer_agent: reviewerAgent },
-        runtimeProfiles,
-      );
-    } catch { /* best-effort — a malformed spec fails later at plan() */ }
-    const effectiveProfiles = { ...stepProfiles, ...runtimeProfiles };
+    streamWriter.write({ type: 'profile_preflight', steps: profilePreflight.resolved });
     // H1: reducer steps — ReviewResult-out steps that MERGE/deduplicate rather
     // than review (e.g. review_merge). They still get review normalization +
     // confidence handling, but must NOT get the reviewer scaffold. python's
@@ -3221,6 +3692,7 @@ export async function runBuild(featureCode, opts = {}) {
       // V4: merged runtime + static agent profiles let scoped consumer steps
       // recover their tier/capability profile via resolveStepProfile normalization.
       stepProfiles: effectiveProfiles,
+      pipelineProfiles,
       // COMP-BUILD-QUICK-1: the pipeline template (e.g. 'build-quick') so the ship
       // step can stamp built_via onto feature.json for the validator's exemption.
       templateName,
@@ -3339,12 +3811,23 @@ export async function runBuild(featureCode, opts = {}) {
           // unpinned journal a drifted spec could re-pin (R1).
           revisionDigest: pins?.revisionDigest,
           specDigest: pins?.specDigest,
+          profilesDigest: waveProfilesEnabled(pipelineProfiles) ? profilePreflight.profilesDigest : undefined,
         });
       } else if (consumerArtifacts.runId !== runId) {
         throw new Error(`consumer artifact manager is bound to ${consumerArtifacts.runId}, not ${runId}`);
       }
+      context.artifacts = consumerArtifacts;
       return consumerArtifacts;
     };
+    if (waveProfilesEnabled(pipelineProfiles)) {
+      artifactsForRun(context.flowId, { revisionDigest: response.revisionDigest, specDigest: localSpecDigest });
+      context.streamWriter = streamWriter;
+      // A ceiling gate turns delivery failures into a durable human hold below.
+      try { await flushWaveReceipts(context); } catch (error) {
+        if (!pipelineProfiles._costCeiling || buildCancel.cancelled) throw error;
+      }
+      await replicateCheckpoints(context);
+    }
 
 
     // COMP-PLAN-GATE-LOOP: per-step gate re-entry counter. A `revise` that
@@ -3385,7 +3868,7 @@ export async function runBuild(featureCode, opts = {}) {
       }
     };
 
-    const runConsumerDescriptor = async (descriptor, sourceResponse) => {
+    const runConsumerDescriptor = async (descriptor, sourceResponse, admission) => {
       const flowId = sourceResponse.runId ?? sourceResponse.flow_id;
       const artifacts = artifactsForRun(flowId);
       const audit = await stratum.audit(flowId);
@@ -3396,6 +3879,7 @@ export async function runBuild(featureCode, opts = {}) {
       });
       return runConsumerIssuance({
         descriptor,
+        admission,
         flowId,
         buildCancel,
         stratum,
@@ -3409,8 +3893,8 @@ export async function runBuild(featureCode, opts = {}) {
         // claude:read-only-reviewer, or a runtime --implementer=claude::critical)
         // so an isolation:none review item runs read-only instead of with
         // Edit/Write/Bash in the target workspace.
-        profile: resolveStepProfile(effectiveProfiles, descriptor.step)
-          ?? resolveStepProfile(effectiveProfiles, descriptor.id),
+        profile: resolveStepProfile(context.stepProfiles, descriptor.step)
+          ?? resolveStepProfile(context.stepProfiles, descriptor.id),
       });
     };
 
@@ -3420,7 +3904,7 @@ export async function runBuild(featureCode, opts = {}) {
         && consumerPending.length > 0) {
         const work = consumerPending.shift();
         const token = work.descriptor.dispatchToken;
-        const task = runConsumerDescriptor(work.descriptor, work.sourceResponse)
+        const task = runConsumerDescriptor(work.descriptor, work.sourceResponse, work.admission)
           .then((nextResponse) => {
             consumerCompleted.push(nextResponse);
           }, (error) => {
@@ -3446,7 +3930,8 @@ export async function runBuild(featureCode, opts = {}) {
         for (const descriptor of descriptors) {
           if (consumerSeenTokens.has(descriptor.dispatchToken)) continue;
           const flowId = engineResponse.runId ?? engineResponse.flow_id;
-          const runPins = { revisionDigest: descriptor.revisionDigest, specDigest: localSpecDigest };
+          const runPins = { revisionDigest: descriptor.revisionDigest, specDigest: localSpecDigest,
+            profilesDigest: waveProfilesEnabled(pipelineProfiles) ? profilePreflight.profilesDigest : undefined };
           // Preflight a whole ready batch before launching it. This preserves the
           // shipped crash-before-first-bind boundary (zero issuances may execute)
           // while allowing the work after revision fencing to overlap.
@@ -3455,8 +3940,11 @@ export async function runBuild(featureCode, opts = {}) {
             await artifacts.hooks.beforeRevisionBind({ descriptor, journal: artifacts.journal });
           }
           artifacts.bindRunRevision(runPins);
+          const admission = await admitConsumerWave({ descriptor, descriptors,
+            localSpec, profiles: pipelineProfiles,
+            artifacts, stratum, flowId });
           consumerSeenTokens.add(descriptor.dispatchToken);
-          consumerPending.push({ descriptor, sourceResponse: engineResponse });
+          consumerPending.push({ descriptor, sourceResponse: engineResponse, admission });
         }
         launchPendingConsumers();
       }
@@ -3711,7 +4199,7 @@ export async function runBuild(featureCode, opts = {}) {
               // here handed the fixer an unrestricted profile; the sibling
               // review-repair site keys off `fix` the same way. Identity still
               // comes from the dispatch (`agent: fixAgent`).
-              profile: resolveStepProfile(context.stepProfiles, 'fix')
+              profile: resolveStepProfile(effectiveProfiles, 'fix')
                 ?? resolveStepProfile(context.stepProfiles, stepId),
               sandboxMode: 'workspace-write',
               ...(flowTag(flowId, stepId) ? { flow: flowTag(flowId, stepId) } : {}),
@@ -3816,7 +4304,7 @@ export async function runBuild(featureCode, opts = {}) {
             // 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.
-            profile: resolveStepProfile(effectiveProfiles, stepId),
+            profile: resolveStepProfile(context.stepProfiles, stepId),
           });
         } catch (err) {
           if (buildCancel.cancelled) throw err;
@@ -3894,7 +4382,7 @@ export async function runBuild(featureCode, opts = {}) {
                   progress, streamWriter, maxDurationMs, stratum, cwd: agentCwd,
                   reviewMode: isReviewMain,
                   confidenceGate: confGateMain,
-                  profile: resolveStepProfile(effectiveProfiles, stepId),
+                  profile: resolveStepProfile(context.stepProfiles, stepId),
                   ...(flowTag(flowId, stepId) ? { flow: flowTag(flowId, stepId) } : {}),
                   flowId, buildCancel,
                   buildSignal: buildCancel.signal,
@@ -4138,6 +4626,9 @@ export async function runBuild(featureCode, opts = {}) {
         // Report each model dispatch before the outcome it funded. The merged
         // step usage remains the accumulator/build-stream shape used by existing
         // callers; receipts use mainResult.usages to preserve per-dispatch data.
+        if (context.pipelineProfiles?._costCeiling && !toEngineUsage(stepUsage)) {
+          await context.recordBuildUsage({ dispatch_id: mainResult.dispatchIds?.primary ?? readyStep?.dispatchToken }, { stepId, source: 'main' });
+        }
         if (toEngineUsage(stepUsage)) {
           buildCostTotals.input_tokens += stepUsage.input_tokens ?? 0;
           buildCostTotals.output_tokens += stepUsage.output_tokens ?? 0;
@@ -4390,6 +4881,9 @@ export async function runBuild(featureCode, opts = {}) {
               { gateStepId, localFanoutStepId: consumerFanoutStep.id, journaledFanoutStepId: journaledFanoutId },
             );
           }
+          if (pipelineProfiles._consumer?.[consumerFanoutStep.id]?.checkpoint_gate === gateStepId) {
+            consumerMergeArtifacts.initializeWave({ ref: `refs/heads/compose/wave/${flowId}`, profilesDigest: profilePreflight.profilesDigest });
+          }
           consumerMergeArtifacts.recordGateBinding({ gateStepId, fanoutStepId: consumerFanoutStep.id });
         }
 
@@ -4451,6 +4945,7 @@ export async function runBuild(featureCode, opts = {}) {
                 await consumerMergeArtifacts.applyMerge(consumerMergeTransaction);
                 mergeApplied = true;
                 try {
+                  if (!consumerMergeArtifacts.journal.wave) {
                   const changed = execSync(
                     'git diff --name-only HEAD; git ls-files --others --exclude-standard',
                     { cwd: agentCwd, encoding: 'utf8', timeout: 5000, stdio: 'pipe' },
@@ -4461,6 +4956,7 @@ export async function runBuild(featureCode, opts = {}) {
                     context.filesChanged = [...files];
                     context.recordFilesChanged(context.filesChanged);
                   }
+                  }
                 } catch { /* best-effort build context projection */ }
               } catch (error) {
                 if (!(error instanceof ConsumerMergeDecisionError)) throw error;
@@ -4494,11 +4990,38 @@ export async function runBuild(featureCode, opts = {}) {
             next = await callFlowWithCancellation(stratum, 'gateResolve', flowId, buildCancel,
               stepId, outcome, rationale, resolvedBy, gateToken,
             );
+            if (consumerMergeArtifacts?.journal.wave && outcome === 'approve') {
+              consumerMergeArtifacts.markGateResolved(consumerMergeTransaction, outcome);
+              // Acknowledged approval creates an obligation even if cancellation follows.
+              consumerMergeArtifacts.recoverCheckpoint(consumerMergeTransaction);
+              mergeApplied = false; // confirmed checkpoint must never be rolled back on cancel
+              await replicateCheckpoints(context);
+            }
             if (next.status === 'cancelled') buildCancel.cancel('flow_cancelled');
             if (buildCancel.cancelled) throw buildCancel.signal.reason;
           } catch (error) {
-            if (mergeApplied && buildCancel.cancelled) reverseCancelledMerge();
-            throw error;
+            if (waveProfilesEnabled(pipelineProfiles)) {
+              const current = await stratum.audit(flowId);
+              const ordinal = (gateAudit.events ?? []).filter(e => e.type === 'gate_resolved' && e.stepId === stepId).length;
+              const decision = (current.events ?? []).filter(e => e.type === 'gate_resolved' && e.stepId === stepId)[ordinal]?.detail?.decision;
+              if (decision) {
+                outcome = decision;
+                if (consumerMergeArtifacts && decision === 'approve') {
+                  consumerMergeArtifacts.markGateResolved(consumerMergeTransaction, decision);
+                  consumerMergeArtifacts.recoverCheckpoint(consumerMergeTransaction);
+                  mergeApplied = false;
+                  await replicateCheckpoints(context);
+                }
+                if (current.status === 'cancelled') throw error;
+                next = await stratum.resume(flowId);
+              } else {
+                if (mergeApplied && buildCancel.cancelled) reverseCancelledMerge();
+                throw error;
+              }
+            } else {
+              if (mergeApplied && buildCancel.cancelled) reverseCancelledMerge();
+              throw error;
+            }
           }
           if (consumerMergeArtifacts) {
             if (typeof consumerMergeArtifacts.hooks.afterGateResolve === 'function') {
@@ -4515,6 +5038,8 @@ export async function runBuild(featureCode, opts = {}) {
             if (outcome === 'approve' || outcome === 'kill' || isTerminalFlow(next.status)) {
               consumerMergeArtifacts.cleanupWorktrees(
                 outcome === 'approve' ? 'merge gate approved and advanced' : 'run terminalized',
+                consumerMergeArtifacts.journal.wave && consumerMergeTransaction
+                  ? { dispatchTokens: consumerMergeTransaction.acceptedDispatchTokens } : {},
               );
             }
           }
@@ -4663,8 +5188,22 @@ export async function runBuild(featureCode, opts = {}) {
           continue;
         }
 
+        const outputDecision = await evaluateConfiguredGate(context, {
+          localSpec, gateStepId: stepId, gateToken, costCeilingUsd: opts.costCeilingUsd,
+        });
+        if (outputDecision && !outputDecision.outcome && (opts.gateOpts?.nonInteractive ?? !process.stdin.isTTY)) {
+          suspended = true;
+          const reason = outputDecision.reason;
+          writeActiveBuild(dataDir, { ...readActiveBuild(dataDir), status: 'waiting_gate', gateToken, reason });
+          streamWriter.pause({ flowId, gateToken, reason });
+          console.log(`Build paused at ${stepId}: ${reason}. Resume with a human gate decision.`);
+          return { status: 'waiting_gate', flowId, gateToken, reason };
+        }
+
         // ── Policy evaluation (ITEM-23) ────────────────────────────────────
-        const policy = evaluatePolicy(policySettings, stepId, {
+        const policy = outputDecision
+          ? { mode: outputDecision.outcome ? 'skip' : 'gate', reason: outputDecision.rationale ?? outputDecision.reason }
+          : evaluatePolicy(policySettings, stepId, {
           fromPhase: synthFromPhase,
           // Gate policy is keyed by the gate step id (evaluatePolicy falls back
           // to stepId when toPhase is absent); the synthesized approval target
@@ -4673,17 +5212,19 @@ export async function runBuild(featureCode, opts = {}) {
 
         if (policy.mode === 'skip') {
           // Silent pass-through — no gate record, no UI
-          const resolved = await resolveGateWithConsumerMerge('approve', policy.reason, 'system');
+          const resolved = await resolveGateWithConsumerMerge(outputDecision?.outcome ?? 'approve', policy.reason, 'system');
           response = resolved.response;
           streamWriter.write({
             type: 'build_gate_resolved',
-            stepId, outcome: resolved.outcome, rationale: resolved.rationale, flowId, policyMode: 'skip',
+            stepId, outcome: resolved.outcome, rationale: resolved.rationale, flowId, policyMode: outputDecision ? 'output' : 'skip',
           });
           // COMP-PLAN-SECTIONS T6: emit sections after plan_gate auto-approve
           if (resolved.outcome === 'approve') {
             maybeEmitSectionsAfterPlanGate(stepId, featureDir, { streamWriter, featureCode });
           }
-          stepHistory.push({ stepId, artifact: null, summary: `Gate skip: ${resolved.rationale}`, outcome: resolved.outcome });
+          if (outputDecision?.outcome) await reportWaveEvidence(context, 'gate_decision', gateToken,
+            { ...outputDecision, outcome: resolved.outcome, rationale: resolved.rationale }, 'accepted');
+          stepHistory.push({ stepId, artifact: null, summary: `Gate ${outputDecision ? 'output' : 'skip'}: ${resolved.rationale}`, outcome: resolved.outcome });
           syncStepHistory(dataDir, stepHistory);
 
         } else if (policy.mode === 'flag') {
@@ -4764,7 +5305,10 @@ export async function runBuild(featureCode, opts = {}) {
             rationale = result.rationale;
           }
 
+          if (outputDecision) await reportWaveEvidence(context, 'gate_human', gateToken, { outcome, rationale, hold: outputDecision }, 'proposed');
           const resolved = await resolveGateWithConsumerMerge(outcome, rationale, 'human');
+          if (outputDecision) await reportWaveEvidence(context, 'gate_human', gateToken,
+            { outcome: resolved.outcome, rationale: resolved.rationale, hold: outputDecision }, 'accepted');
           response = resolved.response;
           outcome = resolved.outcome;
           rationale = resolved.rationale;
@@ -5250,7 +5794,8 @@ export async function runBuild(featureCode, opts = {}) {
     }
     // Close stream writer with appropriate status (idempotent — signal handler may have already closed)
     if (streamWriter) {
-      streamWriter.close(buildStatus, buildCostTotals);
+      if (suspended && !buildCancel.cancelled) streamWriter.pause();
+      else streamWriter.close(buildStatus, buildCostTotals);
     }
     // §3.6: the teardown removes the listeners itself, AFTER its writes. Removing them here
     // while it is pending would send a second Ctrl-C to the default handler, killing the
@@ -5280,7 +5825,10 @@ export async function runBuild(featureCode, opts = {}) {
     } finally {
       try {
         if (!runtimeResourcesFinalized) {
-          if (streamWriter) streamWriter.close(buildStatus);
+          if (streamWriter) {
+            if (suspended && !buildCancel.cancelled) streamWriter.pause();
+            else streamWriter.close(buildStatus);
+          }
           if (signalHandler && !buildCancel.teardown) {
             process.removeListener('SIGINT', signalHandler.listeners.onSigint);
             process.removeListener('SIGTERM', signalHandler.listeners.onSigterm);
@@ -5496,6 +6044,18 @@ export function toPhaseResultOutput(shipResult) {
  * Returns a PhaseResult-shaped object.
  */
 export async function executeShipStep(featureCode, agentCwd, cwd, context, description, progress) {
+  const waveShipTree = prepareWaveShip(context);
+  if (waveShipTree?.replay) {
+    const { dispatchId, receipt } = waveShipTree.replay;
+    const { result, completionEvidence } = receipt.detail;
+    if (!result || result.outcome !== 'complete' || result.commit !== receipt.detail.commit) {
+      throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Recorded ship result is unavailable');
+    }
+    await flushWaveReceipts(context, [dispatchId]);
+    context.recordFilesChanged?.(result.filesChanged, { authoritativeShip: true });
+    context.recordCompletionEvidence?.(completionEvidence);
+    return structuredClone(result);
+  }
   // COMP-FIX-HARD T4: bug mode stages docs/bugs/<code>/ instead of <featuresDir>/<code>/
   // COMP-MCP-MIGRATION-2: feature mode honors paths.features override.
   const featuresDir = loadFeaturesDir(cwd);
@@ -5802,6 +6362,25 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     if (filesChanged.length === 0 && sha) filesChanged = stagedFiles;
     context.recordFilesChanged?.(filesChanged, { authoritativeShip: true });
 
+    const result = {
+      phase: 'ship',
+      artifact: sha ?? '',
+      outcome: 'complete',
+      summary: sha
+        ? `Committed ${sha.slice(0, 8)}: ${commitMsg} (${stagedFiles.length} files)`
+        : `Committed: ${commitMsg} (${stagedFiles.length} files)`,
+      commit: sha,
+      filesChanged,
+      testsAttested,
+      // Preserve structured test metrics on a replay as well as the first result.
+      ...(testSummary.parsed ? { test_count: testSummary.test_count, pass_rate: testSummary.pass_rate } : {}),
+    };
+    const completionEvidence = { commitSha: sha, filesChanged, notes: shortDesc, builtVia, testsAttested, testSummary };
+    if (waveShipTree && sha) await reportWaveEvidence(context, 'wave_ship',
+      context.artifacts.journal.wave.checkpoints.at(-1).gateToken,
+      { commit: sha, baseCommit: context.artifacts.journal.wave.baseCommit, checkpointTree: waveShipTree,
+        filesChanged, result, completionEvidence });
+
     // COMP-COMPLETION-GATE slice 2: the ship step no longer completes the feature.
     //
     // It used to call recordCompletion here, catch ANY failure, and still return
@@ -5812,34 +6391,14 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     //
     // Ship now collects evidence and stops. Exactly one completion happens, at
     // terminalization, through the gate, after health. See §2.3, §2.3c.
-    context.recordCompletionEvidence?.({
-      commitSha: sha,
-      filesChanged,
-      notes: shortDesc,
-      builtVia,
-      testsAttested,
-    });
+    context.recordCompletionEvidence?.(completionEvidence);
 
     // COMP-PATHS-EXTERNAL D6a: if ROADMAP / the feature folder resolved into a
     // DIFFERENT git repo, they were written but not committed here — tell the
     // user to commit them there (v1 does not auto-commit other repos).
     noticeExternalArtifacts(cwd, featureCode, gitToplevel(agentCwd));
 
-    return {
-      phase: 'ship',
-      artifact: sha ?? '',
-      outcome: 'complete',
-      summary: sha
-        ? `Committed ${sha.slice(0, 8)}: ${commitMsg} (${stagedFiles.length} files)`
-        : `Committed: ${commitMsg} (${stagedFiles.length} files)`,
-      commit: sha,
-      filesChanged,
-      testsAttested,
-      // COMP-MODEL-AB: thread structured test counts into the step result so the
-      // main loop can persist them to build-history.jsonl for metrics consumers.
-      // Only present when testSummary.parsed=true (framework detected + output parsed).
-      ...(testSummary.parsed ? { test_count: testSummary.test_count, pass_rate: testSummary.pass_rate } : {}),
-    };
+    return result;
 
   } catch (err) {
     return {