claude-code-session-manager 0.88.1 → 0.90.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.
@@ -940,6 +940,167 @@ function parseBlockingMergePaths(stderrText) {
   return { tracked: Array.from(new Set(tracked)), untracked: Array.from(new Set(untracked)) };
 }
 
+/**
+ * Classifies a failed `git merge` from its stderr — additive metadata for
+ * integrateBranch's `ok: false` results (the `reason` string is untouched).
+ * 'blocking_paths' = git refused up-front over dirty/untracked paths
+ * (auto-resolvable, PRD 1125); 'content_conflict' = a genuine 3-way
+ * `CONFLICT (` (deterministic on every retry); 'other' = anything else.
+ * For content_conflict, reads the unmerged paths — MUST be called before
+ * `git merge --abort`, which clears them. Never throws; a failed read
+ * yields `conflictedPaths: []`. O(p log p) in the conflicted-path count.
+ */
+async function classifyMergeFailure({ cwd, stderrText, stdoutText }) {
+  const blocking = parseBlockingMergePaths(stderrText);
+  if (blocking) return { failureKind: 'blocking_paths', blockingPaths: blocking };
+  // git prints `CONFLICT (...)` lines on STDOUT, not stderr.
+  if (/CONFLICT \(/m.test(`${stdoutText || ''}\n${stderrText || ''}`)) {
+    let conflictedPaths = [];
+    try {
+      const out = await execGit(['diff', '--name-only', '--diff-filter=U'], { cwd, timeout: 10_000 });
+      conflictedPaths = Array.from(new Set(out.split('\n').map((l) => l.trim()).filter(Boolean))).sort();
+    } catch { /* best effort — abort must still run */ }
+    return { failureKind: 'content_conflict', conflictedPaths };
+  }
+  return { failureKind: 'other' };
+}
+
+// Extensions eligible for the pure-addition auto-resolve. All-or-nothing across
+// a merge: one conflicted path outside this list means no auto-resolve at all.
+const AUTO_RESOLVE_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.rst']);
+
+/**
+ * Renders `git merge-file -p --diff3` over the index's three conflict stages
+ * of `p`. Returns the merged text (with markers), or null when any stage is
+ * missing/unreadable, a stage is not valid UTF-8 (the round-trip would not be
+ * byte-exact), or git itself errors. `merge-file` exits with the conflict
+ * count (1..127) on a clean run — only >127 or a signal is an error. Never
+ * throws. O(file size).
+ */
+async function renderStagesDiff3({ cwd, p }) {
+  let tmp = null;
+  try {
+    tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-mergefile-'));
+    const files = [];
+    for (const stage of [2, 1, 3]) { // ours, base, theirs — merge-file's argument order
+      const content = await execGit(['cat-file', 'blob', `:${stage}:${p}`], { cwd, timeout: 10_000 });
+      if (content.includes('�')) return null;
+      const f = path.join(tmp, `stage${stage}`);
+      await fsp.writeFile(f, content, 'utf8');
+      files.push(f);
+    }
+    try {
+      return await execGit(['merge-file', '-p', '--diff3', '-L', 'ours', '-L', 'base', '-L', 'theirs', ...files], { cwd, timeout: 10_000 });
+    } catch (e) {
+      if (e && typeof e.code === 'number' && e.code >= 1 && e.code <= 127 && typeof e.stdoutText === 'string') return e.stdoutText;
+      return null;
+    }
+  } catch {
+    return null;
+  } finally {
+    if (tmp) { try { await fsp.rm(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+}
+
+/**
+ * Parses diff3 merge-file output into segments: `{ text }` for pass-through
+ * regions and `{ ours, base, theirs }` (arrays of lines) for conflict hunks.
+ * Returns null on any out-of-order marker or an unterminated hunk. A marker
+ * prefix is only meaningful in its expected state; `=======` inside the ours
+ * or theirs section (e.g. a markdown setext underline) is treated as
+ * unparseable rather than guessed at. O(n) in output lines.
+ */
+function parseDiff3Output(output) {
+  const lines = output.split('\n');
+  const segments = [];
+  let plain = [];
+  let hunk = null;
+  let state = 'plain';
+  for (const line of lines) {
+    const isOpen = line.startsWith('<<<<<<< ');
+    const isBase = line.startsWith('||||||| ');
+    const isSep = line.startsWith('=======');
+    const isClose = line.startsWith('>>>>>>> ');
+    if (state === 'plain') {
+      if (isBase || isClose) return null;
+      if (isOpen) {
+        segments.push({ lines: plain });
+        plain = [];
+        hunk = { ours: [], base: [], theirs: [] };
+        state = 'ours';
+      } else {
+        plain.push(line);
+      }
+    } else if (state === 'ours') {
+      if (isOpen || isSep || isClose) return null;
+      if (isBase) state = 'base'; else hunk.ours.push(line);
+    } else if (state === 'base') {
+      if (isOpen || isBase || isClose) return null;
+      if (isSep && line === '=======') state = 'theirs'; else if (isSep) return null; else hunk.base.push(line);
+    } else {
+      if (isOpen || isBase || isSep) return null;
+      if (isClose) { segments.push({ hunk }); hunk = null; state = 'plain'; } else hunk.theirs.push(line);
+    }
+  }
+  if (state !== 'plain') return null;
+  segments.push({ lines: plain });
+  return segments;
+}
+
+/**
+ * True ONLY when, for EVERY path, the index holds all three conflict stages
+ * and every diff3 conflict hunk has an EMPTY base section (both sides purely
+ * added text where the merge base had nothing). Proven from the bytes, never
+ * assumed; fails toward false on every error path. Never throws.
+ */
+async function isPureAdditionConflict({ cwd, paths }) {
+  try {
+    if (!Array.isArray(paths) || !paths.length) return false;
+    for (const p of paths) {
+      const out = await renderStagesDiff3({ cwd, p });
+      if (out === null) return false;
+      const segments = parseDiff3Output(out);
+      if (!segments) return false;
+      const hunks = segments.filter((s) => s.hunk);
+      if (!hunks.length) return false;
+      if (hunks.some((s) => s.hunk.base.length !== 0)) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Rewrites each conflicted path in the working tree with every conflict hunk
+ * replaced by OURS then THEIRS (no markers, base, reordering, or dedup);
+ * non-conflicted regions pass through unchanged. Renders ALL paths before
+ * writing any so a late failure leaves nothing half-rewritten. Throws on any
+ * failure — the caller aborts the merge.
+ */
+async function resolveByConcatenation({ cwd, paths }) {
+  const rendered = [];
+  for (const p of paths) {
+    const out = await renderStagesDiff3({ cwd, p });
+    const segments = out === null ? null : parseDiff3Output(out);
+    if (!segments) throw new Error(`cannot render conflict for ${p}`);
+    rendered.push({ p, text: joinSegments(segments) });
+  }
+  for (const { p, text } of rendered) {
+    await fsp.writeFile(path.join(cwd, p), text, 'utf8');
+  }
+}
+
+/** Rebuilds file text from parsed segments, hunks contributing ours+theirs lines. */
+function joinSegments(segments) {
+  const out = [];
+  for (const seg of segments) {
+    if (seg.hunk) out.push(...seg.hunk.ours, ...seg.hunk.theirs);
+    else out.push(...seg.lines);
+  }
+  return out.join('\n');
+}
+
 /**
  * Resolves `cwd`'s default branch, without ever hardcoding `main`: prefers
  * the remote-tracked default (`origin/HEAD`, set by `git clone`/`git remote
@@ -949,6 +1110,16 @@ function parseBlockingMergePaths(stderrText) {
  * this chain (no remote, no config, no matching local branch) simply falls
  * through to the next source.
  */
+// HEAD sha of `cwd` (null on any failure) — stamped on a failed integration so
+// mechanical recovery can tell whether the base tree has moved since.
+async function readHeadSha(cwd) {
+  try {
+    return (await execGit(['rev-parse', 'HEAD'], { cwd, timeout: 10_000 })).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 async function resolveDefaultBranch(cwd) {
   try {
     const out = (await execGit(['symbolic-ref', 'refs/remotes/origin/HEAD'], { cwd, timeout: 10_000 })).trim();
@@ -1112,15 +1283,36 @@ async function integrateBranch({ cwd, branch, key, kind, carriedPaths }) {
             resolvedPaths: allPaths,
           };
         } catch (retryErr) {
-          try { await execGit(['merge', '--abort'], { cwd, timeout: 10_000 }); } catch { /* nothing to abort */ }
           const retryText = (retryErr && (retryErr.stderrText || retryErr.message)) || String(retryErr);
-          return { ok: false, reason: `merge failed (likely a real content conflict): ${retryText}` };
+          const retryClass = await classifyMergeFailure({ cwd, stderrText: retryText, stdoutText: retryErr && retryErr.stdoutText });
+          try { await execGit(['merge', '--abort'], { cwd, timeout: 10_000 }); } catch { /* nothing to abort */ }
+          return { ok: false, reason: `merge failed (likely a real content conflict): ${retryText}`, ...retryClass, baseHeadSha: await readHeadSha(cwd) };
         }
       }
     }
+    // Read the conflicted paths BEFORE the abort — it clears the index stages.
+    const failureClass = await classifyMergeFailure({ cwd, stderrText, stdoutText: e && e.stdoutText });
+    // Pure-addition auto-resolve: two jobs appended different text to the same
+    // doc. All-or-nothing; any doubt or failure falls through to the abort.
+    if (
+      process.env.SM_PURE_ADDITION_MERGE_DISABLE !== '1'
+      && failureClass.failureKind === 'content_conflict'
+      && failureClass.conflictedPaths.length
+      && failureClass.conflictedPaths.every((p) => AUTO_RESOLVE_EXTENSIONS.has(path.extname(p).toLowerCase()))
+    ) {
+      try {
+        const paths = failureClass.conflictedPaths;
+        if (await isPureAdditionConflict({ cwd, paths })) {
+          await resolveByConcatenation({ cwd, paths });
+          await execGit(['add', ...paths], { cwd, timeout: 30_000 });
+          await execGit(['commit', '-m', mergeMessage], { cwd, timeout: 30_000 });
+          return { ok: true, integrated: true, mergeCommit: true, autoResolved: 'pure_addition_concat', resolvedPaths: paths };
+        }
+      } catch { /* fall through to the abort */ }
+    }
     // Abort a half-applied merge so `cwd` isn't left in a mid-merge state.
     try { await execGit(['merge', '--abort'], { cwd, timeout: 10_000 }); } catch { /* nothing to abort */ }
-    return { ok: false, reason: `merge failed (likely a real content conflict): ${stderrText}` };
+    return { ok: false, reason: `merge failed (likely a real content conflict): ${stderrText}`, ...failureClass, baseHeadSha: await readHeadSha(cwd) };
   }
 }
 

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
@@ -295,9 +318,16 @@ function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, i
   const durationMs = meta?.durationMs != null ? `${meta.durationMs}ms` : 'unknown';
   const prevention = PREVENTION_HINTS[failureClass] ?? PREVENTION_HINTS[FAILURE_CLASSES.UNKNOWN];
 
+  const integrationLine = job.integrationFailureKind
+    ? `\n\nIntegration failure subtype: ${job.integrationFailureKind}` +
+      (job.integrationFailureKind === 'content_conflict' && Array.isArray(job.integrationConflictPaths)
+        ? ` (conflicted paths: ${job.integrationConflictPaths.join(', ') || 'unknown'})`
+        : '')
+    : '';
+
   const sections = [
     `# What happened\n\nJob \`${job.slug}\` was parked in \`needs_review\` with verifier verdict ` +
-      `\`${verdict}\` (${humanVerdict(verdict)}).${job.error ? `\n\n${job.error}` : ''}`,
+      `\`${verdict}\` (${humanVerdict(verdict)}).${job.error ? `\n\n${job.error}` : ''}${integrationLine}`,
     `# Evidence\n\n- Exit code: ${exitCode}\n- Duration: ${durationMs}\n\nLast 60 log lines:\n\n\`\`\`\n${last60 || '(no log available)'}\n\`\`\``,
     `# The PRD's acceptance criteria\n\n${acText || '(acceptance criteria not found — original PRD may have been archived or removed)'}`,
     `# Likely failure class\n\n**${failureClass}**\n\nPrevention: ${prevention}`,
@@ -392,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,