mandrel 2.36.0 → 2.38.0

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -7,7 +7,7 @@
  * on a Windows lock-class failure, the entry is appended to
  * `.worktrees/.pending-cleanup.json`. The plan-time `worktree-sweep.js`
  * reader (shipped in Epic #349) picks up the manifest on the next
- * `/plan` run and retries removal
+ * `/mandrel-plan` run and retries removal
  * (`git worktree remove` then `fs.rm`) — by then the live file handles from Node / AV / the Windows
  * Search indexer are almost always gone. If `MAX_SWEEP_ATTEMPTS` elapses
  * without clearing, an `OPERATOR ACTION REQUIRED: persistent-lock` line
@@ -15,14 +15,39 @@
  *
  * The manifest itself lives under `.worktrees/`, which is already
  * git-ignored; no tracked state is mutated.
+ *
+ * **Story #5112 — the manifest is shared mutable state.** `recordPendingCleanup`
+ * runs from the close reap and `drainPendingCleanup` runs from the `/mandrel-plan`
+ * boot, so two concurrent delivery sessions can read-modify-write the same
+ * file. Three properties close that:
+ *
+ *   1. **Atomic write.** Every write lands in a pid-scoped temp file and is
+ *      then `rename`d over the manifest, so a reader never observes a half-
+ *      written array (`readManifest` treats a torn or absent file as empty,
+ *      which used to silently *drop* the backlog).
+ *   2. **Mutual exclusion.** Read-modify-write runs under the shared
+ *      `acquireSweepLock` primitive on a manifest-adjacent lockfile.
+ *   3. **Merge before write.** The drain holds its snapshot across awaited
+ *      removals, so it re-reads and merges by `storyId` before its final
+ *      write — an entry recorded mid-drain survives instead of being erased
+ *      by a stale snapshot.
  */
 
 import fs from 'node:fs';
 import { rm as fsPromisesRm } from 'node:fs/promises';
 import path from 'node:path';
 import { NOOP_LOGGER } from '../../Logger.js';
+import { acquireSweepLock } from '../../single-story-sweep/sweep-lock.js';
 
 const MANIFEST_FILENAME = '.pending-cleanup.json';
+const MANIFEST_LOCK_FILENAME = '.pending-cleanup.lock';
+
+/**
+ * Staleness threshold for the manifest lock. Deliberately short: the guarded
+ * section is a read, an in-memory merge and a rename — milliseconds — so a
+ * lockfile older than this is a crashed holder, not a slow one.
+ */
+const MANIFEST_LOCK_TIMEOUT_MS = 5_000;
 /**
  * After a reap hands off to the manifest, `attempts` counts failed
  * `drainPendingCleanup` passes (initial hand-off uses `attempts: 0`). The entry
@@ -35,6 +60,49 @@ export function manifestPath(worktreeRoot) {
   return path.join(worktreeRoot, MANIFEST_FILENAME);
 }
 
+/**
+ * Path of the lockfile guarding manifest read-modify-write. Manifest-adjacent
+ * (same gitignored `.worktrees/` directory) so it needs no extra config and
+ * shares the manifest's lifetime. Module-private: the lock is internal to
+ * this manifest's read-modify-write, and callers only ever observe that a
+ * mutation completed and left nothing behind.
+ *
+ * @param {string} worktreeRoot
+ * @returns {string}
+ */
+function manifestLockPath(worktreeRoot) {
+  return path.join(worktreeRoot, MANIFEST_LOCK_FILENAME);
+}
+
+/**
+ * Run `fn` under the manifest lock. Best-effort in the same sense as every
+ * other use of this primitive: on contention the work still runs (the
+ * merge-before-write below is what makes a lost race non-destructive), so a
+ * stuck lockfile can never wedge a reap. Always releases.
+ *
+ * @template T
+ * @param {string} worktreeRoot
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withManifestLock(worktreeRoot, fn) {
+  const lock = acquireSweepLock({
+    lockPath: manifestLockPath(worktreeRoot),
+    timeoutMs: MANIFEST_LOCK_TIMEOUT_MS,
+  });
+  try {
+    return fn();
+  } finally {
+    if (lock.acquired) {
+      try {
+        lock.release();
+      } catch {
+        // Release is best-effort; a stale lockfile expires on its own.
+      }
+    }
+  }
+}
+
 export function readManifest(worktreeRoot) {
   const p = manifestPath(worktreeRoot);
   if (!fs.existsSync(p)) return [];
@@ -47,6 +115,13 @@ export function readManifest(worktreeRoot) {
   }
 }
 
+/**
+ * Write the manifest atomically: serialize into a pid-scoped temp file in the
+ * same directory (so `rename` stays within one filesystem and is therefore
+ * atomic), then rename it over the manifest. A concurrent reader sees either
+ * the whole previous manifest or the whole new one — never a truncated array
+ * that `readManifest`'s catch would silently turn into "no pending cleanups".
+ */
 function writeManifest(worktreeRoot, entries) {
   const p = manifestPath(worktreeRoot);
   if (!Array.isArray(entries) || entries.length === 0) {
@@ -58,7 +133,37 @@ function writeManifest(worktreeRoot, entries) {
     return;
   }
   fs.mkdirSync(worktreeRoot, { recursive: true });
-  fs.writeFileSync(p, `${JSON.stringify(entries, null, 2)}\n`, 'utf8');
+  writeFileAtomic(p, `${JSON.stringify(entries, null, 2)}\n`);
+}
+
+/**
+ * Write `contents` to `targetPath` atomically: serialize into a pid-scoped
+ * temp file beside it (same directory, so the rename stays within one
+ * filesystem and is therefore atomic), then rename it into place. On failure
+ * the temp file is reaped and the error propagates — a half-written file is
+ * never left where a reader could pick it up.
+ *
+ * @param {string} targetPath
+ * @param {string} contents
+ */
+function writeFileAtomic(targetPath, contents) {
+  const tmp = `${targetPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, contents, 'utf8');
+    fs.renameSync(tmp, targetPath);
+  } catch (err) {
+    reapTempFile(tmp);
+    throw err;
+  }
+}
+
+/** Best-effort removal of an abandoned atomic-write temp file. */
+function reapTempFile(tmp) {
+  try {
+    fs.unlinkSync(tmp);
+  } catch {
+    // Temp file already gone (or never created) — nothing to reap.
+  }
 }
 
 /**
@@ -71,38 +176,45 @@ export function recordPendingCleanup(
   worktreeRoot,
   { storyId, branch, path: wtPath, push = false },
 ) {
-  const now = new Date().toISOString();
-  const entries = readManifest(worktreeRoot);
-  const idx = entries.findIndex((e) => e.storyId === storyId);
-  if (idx >= 0) {
-    entries[idx] = {
-      ...entries[idx],
-      branch,
-      path: wtPath,
-      push,
-      lastFailedAt: now,
-      attempts: (entries[idx].attempts ?? 0) + 1,
-    };
-  } else {
-    entries.push({
-      storyId,
-      branch,
-      path: wtPath,
-      push,
-      firstFailedAt: now,
-      lastFailedAt: now,
-      attempts: 0,
-    });
-  }
-  writeManifest(worktreeRoot, entries);
-  return entries.find((e) => e.storyId === storyId);
+  // The read, the merge and the write are one critical section: without the
+  // lock a concurrent drain's write can land between our read and our write
+  // and erase this hand-off entirely.
+  return withManifestLock(worktreeRoot, () => {
+    const now = new Date().toISOString();
+    const entries = readManifest(worktreeRoot);
+    const idx = entries.findIndex((e) => e.storyId === storyId);
+    if (idx >= 0) {
+      entries[idx] = {
+        ...entries[idx],
+        branch,
+        path: wtPath,
+        push,
+        lastFailedAt: now,
+        attempts: (entries[idx].attempts ?? 0) + 1,
+      };
+    } else {
+      entries.push({
+        storyId,
+        branch,
+        path: wtPath,
+        push,
+        firstFailedAt: now,
+        lastFailedAt: now,
+        attempts: 0,
+      });
+    }
+    writeManifest(worktreeRoot, entries);
+    return entries.find((e) => e.storyId === storyId);
+  });
 }
 
 export function removePendingCleanup(worktreeRoot, storyId) {
-  const entries = readManifest(worktreeRoot).filter(
-    (e) => e.storyId !== storyId,
-  );
-  writeManifest(worktreeRoot, entries);
+  withManifestLock(worktreeRoot, () => {
+    const entries = readManifest(worktreeRoot).filter(
+      (e) => e.storyId !== storyId,
+    );
+    writeManifest(worktreeRoot, entries);
+  });
 }
 
 async function removeStuckWorktreePath(wtPath, { git, repoRoot, fsRm }) {
@@ -176,6 +288,32 @@ async function retryStage1ForEntry(entry, ctx) {
   return { success: true, ...cleanup };
 }
 
+/**
+ * Write the drain's result, merged against whatever the manifest holds *now*.
+ *
+ * The drain awaits a removal per entry, so its `entries` snapshot can be
+ * minutes old by the time it writes. Writing that snapshot back wholesale
+ * erased any entry a concurrent `recordPendingCleanup` added mid-drain — the
+ * exact hand-off that reap had just decided it could not complete. Merging by
+ * `storyId` keeps it: rows this pass re-computed win, rows it successfully
+ * drained are dropped, and everything else the manifest has gained survives.
+ *
+ * @param {string} worktreeRoot
+ * @param {object[]} next          Rows this drain re-computed (still pending).
+ * @param {Set<number|string>} drainedIds Story ids this drain cleared.
+ */
+function commitDrainedManifest(worktreeRoot, next, drainedIds) {
+  withManifestLock(worktreeRoot, () => {
+    const byId = new Map(next.map((entry) => [entry.storyId, entry]));
+    for (const entry of readManifest(worktreeRoot)) {
+      if (byId.has(entry.storyId)) continue;
+      if (drainedIds.has(entry.storyId)) continue;
+      byId.set(entry.storyId, entry);
+    }
+    writeManifest(worktreeRoot, [...byId.values()]);
+  });
+}
+
 /**
  * Drain the pending-cleanup manifest: for each entry, retry Stage 1
  * cleanup. Successful entries are removed; failing entries have their
@@ -252,7 +390,7 @@ export async function drainPendingCleanup({
     next.push(updated);
   }
 
-  writeManifest(worktreeRoot, next);
+  commitDrainedManifest(worktreeRoot, next, new Set(drained));
   return {
     drained,
     drainedDetails,

package/.agents/scripts/lib/worktree/node-modules-strategy.js

@@ -401,10 +401,7 @@ export function describeAttemptFailure(result, timeoutMs) {
 }
 
 /** Relative path of the per-machine pnpm-store prime sentinel (under tempRoot). */
-export const PNPM_STORE_PRIME_SENTINEL = path.join(
-  'temp',
-  '.pnpm-store-primed',
-);
+const PNPM_STORE_PRIME_SENTINEL = path.join('temp', '.pnpm-store-primed');
 
 /**
  * Pure: one-time per-machine pnpm content-addressable-store prime.
@@ -424,7 +421,7 @@ export const PNPM_STORE_PRIME_SENTINEL = path.join(
  *
  * @returns {{ primed: 'primed' | 'cached' | 'failed' | 'skipped', reason?: string }}
  */
-export function primePnpmStore({
+function primePnpmStore({
   strategy,
   repoRoot,
   logger,

package/.agents/scripts/lint-issue-body.js

@@ -10,8 +10,8 @@
  * human files a ticket whose body `parse()` rejects (or which lacks the
  * binding `goal` / `acceptance` / `verify` sections), the lint surfaces a
  * **comment** on the issue rather than failing silently — the supported
- * human entry points (`/plan` from an existing Epic ID, the qa-assist →
- * `/plan` handoff) depend on a parseable body.
+ * human entry points (`/mandrel-plan` from an existing Epic ID, the qa-assist →
+ * `/mandrel-plan` handoff) depend on a parseable body.
  *
  * ## Design
  *
@@ -157,7 +157,7 @@ export function renderConformanceComment(verdict) {
     '### ⚠️ Ticket body does not round-trip through the Mandrel parser',
     '',
     'Agents build ticket bodies from a canonical schema that this body does ' +
-      'not match, so the supported human entry points (e.g. `/plan` from an ' +
+      'not match, so the supported human entry points (e.g. `/mandrel-plan` from an ' +
       'existing Epic ID) will reject it. Please fix the following:',
     '',
     ...verdict.problems.map((p) => `- ${p}`),

package/.agents/scripts/plan-context.js

@@ -2,9 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * plan-context.js — step 1 of the collapsed `/plan` pipeline.
+ * plan-context.js — step 1 of the collapsed `/mandrel-plan` pipeline.
  *
- * Emits one stdout-pure JSON envelope for the `/plan` authoring middle.
+ * Emits one stdout-pure JSON envelope for the `/mandrel-plan` authoring middle.
  *
  * Two operator modes (exactly one is required):
  *
@@ -25,7 +25,7 @@
  *
  * Flags:
  *   --out <path>     Write the envelope to <path> (parent dirs created).
- *                    `/plan` points this at `<plan-dir>/plan-context.json`,
+ *                    `/mandrel-plan` points this at `<plan-dir>/plan-context.json`,
  *                    which is where `plan-persist.js` auto-discovers the
  *                    `--tickets` source ids from (Story #4554). Without a
  *                    captured envelope persist cannot know a `--tickets` run
@@ -348,7 +348,7 @@ runAsCli(import.meta.url, main, {
     invocation:
       'node .agents/scripts/plan-context.js (--seed "<text>" | --seed-file <path> | --tickets <ids> | --amends <id>) [--out <path>] [--pretty]',
     summary:
-      'Build the /plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
+      'Build the /mandrel-plan authoring-context envelope on stdout. Exactly one entry form must be supplied.',
     flags: [
       ['--seed "<text>"', 'Inline seed prose.'],
       ['--seed-file <path>', 'Seed document to read.'],

package/.agents/scripts/plan-critics.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * plan-critics.js — the /plan critic-dispatch verdict CLI (Story #4592).
+ * plan-critics.js — the /mandrel-plan critic-dispatch verdict CLI (Story #4592).
  *
- * `/plan` step 2.5 (between Author and Persist) runs this against the draft
+ * `/mandrel-plan` step 2.5 (between Author and Persist) runs this against the draft
  * `stories.json`. It evaluates the consolidation + pre-mortem dispatch
  * conditions and prints the verdict as JSON on stdout so the workflow can
  * act on it — dispatching a fresh-context critic sub-agent and folding its

package/.agents/scripts/plan-persist.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * plan-persist.js — flat Story GitHub-write surface for v2 `/plan`
+ * plan-persist.js — flat Story GitHub-write surface for v2 `/mandrel-plan`
  * (Stage 3 — `docs/roadmap.md`).
  *
  * Given the author-written planning artifacts (`stories.json`, optional shared
@@ -201,7 +201,7 @@ async function loadArtifacts(paths) {
  *
  * Exported for tests: this is the join where the envelope-derived source ids
  * meet the persist engine, so a regression here silently un-wires
- * `/plan --tickets` superseding (Story #4554).
+ * `/mandrel-plan --tickets` superseding (Story #4554).
  *
  * @param {object} values Parsed `parseArgs` values.
  * @param {ReturnType<typeof resolveInputPaths>} paths

package/.agents/scripts/plan-run-epilogue.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * plan-run-epilogue.js — execute the real per-run closeout for a
- * multi-Story `/deliver`.
+ * multi-Story `/mandrel-deliver`.
  *
  * Usage:
  *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
@@ -67,7 +67,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   // along with the label itself. The epilogue is keyed on the delivered id
   // set, and the synthesized `adhoc-<ids>` id it already used for positional
   // runs is now the only id it needs.
-  // Range tokens expand here too (`--stories 101-104`): /deliver blesses the
+  // Range tokens expand here too (`--stories 101-104`): /mandrel-deliver blesses the
   // dash range at the operator surface, so the id set the epilogue is keyed on
   // must read the same shape. Rejecting a bad token is deliberate — the old
   // silent filter turned a typo into an empty, wrongly-keyed rollup.