claude-code-session-manager 0.89.0 → 0.90.0

package/src/main/lib/__tests__/telemetryCountersMetadataColumn.test.cjs

@@ -80,11 +80,14 @@ test('every counter event still yields appVersion + machineDigest once persisted
   counters.trackEpicCreate(deps);
   counters.trackSchedulerJobFinish({ status: 'completed' }, deps);
 
-  // track() ingress does real (albeit fast) fs I/O before it resolves; wait a
-  // tick since the counter functions fire it without awaiting the promise.
-  await new Promise((r) => setTimeout(r, 50));
-
-  const recs = await readQueueLines(client);
+  // track() ingress does real fs I/O and the counter functions fire it without
+  // awaiting the promise, so poll (bounded) for all 4 records rather than a fixed
+  // sleep — a fixed 50ms lost the race under CPU contention.
+  let recs = [];
+  for (let i = 0; i < 200 && recs.length < 4; i++) {
+    await new Promise((r) => setTimeout(r, 25));
+    recs = await readQueueLines(client);
+  }
   expect(recs.length).toBe(4);
   for (const rec of recs) {
     const meta = asPersistedMetadata(rec);

package/src/main/lib/effectiveModelInfo.cjs

@@ -27,7 +27,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 
 // Mirrors rawSessionModel.ts's RAW_MODELS — duplicated rather than imported
 // because that file is a renderer ES module and this is a main-process CJS
@@ -252,10 +252,10 @@ function findLatestTranscriptModel(cwd, agentType, deps) {
   matches.sort((a, b) => (Date.parse(b.createdAt || 0) || 0) - (Date.parse(a.createdAt || 0) || 0));
 
   const homeDir = deps.homeDir || os.homedir();
-  const encodeCwdFn = deps.encodeCwd || encodeCwd;
   const re = /"model":"([^"]+)"/g;
   for (const session of matches) {
-    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwdFn(cwd), `${session.claudeSessionId}.jsonl`);
+    const filePath = resolveEpicTranscriptPath({ cwd, claudeSessionId: session.claudeSessionId, deps: { homeDir } }).path;
+    if (!filePath) continue;
     const tail = readTail(filePath, MAX_TRANSCRIPT_TAIL_BYTES, deps);
     if (!tail) continue;
     let match;

package/src/main/lib/epicDelegationStats.cjs

@@ -27,7 +27,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 const { classifyLine } = require('./classifyTranscriptLine.cjs');
 
 // Same cap transcripts.cjs's readDelta uses for a single pass — bounds
@@ -85,7 +85,8 @@ function countInlineEdits(cwd, claudeSessionId, deps = {}) {
   const readFn = deps.readTranscriptTail || readTranscriptTail;
   const homeDir = deps.homeDir || os.homedir();
   try {
-    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwd(cwd), `${claudeSessionId}.jsonl`);
+    const filePath = resolveEpicTranscriptPath({ cwd, claudeSessionId, deps: { homeDir } }).path;
+    if (!filePath) return 0;
     const text = readFn(filePath, deps);
     let count = 0;
     for (const line of text.split('\n')) {

package/src/main/lib/epicSpawnCwd.cjs

@@ -27,6 +27,8 @@
  */
 
 const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { readActiveIndex } = require('./epicMint.cjs');
 
 /**
@@ -61,6 +63,26 @@ function isUsableDir(dir, statImpl) {
   }
 }
 
+/**
+ * Re-attach `branch` at `dir` (`git worktree add`). Sync + bounded; never throws. `dir` comes from
+ * a git-tracked file, so it is only honoured when it sits in a `session-manager-epic-worktrees`
+ * segment and the branch is an `sm-epic/` one — nothing else may be materialised from that record.
+ * @returns {boolean} true when `dir` now exists as a checkout.
+ */
+function restoreEpicWorktree({ dir, branch, baseCwd }) {
+  try {
+    if (!path.isAbsolute(dir) || !path.isAbsolute(baseCwd)) return false;
+    if (!path.resolve(dir).split(path.sep).includes('session-manager-epic-worktrees')) return false;
+    if (typeof branch !== 'string' || !/^sm-epic\/[A-Za-z0-9._-]+$/.test(branch)) return false;
+    const run = (args) => execFileSync('git', args, { cwd: baseCwd, stdio: 'ignore', timeout: 15_000 });
+    run(['worktree', 'prune']);
+    run(['worktree', 'add', dir, branch]);
+    return isUsableDir(dir, fs.statSync);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {{ cwd: string, claudeSessionId: string, deps?: object }} opts
  * @returns {string} `worktree.dir` when the matching Epic has one AND it still
@@ -77,10 +99,19 @@ function resolveEpicSpawnCwd({ cwd, claudeSessionId, deps = {} } = {}) {
         const dir = session.worktree?.dir;
         if (!dir) return cwd;
         if (!isUsableDir(dir, statSync)) {
-          // Falling back is strictly better than failing the spawn: the
-          // session still runs, just un-isolated, which is the same degraded
-          // mode a project that never had a worktree runs in.
-          console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — falling back to ${cwd}`);
+          // NEVER fall back to the project cwd: the CLI files the transcript under
+          // encodeCwd(spawn cwd), so a resumed session started in a different dir splits
+          // its transcript across two encodings ("lost session"). Instead re-attach the
+          // Epic's own branch at the SAME recorded path (encoding unchanged); if that is
+          // impossible, return the recorded dir anyway so the spawn fails loudly (ENOENT)
+          // rather than silently forking the transcript. Read-side callers (no `restore`)
+          // keep the old cwd answer — they never spawn and must never mutate git state.
+          if (deps.restore) {
+            const restored = (deps.restoreWorktree || restoreEpicWorktree)({ dir, branch: session.worktree?.branch, baseCwd: cwd });
+            console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — ${restored ? 'restored at same path' : 'restore failed; spawn will fail rather than split the transcript'}`);
+            return dir;
+          }
+          console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — read-side falls back to ${cwd}`);
           return cwd;
         }
         return dir;
@@ -92,4 +123,4 @@ function resolveEpicSpawnCwd({ cwd, claudeSessionId, deps = {} } = {}) {
   return cwd;
 }
 
-module.exports = { resolveEpicSpawnCwd };
+module.exports = { resolveEpicSpawnCwd, restoreEpicWorktree };

package/src/main/lib/epicSpawnPlan.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * epicSpawnPlan.cjs — decides the spawn cwd AND the --resume/--session-id flag for an Epic's
+ * chat run TOGETHER (PRD 1319). They used to be computed independently: the flag from "does a
+ * transcript exist under ANY encoding" and the cwd separately, so a transcript stranded under a
+ * swept /tmp worktree encoding produced `--resume` from a cwd that cannot see it ("No
+ * conversation found"), the flag-swap retry then hit `--session-id` ("already in use"), and both
+ * doors were locked.
+ *
+ * Chosen fix: (a) first — resolveEpicSpawnCwd({restore:true}) re-attaches the Epic's own branch
+ * at the SAME recorded path (encoding unchanged), so the CLI sees the transcript again. When that
+ * is impossible, (b): refuse BEFORE spawning with an actionable message naming the missing
+ * worktree path, never claim a flag that cannot work. Reachability = "some existing transcript
+ * lives under encodeCwd(spawn cwd)" and the spawn cwd is a real directory.
+ *
+ * Also refuses requests routed to a closed (`completed`) Epic, and keeps a per-session circuit
+ * breaker: once a session is found unreachable, later requests are refused after ONE stat (is the
+ * worktree dir still missing?) without re-running the restore git commands.
+ *
+ * Ops-root hazard (epicSpawnCwd.cjs): `execCwd` returned here is for the spawn cwd option ONLY;
+ * ops reads/writes keep using the project `cwd` (projectRootOf / resolveProjectRoot).
+ */
+
+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');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
+
+/** Map<sessionId, { dir, message }> — sessions found unreachable; valid while `dir` stays missing. */
+const unreachable = new Map();
+
+function __resetForTests() {
+  unreachable.clear();
+}
+
+function isDir(dir, statSync) {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** The Epic record for a session id: active-index first, else a bounded scan of archived `<id>.json`. */
+function findEpic(cwd, claudeSessionId, deps) {
+  try {
+    for (const s of Object.values((deps.readActiveIndex || readActiveIndex)(cwd).sessions || {})) {
+      if (s && s.claudeSessionId === claudeSessionId) return s;
+    }
+  } catch { /* unreadable index → try archives */ }
+  try {
+    const { opsPath } = require('./opsOwnership.cjs');
+    const dir = opsPath(cwd, 'prompt-sessions');
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json') || name === 'active-index.json') continue;
+      try {
+        const s = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))?.session;
+        if (s && s.claudeSessionId === claudeSessionId) return s;
+      } catch { /* malformed archive */ }
+    }
+  } catch { /* no ops dir */ }
+  return null;
+}
+
+/**
+ * @param {{ cwd: string, claudeSessionId: string, fallbackResume?: boolean, deps?: object }} opts
+ * @returns {{ ok: true, execCwd: string, useResume: boolean, transcriptPath: string|null }
+ *   | { ok: false, code: 'epic_closed'|'session_unreachable', message: string }}
+ */
+function planEpicSpawn({ cwd, claudeSessionId, fallbackResume = false, deps = {} } = {}) {
+  const statSync = deps.statSync || fs.statSync;
+  const epic = findEpic(cwd, claudeSessionId, deps);
+
+  if (epic && epic.status === 'completed') {
+    return {
+      ok: false,
+      code: 'epic_closed',
+      message: `This Epic is closed (completed) — it no longer accepts requests. Start a new Epic instead of routing work into session ${claudeSessionId}.`,
+    };
+  }
+
+  const brokenDir = epic?.worktree?.dir;
+  const tripped = unreachable.get(claudeSessionId);
+  if (tripped && !isDir(tripped.dir, statSync)) return { ok: false, code: 'session_unreachable', message: tripped.message };
+  unreachable.delete(claudeSessionId);
+
+  let useResume = !!fallbackResume;
+  let resolved = null;
+  try {
+    resolved = resolveEpicTranscriptPath({ cwd, claudeSessionId, deps });
+    useResume = !!resolved.existsAnywhere;
+  } catch { /* keep the caller-supplied flag */ }
+
+  const execCwd = (deps.resolveSpawnCwd || resolveEpicSpawnCwd)({ cwd, claudeSessionId, deps: { restore: true, readActiveIndex: deps.readActiveIndex, statSync: deps.statSync, restoreWorktree: deps.restoreWorktree } });
+
+  if (resolved && resolved.existsAnywhere) {
+    const projectsDir = path.join(deps.homeDir || os.homedir(), '.claude', 'projects');
+    const home = path.join(projectsDir, encodeCwd(execCwd));
+    const reachable = isDir(execCwd, statSync) && resolved.existingPaths.some((p) => path.dirname(p) === home);
+    if (!reachable) {
+      const missing = brokenDir || execCwd;
+      const message =
+        `Session ${claudeSessionId} cannot be resumed: its transcript is at ${resolved.existingPaths[0]}, ` +
+        `which the CLI only finds when run from ${missing}, and that worktree no longer exists and could not be ` +
+        `re-attached (likely swept from /tmp). Recreate it (git worktree add "${missing}" ${epic?.worktree?.branch || '<sm-epic branch>'}) ` +
+        `or start a new Epic.`;
+      unreachable.set(claudeSessionId, { dir: missing, message });
+      return { ok: false, code: 'session_unreachable', message };
+    }
+  }
+
+  return { ok: true, execCwd, useResume, transcriptPath: resolved?.path ?? null };
+}
+
+module.exports = { planEpicSpawn, __resetForTests };

package/src/main/lib/epicTranscriptDiagnostic.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * epicTranscriptDiagnostic.cjs — read-only scan for Epics whose claude
+ * transcript is not where the project-scoped lookup would put it.
+ *
+ *   mislocated — exactly one transcript exists and it is not under
+ *                <encodeCwd(project cwd)> (i.e. only a worktree encoding).
+ *   duplicated — the same session id has transcripts under 2+ encodings; the
+ *                state in which `claude --resume` fails from any third cwd.
+ *
+ * Bounded: walks Epic records of the supplied project cwds and stats each
+ * Epic's candidate paths via resolveEpicTranscriptPath. Never enumerates
+ * ~/.claude/projects. Writes nothing. Complexity: O(epics x candidates).
+ */
+
+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 { opsPath } = require('./opsOwnership.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
+
+/** [epicId, session] pairs: active-index rows plus archived per-Epic `<id>.json` records. */
+function epicRecords(cwd) {
+  const out = new Map();
+  try {
+    for (const [id, s] of Object.entries(readActiveIndex(cwd).sessions || {})) out.set(id, s);
+  } catch { /* unreadable index → archives only */ }
+  let dir;
+  let names = [];
+  try {
+    dir = opsPath(cwd, 'prompt-sessions');
+    names = fs.readdirSync(dir);
+  } catch { /* no ops dir → skip */ }
+  for (const name of names) {
+    if (!name.endsWith('.json') || name === 'active-index.json') continue;
+    const id = name.slice(0, -5);
+    if (out.has(id)) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))?.session;
+      if (s && typeof s === 'object') out.set(id, s);
+    } catch { /* malformed record → skip */ }
+  }
+  return out;
+}
+
+/**
+ * @param {{ cwds: string[], homeDir?: string }} opts
+ * @returns {Array<{ sessionId: string, epicId: string, cwd: string, paths: string[], classification: 'mislocated'|'duplicated' }>}
+ */
+function scanEpicTranscripts({ cwds, homeDir = os.homedir() }) {
+  const findings = [];
+  const projectsDir = path.join(homeDir, '.claude', 'projects');
+  for (const cwd of cwds || []) {
+    const sessions = epicRecords(cwd);
+    const home = path.join(projectsDir, encodeCwd(cwd));
+    for (const [epicId, s] of sessions) {
+      const sessionId = s && s.claudeSessionId;
+      if (!sessionId || typeof sessionId !== 'string') continue;
+      let res;
+      try {
+        res = resolveEpicTranscriptPath({ cwd, claudeSessionId: sessionId, deps: { homeDir } });
+      } catch {
+        continue;
+      }
+      const paths = res.existingPaths;
+      if (paths.length > 1) {
+        findings.push({ sessionId, epicId, cwd, paths, classification: 'duplicated' });
+      } else if (paths.length === 1 && path.dirname(paths[0]) !== home) {
+        findings.push({ sessionId, epicId, cwd, paths, classification: 'mislocated' });
+      }
+    }
+  }
+  return findings;
+}
+
+module.exports = { scanEpicTranscripts };

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);