claude-code-session-manager 0.98.0 → 0.101.0

package/src/main/lib/credentials.cjs

@@ -6,6 +6,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { spawn, execFileSync } = require('node:child_process');
 const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
+const atomicFs = require('./atomicFs.cjs');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
 
 const CREDS_PATH = path.join(os.homedir(), '.claude', '.credentials.json');
@@ -160,10 +161,7 @@ async function writeCredentials(rawData, freshOauth, source = 'file') {
     writeKeychainRaw(JSON.stringify(next));
     return;
   }
-  const tmp = `${CREDS_PATH}.${process.pid}.${Date.now()}.tmp`;
-  await fsp.writeFile(tmp, JSON.stringify(next, null, 2), { encoding: 'utf8', mode: 0o600 });
-  try { await fsp.chmod(tmp, 0o600); } catch { /* umask may have already set it */ }
-  await fsp.rename(tmp, CREDS_PATH);
+  await atomicFs.writeJsonAtomic(CREDS_PATH, next, { mode: 0o600, newline: false });
 }
 
 function appendRefreshLog(entry) {

package/src/main/lib/crossProjectFeedback.cjs

@@ -69,9 +69,9 @@ const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 const { resolveProjectContext } = require('./projectRootResolve.cjs');
 
 /** Only these three Epic tags make sense for an inbound report — they are
- *  exactly the tags that route through /develop (tagLibrary.ts). 'build',
- *  'project-home-builder' and 'bilko-host-publisher' name dedicated local
- *  pipelines and are meaningless as a request from another project. */
+ *  exactly the tags that route through /develop (tagLibrary.ts). 'build' and
+ *  'project-home-builder' name dedicated local pipelines and are meaningless
+ *  as a request from another project. */
 const FEEDBACK_TAGS = Object.freeze(['bug', 'feature', 'discussion']);
 const DEFAULT_FEEDBACK_TAG = 'discussion';
 

package/src/main/lib/cwdClassify.cjs

@@ -115,7 +115,9 @@ function inspectGit(start) {
   } catch {
     return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `worktree admin back-reference missing (${adminGitdirFile})` };
   }
-  if (path.resolve(backRef) !== path.resolve(gitPath)) {
+  // git records realpaths, so compare canonical spellings (macOS /var -> /private/var).
+  const canon = (q) => { try { return fs.realpathSync(q); } catch { return path.resolve(q); } };
+  if (path.resolve(backRef) !== path.resolve(gitPath) && canon(backRef) !== canon(gitPath)) {
     return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `worktree admin back-reference points elsewhere (${adminGitdirFile})` };
   }
   return { shape: 'worktree', dir: entry.dir, mainRoot: candidateMain, reason: 'linked worktree, back-reference verified' };
@@ -133,12 +135,22 @@ function worktreeMainRootOf(cwd) {
   return null;
 }
 
+// A root may be a symlink (macOS os.tmpdir() is /var -> /private/var) while callers hand us
+// either spelling (config.validatePath returns realpaths). Match on both the raw and the
+// canonical spelling of the root.
+function rootSpellings(root) {
+  const abs = path.resolve(root);
+  let real = abs;
+  try { real = fs.realpathSync(abs); } catch { /* root not created yet — raw spelling only */ }
+  return real === abs ? [abs] : [abs, real];
+}
+
 function isExactlyTmpdir(absCwd) {
-  return absCwd === path.resolve(os.tmpdir());
+  return rootSpellings(os.tmpdir()).includes(absCwd);
 }
 
 function isUnderManagedWorktreeRoot(absCwd) {
-  return ['job', 'epic'].map((k) => path.resolve(schedulerPaths.worktreeRoot(k))).some((root) => {
+  return ['job', 'epic'].flatMap((k) => rootSpellings(schedulerPaths.worktreeRoot(k))).some((root) => {
     const rel = path.relative(root, absCwd);
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
   });

package/src/main/lib/definitionOfDone.cjs

@@ -15,6 +15,7 @@ const { spawn, spawnSync } = require('node:child_process');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
 const schedulerPaths = require('./schedulerPaths.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 // Regex identifying meta/dod slugs that must NOT influence the batchKey.
 // This is the load-bearing loop-avoidance filter: when the gate job itself
@@ -89,10 +90,29 @@ function reportExists(key, runsDir = schedulerPaths.runsDir()) {
 
 const DEFAULT_GATE_TIMEOUT_MS = 300_000;
 
+// Any whitespace other than a plain space/tab, or a control char other than
+// tab — refused everywhere a gate chain is checked, quoted or not. Why: a
+// shell and this tokenizer must see the same bytes; plain `/\s/` would miss a
+// no-break space, U+2028/U+2029 or U+FEFF, which a shell treats as ordinary
+// (non-separator) characters inside a word.
+const FOREIGN_WHITESPACE_RE = /[^\S \t]|[\u0000-\u0008\u000A-\u001F\u007F]/;
+
+// Chars a shell treats specially — refused outside quotes. `#` and `~` are
+// handled on their own (they are fine in the middle of a word).
+const UNQUOTED_BAD_CHARS = '|<>;&`$\\*?[](){}!';
+
 /**
- * Quote-aware tokenizer for ONE command segment — no shell. Returns the argv
- * tokens, or null when an unquoted shell metacharacter survives (pipe,
- * redirect, `;`, lone `&`, backtick, `$(`/`${`) or a quote is unbalanced.
+ * Quote-aware tokenizer for ONE command segment — no shell. Returns
+ * `{ ok: true, tokens }`, or `{ ok: false, error }` when the segment needs a
+ * shell to run the same way a human would read it. Rules enforced (see
+ * explainChain's doc comment for the full numbered list):
+ *   - Outside quotes, only a space or tab separates words.
+ *   - Outside quotes, any char in UNQUOTED_BAD_CHARS is refused.
+ *   - An unquoted word may not start with `#` or `~`; `~` right after an
+ *     unquoted `=` or `:` is refused too (`a#b`, `HEAD~1` are fine).
+ *   - Inside double quotes, `$`, backtick and `\` are refused — a shell
+ *     would expand them. Inside single quotes, everything is literal.
+ *   - An unclosed quote is refused.
  * Complexity: O(n) over the segment's characters.
  */
 function tokenizeNoShell(seg) {
@@ -100,25 +120,51 @@ function tokenizeNoShell(seg) {
   let cur = '';
   let inTok = false;
   let quote = null;
+  let atWordStart = true;
+  let afterEqualsOrColon = false;
   for (let i = 0; i < seg.length; i++) {
     const c = seg[i];
     if (quote) {
-      if (c === quote) quote = null;
-      else cur += c;
+      if (c === quote) { quote = null; continue; }
+      if (quote === '"' && (c === '$' || c === '`' || c === '\\')) {
+        return { ok: false, error: `has "${c}" inside double quotes. A shell would expand it; the scheduler would not. Use single quotes.` };
+      }
+      cur += c;
       continue;
     }
-    if (c === '"' || c === "'") { quote = c; inTok = true; continue; }
-    if (/\s/.test(c)) {
+    if (c === '"' || c === "'") {
+      quote = c;
+      inTok = true;
+      atWordStart = false;
+      afterEqualsOrColon = false;
+      continue;
+    }
+    if (c === ' ' || c === '\t') {
       if (inTok) { tokens.push(cur); cur = ''; inTok = false; }
+      atWordStart = true;
+      afterEqualsOrColon = false;
       continue;
     }
-    if ('|<>;&`'.includes(c) || (c === '$' && (seg[i + 1] === '(' || seg[i + 1] === '{'))) return null;
+    if (c === '#' && atWordStart) {
+      return { ok: false, error: 'has a word that starts with "#". A shell reads it as a comment. Quote it.' };
+    }
+    if (c === '~' && (atWordStart || afterEqualsOrColon)) {
+      return {
+        ok: false,
+        error: 'has "~" at the start of a word or after "=" or ":". A shell would turn it into the home folder; the scheduler would not. Write the full path, or quote it.',
+      };
+    }
+    if (UNQUOTED_BAD_CHARS.includes(c)) {
+      return { ok: false, error: `has an unquoted "${c}". The scheduler runs gate commands without a shell. Put it inside single quotes, or move the check into a test file.` };
+    }
     cur += c;
     inTok = true;
+    atWordStart = false;
+    afterEqualsOrColon = c === '=' || c === ':';
   }
-  if (quote) return null;
+  if (quote) return { ok: false, error: 'has an unclosed quote.' };
   if (inTok) tokens.push(cur);
-  return tokens;
+  return { ok: true, tokens };
 }
 
 /**
@@ -145,37 +191,83 @@ function splitOnAndAnd(text) {
 }
 
 /**
- * Parse one `&&` chain into [{argv, timeoutMs, env, raw}]. Returns [] when any
- * segment is empty or needs a shell — a half-parsed gate must never run.
- * A leading `timeout N` (or `Ns`) token sets timeoutMs; leading literal
- * `NAME=value` tokens become env (a `TMPDIR=` assignment is dropped — the
- * shadow runner always supplies its own isolated TMPDIR; its value is
- * typically the un-runnable `$(mktemp -d)`, which is handled here without a
- * shell by simply never evaluating it).
+ * Explain whether a `&&`-joined command chain is a gate the scheduler can run
+ * without a shell, step by step. Rules, checked in this order (each failure
+ * returns its own `error`):
+ *   1. Any whitespace other than a plain space/tab, or a stray control char,
+ *      anywhere in the text (quoted or not).
+ *   2. An empty step (`a && && b`, a trailing `&&`).
+ *   3-9. tokenizeNoShell's rules, applied to each step in turn.
+ *   10. A step with no command left after `NAME=value` words and `timeout N`.
+ * "Start of a word" means the first char after a separator or the start of
+ * the step, when that char is unquoted — a word may mix quoted and unquoted
+ * parts, as in bash (`a'b c'd` is one word `ab cd`).
+ *
+ * @param {string} text
+ * @returns {{ok:true, steps:Array<{argv:string[],timeoutMs:number,env:object,raw:string}>, timeoutGiven:boolean[]}|{ok:false, error:string}}
  */
-function parseChain(text) {
-  const out = [];
-  for (const seg of splitOnAndAnd(text)) {
-    const raw = seg.trim();
-    if (!raw) return [];
-    // A dropped TMPDIR=$(mktemp -d) prefix is the one substitution we accept.
-    const stripped = raw.replace(/^TMPDIR=\$\(mktemp -d\)\s+/, '');
-    const tokens = tokenizeNoShell(stripped);
-    if (!tokens || !tokens.length) return [];
+function explainChain(text) {
+  if (FOREIGN_WHITESPACE_RE.test(text)) {
+    return {
+      ok: false,
+      error: 'has a character that is not a plain space or tab (for example a no-break space or a line break). Retype it.',
+    };
+  }
+
+  const steps = [];
+  const timeoutGiven = [];
+  const segs = splitOnAndAnd(text);
+  for (let i = 0; i < segs.length; i++) {
+    const stepNo = i + 1;
+    const raw = segs[i].trim();
+    if (!raw) return { ok: false, error: `step ${stepNo} is empty. Check the "&&" joins.` };
+    // A dropped TMPDIR=$(mktemp -d) prefix is the one substitution we accept
+    // — the shadow runner always supplies its own isolated TMPDIR, so the
+    // un-runnable `$(mktemp -d)` is handled here by simply never evaluating it.
+    const stripped = raw.replace(/^TMPDIR=\$\(mktemp -d\)[ \t]+/, '');
+    const tokenized = tokenizeNoShell(stripped);
+    if (!tokenized.ok) return { ok: false, error: tokenized.error };
+    const tokens = tokenized.tokens;
     const env = {};
     while (tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[0])) {
       const [k, ...rest] = tokens.shift().split('=');
       if (k !== 'TMPDIR') env[k] = rest.join('=');
     }
     let timeoutMs = DEFAULT_GATE_TIMEOUT_MS;
+    let hadTimeout = false;
     if (tokens[0] === 'timeout' && /^\d+s?$/.test(tokens[1] || '')) {
       timeoutMs = parseInt(tokens[1], 10) * 1000;
       tokens.splice(0, 2);
+      hadTimeout = true;
     }
-    if (!tokens.length) return [];
-    out.push({ argv: tokens, timeoutMs, env, raw });
+    if (!tokens.length) return { ok: false, error: `step ${stepNo} has no command after "timeout" or NAME=value.` };
+    steps.push({ argv: tokens, timeoutMs, env, raw });
+    timeoutGiven.push(hadTimeout);
   }
-  return out;
+  return { ok: true, steps, timeoutGiven };
+}
+
+/**
+ * Parse one `&&` chain into [{argv, timeoutMs, env, raw}]. Returns [] when any
+ * step is empty or needs a shell — a half-parsed gate must never run. See
+ * explainChain for the rules and the reason behind each refusal.
+ */
+function parseChain(text) {
+  const r = explainChain(text);
+  return r.ok ? r.steps : [];
+}
+
+/**
+ * True when `entry` is the literal opt-out `"none"` (case-insensitive, outer
+ * whitespace ignored) — nothing else. A near-miss (`"none."`, `"'none'"`,
+ * `"NONE!"`) is NOT none; a caller that accepts a quoted YAML form strips the
+ * quotes first (see readExplicitGate).
+ *
+ * @param {unknown} entry
+ * @returns {boolean}
+ */
+function isNoneGate(entry) {
+  return typeof entry === 'string' && /^none$/i.test(entry.trim());
 }
 
 /** Locate the `# Acceptance criteria` lines (whole body when the heading is absent). */
@@ -215,7 +307,10 @@ function readExplicitGate(prdText) {
       const m = fmLines[i].match(/^gate:\s*(.*)$/);
       if (!m) continue;
       const rest = m[1].trim();
-      if (/^(['"]?)none\1$/i.test(rest)) return { kind: 'none' };
+      // YAML quoting ('none' / "none") still reads as the opt-out — strip a
+      // matching pair of outer quotes, if present, before the isNoneGate test.
+      const unquotedRest = rest.replace(/^(['"])(.*)\1$/, '$2');
+      if (isNoneGate(unquotedRest)) return { kind: 'none' };
       const chains = [];
       if (rest.startsWith('[') && rest.endsWith(']')) {
         // Inline list — items may hold commas inside quotes, so split quote-aware.
@@ -241,7 +336,7 @@ function readExplicitGate(prdText) {
   const fence = prdText.match(/^```gate[ \t]*\r?\n([\s\S]*?)^```/m);
   if (fence) {
     const chains = fence[1].split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
-    if (chains.length === 1 && /^none$/i.test(chains[0])) return { kind: 'none' };
+    if (chains.length === 1 && isNoneGate(chains[0])) return { kind: 'none' };
     if (chains.length) return { kind: 'commands', chains };
   }
   return null;
@@ -254,7 +349,7 @@ function readExplicitGate(prdText) {
  * `timeout N`). Accepts the PRD with or without frontmatter.
  *
  * @param {string} prdText
- * @returns {{ source: 'none'|'explicit'|'ac-line'|'absent', sequence: Array<{argv:string[], timeoutMs:number, env:object, raw:string}> }}
+ * @returns {{ source: 'none'|'explicit'|'ac-line'|'ac-line-guess'|'absent', sequence: Array<{argv:string[], timeoutMs:number, env:object, raw:string}> }}
  */
 function resolveGate(prdText) {
   if (!prdText || typeof prdText !== 'string') return { source: 'absent', sequence: [] };
@@ -285,7 +380,9 @@ function resolveGate(prdText) {
       while (tokens.length > 4 && /^[a-z]+$/.test(tokens[tokens.length - 1])) tokens.pop();
       segs[segs.length - 1] = tokens.join(' ');
       const seq = parseChain(segs.join('&&'));
-      if (seq.length) return { source: 'ac-line', sequence: seq };
+      // The command's end is a guess here ("timeout 300 npm run typecheck
+      // passes" becomes `npm run`), so gate authority never trusts it.
+      if (seq.length) return { source: 'ac-line-guess', sequence: seq };
     }
   }
   return { source: 'absent', sequence: [] };
@@ -306,7 +403,8 @@ function extractAcSequence(prdBody) {
 /**
  * The single-command view of the gate, as the original `timeout NNN cmd …`
  * string, or null when the gate is absent or is a multi-command chain
- * (reverifyAc runs one command; the chain is the shadow runner's job).
+ * (reverifyAc runs the whole sequence; this view is for callers that only
+ * ever handle one command).
  *
  * @param {string} prdBody  PRD markdown with frontmatter already stripped.
  * @returns {string|null}
@@ -317,107 +415,98 @@ function extractAcCommand(prdBody) {
 }
 
 /**
- * Re-run the AC test command for a single completed job and report the result.
+ * Re-run a completed job's authored gate and report whether it still holds.
+ *
+ * Finds the PRD with `resolvePrdPath(job)`, a caller-injected async function
+ * that returns an absolute path or null. This never guesses a path itself.
+ * Why: a PRD lives in its Epic's `prds/` dir while queued and moves to that
+ * Epic's `prds-archived/` sibling once it completes — only the caller (which
+ * knows about Epics and archiving) can say which one applies.
  *
- * Never touches queue.json or spawns claude — only re-runs the already-authored
- * test command. That is what keeps this function loop-safe and cheap.
+ * Runs the resolved gate with `runGateSequence`, the same runner the
+ * scheduler's shadow gate uses: `&&` semantics, each run gets its own
+ * isolated TMPDIR and `CI=1`, and at most one gate runs machine-wide at a
+ * time. This never spawns `claude` and never writes to queue.json — it only
+ * re-runs the already-authored gate command.
+ *
+ * Result `status` meanings:
+ *   - `pass`         the gate went green.
+ *   - `fail`         a gate step exited non-zero, and it did not time out.
+ *   - `unverifiable` nothing ran, or the result can't be trusted. `reason`
+ *     says which: `no-prd-resolver` (opts.resolvePrdPath was not given),
+ *     `prd-not-found` (resolver returned null/threw), `prd-unreadable`
+ *     (resolved path doesn't exist or can't be read), `no-parseable-gate`
+ *     (PRD opted out with `gate: none`, or has no gate the scheduler can
+ *     run), `cwd-missing` (job.cwd no longer exists), `busy` (another gate
+ *     is already running — see runGateSequence), `gate-unavailable` (a step
+ *     could not even start), or `timeout` (a step hit its own `timeout N`
+ *     and was killed — not evidence either way, so it is not reported as a
+ *     failure).
  *
  * @param {{ slug: string, cwd: string }} job
- * @param {{ timeoutMs?: number, prdsDir?: string }} opts
- *   timeoutMs  Hard kill ceiling for the child (default 60s).
- *   prdsDir    Override PRD directory (for tests). Defaults to the job's own
- *              per-project PRDs dir (resolvePrdWriteDir(job.cwd)).
- * @returns {Promise<{ slug: string, status: 'pass'|'fail'|'unverifiable', code: number|null, ms: number }>}
+ * @param {{ resolvePrdPath?: (job: object) => (string|null|Promise<string|null>) }} opts
+ *   resolvePrdPath  Finds the PRD's current absolute path for this job.
+ *                    Required — with none, the result is always unverifiable.
+ * @returns {Promise<{ slug: string, status: 'pass'|'fail'|'unverifiable', code: number|null, ms: number, reason?: string }>}
  */
-function reverifyAc(job, { timeoutMs = 60_000, prdsDir } = {}) {
-  const resolvedPrdsDir = prdsDir ?? (job.cwd ? resolvePrdWriteDir(job.cwd) : null);
+async function reverifyAc(job, { resolvePrdPath } = {}) {
   const startNs = process.hrtime.bigint();
 
   function elapsedMs() {
     return Math.round(Number(process.hrtime.bigint() - startNs) / 1e6);
   }
 
-  function unverifiable() {
-    return { slug: job.slug, status: 'unverifiable', code: null, ms: elapsedMs() };
+  function unverifiable(reason) {
+    return { slug: job.slug, status: 'unverifiable', code: null, ms: elapsedMs(), reason };
   }
 
   // Guard: cwd must exist (target project may have been deleted).
   try {
     fs.statSync(job.cwd);
   } catch {
-    return Promise.resolve(unverifiable());
+    return unverifiable('cwd-missing');
   }
 
-  // Read and strip PRD frontmatter via the shared parser.
-  const prdPath = path.join(resolvedPrdsDir, `${job.slug}.md`);
-  let prdBody;
+  if (typeof resolvePrdPath !== 'function') return unverifiable('no-prd-resolver');
+
+  let prdPath;
   try {
-    const raw = fs.readFileSync(prdPath, 'utf8');
-    prdBody = splitFrontmatter(raw).body;
+    prdPath = await resolvePrdPath(job);
   } catch {
-    return Promise.resolve(unverifiable());
+    prdPath = null;
   }
+  if (!prdPath) return unverifiable('prd-not-found');
 
-  const cmd = extractAcCommand(prdBody);
-  if (!cmd) return Promise.resolve(unverifiable());
-
-  // Simple whitespace split — extractAcCommand already excludes
-  // commands that would need a shell (tokenizeNoShell). Paths with spaces are not expected in AC
-  // commands (PRD authoring convention: use relative paths from cwd).
-  const argv = cmd.trim().split(/\s+/);
-  if (argv.length < 2) return Promise.resolve(unverifiable());
-
-  return new Promise((resolve) => {
-    let settled = false;
-
-    let child;
-    try {
-      child = spawn(argv[0], argv.slice(1), {
-        cwd: job.cwd,
-        stdio: 'ignore',
-        // No shell:true — tokenizeNoShell rejects commands with shell metacharacters.
-      });
-    } catch (err) {
-      resolve(unverifiable());
-      return;
-    }
-
-    let escalate;
-    const killTimer = setTimeout(() => {
-      try { child.kill('SIGTERM'); } catch { /* already dead */ }
-      escalate = setTimeout(() => {
-        try { child.kill('SIGKILL'); } catch { /* race */ }
-      }, 5_000);
-      if (escalate.unref) escalate.unref();
-    }, timeoutMs);
-    if (killTimer.unref) killTimer.unref();
-
-    child.on('error', () => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(killTimer);
-      clearTimeout(escalate);
-      resolve(unverifiable());
-    });
+  // Read the raw PRD text, frontmatter included, and resolve its gate the
+  // same way the shadow gate does.
+  let raw;
+  try {
+    raw = fs.readFileSync(prdPath, 'utf8');
+  } catch {
+    return unverifiable('prd-unreadable');
+  }
 
-    child.on('close', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(killTimer);
-      clearTimeout(escalate);
-      const exitCode = typeof code === 'number' ? code : -1;
-      resolve({
-        slug: job.slug,
-        status: exitCode === 0 ? 'pass' : 'fail',
-        code: exitCode,
-        ms: elapsedMs(),
-      });
-    });
-  });
+  const { source, sequence } = resolveGate(raw);
+  if (source === 'none' || source === 'absent' || !sequence.length) return unverifiable('no-parseable-gate');
+
+  const result = await runGateSequence(sequence, { cwd: job.cwd });
+  if (result.status === 'green') return { slug: job.slug, status: 'pass', code: 0, ms: elapsedMs() };
+  if (result.status === 'busy') return unverifiable('busy');
+  if (result.status === 'unavailable') return unverifiable('gate-unavailable');
+
+  // status === 'red': a step exited non-zero. A step that was killed for
+  // running past its own `timeout N` is not trustworthy evidence of a real
+  // failure (the machine may just be slow right now), so it is reported as
+  // unverifiable instead of fail — same reasoning reverifyAc has always used
+  // for a step that couldn't even start.
+  const timedOutStep = result.results.find((r) => r.timedOut);
+  if (timedOutStep) return unverifiable('timeout');
+  const failedStep = result.results.find((r) => r.status === 'fail');
+  return { slug: job.slug, status: 'fail', code: failedStep ? failedStep.code : null, ms: elapsedMs() };
 }
 
 /**
- * Re-run AC commands sequentially over a batch of completed jobs.
+ * Re-run AC gates sequentially over a batch of completed jobs.
  *
  * Sequential execution respects the machine's max-3-concurrent rule — a drain
  * event that fires reverifyBatch is already consuming one slot; sequential
@@ -431,13 +520,12 @@ function reverifyAc(job, { timeoutMs = 60_000, prdsDir } = {}) {
  * by the scheduler queue size, not user-scaled data).
  *
  * @param {Array<{ slug: string, cwd: string }>} jobs
- * @param {{ timeoutMs?: number, batchTimeoutMs?: number, prdsDir?: string }} opts
- *   timeoutMs       Per-job kill ceiling (default 60s).
+ * @param {{ batchTimeoutMs?: number, resolvePrdPath?: (job: object) => (string|null|Promise<string|null>) }} opts
  *   batchTimeoutMs  Total wall-time cap for the whole batch (default 10m).
- *   prdsDir         Override PRD directory (for tests).
+ *   resolvePrdPath  Forwarded to reverifyAc for every job — see its doc comment.
  * @returns {Promise<Array<{ slug: string, status: string, code: number|null, ms: number }>>}
  */
-async function reverifyBatch(jobs, { timeoutMs = 60_000, batchTimeoutMs = 600_000, prdsDir } = {}) {
+async function reverifyBatch(jobs, { batchTimeoutMs = 600_000, resolvePrdPath } = {}) {
   const batchStartNs = process.hrtime.bigint();
   const results = [];
 
@@ -447,7 +535,7 @@ async function reverifyBatch(jobs, { timeoutMs = 60_000, batchTimeoutMs = 600_00
       results.push({ slug: job.slug, status: 'unverifiable', code: null, ms: 0 });
       continue;
     }
-    const result = await reverifyAc(job, { timeoutMs, prdsDir });
+    const result = await reverifyAc(job, { resolvePrdPath });
     results.push(result);
   }
 
@@ -560,18 +648,9 @@ function flagRiskySurfaces(jobs, { prdsDir, gitTimeoutMs = 10_000 } = {}) {
 }
 
 // ─── Atomic write helper ───────────────────────────────────────────────────────
-// Re-implements the tmp+rename recipe from config.cjs writeTextAtomic (sync
-// variant), avoiding an import of Electron IPC code in a pure-node context.
-// Cross-ref: src/main/config.cjs writeJsonSync (same pattern).
+// Delegates to atomicFs.cjs's tmp+rename recipe (pure-node, no Electron import).
 function _writeFileAtomic(absPath, text) {
-  const tmp = `${absPath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-  try {
-    fs.writeFileSync(tmp, text, 'utf8');
-    fs.renameSync(tmp, absPath);
-  } catch (err) {
-    try { fs.unlinkSync(tmp); } catch { /* tmp never created or already gone */ }
-    throw err;
-  }
+  atomicFs.writeTextAtomicSync(absPath, text);
 }
 
 const STATUS_EMOJI = { pass: '✅', fail: '❌', unverifiable: '⚠️' };
@@ -811,6 +890,9 @@ module.exports = {
   reportExists,
   extractAcCommand,
   extractAcSequence,
+  parseChain,
+  explainChain,
+  isNoneGate,
   resolveGate,
   runGateSequence,
   extractSection,

package/src/main/lib/dodDrainHook.cjs

@@ -47,14 +47,20 @@ const _inFlight = new Set();
  *
  * @param {{ paused: object|null, jobs: Array }} state   Scheduler queue state.
  * @param {{
- *   cancelToken?: { cancelled: boolean },
- *   prdsDir?:     string,
- *   runsDir?:     string,
+ *   cancelToken?:     { cancelled: boolean },
+ *   prdsDir?:         string,
+ *   runsDir?:         string,
+ *   resolvePrdPath?:  (job: object) => (string|null|Promise<string|null>),
  * }} opts
+ *   prdsDir         Forwarded to flagRiskySurfaces only (its own PRD lookup).
+ *   resolvePrdPath  Forwarded to reverifyBatch/reverifyAc — finds each job's
+ *                   PRD across the live Epic dir and its archive. Required
+ *                   for a real AC re-run; with none, every job in the report
+ *                   comes back unverifiable (see reverifyAc's doc comment).
  * @returns {Promise<void>}
  */
 async function runDefinitionOfDoneOnDrain(state, opts = {}) {
-  const { cancelToken = {}, prdsDir, runsDir } = opts;
+  const { cancelToken = {}, prdsDir, runsDir, resolvePrdPath } = opts;
 
   if (process.env.SM_DOD_DISABLE === '1') return;
   if (state.paused) return;
@@ -82,7 +88,7 @@ async function runDefinitionOfDoneOnDrain(state, opts = {}) {
 
   _inFlight.add(key);
   try {
-    const acResults = await reverifyBatch(completedJobs, { prdsDir });
+    const acResults = await reverifyBatch(completedJobs, { resolvePrdPath });
     // Re-check after the slow await — scheduler may have stopped mid-flight.
     if (cancelToken.cancelled) return;
     const riskFlags = flagRiskySurfaces(completedJobs, { prdsDir });

package/src/main/lib/epicMint.cjs

@@ -35,6 +35,7 @@ const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
 const { mirrorEpicStatus, removeEpicMirror } = require('./epicStatusMirror.cjs');
+const atomicFs = require('./atomicFs.cjs');
 const telemetryCounters = require('./telemetryCounters.cjs');
 // Required as the module object (not destructured) so a test can
 // monkeypatch promptSessionSchema.assertValidPromptSession in place to
@@ -106,10 +107,7 @@ function writeActiveIndex(cwd, index) {
   // holds a narrow delegation for active-index.json only (opsOwnership.cjs).
   assertOpsWrite(activeIndexPath(cwd), 'scheduler');
   const file = activeIndexPath(cwd);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(index, null, 2));
-  fs.renameSync(tmp, file);
+  atomicFs.writeJsonAtomicSync(file, index, { newline: false });
 }
 
 // index.sessions/index.events are plain objects parsed from JSON — bracket

package/src/main/lib/epicStatusMirror.cjs

@@ -15,18 +15,19 @@
  * file this module targets; a live (proposed/active) Epic gets a sparse
  * mirror here instead, later overwritten wholesale by the real archive.
  *
- * Raw fs tmp+rename — NOT config.cjs's `writeJson` — so this module stays
+ * Uses atomicFs.cjs (NOT config.cjs's `writeJson`) so this module stays
  * requirable from epicMint.cjs, which is deliberately Electron-free (its own
  * header: "so the external watchdog scripts can require it"; config.cjs
- * requires 'electron' at module load). The write shape matches config.cjs's
- * writeJson exactly (`JSON.stringify(data, null, 2) + '\n'`, `<path>.tmp-
- * <pid>` then rename) so main-process callers (activeIndexMerge.cjs) and
- * epicMint.cjs never diverge in format despite using different write paths.
+ * requires 'electron' at module load — atomicFs.cjs does not). The write
+ * shape matches config.cjs's writeJson exactly (`JSON.stringify(data, null,
+ * 2) + '\n'`, tmp-then-rename) so main-process callers (activeIndexMerge.cjs)
+ * and epicMint.cjs never diverge in format despite using different write
+ * paths — both go through the same atomicFs primitive now.
  */
 
 const fs = require('node:fs');
-const path = require('node:path');
 const { assertOpsWrite, opsPath } = require('./opsOwnership.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 function epicMirrorPath(cwd, epicId) {
   return opsPath(cwd, 'prompt-sessions', `${epicId}.json`);
@@ -74,10 +75,7 @@ function mirrorEpicStatus(cwd, epicId, { session = null, status = null, archived
     archivedAt: archivedAt ?? existing.archivedAt ?? null,
     indexedAt: new Date().toISOString(),
   };
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const tmp = `${file}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n');
-  fs.renameSync(tmp, file);
+  atomicFs.writeJsonAtomicSync(file, merged);
 }
 
 /**