@ikunin/sprintpilot 2.0.6 → 2.0.8

package/_Sprintpilot/scripts/dispatch-layer.js

@@ -64,8 +64,25 @@ function parseLayer(raw) {
 }
 
 function planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch }) {
-  const effectiveParallel = Math.max(1, Math.min(maxParallel | 0, keys.length));
-  const worktrees = keys.map((key) => ({
+  // Dedupe story keys — a duplicated key in --layer would otherwise
+  // produce two entries pointing at the same worktree path and same
+  // branch name, racing on `git worktree add`.
+  const seen = new Set();
+  const dedupedKeys = [];
+  for (const k of keys) {
+    if (seen.has(k)) continue;
+    seen.add(k);
+    dedupedKeys.push(k);
+  }
+  const effectiveParallel = Math.max(1, Math.min(maxParallel | 0, dedupedKeys.length));
+  // CAP: only dispatch the first `effectiveParallel` stories. The
+  // remaining keys are deferred — the autopilot loop will pick them up
+  // in the next iteration after this batch completes. Pre-2.0.8 the
+  // script created worktrees for ALL keys regardless of the cap, then
+  // the workflow spawned N agents anyway, fully ignoring --max-parallel.
+  const dispatchedKeys = dedupedKeys.slice(0, effectiveParallel);
+  const deferredKeys = dedupedKeys.slice(effectiveParallel);
+  const worktrees = dispatchedKeys.map((key) => ({
     story: key,
     worktree: path.join(projectRoot, '.worktrees', key),
     branch: `${branchPrefix}${key}`,
@@ -77,6 +94,7 @@ function planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch })
     effective_parallel: effectiveParallel,
     max_parallel: maxParallel,
     stories: worktrees,
+    deferred: deferredKeys,
   };
 }
 
@@ -90,8 +108,14 @@ function writePlan(projectRoot, plan) {
   return file;
 }
 
+// Match git's "branch already exists" diagnostic. We retry without -b
+// only when the FIRST attempt failed for this specific reason —
+// pre-2.0.8 the bare retry fired on ANY first-attempt failure and
+// silently checked out whatever stale branch happened to exist at the
+// requested name (e.g. last week's commits from an abandoned story).
+const BRANCH_EXISTS_RE = /a branch named .* already exists/i;
+
 function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
-  // Try -b first, fall back to checkout-existing-branch if already present.
   const args = ['worktree', 'add', worktree, '-b', branch];
   if (baseBranch) args.push(baseBranch);
   const first = spawnSync('git', ['-C', projectRoot, ...args], {
@@ -99,7 +123,16 @@ function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
     stdio: ['ignore', 'pipe', 'pipe'],
   });
   if (first.status === 0) return { created: true, retried: false, stderr: first.stderr || '' };
-  // Retry without -b (branch exists).
+  // Only retry without -b if git specifically reported the branch
+  // already exists. Any other error (path collision, missing base
+  // branch, dirty index, etc.) is propagated rather than masked.
+  if (!BRANCH_EXISTS_RE.test(first.stderr || '')) {
+    return {
+      created: false,
+      retried: false,
+      stderr: first.stderr || '',
+    };
+  }
   const second = spawnSync(
     'git',
     ['-C', projectRoot, 'worktree', 'add', worktree, branch],
@@ -112,26 +145,45 @@ function createWorktree({ projectRoot, worktree, branch, baseBranch }) {
   };
 }
 
+// After a worktree is created, disable gc.auto on it. The sequential
+// path in workflow.md does this at line 738; pre-2.0.8 the parallel
+// path skipped it, so concurrent sub-agents in heavy repos could
+// trigger gc on each worktree mid-dispatch. Best-effort — never block
+// dispatch on a config write.
+function disableGcAutoOnWorktree(worktree) {
+  spawnSync('git', ['-C', worktree, 'config', '--local', 'gc.auto', '0'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+// Roll back successful worktrees when a later create fails — leaves
+// no orphaned worktrees on disk, no `.layer-plan.json` describing
+// state that doesn't exist. Best-effort; rollback failures are logged
+// but don't change the overall non-zero exit.
+function rollbackWorktrees(projectRoot, created) {
+  for (const entry of created) {
+    const r = spawnSync(
+      'git',
+      ['-C', projectRoot, 'worktree', 'remove', '--force', entry.worktree],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    if (r.status !== 0) {
+      log.warn(`failed to roll back worktree ${entry.worktree}: ${r.stderr || 'unknown'}`);
+    }
+  }
+}
+
 function dispatch({ keys, maxParallel, projectRoot, branchPrefix, baseBranch, dryRun }) {
   const plan = planLayer({ keys, maxParallel, projectRoot, branchPrefix, baseBranch });
   const results = {
     plan_file: null,
     effective_parallel: plan.effective_parallel,
     stories: [],
+    deferred: plan.deferred,
     dry_run: !!dryRun,
   };
-  if (!dryRun) {
-    for (const entry of plan.stories) {
-      const out = createWorktree({
-        projectRoot,
-        worktree: entry.worktree,
-        branch: entry.branch,
-        baseBranch: entry.base_branch,
-      });
-      results.stories.push({ story: entry.story, worktree: entry.worktree, branch: entry.branch, ...out });
-    }
-    results.plan_file = writePlan(projectRoot, plan);
-  } else {
+  if (dryRun) {
     results.stories = plan.stories.map((e) => ({
       story: e.story,
       worktree: e.worktree,
@@ -140,7 +192,60 @@ function dispatch({ keys, maxParallel, projectRoot, branchPrefix, baseBranch, dr
       retried: false,
       stderr: '(dry-run)',
     }));
+    return results;
+  }
+  // Real dispatch. Track successful creates so we can roll them back if
+  // a later create fails — leaving an orphan worktree + a plan file
+  // claiming it succeeded was the v2.0.7 partial-failure bug.
+  const succeeded = [];
+  let failureIndex = -1;
+  for (let i = 0; i < plan.stories.length; i++) {
+    const entry = plan.stories[i];
+    const out = createWorktree({
+      projectRoot,
+      worktree: entry.worktree,
+      branch: entry.branch,
+      baseBranch: entry.base_branch,
+    });
+    results.stories.push({
+      story: entry.story,
+      worktree: entry.worktree,
+      branch: entry.branch,
+      ...out,
+    });
+    if (out.created) {
+      disableGcAutoOnWorktree(entry.worktree);
+      succeeded.push(entry);
+    } else {
+      failureIndex = i;
+      break; // stop creating; remaining keys are not attempted
+    }
+  }
+  if (failureIndex !== -1) {
+    rollbackWorktrees(projectRoot, succeeded);
+    // Mark the previously-succeeded entries as rolled back so the
+    // workflow doesn't think their worktrees still exist on disk.
+    for (let i = 0; i < failureIndex; i++) {
+      results.stories[i].rolled_back = true;
+      results.stories[i].created = false;
+    }
+    // Mark untried-after-failure stories (the keys past failureIndex
+    // that we never attempted) so the workflow can see what's missing.
+    for (let i = failureIndex + 1; i < plan.stories.length; i++) {
+      results.stories.push({
+        story: plan.stories[i].story,
+        worktree: plan.stories[i].worktree,
+        branch: plan.stories[i].branch,
+        created: false,
+        retried: false,
+        stderr: '(skipped — earlier dispatch failed)',
+      });
+    }
+    // Do NOT write the plan file on partial failure — workflow.md
+    // should never read a plan describing worktrees that don't exist.
+    return results;
   }
+  results.plan_file = writePlan(projectRoot, plan);
   return results;
 }
 

package/_Sprintpilot/scripts/log-timing.js

@@ -52,12 +52,17 @@ const VALID_ACTIONS = ['start', 'end', 'once', 'mark'];
 // rename target). The constant is gone; runtime always uses per-story
 // paths.
 //
-// Sanity ceiling for a single duration record. A wall-clock skip
-// forward of more than this many ms is treated as clock skew rather
-// than a real duration — clamped to 0 with `clock_skew: true` stamped.
-// 24h chosen because no realistic skill phase is longer than that, and
-// it's well above any plausible CI timeout.
-const MAX_PLAUSIBLE_DURATION_MS = 24 * 60 * 60 * 1000;
+// Sanity ceiling for a single duration record. Phase durations longer
+// than this are treated as overflow (likely a stale marker from an
+// abandoned session) and clamped to 0 with `over_threshold: true`
+// stamped. 7 days chosen so legitimate weekend-spanning sprint-level
+// phases (sprint, dispatch.layer-X) are preserved; only genuinely
+// stale markers get clamped.
+//
+// Negative deltas (wall-clock backsteps) are an orthogonal anomaly,
+// flagged with `clock_skew: true` instead. The two flags are mutually
+// exclusive — see the JSDoc on `markPhase`.
+const MAX_PLAUSIBLE_DURATION_MS = 7 * 24 * 60 * 60 * 1000;
 
 function help() {
   log.out(
@@ -314,10 +319,16 @@ function clearMarker(projectRoot, story) {
  * duration record but the next mark will read the new marker (not the
  * stale prev) and won't double-count.
  *
- * Wall-clock skew: durations are clamped to [0, MAX_PLAUSIBLE_DURATION_MS]
- * with a `clock_skew: true` flag in the entry so aggregators don't get
- * poisoned by NTP backsteps, DST transitions, or container clock skips
- * forward of unrealistic magnitudes (e.g. "this skill ran for 7 hours").
+ * Two anomaly classes are flagged separately so consumers can treat
+ * them differently. Both clamp `duration_ms` to 0:
+ *   - `clock_skew: true`  — wall-clock went backwards (NTP backstep,
+ *     DST transition, manual clock change). The flag is reliable as a
+ *     "the clock did something weird" signal.
+ *   - `over_threshold: true` — elapsed time exceeded
+ *     `MAX_PLAUSIBLE_DURATION_MS` (7 days). Almost always a stale
+ *     marker from an abandoned session, not a real measurement.
+ * The flags are mutually exclusive (a single rawDelta can be either
+ * negative OR exceed the ceiling, never both).
  *
  * Returns { duration_ms, prev_phase } so callers can log/inspect.
  */
@@ -336,8 +347,14 @@ function markPhase(projectRoot, story, phase, meta) {
     const prevTs = Date.parse(prev.ts);
     if (!Number.isNaN(prevTs)) {
       const rawDelta = now.getTime() - prevTs;
-      const clamped = rawDelta < 0 || rawDelta > MAX_PLAUSIBLE_DURATION_MS;
-      durationMs = clamped ? 0 : rawDelta;
+      // Two distinct anomalies — flagged separately so consumers can
+      // treat them differently. clock_skew = wall-clock went backwards
+      // (NTP backstep, DST, manual change). over_threshold = elapsed
+      // time exceeds the sanity ceiling (likely a stale marker, not
+      // genuine clock skew). Both clamp duration_ms to 0.
+      const clockSkew = rawDelta < 0;
+      const overThreshold = rawDelta > MAX_PLAUSIBLE_DURATION_MS;
+      durationMs = clockSkew || overThreshold ? 0 : rawDelta;
       prevPhase = prev.phase;
       durationEntry = {
         event: 'duration',
@@ -347,7 +364,8 @@ function markPhase(projectRoot, story, phase, meta) {
         ended: now.toISOString(),
         duration_ms: durationMs,
       };
-      if (clamped) durationEntry.clock_skew = true;
+      if (clockSkew) durationEntry.clock_skew = true;
+      if (overThreshold) durationEntry.over_threshold = true;
       if (prev.meta !== undefined) durationEntry.meta = prev.meta;
     }
   }

package/_Sprintpilot/scripts/merge-shards.js

@@ -51,8 +51,100 @@ function help() {
   );
 }
 
+// Read BMad's `output_folder` from _bmad/bmm/config.yaml if present, so
+// projects that have configured a non-default output dir don't desync
+// from sibling scripts (mark-done-stories-tasks.js etc.).
+function readOutputFolder(projectRoot) {
+  const cfg = path.join(projectRoot, '_bmad', 'bmm', 'config.yaml');
+  if (!fs.existsSync(cfg)) return null;
+  try {
+    const body = fs.readFileSync(cfg, 'utf8');
+    const m = body.match(/^output_folder\s*:\s*(\S+)/m);
+    if (!m) return null;
+    return m[1].replace(/^["']|["']$/g, '').trim();
+  } catch {
+    return null;
+  }
+}
+
 function implArtifactsDir(projectRoot) {
-  return path.join(projectRoot, '_bmad-output', 'implementation-artifacts');
+  const folder = readOutputFolder(projectRoot) || '_bmad-output';
+  return path.join(projectRoot, folder, 'implementation-artifacts');
+}
+
+// ──────────────────────────────────────────────────────────────────
+// Cross-process merge lock
+// ──────────────────────────────────────────────────────────────────
+//
+// Pre-2.0.8 two concurrent merge invocations would each compute the
+// merge in-memory then both rename their tmp file over autopilot-state
+// .yaml. Tmp filenames are unique, so the renames never collided on
+// the source — but the LAST rename wins on the destination, and the
+// earlier merge (potentially with newer shard data) was clobbered.
+// Combined with the archive race below, the loser's archived shards
+// were also gone — silent state rewind.
+//
+// The fix: a sibling lock file. If another invocation holds the lock,
+// either wait briefly + retry, or fail with a clear message naming
+// the holder's pid and start time so the operator can diagnose.
+
+const MERGE_LOCK_FILE = '.merge-shards.lock';
+const STALE_LOCK_AGE_MS = 5 * 60 * 1000; // 5 minutes — merges are fast
+
+function lockPath(projectRoot) {
+  return path.join(implArtifactsDir(projectRoot), MERGE_LOCK_FILE);
+}
+
+function acquireMergeLock(projectRoot) {
+  const file = lockPath(projectRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(file, 'wx');
+      const payload = JSON.stringify({
+        pid: process.pid,
+        ts: new Date().toISOString(),
+      });
+      fs.writeSync(fd, payload);
+      fs.closeSync(fd);
+      return file;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Try stale-recovery once.
+      if (attempt === 0) {
+        try {
+          const st = fs.statSync(file);
+          if (Date.now() - st.mtimeMs > STALE_LOCK_AGE_MS) {
+            log.warn(`merge-shards: removing stale lock ${file} (older than ${STALE_LOCK_AGE_MS}ms)`);
+            fs.unlinkSync(file);
+            continue;
+          }
+        } catch {
+          /* lock vanished between EEXIST and stat — retry */
+          continue;
+        }
+      }
+      let holder = '';
+      try {
+        holder = fs.readFileSync(file, 'utf8');
+      } catch {
+        /* ignore */
+      }
+      throw new Error(
+        `merge-shards: another invocation holds ${file} (${holder}); ` +
+          'wait for it to finish or remove the lock manually if known stale',
+      );
+    }
+  }
+  throw new Error(`merge-shards: failed to acquire lock at ${file}`);
+}
+
+function releaseMergeLock(file) {
+  try {
+    fs.unlinkSync(file);
+  } catch {
+    /* idempotent */
+  }
 }
 
 function readShardFile(file) {
@@ -91,16 +183,49 @@ function compareStamps(a, b) {
   return 0;
 }
 
+// Snapshot file stat at read time so we can verify it's unchanged
+// before archiving. Pre-2.0.8: a worker writing a fresh shard between
+// merge-read and archive-rename would have its shard moved into
+// .archive/ without ever being folded into the merged YAML — silent
+// data loss under parallel dispatch.
+function snapshotShard(file) {
+  try {
+    const st = fs.statSync(file);
+    return { mtime: st.mtimeMs, size: st.size, ino: st.ino };
+  } catch {
+    return null;
+  }
+}
+
+function shardUnchanged(file, snapshot) {
+  if (!snapshot) return false;
+  try {
+    const st = fs.statSync(file);
+    return (
+      st.mtimeMs === snapshot.mtime &&
+      st.size === snapshot.size &&
+      st.ino === snapshot.ino
+    );
+  } catch {
+    return false;
+  }
+}
+
 function mergeStateShards(projectRoot) {
-  // Returns { byStory: { [storyKey]: shard }, corrupt: [...], invalid: [...] }
+  // Returns { byStory: { [storyKey]: shard }, snapshots: { [storyKey]: stat },
+  //   corrupt: [...], invalid: [...] }
   const dir = path.join(implArtifactsDir(projectRoot), KIND_DIR.state);
-  if (!fs.existsSync(dir)) return { byStory: {}, corrupt: [], invalid: [] };
+  if (!fs.existsSync(dir)) return { byStory: {}, snapshots: {}, corrupt: [], invalid: [] };
   const stories = listShardStories(projectRoot, 'state');
   const byStory = {};
+  const snapshots = {};
   const corrupt = [];
   const invalid = [];
   for (const story of stories) {
     const file = path.join(dir, `${story}.yaml`);
+    // Snapshot BEFORE reading so a writer that touches the file during
+    // read still produces a stat mismatch later.
+    const snap = snapshotShard(file);
     let shard;
     try {
       shard = readShardFile(file);
@@ -113,19 +238,33 @@ function mergeStateShards(projectRoot) {
       continue;
     }
     byStory[story] = shard;
+    snapshots[story] = snap;
   }
-  return { byStory, corrupt, invalid };
+  return { byStory, snapshots, corrupt, invalid };
+}
+
+// Parse a timestamp string defensively: malformed `ts` returns 0
+// rather than NaN (which Array.sort treats unpredictably). Pre-2.0.8
+// `Date.parse('not-a-date')` returned NaN, NaN comparisons returned
+// 0, and entries clustered in undefined order — the documented
+// "sort by ts ascending" claim was silently violated.
+function tsToMs(ts) {
+  if (!ts) return 0;
+  const v = Date.parse(ts);
+  return Number.isFinite(v) ? v : 0;
 }
 
 function mergeDecisionShards(projectRoot) {
   const dir = path.join(implArtifactsDir(projectRoot), KIND_DIR['decision-log']);
-  if (!fs.existsSync(dir)) return { entries: [], corrupt: [], invalid: [] };
-  const stories = listShardStories(projectRoot, 'decision-log');
+  if (!fs.existsSync(dir)) return { entries: [], snapshots: {}, corrupt: [], invalid: [] };
+  const stories = listShardStories(projectRoot, 'decision-log').sort();
   const entries = [];
+  const snapshots = {};
   const corrupt = [];
   const invalid = [];
   for (const story of stories) {
     const file = path.join(dir, `${story}.yaml`);
+    const snap = snapshotShard(file);
     let shard;
     try {
       shard = readShardFile(file);
@@ -142,29 +281,50 @@ function mergeDecisionShards(projectRoot) {
       if (!item || typeof item !== 'object') continue;
       entries.push({ ...item, _story: story });
     }
+    snapshots[story] = snap;
   }
-  // Dedupe by id (if present), otherwise keep all. Sort by ts ascending.
+  // Deterministic dedup: sort by (id asc, ts DESC) first, then keep the
+  // first entry for each id — that's the latest-by-ts. Pre-2.0.8 the
+  // dedup was iteration-order-dependent (filesystem readdir order is
+  // unspecified), so identical inputs produced different outputs across
+  // OSes. Idempotency claim was filesystem-dependent.
+  entries.sort((a, b) => {
+    const ai = a.id !== undefined && a.id !== null ? String(a.id) : '';
+    const bi = b.id !== undefined && b.id !== null ? String(b.id) : '';
+    if (ai !== bi) return ai < bi ? -1 : 1;
+    // Within same id: latest ts wins (desc).
+    const aw = tsToMs(a.ts);
+    const bw = tsToMs(b.ts);
+    return bw - aw;
+  });
   const seen = new Set();
   const deduped = [];
   for (const e of entries) {
-    if (e.id !== undefined && e.id !== null && seen.has(String(e.id))) continue;
-    if (e.id !== undefined && e.id !== null) seen.add(String(e.id));
+    if (e.id !== undefined && e.id !== null) {
+      if (seen.has(String(e.id))) continue;
+      seen.add(String(e.id));
+    }
     deduped.push(e);
   }
+  // Final sort for output: ts ascending, with deterministic tiebreaks.
   deduped.sort((a, b) => {
-    const aw = a.ts ? Date.parse(a.ts) : 0;
-    const bw = b.ts ? Date.parse(b.ts) : 0;
+    const aw = tsToMs(a.ts);
+    const bw = tsToMs(b.ts);
     if (aw !== bw) return aw - bw;
-    // Tiebreak alphabetically by id then story for determinism.
     const ai = a.id !== undefined ? String(a.id) : '';
     const bi = b.id !== undefined ? String(b.id) : '';
     if (ai !== bi) return ai < bi ? -1 : 1;
     return (a._story || '').localeCompare(b._story || '');
   });
-  return { entries: deduped.map((e) => {
-    const { _story, ...rest } = e;
-    return rest;
-  }), corrupt, invalid };
+  return {
+    entries: deduped.map((e) => {
+      const { _story, ...rest } = e;
+      return rest;
+    }),
+    snapshots,
+    corrupt,
+    invalid,
+  };
 }
 
 function archiveCorrupt(projectRoot, kind, story, file, reason) {
@@ -186,18 +346,38 @@ function archiveCorrupt(projectRoot, kind, story, file, reason) {
   return { archived: dest, reason };
 }
 
-function archiveShardsToLayer(projectRoot, layerId, storyKeys) {
-  const ts = layerId || new Date().toISOString().replace(/[:.]/g, '-');
+function archiveShardsToLayer(projectRoot, layerId, snapshotsByKind) {
+  // Default layerId includes pid + hrtime to avoid collision when two
+  // archive operations land in the same millisecond on fast CI. Pre-
+  // 2.0.8 the bare ISO timestamp could collide and the second archive
+  // would race-clobber the first.
+  const ts =
+    layerId ||
+    `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}-${process.hrtime.bigint().toString(36)}`;
   const base = path.join(implArtifactsDir(projectRoot), '.archive', `layer-${ts}`);
   fs.mkdirSync(base, { recursive: true });
+  // Snapshot-verify each shard before moving — if a writer touched the
+  // file after merge-read but before archive, the stat won't match and
+  // we must NOT move it (otherwise the fresh shard's contents are lost
+  // without ever being folded into the merged YAML). Skip + log so the
+  // shard stays on disk for the next merge to pick up.
+  const skipped = [];
   for (const kind of ['state', 'decision-log']) {
     const src = path.join(implArtifactsDir(projectRoot), KIND_DIR[kind]);
     if (!fs.existsSync(src)) continue;
     const destDir = path.join(base, KIND_DIR[kind]);
     fs.mkdirSync(destDir, { recursive: true });
-    for (const story of storyKeys) {
+    const snapshots = (snapshotsByKind && snapshotsByKind[kind]) || {};
+    for (const story of Object.keys(snapshots)) {
       const file = path.join(src, `${story}.yaml`);
       if (!fs.existsSync(file)) continue;
+      if (!shardUnchanged(file, snapshots[story])) {
+        log.warn(
+          `merge-shards: shard ${file} changed during merge; not archiving (will be folded into next merge)`,
+        );
+        skipped.push({ kind, story, file, reason: 'changed during merge' });
+        continue;
+      }
       const dest = path.join(destDir, `${story}.yaml`);
       try {
         fs.renameSync(file, dest);
@@ -207,7 +387,7 @@ function archiveShardsToLayer(projectRoot, layerId, storyKeys) {
       }
     }
   }
-  return base;
+  return { dir: base, skipped };
 }
 
 function writeAuthoritative(projectRoot, filename, body, { dryRun } = {}) {
@@ -263,43 +443,63 @@ function composeDecisionYaml(decisionMerge) {
 }
 
 function merge(projectRoot, { layerId, archive, dryRun } = {}) {
-  const state = mergeStateShards(projectRoot);
-  const decisions = mergeDecisionShards(projectRoot);
-
-  // Archive corrupt shards before writing merged files so subsequent
-  // merges don't re-surface the same errors.
-  const archivedCorrupt = [];
-  if (!dryRun) {
-    for (const c of state.corrupt.concat(state.invalid)) {
-      const arch = archiveCorrupt(projectRoot, 'state', c.story, c.file, c.error || c.reason);
-      archivedCorrupt.push({ kind: 'state', story: c.story, ...arch });
-    }
-    for (const c of decisions.corrupt.concat(decisions.invalid)) {
-      const arch = archiveCorrupt(projectRoot, 'decision-log', c.story, c.file, c.error || c.reason);
-      archivedCorrupt.push({ kind: 'decision-log', story: c.story, ...arch });
+  // Acquire cross-process lock. Even dry-run takes the lock so a real
+  // merge in progress doesn't have its shard reads disturbed by a
+  // concurrent dry-run that might (e.g.) tail the same files.
+  const lockFile = acquireMergeLock(projectRoot);
+  try {
+    const state = mergeStateShards(projectRoot);
+    const decisions = mergeDecisionShards(projectRoot);
+
+    // Archive corrupt shards before writing merged files so subsequent
+    // merges don't re-surface the same errors.
+    const archivedCorrupt = [];
+    if (!dryRun) {
+      for (const c of state.corrupt.concat(state.invalid)) {
+        const arch = archiveCorrupt(projectRoot, 'state', c.story, c.file, c.error || c.reason);
+        archivedCorrupt.push({ kind: 'state', story: c.story, ...arch });
+      }
+      for (const c of decisions.corrupt.concat(decisions.invalid)) {
+        const arch = archiveCorrupt(projectRoot, 'decision-log', c.story, c.file, c.error || c.reason);
+        archivedCorrupt.push({ kind: 'decision-log', story: c.story, ...arch });
+      }
     }
-  }
 
-  const stateBody = composeStateYaml(state);
-  const decisionBody = composeDecisionYaml(decisions);
+    const stateBody = composeStateYaml(state);
+    const decisionBody = composeDecisionYaml(decisions);
 
-  const stateWrite = writeAuthoritative(projectRoot, 'autopilot-state.yaml', stateBody, { dryRun });
-  const decisionWrite = writeAuthoritative(projectRoot, 'decision-log.yaml', decisionBody, { dryRun });
+    const stateWrite = writeAuthoritative(projectRoot, 'autopilot-state.yaml', stateBody, { dryRun });
+    const decisionWrite = writeAuthoritative(projectRoot, 'decision-log.yaml', decisionBody, { dryRun });
 
-  let archiveDir = null;
-  if (archive && !dryRun) {
-    const storyKeys = Object.keys(state.byStory);
-    archiveDir = archiveShardsToLayer(projectRoot, layerId, storyKeys);
-  }
+    let archiveDir = null;
+    let archiveSkipped = [];
+    if (archive && !dryRun) {
+      const archResult = archiveShardsToLayer(projectRoot, layerId, {
+        state: state.snapshots,
+        'decision-log': decisions.snapshots,
+      });
+      archiveDir = archResult.dir;
+      archiveSkipped = archResult.skipped;
+    }
 
-  return {
-    state: { stories: Object.keys(state.byStory).length, problems: state.corrupt.length + state.invalid.length },
-    decisions: { entries: decisions.entries.length, problems: decisions.corrupt.length + decisions.invalid.length },
-    files: { state: stateWrite.file, decisions: decisionWrite.file },
-    archived_corrupt: archivedCorrupt,
-    archive_dir: archiveDir,
-    dry_run: !!dryRun,
-  };
+    return {
+      state: {
+        stories: Object.keys(state.byStory).length,
+        problems: state.corrupt.length + state.invalid.length,
+      },
+      decisions: {
+        entries: decisions.entries.length,
+        problems: decisions.corrupt.length + decisions.invalid.length,
+      },
+      files: { state: stateWrite.file, decisions: decisionWrite.file },
+      archived_corrupt: archivedCorrupt,
+      archive_dir: archiveDir,
+      archive_skipped: archiveSkipped,
+      dry_run: !!dryRun,
+    };
+  } finally {
+    releaseMergeLock(lockFile);
+  }
 }
 
 function main() {