claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/lib/cwdClassify.cjs

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * cwdClassify.cjs — THE one answer to "what project is this path?".
+ *
+ * activeSessions.projectRootOf, ephemeralCwd.isEphemeralCwd and
+ * opsOwnership.resolveProjectRoot each used to re-derive that answer and each
+ * failed OPEN: when a worktree's `.git` FILE survives but its admin-dir
+ * back-reference is gone, worktreeMainRootOf returned null, projectRootOf
+ * handed the worktree path back unchanged, isLinkedWorktreeRoot said false, and
+ * resolveOpsRoot built `<worktree>/session-manager-operations` — the shape
+ * behind the lost-Epics incidents. classifyCwd reports BOTH facts (which
+ * project, and how sure we are) so a caller can refuse WRITES for the
+ * unprovable case (`unknown`) while dispatch and reads carry on.
+ *
+ * Kinds:
+ *   worktree  — `.git` is a FILE whose gitdir sits under `<main>/.git/worktrees/`
+ *               AND the main tree's admin dir back-references it (round trip).
+ *               projectRoot = <main>.
+ *   project   — `.git` is a directory, OR a FILE whose gitdir is NOT under a
+ *               worktrees/ dir (separate-git-dir / submodule), OR no `.git` at
+ *               all. projectRoot = the dir holding `.git` (else the cwd).
+ *   ephemeral — os.tmpdir() itself, or inside a managed job/epic worktree root,
+ *               and not provably a live worktree.
+ *   unknown   — a `.git` FILE we cannot resolve (garbled, unreadable, worktrees
+ *               gitdir with a missing/mismatched back-reference). projectRoot is
+ *               the (ops-truncated) cwd unchanged; ops WRITES must be refused.
+ *
+ * Two ops-root facts are returned and deliberately NOT unified:
+ *   outermostOpsRoot — first `session-manager-operations` segment (indexOf).
+ *       activeSessions truncates here: a stray nested ops root is itself the bug.
+ *   innermostOpsRoot — last segment (lastIndexOf). opsOwnership.assertOpsWrite
+ *       derives the project a write targets from here.
+ *   Both are null when the path is not inside an ops root.
+ *
+ * Pure fs, synchronous, never throws. Must stay light — required by
+ * scripts/hooks/guard-inline-implementation.cjs (via nearestGitEntry) and
+ * activeSessions.cjs; no gitWorktree/config requires.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const schedulerPaths = require('./schedulerPaths.cjs');
+
+const OPS_DIRNAME = 'session-manager-operations';
+const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+// Bound on the ancestor walk — past any real fs depth, guarantees termination.
+const MAX_WALK = 40;
+
+/**
+ * nearestGitEntry(cwd) → { dir, isFile } for the nearest ancestor-or-self that
+ * has a `.git` entry (`isFile` true = linked worktree / submodule pointer file),
+ * or null. The tiny pure helper for callers that must not load git tooling.
+ */
+function nearestGitEntry(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < MAX_WALK; i++) {
+    let stat = null;
+    try { stat = fs.statSync(path.join(dir, '.git')); } catch { /* none here */ }
+    if (stat) return { dir, isFile: stat.isFile() };
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Classify the git shape at/above `start`. O(depth) stats + ≤2 small reads.
+ * → { shape: 'none' | 'gitdir' | 'worktree' | 'separate' | 'unknown', dir, mainRoot, reason }
+ */
+function inspectGit(start) {
+  const entry = nearestGitEntry(start);
+  if (!entry) return { shape: 'none', dir: null, mainRoot: null, reason: 'no .git found' };
+  if (!entry.isFile) return { shape: 'gitdir', dir: entry.dir, mainRoot: null, reason: '.git is a directory' };
+
+  const gitPath = path.join(entry.dir, '.git');
+  let body;
+  try {
+    body = fs.readFileSync(gitPath, 'utf8');
+  } catch (e) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `unreadable .git file: ${e?.code || e?.message}` };
+  }
+  const firstLine = body.split('\n', 1)[0].trim();
+  if (!firstLine.startsWith('gitdir:')) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: '.git file has no "gitdir:" line' };
+  }
+  const gitdirRaw = firstLine.slice('gitdir:'.length).trim();
+  if (!gitdirRaw) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: '.git file has an empty gitdir' };
+  }
+  // Submodules point at a RELATIVE gitdir; resolve against the file's own dir.
+  const gitdir = path.resolve(entry.dir, gitdirRaw);
+  const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
+  if (markerIdx === -1) {
+    // Not a linked worktree: separate-git-dir / submodule. Its own project.
+    return { shape: 'separate', dir: entry.dir, mainRoot: null, reason: 'gitdir is not under .git/worktrees/ (separate-git-dir or submodule)' };
+  }
+  if (markerIdx <= 0) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: 'gitdir worktrees marker has no main root above it' };
+  }
+  const candidateMain = gitdir.slice(0, markerIdx);
+  const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
+  if (!worktreeName) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: 'gitdir names no worktree' };
+  }
+  // Round-trip: the .git file is plain text anything could have written, so it
+  // must not redirect callers to an arbitrary path. The main tree's own admin
+  // dir must point back at THIS .git file.
+  const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
+  let backRef;
+  try {
+    backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
+  } catch {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `worktree admin back-reference missing (${adminGitdirFile})` };
+  }
+  if (path.resolve(backRef) !== path.resolve(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' };
+}
+
+/**
+ * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
+ * verified linked worktree, the ancestor itself when `.git` is a directory,
+ * else null (no git, separate-git-dir, or anything unprovable).
+ */
+function worktreeMainRootOf(cwd) {
+  const g = inspectGit(cwd);
+  if (g.shape === 'worktree') return g.mainRoot;
+  if (g.shape === 'gitdir') return g.dir;
+  return null;
+}
+
+function isExactlyTmpdir(absCwd) {
+  return absCwd === path.resolve(os.tmpdir());
+}
+
+function isUnderManagedWorktreeRoot(absCwd) {
+  return ['job', 'epic'].map((k) => path.resolve(schedulerPaths.worktreeRoot(k))).some((root) => {
+    const rel = path.relative(root, absCwd);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  });
+}
+
+/**
+ * classifyCwd(cwd) → { kind, projectRoot, outermostOpsRoot, innermostOpsRoot, reason }
+ * See the file header. A non-string/empty cwd is `unknown` with a null root.
+ */
+function classifyCwd(cwd) {
+  if (!cwd || typeof cwd !== 'string') {
+    return { kind: 'unknown', projectRoot: null, outermostOpsRoot: null, innermostOpsRoot: null, reason: 'cwd is not a non-empty string' };
+  }
+  const parts = cwd.split(path.sep);
+  const first = parts.indexOf(OPS_DIRNAME);
+  const last = parts.lastIndexOf(OPS_DIRNAME);
+  const opsAt = (i) => (i >= 0 ? (parts.slice(0, i + 1).join(path.sep) || path.sep) : null);
+  const outermostOpsRoot = opsAt(first);
+  const innermostOpsRoot = opsAt(last);
+  // Outermost truncation (the activeSessions law). i === 0 is a relative
+  // fragment, never truncated.
+  const truncated = first > 0 ? (parts.slice(0, first).join(path.sep) || path.sep) : cwd;
+
+  const g = inspectGit(truncated);
+  const facts = { outermostOpsRoot, innermostOpsRoot };
+  if (g.shape === 'worktree') {
+    return { kind: 'worktree', projectRoot: g.mainRoot, ...facts, reason: g.reason };
+  }
+  if (path.isAbsolute(cwd)) {
+    const abs = path.resolve(cwd);
+    if (isExactlyTmpdir(abs) || isUnderManagedWorktreeRoot(abs)) {
+      return { kind: 'ephemeral', projectRoot: truncated, ...facts, reason: 'tmpdir or managed job/epic worktree root' };
+    }
+  }
+  if (g.shape === 'unknown') {
+    return { kind: 'unknown', projectRoot: truncated, ...facts, reason: g.reason };
+  }
+  if (g.shape === 'none') {
+    return { kind: 'project', projectRoot: truncated, ...facts, reason: g.reason };
+  }
+  return { kind: 'project', projectRoot: g.dir, ...facts, reason: g.reason };
+}
+
+module.exports = { classifyCwd, nearestGitEntry, worktreeMainRootOf, OPS_DIRNAME };

package/src/main/lib/definitionOfDone.cjs

@@ -91,41 +91,104 @@ function reportExists(key, runsDir = RUNS_DIR) {
   return false;
 }
 
-// Shell metacharacters that require shell:true — prohibited by CLAUDE.md for
-// non-user-supplied strings. Commands containing these are marked unverifiable
-// rather than running under a shell, since CLAUDE.md restricts shell:true to
-// watchers.cjs and app:test-fire-hook only.
-const SHELL_META_RE = /[|>&;<`]|\$[({]/;
+const DEFAULT_GATE_TIMEOUT_MS = 300_000;
 
 /**
- * Extract the first bounded AC test command from a PRD body.
- *
- * Searches the # Acceptance criteria section for lines containing a
- * `timeout NNN cmd [args...]` invocation. Returns the command string or null.
- *
- * Commands containing shell metacharacters (pipe, redirect, subshell) are
- * skipped — they cannot be run without shell:true which is prohibited here.
- * The parser falls through to the next AC line in that case.
- *
- * Complexity: O(L) where L = number of lines in the body (not user-scaled;
- * PRD bodies are bounded documents, typically < 200 lines).
- *
- * @param {string} prdBody  PRD markdown with frontmatter already stripped.
- * @returns {string|null}
+ * 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.
+ * Complexity: O(n) over the segment's characters.
  */
-function extractAcCommand(prdBody) {
-  if (!prdBody || typeof prdBody !== 'string') return null;
+function tokenizeNoShell(seg) {
+  const tokens = [];
+  let cur = '';
+  let inTok = false;
+  let quote = null;
+  for (let i = 0; i < seg.length; i++) {
+    const c = seg[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else cur += c;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; inTok = true; continue; }
+    if (/\s/.test(c)) {
+      if (inTok) { tokens.push(cur); cur = ''; inTok = false; }
+      continue;
+    }
+    if ('|<>;&`'.includes(c) || (c === '$' && (seg[i + 1] === '(' || seg[i + 1] === '{'))) return null;
+    cur += c;
+    inTok = true;
+  }
+  if (quote) return null;
+  if (inTok) tokens.push(cur);
+  return tokens;
+}
+
+/**
+ * Split a command chain on `&&` outside quotes and backticks.
+ * Complexity: O(n).
+ */
+function splitOnAndAnd(text) {
+  const segs = [];
+  let cur = '';
+  let quote = null;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quote) {
+      cur += c;
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; cur += c; continue; }
+    if (c === '&' && text[i + 1] === '&') { segs.push(cur); cur = ''; i++; continue; }
+    cur += c;
+  }
+  segs.push(cur);
+  return segs;
+}
+
+/**
+ * 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).
+ */
+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 [];
+    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;
+    if (tokens[0] === 'timeout' && /^\d+s?$/.test(tokens[1] || '')) {
+      timeoutMs = parseInt(tokens[1], 10) * 1000;
+      tokens.splice(0, 2);
+    }
+    if (!tokens.length) return [];
+    out.push({ argv: tokens, timeoutMs, env, raw });
+  }
+  return out;
+}
 
-  // Parse line-by-line to locate the # Acceptance criteria section.
-  // A regex lookahead approach with the `m` flag misidentifies `$` as
-  // end-of-line (not end-of-string), causing the lazy capture to terminate
-  // immediately. Line-by-line parsing avoids that pitfall.
-  const lines = prdBody.split('\n');
+/** Locate the `# Acceptance criteria` lines (whole body when the heading is absent). */
+function acCandidateLines(body) {
+  const lines = body.split('\n');
   let inAcSection = false;
   let hasAcSection = false;
   let acHeadingLevel = 0;
   const acLines = [];
-
   for (const line of lines) {
     if (/^#+\s/i.test(line)) {
       const level = line.match(/^(#+)/)[1].length;
@@ -134,42 +197,127 @@ function extractAcCommand(prdBody) {
         hasAcSection = true;
         acHeadingLevel = level;
       } else if (inAcSection && level <= acHeadingLevel) {
-        // A sibling or parent heading ends the AC section;
-        // sub-headings (level > acHeadingLevel) stay inside it.
         inAcSection = false;
       }
       continue;
     }
     if (inAcSection) acLines.push(line);
   }
+  return hasAcSection ? acLines : lines;
+}
 
-  // Fall back to full body if no AC section header was found.
-  const candidates = hasAcSection ? acLines : lines;
+/**
+ * Read an explicit gate spec: frontmatter `gate:` (`none`, inline `[a, b]`, or
+ * a `- item` list) or a fenced ```gate block (one command chain per line).
+ * Returns { kind: 'none' } | { kind: 'commands', chains: string[] } | null.
+ */
+function readExplicitGate(prdText) {
+  const fmMatch = prdText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (fmMatch) {
+    const fmLines = fmMatch[1].split(/\r?\n/);
+    for (let i = 0; i < fmLines.length; i++) {
+      const m = fmLines[i].match(/^gate:\s*(.*)$/);
+      if (!m) continue;
+      const rest = m[1].trim();
+      if (/^(['"]?)none\1$/i.test(rest)) return { kind: 'none' };
+      const chains = [];
+      if (rest.startsWith('[') && rest.endsWith(']')) {
+        // Inline list — items may hold commas inside quotes, so split quote-aware.
+        let cur = ''; let q = null;
+        for (const c of rest.slice(1, -1)) {
+          if (q) { if (c === q) q = null; else cur += c; continue; }
+          if (c === '"' || c === "'") { q = c; continue; }
+          if (c === ',') { chains.push(cur.trim()); cur = ''; continue; }
+          cur += c;
+        }
+        chains.push(cur.trim());
+      } else if (rest === '') {
+        for (let j = i + 1; j < fmLines.length; j++) {
+          const li = fmLines[j].match(/^\s+-\s+(.*)$/);
+          if (!li) break;
+          chains.push(li[1].trim().replace(/^(['"])(.*)\1$/, '$2'));
+        }
+      }
+      const kept = chains.filter(Boolean);
+      if (kept.length) return { kind: 'commands', chains: kept };
+    }
+  }
+  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) return { kind: 'commands', chains };
+  }
+  return null;
+}
 
-  for (const line of candidates) {
-    // Prefer backtick-delimited inline code: `timeout NNN cmd ...`
-    const backtickMatch = line.match(/`(timeout\s+\d+\s+[^`]+)`/i);
+/**
+ * Resolve a PRD's gate: explicit spec first (frontmatter `gate:` / ```gate
+ * fence), else the first acceptance-criteria line carrying a parseable
+ * `timeout N …` chain (backtick span preferred, else bare from the first
+ * `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}> }}
+ */
+function resolveGate(prdText) {
+  if (!prdText || typeof prdText !== 'string') return { source: 'absent', sequence: [] };
+  const explicit = readExplicitGate(prdText);
+  if (explicit) {
+    if (explicit.kind === 'none') return { source: 'none', sequence: [] };
+    const sequence = [];
+    for (const chain of explicit.chains) {
+      const parsed = parseChain(chain);
+      if (!parsed.length) return { source: 'explicit', sequence: [] };
+      sequence.push(...parsed);
+    }
+    return { source: 'explicit', sequence };
+  }
+  const body = splitFrontmatter(prdText).body;
+  for (const line of acCandidateLines(body)) {
+    const backtickMatch = line.match(/`([^`]*\btimeout\s+\d+\s[^`]*)`/i);
     if (backtickMatch) {
-      const cmd = backtickMatch[1].trim();
-      if (!SHELL_META_RE.test(cmd)) return cmd;
+      const seq = parseChain(backtickMatch[1]);
+      if (seq.length) return { source: 'ac-line', sequence: seq };
     }
-
-    // Fall back: bare `timeout NNN cmd ...` anywhere on the line.
-    // Trim trailing all-lowercase-alpha tokens (prose words like "passes",
-    // "and", "the") while keeping at least 4 tokens (timeout, N, binary,
-    // first-arg). This prevents over-matching into prose that follows the
-    // command on the same AC line (e.g. "timeout 60 npm test and verify").
+    // Bare fallback: from the first `timeout N` to end of line, dropping
+    // trailing all-lowercase prose words (keeping ≥ 4 tokens, as before).
     const rawMatch = line.match(/\btimeout\s+\d+\s+\S+(?:\s+\S+)*/);
     if (rawMatch) {
-      const tokens = rawMatch[0].trim().split(/\s+/);
-      while (tokens.length > 4 && /^[a-z]+$/.test(tokens[tokens.length - 1])) {
-        tokens.pop();
-      }
-      const cmd = tokens.join(' ');
-      if (!SHELL_META_RE.test(cmd)) return cmd;
+      const segs = splitOnAndAnd(rawMatch[0]);
+      const tokens = segs[segs.length - 1].trim().split(/\s+/);
+      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 };
     }
   }
-  return null;
+  return { source: 'absent', sequence: [] };
+}
+
+/**
+ * The gate as an ordered list of no-shell commands: [{argv, timeoutMs}, …].
+ * Empty when there is no parseable gate or the PRD opted out with `gate: none`
+ * (resolveGate distinguishes the two). Complexity: O(L) over the PRD's lines.
+ *
+ * @param {string} prdBody  PRD markdown (frontmatter optional).
+ * @returns {Array<{argv:string[], timeoutMs:number, env:object, raw:string}>}
+ */
+function extractAcSequence(prdBody) {
+  return resolveGate(prdBody).sequence;
+}
+
+/**
+ * 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).
+ *
+ * @param {string} prdBody  PRD markdown with frontmatter already stripped.
+ * @returns {string|null}
+ */
+function extractAcCommand(prdBody) {
+  const seq = extractAcSequence(prdBody);
+  return seq.length === 1 && seq[0].raw.startsWith('timeout') ? seq[0].raw : null;
 }
 
 /**
@@ -217,8 +365,8 @@ function reverifyAc(job, { timeoutMs = 60_000, prdsDir } = {}) {
   const cmd = extractAcCommand(prdBody);
   if (!cmd) return Promise.resolve(unverifiable());
 
-  // Simple whitespace split — SHELL_META_RE in extractAcCommand already excludes
-  // commands that would need a shell. Paths with spaces are not expected in AC
+  // 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());
@@ -231,7 +379,7 @@ function reverifyAc(job, { timeoutMs = 60_000, prdsDir } = {}) {
       child = spawn(argv[0], argv.slice(1), {
         cwd: job.cwd,
         stdio: 'ignore',
-        // No shell:true — extractAcCommand rejects commands with shell metacharacters.
+        // No shell:true — tokenizeNoShell rejects commands with shell metacharacters.
       });
     } catch (err) {
       resolve(unverifiable());
@@ -532,6 +680,99 @@ function writeReport(key, { acResults = [], riskFlags = [], runsDir } = {}) {
   return reportPath;
 }
 
+
+// ─── Shadow gate runner ────────────────────────────────────────────────────────
+// Runs a PRD's parsed gate sequence WITHOUT deciding anything: the caller
+// records the outcome next to the verdict. Not a claude -p run, so it takes no
+// slot from sessionSlots; instead a single module-level flag keeps at most one
+// shadow gate in flight machine-wide (the scheduler is one process).
+let gateInFlight = false;
+const OUTPUT_TAIL_CHARS = 1000;
+
+function runOneGateCommand(cmd, { cwd, env }) {
+  return new Promise((resolve) => {
+    const startNs = process.hrtime.bigint();
+    const ms = () => Math.round(Number(process.hrtime.bigint() - startNs) / 1e6);
+    const label = cmd.argv.join(' ');
+    let child;
+    try {
+      child = spawn(cmd.argv[0], cmd.argv.slice(1), {
+        cwd,
+        env: { ...env, ...cmd.env },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        // No shell:true — the sequence was tokenized by tokenizeNoShell.
+      });
+    } catch {
+      resolve({ cmd: label, status: 'unavailable', code: null, ms: ms(), timedOut: false, tail: '' });
+      return;
+    }
+    let tail = '';
+    const onData = (d) => { tail = (tail + d).slice(-OUTPUT_TAIL_CHARS); };
+    child.stdout.on('data', onData);
+    child.stderr.on('data', onData);
+    let settled = false;
+    let timedOut = false;
+    let escalate;
+    const killTimer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGTERM'); } catch { /* already dead */ }
+      escalate = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* race */ }
+      }, 5_000);
+      if (escalate.unref) escalate.unref();
+    }, cmd.timeoutMs);
+    if (killTimer.unref) killTimer.unref();
+    const finish = (r) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(killTimer);
+      clearTimeout(escalate);
+      resolve({ cmd: label, ms: ms(), timedOut, tail, ...r });
+    };
+    child.on('error', () => finish({ status: 'unavailable', code: null }));
+    child.on('close', (code) => {
+      const exitCode = typeof code === 'number' ? code : -1;
+      finish({ status: exitCode === 0 ? 'pass' : 'fail', code: exitCode });
+    });
+  });
+}
+
+/**
+ * Run a gate sequence (extractAcSequence output) in `cwd` with `&&` semantics:
+ * stop at the first non-pass. Each run gets its own isolated TMPDIR (mkdtemp,
+ * removed afterwards) and CI=1, so a suite that sweeps its temp root can never
+ * touch a live one.
+ *
+ * @param {Array<{argv:string[], timeoutMs:number, env?:object}>} sequence
+ * @param {{ cwd: string }} opts
+ * @returns {Promise<{ status: 'green'|'red'|'unavailable'|'busy', results: object[] }>}
+ *   'busy' = another shadow gate is in flight; nothing ran, nothing to record.
+ */
+async function runGateSequence(sequence, { cwd }) {
+  if (gateInFlight) return { status: 'busy', results: [] };
+  if (!Array.isArray(sequence) || !sequence.length) return { status: 'unavailable', results: [] };
+  try { fs.statSync(cwd); } catch { return { status: 'unavailable', results: [] }; }
+  gateInFlight = true;
+  let tmp = null;
+  try {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-gate-shadow-'));
+    const env = { ...process.env, TMPDIR: tmp, CI: '1' };
+    const results = [];
+    for (const cmd of sequence) {
+      const r = await runOneGateCommand(cmd, { cwd, env });
+      results.push(r);
+      if (r.status === 'unavailable') return { status: 'unavailable', results };
+      if (r.status === 'fail') return { status: 'red', results };
+    }
+    return { status: 'green', results };
+  } catch {
+    return { status: 'unavailable', results: [] };
+  } finally {
+    gateInFlight = false;
+    if (tmp) { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } }
+  }
+}
+
 const WATERMARK_FILENAME = '.dod-watermark.json';
 
 /**
@@ -573,6 +814,9 @@ module.exports = {
   reportPathFor,
   reportExists,
   extractAcCommand,
+  extractAcSequence,
+  resolveGate,
+  runGateSequence,
   extractSection,
   reverifyAc,
   reverifyBatch,

package/src/main/lib/dispatchLoop.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * dispatchLoop.cjs — dispatch's own periodic driver. Cadence is owned here and
+ * nothing else can degrade it: no billing backoff, utilization, fire policy or
+ * cancel token is read. It only calls the injected `tick` (scheduler's
+ * tickQueue, which funnels through sessionSlots/pickNextBatch).
+ */
+
+const RECONCILE_INTERVAL_MS = 30_000;
+const MIN_INTERVAL_MS = 10_000;
+const MAX_INTERVAL_MS = 300_000;
+
+/** Pure: env override (SM_DISPATCH_LOOP_INTERVAL_MS) or explicit value, clamped to [10s, 300s]. */
+function resolveIntervalMs(intervalMs, env = process.env) {
+  const raw = intervalMs ?? env.SM_DISPATCH_LOOP_INTERVAL_MS;
+  const n = Number(raw);
+  if (raw === undefined || raw === null || raw === '' || !Number.isFinite(n)) return RECONCILE_INTERVAL_MS;
+  return Math.min(MAX_INTERVAL_MS, Math.max(MIN_INTERVAL_MS, Math.floor(n)));
+}
+
+/**
+ * @param {{ tick: () => any, intervalMs?: number, onError?: (e: Error) => void }} opts
+ * @returns {{ stop: () => void }}
+ */
+function startDispatchLoop({ tick, intervalMs, onError } = {}) {
+  if (typeof tick !== 'function') throw new TypeError('startDispatchLoop: tick must be a function');
+  if (process.env.SM_DISPATCH_LOOP_DISABLE === '1') return { stop() {} };
+  let running = false;
+  const report = (e) => { try { if (onError) onError(e); } catch { /* reporting must not throw */ } };
+  const timer = setInterval(async () => {
+    if (running) return; // previous pass still in flight — no pile-up
+    running = true;
+    try { await tick(); } catch (e) { report(e); } finally { running = false; }
+  }, resolveIntervalMs(intervalMs));
+  if (timer.unref) timer.unref();
+  return { stop() { clearInterval(timer); } };
+}
+
+module.exports = { startDispatchLoop, resolveIntervalMs, RECONCILE_INTERVAL_MS, MIN_INTERVAL_MS, MAX_INTERVAL_MS };

package/src/main/lib/effectiveModelInfo.cjs

@@ -91,7 +91,14 @@ function computeEffortReachable(deps) {
  */
 async function resolvePersonaModelAlias(cwd, agentType, deps) {
   const getPersonaBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
-  const resolvePersonaPaths = deps.resolvePersonaPaths || require('./epicMint.cjs').resolvePersonaPaths;
+  // The overlay-vs-global provenance question itself ("which of
+  // resolvePersonaPaths' two candidates won") is answered by
+  // agentModelResolve.cjs's isProjectOverlayPersonaPath, not re-derived here
+  // — that module already owns this precedence decision for the launch
+  // path (readOverlayAwarePersonaModel), and this observer must never let
+  // its own copy of the comparison drift from the one that actually decides
+  // what gets spawned.
+  const { isProjectOverlayPersonaPath } = deps.agentModelResolve || require('./agentModelResolve.cjs');
 
   let persona;
   try {
@@ -102,15 +109,7 @@ async function resolvePersonaModelAlias(cwd, agentType, deps) {
   if (!persona) return { modelAlias: null, modelSource: 'fallback' };
 
   const { fm } = splitFrontmatter(persona.text);
-
-  let fromOverlay = false;
-  try {
-    const { projectPath } = resolvePersonaPaths(cwd, agentType);
-    fromOverlay = Boolean(projectPath) && path.resolve(projectPath) === path.resolve(persona.path);
-  } catch {
-    // Best-effort overlay signal only — a resolution failure here just means
-    // "assume global", never a reason to fail the whole lookup.
-  }
+  const fromOverlay = isProjectOverlayPersonaPath(cwd, agentType, persona.path, deps);
 
   if (fm.model && fm.model !== 'inherit') {
     return { modelAlias: fm.model, modelSource: fromOverlay ? 'persona-overlay' : 'persona' };