@smartmemory/compose 0.2.12-beta → 0.2.14-beta

package/lib/build.js

@@ -18,7 +18,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { StratumMcpClient, StratumError } from './stratum-mcp-client.js';
 import { runAndNormalize, AgentTimeoutError, UserInterruptError, AgentError } from './result-normalizer.js';
 import { checkCapabilityViolation } from './capability-checker.js';
-import { buildStepPrompt, buildRetryPrompt, buildGateContext, clearAmbientContextCache } from './step-prompt.js';
+import { buildStepPrompt, buildRetryPrompt, buildGateContext, clearAmbientContextCache, formatBounceForPrompt } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter, ServerUnreachableError } from './vision-writer.js';
 import { resolvePort } from './resolve-port.js';
@@ -60,6 +60,7 @@ import { appendHypothesisEntry, readHypotheses } from './bug-ledger.js';
 import { tier1CodexReview, tier2FreshAgent } from './bug-escalation.js';
 import { recordTaskStates, writeTimingSidecar } from './gsd-timing.js';
 import { writeGsdTaskDiff } from './gsd-diff-capture.js';
+import { resolvePreMergeGate } from './gsd.js';
 
 // ---------------------------------------------------------------------------
 // COMP-FIX-HARD T5: per-step retries cap parser
@@ -626,6 +627,15 @@ export async function runBuild(featureCode, opts = {}) {
   try { composeConfig = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { /* use defaults */ }
   const contextDirPath = join(cwd, composeConfig.paths?.context ?? 'docs/context');
 
+  // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (D5): per-task pre-merge gate is opt-in.
+  // Resolve ONCE and thread into startFresh's planInputs only when the capability
+  // is on. Left `undefined` ⇒ the `pre_merge_gate` key is omitted from the plan
+  // envelope (not `[]`), so the default-OFF path is byte-identical to before.
+  let preMergeGate;
+  if (composeConfig?.capabilities?.preMergeGate) {
+    preMergeGate = resolvePreMergeGate(agentCwd, opts.preMergeGate);
+  }
+
   // ---------------------------------------------------------------------------
   // Pre-build triage — runs before spec loading so profile can toggle skip_if.
   // Skipped when:
@@ -868,10 +878,10 @@ export async function runBuild(featureCode, opts = {}) {
           `Previous build for ${featureCode} was in ${active.mode} mode, ` +
           `current invocation is ${mode} mode. Starting fresh.`
         );
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
       } else if (active.status && active.status !== 'running') {
         console.log(`Previous build ${active.status}. Starting fresh.`);
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
       } else if (active.pid && active.pid !== process.pid && isProcessAlive(active.pid)) {
         // Same feature, different live process — block
         throw new Error(
@@ -884,7 +894,7 @@ export async function runBuild(featureCode, opts = {}) {
           response = await stratum.resume(active.flowId);
           if (isTerminalFlow(response.status)) {
             console.log(`Previous build already ${response.status}. Starting fresh.`);
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
           } else {
             console.log(`Resuming from step: ${response.step_id}`);
             isFreshStart = false;
@@ -895,7 +905,7 @@ export async function runBuild(featureCode, opts = {}) {
             || err?.message?.includes('No active flow');
           if (recoverable) {
             console.log('Previous flow not found. Starting fresh.');
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
           } else {
             throw err;
           }
@@ -905,7 +915,7 @@ export async function runBuild(featureCode, opts = {}) {
       // Different feature or no active build — start fresh.
       // active-build.json is last-writer-wins: concurrent builds for
       // different features are allowed; the UI shows the most recent.
-      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode);
+      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
     }
 
     // Update vision state
@@ -1638,6 +1648,17 @@ export async function runBuild(featureCode, opts = {}) {
         response = await stratum.stepDone(parentFlowId, parentStepId, childResult);
 
       } else if (response.status === 'ensure_failed' || response.status === 'schema_failed') {
+        // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W4): a parallel step that exhausted its
+        // OWN retry loop must NOT be single-agent-retried here. Terminate the build.
+        if (isParallelRetriesExhausted(response)) {
+          streamWriter?.write({
+            type: 'build_error', stepId: response.step_id ?? stepId,
+            message: 'parallel step failed after retries', flowId: response.flow_id,
+          });
+          buildStatus = 'failed';
+          response.status = 'killed';
+          break;
+        }
         {
           // COMP-HEALTH: track contract compliance failure
           contractCompliance.push({ passed: false, stepId: response.step_id ?? stepId, status: response.status });
@@ -2591,7 +2612,7 @@ async function runCrossModelReview(mergedResult, filesChanged, cwd, stratum, str
  * Handles the child's internal step loop (execute_step, await_gate, ensure_failed, etc.)
  * including nested execute_flow (recursive).
  */
-async function executeChildFlow(
+export async function executeChildFlow(
   flowDispatch, stratum, context,
   visionWriter, itemId, dataDir, gateOpts, progress,
   streamWriter
@@ -2782,6 +2803,17 @@ async function executeChildFlow(
       }
 
     } else if (resp.status === 'ensure_failed' || resp.status === 'schema_failed') {
+      // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W4): a child-flow parallel step that
+      // exhausted its OWN retry loop must NOT be single-agent-fixed here (no double-
+      // handle). Terminate the child flow; the marker keeps it out of the fix branch.
+      if (isParallelRetriesExhausted(resp)) {
+        streamWriter?.write({
+          type: 'build_error', stepId: resp.step_id,
+          message: 'parallel step failed after retries', flowId: childFlowId,
+        });
+        resp.status = 'killed';
+        continue;
+      }
       {
         const currentState = readActiveBuild(dataDir);
         const violationList = (resp.violations || []).slice(-10);
@@ -2901,6 +2933,18 @@ export function resolveBuildStatusForCompleteResponse(response) {
   return 'complete';
 }
 
+/**
+ * COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W4): a parallel_dispatch step that exhausted
+ * its OWN bounded retry loop (executeParallelDispatch) tags its terminal envelope
+ * with `_parallelRetriesExhausted: true`. The outer dispatch loops (runBuild and
+ * executeChildFlow) must recognise that marker and terminate — never fall through
+ * to the single-agent fix/retry path, which cannot re-run parallel tasks. Keyed on
+ * the explicit marker, NOT a brittle "does response.tasks exist" heuristic.
+ */
+export function isParallelRetriesExhausted(response) {
+  return !!(response && response._parallelRetriesExhausted);
+}
+
 export function shouldUseServerDispatch(dispatchResponse) {
   if (process.env.COMPOSE_SERVER_DISPATCH !== '1') return false;
   const isolation = dispatchResponse?.isolation ?? 'worktree';
@@ -3574,7 +3618,121 @@ function applyServerDispatchDiffs(taskList, pollTasks, baseCwd, streamWriter, st
   }
 }
 
-async function executeParallelDispatch(
+// ---------------------------------------------------------------------------
+// COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W2) — anchor-commit + entry-snapshot
+// helpers for the consumer-path parallel retry loop. All three operate through
+// a TEMP git index so the base repo's real index, working tree, and HEAD are
+// never mutated. The temp index lives in os.tmpdir() (NOT inside the repo):
+// `git add -A` would otherwise stage the temp-index file itself into the
+// snapshot tree, since `.compose/` is not guaranteed to be gitignored in target
+// repos. Putting it outside the worktree sidesteps that self-capture entirely.
+// The dangling commits these create carry no ref → git GC reclaims them.
+// ---------------------------------------------------------------------------
+
+let anchorSeq = 0;
+
+function tempIndexEnv(baseCwd) {
+  const idx = join(tmpdir(), `compose-par-idx-${process.pid}-${anchorSeq++}`);
+  // Deterministic identity so commit-tree works even in repos without a
+  // configured git user. These commits never reach a ref.
+  const env = {
+    ...process.env,
+    GIT_INDEX_FILE: idx,
+    GIT_AUTHOR_NAME: 'compose', GIT_AUTHOR_EMAIL: 'compose@local',
+    GIT_COMMITTER_NAME: 'compose', GIT_COMMITTER_EMAIL: 'compose@local',
+  };
+  return { idx, env };
+}
+
+/**
+ * Build a dangling anchor commit = HEAD + `goodDiffs` (applied index-only, in
+ * the order given). Returns the commit SHA. The base working tree, real index,
+ * and HEAD are untouched. Used to seed round-N retry worktrees with the round's
+ * already-successful work (`git worktree add <sha> --detach`).
+ */
+export function buildAnchorCommit(baseCwd, goodDiffs = [], label = 'par-anchor') {
+  const { idx, env } = tempIndexEnv(baseCwd);
+  try {
+    execSync('git read-tree HEAD', { cwd: baseCwd, env, stdio: 'pipe' });
+    for (const d of goodDiffs) {
+      if (!d) continue;
+      execSync('git apply --cached -', { cwd: baseCwd, env, input: d, stdio: 'pipe' });
+    }
+    const tree = execSync('git write-tree', { cwd: baseCwd, env, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    const sha = execFileSync('git', ['commit-tree', tree, '-p', 'HEAD', '-m', label], {
+      cwd: baseCwd, env, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    return sha;
+  } finally {
+    try { rmSync(idx, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+/**
+ * Capture the FULL entry working tree (tracked + untracked, honoring
+ * .gitignore) as a dangling commit, through a temp index so the real index and
+ * working tree are never touched. Returns the snapshot commit SHA. Restored
+ * between retry rounds via restoreToSnapshot.
+ */
+export function captureEntrySnapshot(baseCwd, label = 'par-entry-snapshot') {
+  const { idx, env } = tempIndexEnv(baseCwd);
+  try {
+    execSync('git read-tree HEAD', { cwd: baseCwd, env, stdio: 'pipe' });
+    execSync('git add -A', { cwd: baseCwd, env, stdio: 'pipe' });   // tracked + untracked → TEMP index only
+    const tree = execSync('git write-tree', { cwd: baseCwd, env, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    const sha = execFileSync('git', ['commit-tree', tree, '-p', 'HEAD', '-m', label], {
+      cwd: baseCwd, env, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    return sha;
+  } finally {
+    try { rmSync(idx, { force: true }); } catch { /* best effort */ }
+  }
+}
+
+/**
+ * Restore the base working-tree CONTENT (tracked + untracked) to a snapshot
+ * captured by captureEntrySnapshot. The staged-vs-unstaged split is NOT
+ * preserved (the next round's applyTaskDiffsToBaseCwd stash normalizes the
+ * index anyway). Drops this round's tracked + untracked changes, then
+ * re-materializes the entry tree, then resets the index to HEAD.
+ */
+export function restoreToSnapshot(baseCwd, snap) {
+  const run = (cmd) => execSync(cmd, { cwd: baseCwd, encoding: 'utf-8', timeout: 30000, stdio: 'pipe' });
+  try { run('git checkout -- .'); } catch { /* nothing tracked to drop */ }
+  try { run('git clean -fd'); } catch { /* nothing untracked to drop */ }
+  run(`git checkout ${snap} -- .`);   // re-materialize entry tracked + untracked content
+  try { run('git reset -q'); } catch { /* unstage; best effort */ }
+}
+
+/**
+ * Return the diffs in `diffMap` ordered by the tasks' depends_on topology (the
+ * same DFS applyTaskDiffsToBaseCwd uses), so an anchor commit replays the good
+ * diffs in a consistent order. COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W2).
+ */
+function topoOrderedDiffs(tasks, diffMap) {
+  const taskMap = new Map(tasks.map(t => [t.id, t]));
+  const order = [];
+  const visited = new Set();
+  const visiting = new Set();
+  const visit = (id) => {
+    if (visited.has(id) || visiting.has(id)) return;
+    visiting.add(id);
+    const t = taskMap.get(id);
+    if (t) for (const dep of (t.depends_on ?? [])) visit(dep);
+    visiting.delete(id);
+    visited.add(id);
+    order.push(id);
+  };
+  for (const t of tasks) visit(t.id);
+  const out = [];
+  for (const id of order) {
+    const d = diffMap.get(id);
+    if (d) out.push(d);
+  }
+  return out;
+}
+
+export async function executeParallelDispatch(
   dispatchResponse,
   stratum,
   context,
@@ -3620,8 +3778,52 @@ async function executeParallelDispatch(
   const worktreeIsolation = useWorktrees && isGitRepo;
 
   const maxConcurrent = Math.max(1, dispatchResponse.max_concurrent ?? 3);
+
+  // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W3): the consumer-dispatch path owns a
+  // bounded, bounce-injected retry loop. Each round re-runs ONLY the failed
+  // subset; successful diffs are replayed onto a throwaway per-round anchor
+  // commit so re-run tasks see prior good work. The real base is restored to an
+  // entry snapshot between rounds (no cross-round double-apply), the union is
+  // applied to the base BEFORE parallelDone every round (today's order), and the
+  // terminal build_step_done fires exactly once — after the terminal
+  // parallelDone — mirroring the server-dispatch discipline.
+  // Cap = the step's declared `retries` (Stratum's field is declarative-only on the
+  // consumer path; Compose enforces it here), then a per-dispatch override, then 2.
+  // Hard-ceilinged at 10 as a runaway backstop.
+  const RETRY_CAP = Math.min(10, Math.max(0, dispatchResponse.retries ?? dispatchResponse.max_par_retries ?? 2));
+
+  // Entry snapshot: full working tree (tracked + untracked), captured ONCE before
+  // round 0 mutates the base (its state is gone after the round-0 apply), for
+  // restore-between-rounds. Skipped when retries are disabled. On the single-round
+  // happy path it is a captured-but-never-used dangling commit (GC-reclaimable) —
+  // the real index/worktree and the parallelDone call stay byte-identical to today.
+  let entrySnapshot = null;
+  if (worktreeIsolation && RETRY_CAP > 0) {
+    try {
+      entrySnapshot = captureEntrySnapshot(baseCwd);
+    } catch (err) {
+      // Capture only fails when the base has no HEAD (unborn branch — the worktree
+      // dispatch itself can't run) or git/disk is broken. We DEGRADE to a single
+      // pass: retryable is gated on `entrySnapshot !== null`, so no round ever runs
+      // against an unrecoverable base. A failed step then leaves round 0's partial
+      // merge in place — identical to the pre-feature consumer path, which never
+      // rolled back either (a coarse `checkout/clean` is NOT a safe fallback: it
+      // would also discard the user's entry uncommitted changes).
+      entrySnapshot = null;
+      console.warn(`[par-retry] entry snapshot capture failed (${err?.message ?? err}); parallel retry disabled for ${dispStepId}`);
+    }
+  }
+
+  // Cross-round state.
+  const goodDiffs = new Map();    // taskId -> captured diff of a non-failed task (replayed each round)
+  const goodResults = new Map();  // taskId -> { task_id, status:'complete', result }
+  let subset = tasks;             // round 0 runs all tasks
+  let inboundBounces = new Map(); // taskId -> ParMergeBounce from the prior round (drives W1 injection)
+  let round = 0;
+
+  // Per-round mutable state (reset at the top of each round).
   let activeSlots = 0;
-  const slotWaiters = [];
+  let slotWaiters = [];
   const acquireSlot = () => {
     if (activeSlots < maxConcurrent) { activeSlots++; return Promise.resolve(); }
     return new Promise(res => slotWaiters.push(res));
@@ -3630,12 +3832,24 @@ async function executeParallelDispatch(
     activeSlots--;
     if (slotWaiters.length > 0) { activeSlots++; slotWaiters.shift()(); }
   };
+  let worktreePaths = new Map();
+  let taskDiffs = new Map();
+  let anchorRef = 'HEAD';
 
-  const worktreePaths = new Map();
-  const taskDiffs = new Map();
+  while (true) {
+    // Reset per-round state.
+    activeSlots = 0;
+    slotWaiters = [];
+    worktreePaths = new Map();
+    taskDiffs = new Map();
+    // Round 0 worktrees off HEAD (byte-identical). Round N off a dangling anchor
+    // = HEAD + replayed good diffs (topo order) so re-run tasks SEE prior good work.
+    anchorRef = round === 0
+      ? 'HEAD'
+      : buildAnchorCommit(baseCwd, topoOrderedDiffs(tasks, goodDiffs), `par-anchor-round-${round}`);
 
   const settled = await Promise.allSettled(
-    tasks.map(async (task) => {
+    subset.map(async (task) => {
       await acquireSlot();
       const taskId = task.id;
       let taskCwd = baseCwd;
@@ -3643,7 +3857,7 @@ async function executeParallelDispatch(
 
       if (worktreeIsolation) {
         try {
-          execSync(`git worktree add "${wtPath}" --detach HEAD`, {
+          execSync(`git worktree add "${wtPath}" --detach ${anchorRef}`, {
             cwd: baseCwd, encoding: 'utf-8', timeout: 30000, stdio: 'pipe',
           });
           worktreePaths.set(taskId, wtPath);
@@ -3700,7 +3914,16 @@ async function executeParallelDispatch(
       }
 
       try {
-        const baseTaskPrompt = buildStepPrompt(syntheticDispatch, context);
+        let baseTaskPrompt = buildStepPrompt(syntheticDispatch, context);
+        // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (W1): inject the prior round's bounce
+        // (gate failure / merge conflict) into a re-run task's prompt. Empty on round 0.
+        const inbound = inboundBounces.get(taskId);
+        if (inbound) {
+          try {
+            const bounceText = formatBounceForPrompt(inbound);
+            if (bounceText) baseTaskPrompt = `${baseTaskPrompt}\n\n${bounceText}`;
+          } catch { /* degrade — never block a task on injection */ }
+        }
         const taskTimeout = STEP_TIMEOUT_MS[dispStepId] ?? DEFAULT_TIMEOUT_MS;
         // review_mode is passed via inputs (as string "true") since top-level step props are Stratum-validated.
         // Fallback: parallel_dispatch steps with output_contract=ReviewResult are review by definition.
@@ -3776,6 +3999,11 @@ async function executeParallelDispatch(
 
           try {
             execSync('git add -A', { cwd: wtPath, encoding: 'utf-8', timeout: 10000, stdio: 'pipe' });
+            // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY: never let the worktree-ownership
+            // marker leak into a task's captured diff — every task writes `.owner`
+            // at its worktree root, so capturing it makes each task's diff add the
+            // same path and the SECOND task's merge conflicts ("already exists").
+            try { execSync('git reset -q -- .owner', { cwd: wtPath, encoding: 'utf-8', timeout: 10000, stdio: 'pipe' }); } catch { /* .owner absent — fine */ }
             const diff = execSync('git diff --cached HEAD', {
               cwd: wtPath, encoding: 'utf-8', timeout: 30000, stdio: 'pipe',
             });
@@ -3815,82 +4043,190 @@ async function executeParallelDispatch(
     })
   );
 
-  // COMP-PAR-MERGE-QUEUE-CONSUMER: collect structured bounce records (gate-failed
-  // here, merge-conflict below) to surface on the parallelDone envelope.
-  const bouncedTasks = [];
-  const taskResults = settled.map(outcome => {
-    if (outcome.status === 'rejected') {
-      return { task_id: 'unknown', status: 'failed', error: String(outcome.reason) };
-    }
-    const { taskId, status, result, error, gateBounce } = outcome.value;
-    if (gateBounce) bouncedTasks.push(gateBounce);
-    return status === 'complete'
-      ? { task_id: taskId, status: 'complete', result }
-      : { task_id: taskId, status: 'failed', error };
-  });
+    // COMP-PAR-MERGE-QUEUE-CONSUMER: collect structured bounce records (gate-failed
+    // here, merge-conflict below) to surface on the parallelDone envelope.
+    const bouncedTasks = [];
+    const roundResults = settled.map(outcome => {
+      if (outcome.status === 'rejected') {
+        return { task_id: 'unknown', status: 'failed', error: String(outcome.reason) };
+      }
+      const { taskId, status, result, error, gateBounce } = outcome.value;
+      if (gateBounce) bouncedTasks.push(gateBounce);
+      return status === 'complete'
+        ? { task_id: taskId, status: 'complete', result }
+        : { task_id: taskId, status: 'failed', error };
+    });
 
-  let mergeStatus = 'clean';
-  if (worktreeIsolation && taskDiffs.size > 0) {
-    const result = applyTaskDiffsToBaseCwd(
-      tasks, taskDiffs, baseCwd, streamWriter, dispStepId, parDir,
-    );
-    mergeStatus = result.mergeStatus;
+    // Union re-applied to the real base each round = carried good diffs + this
+    // round's fresh diffs. The base was restored to the entry snapshot before
+    // this round, so applyTaskDiffsToBaseCwd never sees a prior round's union
+    // → no cross-round double-apply. Round 0: goodDiffs empty ⇒ union = today's diffs.
+    const unionDiffs = new Map(goodDiffs);
+    for (const [id, d] of taskDiffs) unionDiffs.set(id, d);
+
+    let mergeStatus = 'clean';
+    if (worktreeIsolation && unionDiffs.size > 0) {
+      const result = applyTaskDiffsToBaseCwd(
+        tasks, unionDiffs, baseCwd, streamWriter, dispStepId, parDir,
+      );
+      mergeStatus = result.mergeStatus;
 
-    // Merge applied files into context (matches existing behavior)
-    if (mergeStatus !== 'conflict' && result.appliedFiles.length > 0) {
-      const existing = new Set(context.filesChanged ?? []);
-      for (const f of result.appliedFiles) existing.add(f);
-      context.filesChanged = [...existing];
+      // Merge applied files into context (matches existing behavior)
+      if (mergeStatus !== 'conflict' && result.appliedFiles.length > 0) {
+        const existing = new Set(context.filesChanged ?? []);
+        for (const f of result.appliedFiles) existing.add(f);
+        context.filesChanged = [...existing];
+      }
+
+      // Mark conflicted task as failed in THIS round's results (matches existing behavior)
+      if (mergeStatus === 'conflict' && result.conflictedTaskId) {
+        const idx = roundResults.findIndex(r => r.task_id === result.conflictedTaskId);
+        if (idx >= 0) {
+          roundResults[idx].status = 'failed';
+          roundResults[idx].error = `merge conflict: ${result.conflictError}`;
+        }
+        // COMP-PAR-MERGE-QUEUE-CONSUMER: structured merge-conflict bounce.
+        bouncedTasks.push(
+          buildMergeConflictBounce(result.conflictedTaskId, result.conflictError, result.conflictFiles),
+        );
+      }
+    }
+
+    if (worktreeIsolation) {
+      try { execSync(`rm -rf "${parDir}"`, { cwd: baseCwd, timeout: 5000, stdio: 'pipe' }); } catch { /* ignore */ }
     }
 
-    // Mark conflicted task as failed in taskResults (matches existing behavior)
-    if (mergeStatus === 'conflict' && result.conflictedTaskId) {
-      const idx = taskResults.findIndex(r => r.task_id === result.conflictedTaskId);
-      if (idx >= 0) {
-        taskResults[idx].status = 'failed';
-        taskResults[idx].error = `merge conflict: ${result.conflictError}`;
+    // Full aggregate over ALL tasks = carried good results (complete) + this round's.
+    const taskResults = [...goodResults.values(), ...roundResults];
+
+    // COMP-PAR-MERGE-QUEUE-CONSUMER: when there are bounce records, send a structured
+    // merge_status {status, bounced_tasks} so Stratum threads them onto the failure
+    // envelope (and derives readable violations). Bare string otherwise — byte-identical.
+    const mergeArg = bouncedTasks.length > 0
+      ? { status: mergeStatus, bounced_tasks: bouncedTasks }
+      : mergeStatus;
+
+    // isolation:none (e.g. the review lenses): nothing to merge, no retry semantics.
+    // Preserve the pre-feature single-pass behavior EXACTLY — emit the parent
+    // build_step_done (mergeStatus-based summary) BEFORE parallelDone, then return
+    // the raw envelope so the parent fix-loop owns any ensure_failed. No snapshot,
+    // no marker, no event-ordering change for this path.
+    if (!worktreeIsolation) {
+      if (streamWriter) {
+        const nComplete = taskResults.filter(r => r.status === 'complete').length;
+        streamWriter.write({
+          type: 'build_step_done', stepId: dispStepId,
+          summary: `parallel_dispatch: ${nComplete}/${taskResults.length} tasks ${mergeStatus === 'clean' ? 'merged' : 'conflict'}`,
+          retries: 0,
+          violations: [],
+          flowId: dispFlowId, parallel: true,
+          ...(parentFlowId ? { parentFlowId } : {}),
+        });
       }
-      // COMP-PAR-MERGE-QUEUE-CONSUMER: structured merge-conflict bounce.
-      bouncedTasks.push(
-        buildMergeConflictBounce(result.conflictedTaskId, result.conflictError, result.conflictFiles),
-      );
+      return stratum.parallelDone(dispFlowId, dispStepId, taskResults, mergeArg);
     }
-  }
 
-  if (worktreeIsolation) {
-    try { execSync(`rm -rf "${parDir}"`, { cwd: baseCwd, timeout: 5000, stdio: 'pipe' }); } catch { /* ignore */ }
-  }
+    const env = await stratum.parallelDone(dispFlowId, dispStepId, taskResults, mergeArg);
 
-  const nComplete = taskResults.filter(r => r.status === 'complete').length;
-  if (streamWriter) {
-    streamWriter.write({
-      type: 'build_step_done', stepId: dispStepId,
-      summary: `parallel_dispatch: ${nComplete}/${taskResults.length} tasks ${mergeStatus === 'clean' ? 'merged' : 'conflict'}`,
-      retries: 0,
-      violations: [],
-      flowId: dispFlowId, parallel: true,
-      ...(parentFlowId ? { parentFlowId } : {}),
-    });
-  }
+    // The terminal build_step_done (parent step) — emitted exactly ONCE, after the
+    // terminal parallelDone, mirroring executeParallelDispatchServer's discipline.
+    // (The one deliberate departure from the pre-feature consumer path, which emitted
+    // unconditionally before parallelDone; terminality is only known after the call.)
+    const emitTerminalDone = () => {
+      if (!streamWriter) return;
+      const nComplete = taskResults.filter(r => r.status === 'complete').length;
+      streamWriter.write({
+        type: 'build_step_done', stepId: dispStepId,
+        summary: `parallel_dispatch: ${nComplete}/${taskResults.length} tasks ${env.status === 'complete' ? 'merged' : 'failed'}`,
+        retries: round,
+        violations: [],
+        flowId: dispFlowId, parallel: true,
+        ...(parentFlowId ? { parentFlowId } : {}),
+      });
+    };
 
-  // COMP-PAR-MERGE-QUEUE-CONSUMER: when there are bounce records, send a structured
-  // merge_status {status, bounced_tasks} so Stratum threads them onto the failure
-  // envelope (and derives readable violations). Bare string otherwise — byte-identical.
-  const mergeArg = bouncedTasks.length > 0
-    ? { status: mergeStatus, bounced_tasks: bouncedTasks }
-    : mergeStatus;
-  return stratum.parallelDone(dispFlowId, dispStepId, taskResults, mergeArg);
+    // Terminal complete — the base holds the merged union and context.filesChanged
+    // is set. Emit the single terminal build_step_done and return the envelope.
+    // On round 0 this is one apply + one parallelDone + one emit — same final base,
+    // same event content, same stratum call as the pre-feature path.
+    if (env.status === 'complete') {
+      emitTerminalDone();
+      return env;
+    }
+
+    // Retry — same gate the server-dispatch path uses (mirror), bounded by RETRY_CAP.
+    // REQUIRES a clean-base snapshot: a successful entry snapshot is the only thing
+    // that lets a later round start from the pristine base. If capture failed
+    // (entrySnapshot === null) we must NOT retry — retrying against round 0's already-
+    // applied union would double-apply / corrupt the base. Degrade to a tagged
+    // terminal instead (the W4 guard then fails the build cleanly).
+    const retryable = (env.status === 'ensure_failed' || env.status === 'schema_failed')
+      && Array.isArray(env.tasks)
+      && env.step_id === dispStepId
+      && round < RETRY_CAP
+      && entrySnapshot !== null;
+
+    if (retryable) {
+      // Restore the base to the entry snapshot so the next round starts clean (no
+      // leftover/partial union). Idempotent on a conflict round, which
+      // applyTaskDiffsToBaseCwd already rolled back. If the restore FAILS we cannot
+      // guarantee a clean base for the next round, so we abort the retry and fall
+      // through to the tagged terminal rather than running against residual state.
+      let restored = true;
+      try { restoreToSnapshot(baseCwd, entrySnapshot); } catch { restored = false; }
+      if (restored) {
+        // Accumulate every non-failed task's diff/result so it replays next round.
+        for (const r of roundResults) {
+          if (r.status !== 'failed') {
+            goodResults.set(r.task_id, r);
+            const d = taskDiffs.get(r.task_id);
+            if (d) goodDiffs.set(r.task_id, d);
+          }
+        }
+        // Authoritative failed set (gate-failed + schema_failed + conflict-loser)
+        // becomes the next subset — never inferred from per-file apply output.
+        const taskById = new Map(tasks.map(t => [t.id, t]));
+        subset = taskResults
+          .filter(r => r.status === 'failed')
+          .map(r => taskById.get(r.task_id))
+          .filter(Boolean);
+        inboundBounces = new Map((bouncedTasks ?? []).map(b => [b.task_id, b]));
+        round++;
+        continue; // no build_step_done this round
+      }
+      if (streamWriter) {
+        streamWriter.write({
+          type: 'build_error', stepId: dispStepId,
+          message: 'parallel retry aborted: base snapshot restore failed', flowId: dispFlowId,
+        });
+      }
+      // fall through to the tagged terminal below
+    }
+
+    // Worktree path, non-complete terminal: cap exceeded or a terminal we cannot
+    // retry. Restore the base (the step failed → leave no partial merge behind) and
+    // tag the envelope so the outer loop terminates instead of single-agent-retrying
+    // a parallel step (W4). (isolation:none already returned above.)
+    emitTerminalDone();
+    if (entrySnapshot) {
+      try { restoreToSnapshot(baseCwd, entrySnapshot); } catch { /* best effort */ }
+    }
+    return { ...env, _parallelRetriesExhausted: true };
+  }
 }
 
-async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode = 'feature') {
+export async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode = 'feature', preMergeGate) {
   const flowName = extractFlowName(specYaml, templateName);
   console.log(`Starting ${flowName} for ${featureCode}...`);
   // COMP-FIX-HARD T4: bug-mode flows take input as { task: <description> }
   // because pipelines/bug-fix.stratum.yaml's flow input contract uses `task`,
   // not the feature flow's `{ featureCode, description }`.
+  // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (D5): fold pre_merge_gate into the
+  // feature plan envelope ONLY when resolved (undefined ⇒ key omitted, not [])
+  // so the default-OFF path is byte-identical to pre-feature behavior.
   const planInputs = mode === 'bug'
     ? { task: description }
-    : { featureCode, description };
+    : { featureCode, description, ...(preMergeGate !== undefined ? { pre_merge_gate: preMergeGate } : {}) };
   const response = await stratum.plan(specYaml, flowName, planInputs);
 
   writeActiveBuild(dataDir, {

package/lib/step-prompt.js

@@ -162,11 +162,46 @@ function buildConflictSection(conflicts) {
   return lines.join('\n');
 }
 
-// COMP-PAR-MERGE-QUEUE note: pre-merge bounce context (gate_failed / merge_conflict)
-// is injected into a re-dispatched task's prompt SERVER-SIDE, in Stratum's
-// ParallelExecutor._render_prompt — because the server re-resolves the task list
-// from flow state on each re-dispatch, so a Compose-side prompt edit here would
-// never reach the re-run task. See parallel_exec.py `_format_bounce_for_prompt`.
+// COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY: pre-merge bounce context (gate_failed /
+// merge_conflict) is injected into a re-dispatched task's prompt on BOTH paths:
+// - server-dispatch: SERVER-SIDE in Stratum's ParallelExecutor._render_prompt
+//   (the server re-resolves the task list from flow state on each re-dispatch).
+// - consumer-dispatch: COMPOSE-SIDE via formatBounceForPrompt() below, appended
+//   in executeParallelDispatch's retry loop (Compose, not Stratum, builds the
+//   per-task prompt on that path). This is the Compose mirror of
+//   parallel_exec.py `_format_bounce_for_prompt`.
+
+/**
+ * Format a ParMergeBounce record (contracts/par-merge-bounce.json) as a prompt
+ * section telling a re-dispatched task its prior attempt was rejected before
+ * merge. Mirrors Stratum's `_format_bounce_for_prompt` (parallel_exec.py).
+ * Degrades to '' on null/non-object input so a malformed bounce never breaks a
+ * re-run prompt.
+ *
+ * @param {{task_id?:string, reason?:string, command?:string|null,
+ *          exit_code?:number|null, files?:string[], excerpt?:string}} bounce
+ * @returns {string}
+ */
+export function formatBounceForPrompt(bounce) {
+  if (!bounce || typeof bounce !== 'object') return '';
+  const files = Array.isArray(bounce.files) && bounce.files.length
+    ? bounce.files.join(', ')
+    : '(none reported)';
+  const lines = ['## Previous attempt was rejected before merge — fix this before finishing'];
+  if (bounce.reason === 'gate_failed') {
+    const code = bounce.exit_code == null ? '?' : String(bounce.exit_code);
+    lines.push(`Your last attempt FAILED the pre-merge gate \`${bounce.command ?? '?'}\` (exit ${code}). It was not merged.`);
+  } else if (bounce.reason === 'merge_conflict') {
+    lines.push("Your last attempt produced changes that CONFLICTED with another task's changes at merge time. It was not merged.");
+  } else {
+    lines.push('Your last attempt was rejected before merge.');
+  }
+  lines.push(`Files involved: ${files}`);
+  if (bounce.excerpt) {
+    lines.push('Failure output:', '```', String(bounce.excerpt), '```');
+  }
+  return lines.join('\n');
+}
 
 /**
  * Build a retry prompt when postconditions failed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/compose",
-  "version": "0.2.12-beta",
+  "version": "0.2.14-beta",
   "description": "Structured AI dev pipeline — goal-to-product orchestration with gates, iteration loops, and feature lifecycle management.",
   "author": "SmartMemory",
   "license": "MIT",

package/pipelines/build.stratum.yaml

@@ -18,6 +18,9 @@ workflow:
     description:
       type: string
       required: true
+    pre_merge_gate:
+      type: array
+      required: false   # COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY: default-OFF per-task gate (lint+build), omitted unless capabilities.preMergeGate
 
 contracts:
   PhaseResult:
@@ -189,6 +192,7 @@ flows:
     input:
       featureCode: {type: string}
       description: {type: string}
+      pre_merge_gate: {type: array}   # COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY: optional per-task pre-merge gate
     output: PhaseResult
     max_rounds: 10
     steps:
@@ -345,6 +349,7 @@ flows:
         isolation: worktree
         capture_diff: true
         defer_advance: true
+        pre_merge_verify: "$.input.pre_merge_gate"   # COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY: optional per-task fast gate (default-OFF)
         require: all
         merge: sequential_apply
         intent_template: >