claude-code-session-manager 0.89.0 → 0.91.0

package/src/main/lib/epicTranscriptPath.cjs

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * epicTranscriptPath.cjs — answers "where does this Epic session's JSONL
+ * transcript actually live?".
+ *
+ * The CLI writes `~/.claude/projects/<encodeCwd(spawn cwd)>/<id>.jsonl`, and an
+ * Epic's spawn cwd is its isolated worktree dir (chatRunner.cjs via
+ * resolveEpicSpawnCwd), NOT the project cwd. Turn 1 can still land under the
+ * project encoding (the worktree mint is fire-and-forget), and the worktree dir
+ * itself is routinely swept from /tmp while its transcript survives under
+ * ~/.claude/projects. So candidates are built from the recorded `worktree.dir`
+ * even when that directory no longer exists.
+ *
+ * Bounded: never enumerates ~/.claude/projects, only stats its candidate list.
+ * The active-index.json read and the archive scan are memoised per cwd on
+ * mtimeMs + size (same shape as transcripts.cjs's usageCache) because
+ * usageFor() can call this for up to 500 ids in one IPC.
+ *
+ * Ops-root hazard (see epicSpawnCwd.cjs): `cwd` here is the PROJECT cwd used
+ * for ops-root reads; this returns transcript paths only, never a spawn cwd.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { encodeCwd } = require('./encodeCwd.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { resolveEpicSpawnCwd } = require('./epicSpawnCwd.cjs');
+
+/** Map<cwd, { key, sessions }> — active-index.json parse, keyed on mtime+size. */
+const indexCache = new Map();
+/** Map<cwd, { dirKey, files: Map<name,{key,sid,dir}>, byId: Map<sid,string[]> }> */
+const archiveCache = new Map();
+
+function __resetCacheForTests() {
+  indexCache.clear();
+  archiveCache.clear();
+}
+
+function emptyResult() {
+  return { path: null, candidates: [], existsAnywhere: false, existingPaths: [] };
+}
+
+function statKey(statSync, p) {
+  try {
+    const s = statSync(p);
+    return `${s.mtimeMs}:${s.size}`;
+  } catch {
+    return 'missing';
+  }
+}
+
+function opsFile(cwd, ...segments) {
+  const { opsPath } = require('./opsOwnership.cjs');
+  return opsPath(cwd, 'prompt-sessions', ...segments);
+}
+
+/** Sessions map from active-index.json; O(1) stat when unchanged. */
+function cachedSessions(cwd, deps, statSync) {
+  const key = statKey(statSync, opsFile(cwd, 'active-index.json'));
+  const hit = indexCache.get(cwd);
+  if (hit && hit.key === key) return hit.sessions;
+  let sessions = {};
+  try {
+    sessions = (deps.readActiveIndex || readActiveIndex)(cwd).sessions || {};
+  } catch {
+    sessions = {};
+  }
+  indexCache.set(cwd, { key, sessions });
+  return sessions;
+}
+
+/** Worktree dirs recorded for `sid` across archived per-Epic JSON files. */
+function archivedWorktreeDirs(cwd, sid, statSync) {
+  let dirPath;
+  try {
+    dirPath = opsFile(cwd);
+  } catch {
+    return [];
+  }
+  const dirKey = statKey(statSync, dirPath);
+  let entry = archiveCache.get(cwd);
+  if (entry && entry.dirKey === dirKey) return entry.byId.get(sid) || [];
+  const prevFiles = entry ? entry.files : new Map();
+  const files = new Map();
+  let names = [];
+  try {
+    names = fs.readdirSync(dirPath);
+  } catch {
+    names = [];
+  }
+  for (const name of names) {
+    if (!name.endsWith('.json') || name === 'active-index.json') continue;
+    const file = path.join(dirPath, name);
+    const key = statKey(statSync, file);
+    const prev = prevFiles.get(name);
+    if (prev && prev.key === key) {
+      files.set(name, prev);
+      continue;
+    }
+    let rec = { key, sid: null, dir: null };
+    try {
+      const s = JSON.parse(fs.readFileSync(file, 'utf8'))?.session;
+      if (s && typeof s.claudeSessionId === 'string' && typeof s.worktree?.dir === 'string') {
+        rec = { key, sid: s.claudeSessionId, dir: s.worktree.dir };
+      }
+    } catch {
+      // malformed archive → no hint
+    }
+    files.set(name, rec);
+  }
+  const byId = new Map();
+  for (const rec of files.values()) {
+    if (!rec.sid || !rec.dir) continue;
+    const list = byId.get(rec.sid) || [];
+    list.push(rec.dir);
+    byId.set(rec.sid, list);
+  }
+  entry = { dirKey, files, byId };
+  archiveCache.set(cwd, entry);
+  return byId.get(sid) || [];
+}
+
+/**
+ * @param {{ cwd: string, claudeSessionId: string, deps?: object }} opts
+ * @returns {{ path: string|null, candidates: string[], existsAnywhere: boolean, existingPaths: string[] }}
+ */
+function resolveEpicTranscriptPath({ cwd, claudeSessionId, deps = {} } = {}) {
+  if (!cwd || typeof cwd !== 'string' || !claudeSessionId || typeof claudeSessionId !== 'string') {
+    return emptyResult();
+  }
+  // The id becomes a filename — refuse anything that could escape the project dir.
+  if (/[\\/\0]/.test(claudeSessionId) || claudeSessionId === '.' || claudeSessionId === '..') {
+    return emptyResult();
+  }
+  const statSync = deps.statSync || fs.statSync;
+  const projectsDir = path.join(deps.homeDir || os.homedir(), '.claude', 'projects');
+  const file = (dir) => path.join(projectsDir, encodeCwd(dir), `${claudeSessionId}.jsonl`);
+
+  const worktreeDirs = [];
+  try {
+    const sessions = cachedSessions(cwd, deps, statSync);
+    let inIndex = false;
+    for (const s of Object.values(sessions)) {
+      if (s && s.claudeSessionId === claudeSessionId) {
+        inIndex = true;
+        if (typeof s.worktree?.dir === 'string' && s.worktree.dir) worktreeDirs.push(s.worktree.dir);
+      }
+    }
+    if (!inIndex) worktreeDirs.push(...archivedWorktreeDirs(cwd, claudeSessionId, statSync));
+  } catch {
+    // unreadable ops state → fall through to whatever candidates we have
+  }
+
+  let spawnCwd = cwd;
+  try {
+    spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId, deps: { ...deps, readActiveIndex: () => ({ sessions: cachedSessions(cwd, deps, statSync) }) } }) || cwd;
+  } catch {
+    spawnCwd = cwd;
+  }
+
+  const candidates = [...new Set([file(spawnCwd), ...worktreeDirs.map(file), file(cwd)])];
+
+  const existing = [];
+  for (const p of candidates) {
+    try {
+      const st = statSync(p);
+      if (st.isFile()) existing.push({ p, mtimeMs: st.mtimeMs, size: st.size });
+    } catch {
+      // absent
+    }
+  }
+  const existingPaths = existing.map((e) => e.p);
+  const newest = (list) => list.reduce((a, b) => (b.mtimeMs > a.mtimeMs ? b : a));
+  const nonEmpty = existing.filter((e) => e.size > 0);
+  let chosen = candidates[0];
+  if (nonEmpty.length) chosen = newest(nonEmpty).p;
+  else if (existing.length) chosen = existing[0].p;
+
+  return { path: chosen, candidates, existsAnywhere: existing.length > 0, existingPaths };
+}
+
+module.exports = { resolveEpicTranscriptPath, __resetCacheForTests };

package/src/main/lib/gitWorktree.cjs

@@ -330,7 +330,7 @@ async function removeWorktreeDir(cwd, dir) {
     /* best-effort */
   }
   const parentDir = path.dirname(dir);
-  // Guard against ever rmdir-ing the worktree base (os.tmpdir() or SM_WORKTREE_ROOT) itself — every real caller's
+  // Guard against ever rmdir-ing the worktree base (persistent state dir or SM_WORKTREE_ROOT) itself — every real caller's
   // `dir` is `<kind root>/<hash>/<key>`, so `parentDir` is always the hash
   // dir, never the tmpdir root, but this keeps the guarantee explicit rather
   // than relying solely on call-site discipline.

package/src/main/lib/mcpToolCatalog.cjs

@@ -96,7 +96,12 @@ const MCP_TOOL_CATALOG = [
       + 'and is rejected at write time if it does not name a real persona file. '
       + 'If this PRD has no dependsOn of its own AND the target Epic already has incomplete PRDs, '
       + '`disposition` ("append" or "new-head") is REQUIRED — the write is refused without it (a '
-      + 'headless job caller instead gets a logged "append" default, since no human is present to ask).',
+      + 'headless job caller instead gets a logged "append" default, since no human is present to ask). '
+      + '`deliverable` ("artifact") + `artifactPaths` declare an ARTIFACT-ONLY PRD: `artifactPaths` are the '
+      + 'files this PRD produces that are NOT meant to be committed (git-excluded), they are stat-checked on '
+      + 'disk by the verifier, and declaring them is the ONLY way an artifact-only PRD can pass the finish '
+      + 'protocol without a commit. Each requires the other (the write is refused if only one is given), and '
+      + 'no path may contain "..".',
     whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
     whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
       + '(a) this tool call is PRESENT in your tool list but ERRORS as app-not-running / admin '

package/src/main/lib/prdCreate.cjs

@@ -75,7 +75,7 @@ function deriveSlugFromTitle(title) {
 function buildPrdBody(input) {
   const {
     title, cwd, estimateMinutes, goal, acceptanceCriteria,
-    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine, disposition,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine, disposition, deliverable, artifactPaths,
   } = input;
 
   // No `parallelGroup` frontmatter key by convention (SKILL.md) — the NN-
@@ -114,6 +114,9 @@ function buildPrdBody(input) {
   // site above); a first-ever PRD in an Epic, or one with its own explicit
   // dependsOn, has nothing to decide against and omits this key.
   if (disposition) fmLines.push(`disposition: ${disposition}`);
+  // Artifact-only declaration — validated by createPrd() before this runs.
+  if (deliverable) fmLines.push(`deliverable: ${deliverable}`);
+  if (artifactPaths && artifactPaths.length) fmLines.push(`artifactPaths: [${artifactPaths.join(', ')}]`);
   // Opt-in exclusive-lease flag (PRD 1107): serializes this job against
   // every other job machine-wide for its run, for a PRD whose acceptance
   // criteria are wall-clock/timing measurements that CPU contention from
@@ -317,6 +320,29 @@ async function createPrd(input, remote) {
   if (input.parallelGroup != null) {
     console.warn(`[prdCreate] parallelGroup input is deprecated and ignored (got ${input.parallelGroup}) — numbers are unique per project; use dependsOn for ordering`);
   }
+  // Artifact-only declaration (deliverable + artifactPaths): fail-closed,
+  // checked BEFORE the NN allocation so a refusal burns no number.
+  const hasArtifactPaths = Array.isArray(input.artifactPaths) && input.artifactPaths.length > 0;
+  if (input.deliverable != null && input.deliverable !== 'artifact') {
+    return { ok: false, status: 400, error: 'deliverable must be exactly "artifact" when given' };
+  }
+  if (input.deliverable === 'artifact' && !hasArtifactPaths) {
+    return { ok: false, status: 400, error: 'deliverable: "artifact" requires a non-empty artifactPaths — name every git-excluded file this PRD produces' };
+  }
+  if (input.artifactPaths != null && input.deliverable !== 'artifact') {
+    return { ok: false, status: 400, error: 'artifactPaths requires deliverable: "artifact" — artifactPaths given without it' };
+  }
+  if (hasArtifactPaths) {
+    for (const ap of input.artifactPaths) {
+      if (typeof ap !== 'string' || !ap.trim() || /[\r\n,\[\]]/.test(ap)) {
+        return { ok: false, status: 400, error: `artifactPaths entry ${JSON.stringify(ap)} must be a non-empty single-line path without commas or brackets` };
+      }
+      if (ap.includes('..')) {
+        return { ok: false, status: 400, error: `artifactPaths entry "${ap}" must not contain ".."` };
+      }
+    }
+  }
+
   const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 

package/src/main/lib/prdFrontmatter.cjs

@@ -77,8 +77,8 @@ function splitFrontmatter(raw) {
  * never emitted, which is how `scheduler_update_prd` clears a dependency.
  */
 
-const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition']);
-const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition'];
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition', 'deliverable', 'artifactPaths']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition', 'deliverable', 'artifactPaths'];
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 function indentOf(line) {
@@ -185,6 +185,17 @@ function applyKey(fm, key, after) {
       // full rationale. Only these two values are recognized.
       if (v === 'append' || v === 'new-head') fm.disposition = v;
       return;
+    case 'deliverable':
+      // Artifact-only PRD declaration — only the literal `artifact` is
+      // recognized; anything else is dropped so a typo can never opt in.
+      if (v === 'artifact') fm.deliverable = v;
+      return;
+    case 'artifactPaths': {
+      // Inline `[a, b]` list, same shape as dependsOn.
+      const list = parseInlineList(after);
+      if (list) fm.artifactPaths = list;
+      return;
+    }
   }
 }
 
@@ -220,10 +231,10 @@ function parsePrdFile(text) {
 
     if (RECOGNIZED_KEYS.has(key)) {
       applyKey(fm, key, after);
-      if (key === 'dependsOn') {
-        if (fm.dependsOn) {
+      if (key === 'dependsOn' || key === 'artifactPaths') {
+        if (fm[key]) {
           if (!fm._raw) fm._raw = {};
-          fm._raw[key] = { line, parsed: fm.dependsOn };
+          fm._raw[key] = { line, parsed: fm[key] };
         }
       } else {
         const parsed = parseScalar(after);

package/src/main/lib/rcaReport.cjs

@@ -150,13 +150,35 @@ function extractRcaBlock(text) {
 
 const ALREADY_SHIPPED_RE = /already (fully )?(satisfied|implemented|committed|done|shipped)|was (already )?(implemented|committed) in|nothing (new )?to commit|no (code )?changes were needed/i;
 const SELF_QUEUE_SKILL_RE = /Launching skill: session-manager-dev:(develop|process-feedback)/;
-const SELF_QUEUE_WAKEUP_RE = /ScheduleWakeup/;
+// SELF_QUEUE rules must match an actual INVOCATION, never a bare tool-name
+// mention. Incident: sigma `816-prepare-157-copy-citation-extras-patch`, run
+// `2026-09-20T18-17-03-476Z` — a 23 KB log (well under the 64 KB `readTail`
+// window) whose single `ScheduleWakeup` occurrence was the harness's
+// `{"type":"system","subtype":"init",...,"tools":[...]}` tool list — was
+// classified `failure-class: self-queue` in its root-cause report. The wakeup
+// rule now requires a stream-json tool_use `"name":"ScheduleWakeup"` field, and
+// classifyFailure strips init events before any rule runs.
+const SELF_QUEUE_WAKEUP_RE = /"name"\s*:\s*"ScheduleWakeup"/;
 const STUCK_LOOP_RE = /\b(until\s|while\s+true|sleep\s)/i;
 const AC_CHECKBOX_RE = /^\s*[-*]\s*\[[xX]\]/;
 const SENTINEL_PASS_RE = /SCHEDULER_VERDICT:\s*PASS/;
 const STUCK_LOOP_WINDOW = 40; // "final lines" per AC
 const POST_AC_OVERRUN_MIN_TAIL_FRACTION = 0.3;
 
+/**
+ * Drop every stream-json harness init event (`"type":"system"` +
+ * `"subtype":"init"`) from a log tail. That line names every available tool
+ * and would otherwise false-match tool-name/word rules. Other system events
+ * are kept. Pure; single pass, O(n) in characters.
+ */
+function stripHarnessInitEvents(logTail) {
+  if (!logTail) return '';
+  return logTail
+    .split('\n')
+    .filter((l) => !(l.includes('"subtype":"init"') && l.includes('"type":"system"') && l.trimStart().startsWith('{')))
+    .join('\n');
+}
+
 /**
  * Classify why a job likely landed in needs_review, from the log tail plus
  * the verifier verdict. Pure/deterministic — no LLM, no I/O.
@@ -164,8 +186,9 @@ const POST_AC_OVERRUN_MIN_TAIL_FRACTION = 0.3;
  * Complexity: O(n) over log-tail lines (n bounded — callers pass a tail, not
  * a full log).
  */
-function classifyFailure({ verdict, logTail }) {
-  const lines = (logTail || '').split('\n');
+function classifyFailure({ verdict, logTail: rawLogTail }) {
+  const logTail = stripHarnessInitEvents(rawLogTail);
+  const lines = logTail.split('\n');
 
   // Checked before every other rule: an unambiguous, materially-checked
   // verdict (the scheduler itself validated the executor's claimed paths
@@ -399,6 +422,7 @@ module.exports = {
   // Pure helpers, exported for unit tests.
   humanVerdict,
   classifyFailure,
+  stripHarnessInitEvents,
   extractAcceptanceCriteria,
   extractRcaBlock,
   buildRcaMarkdown,

package/src/main/lib/schedulerPaths.cjs

@@ -13,11 +13,12 @@
  * executor jobs BY DESIGN (children inherit env), so a redirected app runs
  * redirected jobs.
  *
- * Worktree roots are NOT under schedulerHome (they live on the tmp filesystem)
- * but are resolved here all the same, via SM_WORKTREE_ROOT (else os.tmpdir()),
+ * Worktree roots are NOT under schedulerHome (they live in a per-user state dir)
+ * but are resolved here all the same, via SM_WORKTREE_ROOT (else persistentWorktreeBase()),
  * so the job and epic roots always move together under one override.
  */
 
+const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
@@ -109,8 +110,29 @@ function instanceLockPath() { return path.join(schedulerHome(), 'scheduler-owner
 /** Where heap snapshots are written — the scheduler home itself. */
 function heapSnapshotDir() { return schedulerHome(); }
 
-/** SM_WORKTREE_ROOT, else os.tmpdir() — the parent of every managed worktree root. */
-function worktreeBase() { return assertNotLiveRoot(process.env.SM_WORKTREE_ROOT || os.tmpdir(), 'worktreeBase'); }
+/**
+ * Persistent per-user default for worktrees: $XDG_STATE_HOME/session-manager (absolute values only,
+ * per the XDG spec) else ~/.local/state/session-manager. NOT os.tmpdir(): a systemd tmp.conf `D /tmp`
+ * empties /tmp at boot, and the Claude CLI keys an Epic's transcript to its SPAWN cwd (the worktree),
+ * so a tmp-resident worktree took the transcript's directory with it ("lost sessions").
+ * It is also deliberately outside every project repo and outside ~/.claude/projects: what /tmp bought
+ * (a checkout never nested in the repo, so the repo's globs, `git status` and packaging never see it)
+ * is kept by living in a per-user state dir instead of beside the project.
+ */
+function persistentWorktreeBase() {
+  const xdg = process.env.XDG_STATE_HOME;
+  const stateHome = xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), '.local', 'state');
+  return path.join(stateHome, 'session-manager');
+}
+
+/** SM_WORKTREE_ROOT, else persistentWorktreeBase() (created 0700 on demand) — parent of every managed worktree root. */
+function worktreeBase() {
+  if (process.env.SM_WORKTREE_ROOT) return assertNotLiveRoot(process.env.SM_WORKTREE_ROOT, 'worktreeBase');
+  // Guard BEFORE mkdir: under vitest an unset SM_WORKTREE_ROOT must throw, never create a live dir.
+  const base = assertNotLiveRoot(persistentWorktreeBase(), 'worktreeBase');
+  try { fs.mkdirSync(base, { recursive: true, mode: 0o700 }); } catch { /* best-effort; createWorktree surfaces a real failure */ }
+  return base;
+}
 
 /** Managed worktree root for `kind` ('job' | 'epic'), resolved fresh on every call. */
 function worktreeRoot(kind) {
@@ -158,6 +180,7 @@ module.exports = {
   adminTokenPath,
   machineStateLogCwd,
   worktreeBase,
+  persistentWorktreeBase,
   worktreeRoot,
   watchdogLogsDir,
   restartRequestPath,

package/src/main/lib/telemetryClient.cjs

@@ -374,12 +374,19 @@ async function persistSent() {
   await config.writeJson(sentPath(), { ids: S.sentOrder, updatedAt: new Date().toISOString() }, { mode: 0o600 });
 }
 
+// Records are immutable once queued, so their serialized size is computed once. Without
+// this, enforceCap() re-stringified the whole queue on every append: O(n^2) stringifies
+// (~15s idle for 5000 appends) and the reason the cap tests blew their budget under load.
+const recordBytesCache = new WeakMap();
 function recordBytes(r) {
+  const hit = recordBytesCache.get(r);
+  if (hit !== undefined) return hit;
+  let n = 0;
   try {
-    return Buffer.byteLength(JSON.stringify(r), 'utf8');
-  } catch {
-    return 0;
-  }
+    n = Buffer.byteLength(JSON.stringify(r), 'utf8');
+  } catch { /* unserializable -> 0 */ }
+  recordBytesCache.set(r, n);
+  return n;
 }
 
 /** Oldest-first eviction, bounded by count and total bytes. O(n) per call, n <= QUEUE_CAP_COUNT. */

package/src/main/lib/terminalRunOutcome.cjs

@@ -21,6 +21,7 @@ const COMPLETED_EQUIVALENT_VERDICTS = new Set([
   'pass_no_commit_target_verified',
   'pass_no_commit_already_shipped',
   'pass_no_commit_prior_run_verified',
+  'pass_no_commit_artifact_verified',
 ]);
 
 // Bounds the scan: only the newest few run dirs are stat'd per slug, never

package/src/main/pty.cjs

@@ -181,7 +181,7 @@ class PtyManager {
     // returns its isolated worktree dir when one exists — `cwd` itself is
     // NEVER repointed; only this actual PTY spawn option is. See
     // epicSpawnCwd.cjs's header comment (the ops-root hazard) for why.
-    const spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: tabId });
+    const spawnCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: tabId, deps: { restore: true } });
     if (spawnCwd !== cwd) {
       console.log(`[pty] tabId=${tabId} isolated in worktree ${spawnCwd}`);
     }

package/src/main/runVerify.cjs

@@ -40,6 +40,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { parsePrdFile } = require('./lib/prdFrontmatter.cjs');
 
 const VERDICTS_SCHEMA_VERSION = 1;
 
@@ -778,6 +779,57 @@ function allDeliverablesAlreadyTracked({ cwd, paths, execImpl = execFileSync, ti
   }
 }
 
+
+/**
+ * Material check for a DECLARED artifact-only PRD (`deliverable: artifact` +
+ * `artifactPaths`). Returns true only when every declared path resolves inside
+ * `cwd`, is a non-empty regular file, and has an mtime inside the run window
+ * (startedAt - 60s .. (finishedAt ?? now) + 120s). Never throws: any doubt
+ * (no paths, `..`, escape, missing, non-file, empty, stale, fs error) → false.
+ * `cwd` may be a list of roots; a path is accepted if it verifies under any.
+ * Complexity O(paths).
+ */
+function artifactsVerifiedOnDisk({ cwd, paths, startedAt, finishedAt, fsImpl = fs } = {}) {
+  return artifactsCheck({ cwd, paths, startedAt, finishedAt, fsImpl }).ok;
+}
+
+function artifactsCheck({ cwd, paths, startedAt, finishedAt, fsImpl = fs }) {
+  const fail = { ok: false, verified: [] };
+  try {
+    const roots = (Array.isArray(cwd) ? cwd : [cwd]).filter((r) => typeof r === 'string' && r);
+    if (!roots.length || !Array.isArray(paths) || paths.length === 0) return fail;
+    const start = Date.parse(startedAt ?? '');
+    if (Number.isNaN(start)) return fail;
+    const endParsed = finishedAt ? Date.parse(finishedAt) : NaN;
+    const end = Number.isNaN(endParsed) ? Date.now() : endParsed;
+    const lo = start - 60_000;
+    const hi = end + 120_000;
+    const verified = [];
+    for (const p of paths) {
+      if (typeof p !== 'string' || !p || p.includes('\0')) return fail;
+      if (p.split(/[\\/]/).includes('..')) return fail;
+      let hit = null;
+      for (const root of roots) {
+        const base = path.resolve(root);
+        const abs = path.resolve(base, p);
+        const rel = path.relative(base, abs);
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        let st;
+        try { st = fsImpl.statSync(abs); } catch { continue; }
+        if (!st.isFile() || st.size <= 0) continue;
+        if (st.mtimeMs < lo || st.mtimeMs > hi) continue;
+        hit = { path: p, size: st.size, mtime: new Date(st.mtimeMs).toISOString() };
+        break;
+      }
+      if (!hit) return fail;
+      verified.push(hit);
+    }
+    return { ok: true, verified };
+  } catch {
+    return fail;
+  }
+}
+
 // ─── main verifier ────────────────────────────────────────────────────────────
 
 /**
@@ -830,7 +882,7 @@ function allDeliverablesAlreadyTracked({ cwd, paths, execImpl = execFileSync, ti
  */
 async function verifyRun({
   runDir, prdPath, queueEntry, allJobs = [], committedDuringRun = false, allowPreSentinelHeal = false,
-  ghExecImpl, priorLandedCommit = null, jobLandedCommitThisRun = null, exitCode = null,
+  ghExecImpl, priorLandedCommit = null, jobLandedCommitThisRun = null, exitCode = null, worktreeDir = null,
 }) {
   const { slug } = queueEntry;
   const logPath = path.join(runDir, `${slug}.log`);
@@ -1202,7 +1254,42 @@ async function verifyRun({
           );
         }
       }
+      // EXEMPTION: a PRD that DECLARES `deliverable: artifact` + `artifactPaths`
+      // (all deliverables live in a git-excluded dir, so "no commit" is
+      // correct). Reads the declared list from frontmatter — never scrapes
+      // prose — and stat-checks each file on disk (non-empty, in the run
+      // window). Paths resolve against queueEntry.cwd, then retry against the
+      // run's worktree dir when the caller supplies one. Any doubt falls
+      // through to pass_no_commit below. The commit guard separately requires
+      // a clean tree for this verdict (scheduler.cjs commitGuardVerdict).
+      let artifactVerified = false;
       if (!mergeMainVerified && !priorRunVerified && !alreadyShipped) {
+        let fm = null;
+        try { fm = parsePrdFile(prdFullText).frontmatter; } catch { fm = null; }
+        if (fm && fm.deliverable === 'artifact' && Array.isArray(fm.artifactPaths) && fm.artifactPaths.length > 0) {
+          const check = artifactsCheck({
+            cwd: [queueEntry?.cwd, worktreeDir],
+            paths: fm.artifactPaths,
+            startedAt: queueEntry?.startedAt,
+            finishedAt: queueEntry?.finishedAt,
+          });
+          if (check.ok) {
+            artifactVerified = true;
+            return conclude(
+              'pass_no_commit_artifact_verified',
+              'SCHEDULER_VERDICT: PASS with no commit, but every declared artifact exists, is non-empty, and was '
+                + `written inside the run window (${check.verified.map((v) => v.path).join(', ')})`,
+              null,
+              {
+                ...(annotations.length ? { annotations } : {}),
+                sentinel,
+                verifiedArtifacts: check.verified,
+              },
+            );
+          }
+        }
+      }
+      if (!mergeMainVerified && !priorRunVerified && !alreadyShipped && !artifactVerified) {
         issues.push({
           verdict: 'pass_no_commit',
           reason: 'SCHEDULER_VERDICT: PASS but no commit landed during the run window — the run claims success but produced no code change',
@@ -1294,6 +1381,7 @@ module.exports = {
   checkMergeablePr,
   extractPrdDeliverablePaths,
   allDeliverablesAlreadyTracked,
+  artifactsVerifiedOnDisk,
   isAncestorCommit,
   isGitRepo,
   hasAbandonedBackgroundTask,

package/src/main/scheduler.cjs

@@ -4540,11 +4540,18 @@ async function findSatisfyingCommitOnMain(job) {
  *     newlyDirty is empty: a fix-plan job that left real dirt behind is
  *     still a genuine finish-protocol violation (incident:
  *     523-fix-bounded-fix-plan-retry, 2026-07-12).
- */
-function commitGuardVerdict({ newlyDirty, siblingRunning, ranInWorktree, jobSelfCommitted, legitimateNoOp, isFixPlanJob, verifyResult, salvagePatch }) {
+ *   - artifactVerified (zero-edit case only): runVerify.cjs proved a PRD that
+ *     DECLARED `deliverable: artifact` wrote its git-excluded artifacts inside
+ *     the run window (pass_no_commit_artifact_verified). That verdict is
+ *     deliberately NOT blanket-excused via legitimateNoOp (the call site
+ *     excludes it) — it stands the guard down only on a clean tree, like the
+ *     fix-plan carve-out, so stray uncommitted tracked edits still park as
+ *     uncommitted_changes.
+ */
+function commitGuardVerdict({ newlyDirty, siblingRunning, ranInWorktree, jobSelfCommitted, legitimateNoOp, isFixPlanJob, artifactVerified, verifyResult, salvagePatch }) {
   if ((siblingRunning && !ranInWorktree) || jobSelfCommitted || legitimateNoOp) return null;
   const dirty = newlyDirty || [];
-  if (dirty.length === 0 && isFixPlanJob) return null;
+  if (dirty.length === 0 && (isFixPlanJob || artifactVerified)) return null;
 
   const carried = [...(verifyResult?.annotations ?? [])];
   if (verifyResult && verifyResult.verdict !== 'clean') {
@@ -7175,6 +7182,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
         priorLandedCommit,
         jobLandedCommitThisRun,
         exitCode: res.exitCode,
+        worktreeDir: worktree.ok ? worktree.dir : null,
       }).catch((e) => ({
         verdict: 'verify_unavailable',
         reason: `verifier threw: ${e?.message ?? String(e)}`,
@@ -7209,7 +7217,8 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
     // annotation, so a real "finish protocol incomplete" is distinguishable from
     // transcript noise in the queue (feedback 2026-06-10 addendum).
     const guardWillRefire = verifyResult && verifyResult.downgradeTo === 'pending';
-    const guardIsLegitimateNoOp = verifyResult && COMPLETED_EQUIVALENT_VERDICTS.has(verifyResult.verdict);
+    const guardArtifactVerified = verifyResult?.verdict === 'pass_no_commit_artifact_verified';
+    const guardIsLegitimateNoOp = verifyResult && !guardArtifactVerified && COMPLETED_EQUIVALENT_VERDICTS.has(verifyResult.verdict);
     if (res.exitCode === 0 && !res.rateLimited && !guardWillRefire && !guardIsLegitimateNoOp) {
       // afterGuardCwd === null means non-git cwd (or git errored) —
       // best-effort skip, same as always; only a git-status result (even an
@@ -7230,6 +7239,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null) {
           jobSelfCommitted,
           legitimateNoOp: guardIsLegitimateNoOp,
           isFixPlanJob: resolveIsFixPlan(job.slug, job.isFixPlan),
+          artifactVerified: guardArtifactVerified,
           verifyResult,
           salvagePatch,
         });
@@ -11056,6 +11066,9 @@ function registerScheduleHandlers() {
   // configuration tab.
   ipcMain.handle('schedule:session-slots', () => sessionSlots.snapshot());
 
+  // Read-only: where Epic/job git worktrees (and so their CLI transcript encodings) live.
+  ipcMain.handle('schedule:worktree-base', () => require('./lib/schedulerPaths.cjs').worktreeBase());
+
   // Home-tab control for the same pool: user-set cap in [0, 10], default 5.
   // 0 pauses new claude -p launches machine-wide without killing anything
   // already running. SM_SESSION_SLOTS (if set) still overrides this at read

package/src/main/templates/PRD_AUTHORING.md

@@ -141,6 +141,17 @@ estimateMinutes: 60
 - `estimateMinutes` is used for ETA display; include a realistic estimate (note: empirical median is ~10 min, p90 ~20 min — avoid wildly inflated estimates that hide real outliers).
 - `parallelGroup` in frontmatter, when present, IS honored by the scheduler (`pickNextBatch` reads `parallelGroup ?? 99` and overrides the filename NN). Use this only for cross-stream interleaving — e.g., the cellar series `122-`, `123-`, `124-` overrides to groups `113`, `114`, `115` so cellar steps fire alongside the parallel etch steps. Do NOT use it to reorder within a single stream; rename the file instead.
 
+### Artifact-only PRDs
+
+Use `deliverable: artifact` + `artifactPaths: [a, b]` (both passed to `scheduler_create_prd`) ONLY when every deliverable is a file the target repo deliberately git-excludes (e.g. patches/notes under `session-manager-operations/review-records/`, matched by `.git/info/exclude`), so "no commit" is the correct outcome.
+
+- Every artifact path must be named in `artifactPaths`; an unlisted file is invisible to the verifier. Each path is relative, never contains `..`.
+- The artifact must be non-empty and written during the run window — the verifier stat-checks it on disk (verdict `pass_no_commit_artifact_verified`; window = start−60s..finish+120s).
+- The run must still leave the working tree clean — declaring artifacts excuses the missing commit, not stray tracked edits. The commit guard enforces this: the `pass_no_commit_artifact_verified` verdict stands the guard down only when nothing tracked was left dirty; any uncommitted tracked change still parks as `uncommitted_changes`.
+- Both fields are required together: the write is refused if only one is given.
+
+Incident: sigma PRD `816-prepare-157-copy-citation-extras-patch` (2026-09-20) wrote its patch into a git-excluded folder; with no way to declare that, two runs both parked in `needs_review`.
+
 ---
 
 ## §7 Self-containment