claude-code-session-manager 0.92.1 → 0.94.0

package/src/main/lib/modelCatalog.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * modelCatalog.cjs — pure observer answering "which model aliases, concrete model
+ * ids and effort levels does the installed `claude` CLI offer right now".
+ *
+ * Sources per field (ladder: live → stale cache → CATALOG_FLOOR):
+ *   aliases       ← `claude -p "/model"` probe
+ *   effortLevels  ← `claude -p "/effort"` probe
+ *   models        ← bounded streaming scan of the CLI binary for `claude-<family>-N…` ids
+ *   settingsEffortLevels ← bundled settings schema (`properties.effortLevel.enum`)
+ *   availableModels      ← settings.json scope chain allowlist (reported, never applied here)
+ * Cached at ~/.claude/session-manager/model-catalog.json keyed by the installed CLI version (24 h TTL).
+ * (NOT userData: config.cjs's validateWrite permits only update-check.json there, so a userData write
+ * is silently swallowed.) An unknown (null) CLI version never reads a cache as fresh and never writes one.
+ * Never throws/rejects. Influences no spawn decision; writes nothing under session-manager-operations/.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CACHE_FILE = 'model-catalog.json';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 45_000;
+const SCAN_CHUNK_BYTES = 1024 * 1024;
+// Longest real id is ~40 bytes; 128 comfortably covers an id split across two reads.
+const SCAN_OVERLAP_BYTES = 128;
+const MODEL_ID_RE = /claude-(?:opus|sonnet|haiku|fable)-[0-9][0-9-]*/g;
+// A real CLI binary is tens of MB; test stubs and launcher shims are tiny shell scripts.
+const MIN_SCAN_BYTES = 1024 * 1024;
+const SCHEMA_PATH = path.join(__dirname, '..', '..', 'renderer', 'data', 'claude-settings-schema.json');
+
+const CATALOG_FLOOR = Object.freeze({
+  aliases: Object.freeze(['haiku', 'sonnet', 'opus', 'fable']),
+  models: Object.freeze([]),
+  effortLevels: Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']),
+  settingsEffortLevels: Object.freeze(['low', 'medium', 'high', 'xhigh']),
+});
+
+let inFlight = null;
+
+/** `Usage: /model <name>. Available: a, b, or a full model ID.` → ['a','b'] (or null). */
+function parseAliases(out) {
+  const m = /Available:\s*([^\n]+)/.exec(String(out || ''));
+  if (!m) return null;
+  const list = m[1].trim().replace(/\.$/, '').split(',')
+    .map((s) => s.trim())
+    .filter((s) => s && !/^or a full model id$/i.test(s));
+  return list.length ? list : null;
+}
+
+/** `Usage: /effort <low|medium|…>` → ['low','medium',…] (or null). */
+function parseEffortLevels(out) {
+  const m = /\/effort\s*<([^>]+)>/.exec(String(out || ''));
+  if (!m) return null;
+  const list = m[1].split('|').map((s) => s.trim()).filter(Boolean);
+  return list.length ? list : null;
+}
+
+/** `auto` is a `/effort` RESET verb, never a `--effort` value — keep it out of the selectable list. */
+function selectableEffort(list) {
+  const l = list ? list.filter((x) => x !== 'auto') : null;
+  return l && l.length ? l : null;
+}
+
+/**
+ * Streaming scan of `file` for concrete model ids. O(size) time, O(chunk+overlap) space.
+ * A match touching the window end is deferred (it may be truncated) and re-found via the overlap.
+ */
+function scanModelIds(file, { fsImpl = fs, chunkSize = SCAN_CHUNK_BYTES, overlap = SCAN_OVERLAP_BYTES } = {}) {
+  const found = new Set();
+  const fd = fsImpl.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(chunkSize);
+    let carry = '';
+    for (;;) {
+      const n = fsImpl.readSync(fd, buf, 0, chunkSize, null);
+      const last = n <= 0;
+      const win = carry + (last ? '' : buf.latin1Slice(0, n));
+      MODEL_ID_RE.lastIndex = 0;
+      let m;
+      while ((m = MODEL_ID_RE.exec(win))) {
+        if (!last && m.index + m[0].length >= win.length) continue;
+        found.add(m[0].replace(/-+$/, ''));
+      }
+      if (last) break;
+      carry = win.slice(-overlap);
+    }
+  } finally {
+    try { fsImpl.closeSync(fd); } catch { /* best-effort */ }
+  }
+  return [...found].sort();
+}
+
+/** True only for a large non-shell-script file — never scan a stub/launcher shim. */
+function isScannableBinary(file, fsImpl) {
+  const st = fsImpl.statSync(file);
+  if (!st.isFile() || st.size < MIN_SCAN_BYTES) return false;
+  const fd = fsImpl.openSync(file, 'r');
+  try {
+    const head = Buffer.alloc(64);
+    const n = fsImpl.readSync(fd, head, 0, 64, 0);
+    return !/^#!\s*\/\S*(?:\/env\s+)?(?:ba|z|da|k)?sh\b/.test(head.latin1Slice(0, n));
+  } finally {
+    try { fsImpl.closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
+function readSettingsEffortLevels(fsImpl) {
+  try {
+    const e = JSON.parse(fsImpl.readFileSync(SCHEMA_PATH, 'utf8')).properties.effortLevel.enum;
+    return Array.isArray(e) && e.length ? e.map(String) : null;
+  } catch { return null; }
+}
+
+function readAvailableModels(cwd, d, fsImpl) {
+  const home = d.homeDir ? d.homeDir() : os.homedir();
+  let root = null;
+  if (cwd) {
+    try { root = (d.projectRootOf || require('./activeSessions.cjs').projectRootOf)(path.resolve(cwd)); } catch { root = path.resolve(cwd); }
+  }
+  const files = [path.join(home, '.claude', 'settings.json')];
+  if (root) files.push(path.join(root, '.claude', 'settings.json'), path.join(root, '.claude', 'settings.local.json'));
+  let merged = null;
+  for (const f of files) {
+    try {
+      const a = JSON.parse(fsImpl.readFileSync(f, 'utf8')).availableModels;
+      if (Array.isArray(a)) merged = [...(merged || []), ...a.filter((x) => typeof x === 'string')];
+    } catch { /* missing/unreadable scope */ }
+  }
+  return merged ? [...new Set(merged)] : null;
+}
+
+function readCache(file, fsImpl) {
+  try {
+    const c = JSON.parse(fsImpl.readFileSync(file, 'utf8'));
+    return c && typeof c === 'object' ? c : null;
+  } catch { return null; }
+}
+
+const strList = (v) => (Array.isArray(v) && v.length && v.every((x) => typeof x === 'string') ? v : null);
+
+/** Ladder: live → stale cache → floor. Returns [value, source]. */
+function ladder(live, liveSource, stale, floor) {
+  if (live) return [live, liveSource];
+  const s = strList(stale);
+  if (s) return [s, 'cache'];
+  return [[...floor], 'floor'];
+}
+
+async function doResolve({ cwd, force, deps }) {
+  const d = deps || {};
+  const env = d.env || process.env;
+  const fsImpl = d.fs || fs;
+  const now = (d.now || Date.now)();
+  let cacheFile = null;
+  try {
+    const home = d.homeDir ? d.homeDir() : os.homedir();
+    if (home) cacheFile = path.join(home, '.claude', 'session-manager', CACHE_FILE);
+  } catch { /* no home → no cache */ }
+  const cached = cacheFile ? readCache(cacheFile, fsImpl) : null;
+  if (cached && Array.isArray(cached.effortLevels)) cached.effortLevels = selectableEffort(cached.effortLevels);
+
+  const availableModels = readAvailableModels(cwd, d, fsImpl);
+  const settingsEffort = readSettingsEffortLevels(fsImpl);
+  const settingsEffortLevels = settingsEffort || strList(cached && cached.settingsEffortLevels) || [...CATALOG_FLOOR.settingsEffortLevels];
+
+  const fromCache = (c) => ({
+    aliases: c.aliases, models: c.models || [], effortLevels: c.effortLevels,
+    settingsEffortLevels, availableModels,
+    claudeVersion: c.claudeVersion ?? null, probedAt: c.probedAt ?? null,
+    sources: { aliases: 'cache', models: 'cache', effortLevels: 'cache' }, degraded: Boolean(c.degraded),
+  });
+
+  // Hermetic e2e: never spawn — any usable cache, else the floor.
+  if (env.SM_E2E === '1') {
+    if (cached && strList(cached.aliases) && strList(cached.effortLevels)) return fromCache(cached);
+    return {
+      aliases: [...CATALOG_FLOOR.aliases], models: [], effortLevels: [...CATALOG_FLOOR.effortLevels],
+      settingsEffortLevels, availableModels, claudeVersion: null, probedAt: null,
+      sources: { aliases: 'floor', models: 'floor', effortLevels: 'floor' }, degraded: true,
+    };
+  }
+
+  let claudeVersion = null;
+  try { claudeVersion = (await (d.probeClaudeVersion || require('./claudeBin.cjs').probeClaudeVersion)()) || null; } catch { /* unknown */ }
+
+  if (!force && cached && claudeVersion && cached.claudeVersion === claudeVersion && !cached.degraded
+    && strList(cached.aliases) && strList(cached.effortLevels)) {
+    const age = now - Date.parse(cached.probedAt);
+    if (age >= 0 && age < CACHE_TTL_MS) return fromCache(cached);
+  }
+
+  const run = d.runClaudeP || require('./runClaudeP.cjs').runClaudeP;
+  const probe = async (prompt) => {
+    try { return await run(prompt, { model: 'haiku', timeoutMs: PROBE_TIMEOUT_MS }); } catch { return { ok: false }; }
+  };
+  const [modelRes, effortRes] = await Promise.all([probe('/model'), probe('/effort')]);
+  const liveAliases = modelRes && modelRes.ok ? parseAliases(modelRes.out) : null;
+  const liveEffort = effortRes && effortRes.ok ? selectableEffort(parseEffortLevels(effortRes.out)) : null;
+
+  let liveModels = null;
+  try {
+    const bin = (d.resolveClaudeBin || require('./claudeBin.cjs').resolveClaudeBin)();
+    const real = fsImpl.realpathSync(bin);
+    if (!isScannableBinary(real, fsImpl)) throw new Error('not a scannable binary');
+    const ids = (d.scanModelIds || scanModelIds)(real, { fsImpl });
+    liveModels = ids.length ? ids : null;
+  } catch { /* unreadable/missing binary */ }
+
+  const [aliases, aliasSrc] = ladder(liveAliases, 'probe', cached && cached.aliases, CATALOG_FLOOR.aliases);
+  const [effortLevels, effortSrc] = ladder(liveEffort, 'probe', cached && cached.effortLevels, CATALOG_FLOOR.effortLevels);
+  const [models, modelsSrc] = ladder(liveModels, 'binary', cached && cached.models, CATALOG_FLOOR.models);
+  const degraded = !(liveAliases && liveEffort && liveModels);
+
+  const catalog = {
+    aliases, models, effortLevels, settingsEffortLevels, availableModels,
+    claudeVersion, probedAt: new Date(now).toISOString(),
+    sources: { aliases: aliasSrc, models: modelsSrc, effortLevels: effortSrc }, degraded,
+  };
+  // Unknown version = unknown cache key: writing it would stamp `claudeVersion: null` over a real entry.
+  if (!degraded && cacheFile && claudeVersion) {
+    try { await (d.writeJson || require('../config.cjs').writeJson)(cacheFile, catalog); } catch { /* cache is best-effort */ }
+  }
+  return catalog;
+}
+
+/** Resolve the live catalog. Never throws. Concurrent calls share one in-flight resolve. */
+function resolveModelCatalog({ cwd, force, deps } = {}) {
+  if (inFlight) return inFlight;
+  inFlight = doResolve({ cwd, force, deps })
+    .catch(() => ({
+      aliases: [...CATALOG_FLOOR.aliases], models: [], effortLevels: [...CATALOG_FLOOR.effortLevels],
+      settingsEffortLevels: [...CATALOG_FLOOR.settingsEffortLevels], availableModels: null,
+      claudeVersion: null, probedAt: null,
+      sources: { aliases: 'floor', models: 'floor', effortLevels: 'floor' }, degraded: true,
+    }))
+    .finally(() => { inFlight = null; });
+  return inFlight;
+}
+
+module.exports = { resolveModelCatalog, CATALOG_FLOOR, parseAliases, parseEffortLevels, scanModelIds };

package/src/main/lib/openExternalApp.cjs

@@ -41,6 +41,28 @@ function findCommand(name) {
   return null;
 }
 
+/**
+ * Spawn a detached opener and resolve once the OS reports the outcome.
+ * A missing/unexecutable binary emits an async 'error' (ENOENT/EACCES); without
+ * a listener that is an uncaught exception and the caller would see ok:true.
+ * Races 'spawn' against 'error' — never uses shell:true.
+ *
+ * @returns {Promise<{ ok: true, opener: string } | { ok: false, error: string }>}
+ */
+function spawnDetached(cmd, args, opener = cmd) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() });
+    } catch (e) {
+      resolve({ ok: false, error: `failed to launch ${opener}: ${e?.message ?? e}` });
+      return;
+    }
+    child.once('error', (e) => resolve({ ok: false, error: `failed to launch ${opener}: ${e?.message ?? e}` }));
+    child.once('spawn', () => { child.unref(); resolve({ ok: true, opener }); });
+  });
+}
+
 /**
  * Open a project root directory in the user's editor.
  *
@@ -51,8 +73,7 @@ async function openInEditor({ cwd, editor }) {
   const candidates = (editor && editor !== 'auto') ? [editor] : editorCandidates();
   for (const cmd of candidates) {
     if (!findCommand(cmd)) continue;
-    spawn(cmd, [cwd], { detached: true, stdio: 'ignore', env: cleanChildEnv() }).unref();
-    return { ok: true, opener: cmd };
+    return spawnDetached(cmd, [cwd]);
   }
   return { ok: false, error: 'no editor found' };
 }
@@ -89,8 +110,7 @@ async function openFileInEditor({ path: abs, line, col, editor }) {
     const supportsGoto = /^(code|cursor|subl)$/.test(cmd);
     const target = (supportsGoto && line) ? `${abs}:${line}${col ? `:${col}` : ''}` : abs;
     const args = supportsGoto ? ['-g', target] : [abs];
-    spawn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() }).unref();
-    return { ok: true, opener: cmd };
+    return spawnDetached(cmd, args);
   }
   return { ok: false, error: 'no editor found' };
 }
@@ -128,14 +148,12 @@ async function openInTerminal({ cwd }) {
       const args = t === 'gnome-terminal'
         ? ['--working-directory=' + cwd]
         : ['-e', `bash -c "cd '${cwd.replace(/'/g, "'\\''")}' && exec bash"`];
-      spawn(t, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() }).unref();
-      return { ok: true, opener: t };
+      return spawnDetached(t, args);
     }
   } else if (process.platform === 'darwin') {
-    spawn('open', ['-a', 'Terminal', cwd], { detached: true, stdio: 'ignore', env: cleanChildEnv() }).unref();
-    return { ok: true, opener: 'Terminal.app' };
+    return spawnDetached('open', ['-a', 'Terminal', cwd], 'Terminal.app');
   }
   return { ok: false, error: 'no terminal found' };
 }
 
-module.exports = { findCommand, openInEditor, openFileInEditor, openInFinder, openInTerminal };
+module.exports = { spawnDetached, findCommand, openInEditor, openFileInEditor, openInFinder, openInTerminal };

package/src/main/lib/opsErrorLog.cjs

@@ -12,6 +12,7 @@
  */
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
 const { isEphemeralCwd } = require('./ephemeralCwd.cjs');
@@ -125,6 +126,23 @@ function reportToTelemetry({ cwd, scope, level, tabId, epicId, tags, message })
   } catch { /* telemetry must never break the caller — this is the sole error funnel */ }
 }
 
+function realOrResolved(p) {
+  const abs = path.resolve(p);
+  try { return fs.realpathSync(abs); } catch { return abs; }
+}
+
+function isInside(child, parent) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/** True when `cwd` resolves inside os.tmpdir() or SM_SANDBOX_DIR. O(roots). */
+function isInsideTestScratch(cwd) {
+  const target = realOrResolved(cwd);
+  const roots = [os.tmpdir(), process.env.SM_SANDBOX_DIR].filter(Boolean);
+  return roots.some((r) => isInside(target, realOrResolved(r)));
+}
+
 /**
  * Append one structured error line, tagged for tracing/analysis.
  *
@@ -142,6 +160,10 @@ function reportToTelemetry({ cwd, scope, level, tabId, epicId, tags, message })
 function appendError({ cwd, scope, level = 'error', tabId, epicId, tags = [], message, meta }) {
   if (!cwd || typeof cwd !== 'string') return; // no project to attribute this line to — skip
 
+  // Test-process guard: a vitest fixture passing a real project root must never
+  // write to that project's logs/ NOR ship a fake event to production telemetry.
+  if (process.env.VITEST && !isInsideTestScratch(cwd)) return;
+
   if (isEphemeralCwd(cwd)) {
     // A worktree is torn down when its Epic/job ends and os.tmpdir() is
     // scratch space either way — never materialize logs there. See

package/src/main/lib/personaMerge.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * personaMerge.cjs — the ONE place a project-local persona overlay
+ * (`<cwd>/.claude/agents/<name>.md`) is combined with the global persona
+ * (`~/.claude/agents/<name>.md`). Every reader — agentModelResolve.cjs (model +
+ * PRD spawn), agentEffortResolve.cjs, agentLibrary.cjs (getPersonaBody /
+ * listPersonas), effectiveModelInfo.cjs — goes through `resolveMergedPersona`;
+ * do not add a second merge per reader.
+ *
+ * MERGE RULES
+ *   - Frontmatter: overlay keys override the global's; a key absent from the
+ *     overlay (or present with an empty value) falls back to the global.
+ *   - Body: an overlay with a non-empty body replaces the global body wholesale
+ *     (the pre-merge behavior); a frontmatter-only overlay (`body.trim() === ''`)
+ *     inherits the global body.
+ *   - `model: inherit` in an overlay is a real value that WINS: it means "defer
+ *     to the settings default", NOT "fall back to the global persona's model".
+ *     (Callers already treat `inherit` as "use the fallback model".) A project
+ *     that wants the global model simply omits the key.
+ *   - An overlay with no global counterpart is the whole persona (standalone).
+ *   - A MALFORMED overlay (opens a `---` frontmatter fence that never closes)
+ *     is ignored, reported once via opsErrorLog, and the global persona
+ *     applies — it never throws and never lets a half-parsed file pick the
+ *     model. With no global to degrade to, the persona is unresolvable (null).
+ *
+ * SECURITY: only the two paths `epicMint.cjs`'s `resolvePersonaPaths` yields
+ * are ever read, each through `validatePath`, and `PERSONA_NAME_RE` gates the
+ * agentType before any path is built — merge never widens what can be read.
+ *
+ * Sync fs on purpose: `readOverlayAwarePersonaModel` must stay synchronous for
+ * chatRunner.cjs's executeRun() (see agentModelResolve.cjs).
+ */
+
+const fs = require('node:fs');
+const { splitFrontmatter } = require('./prdFrontmatter.cjs');
+const { resolvePersonaPaths } = require('./epicMint.cjs');
+const configMgr = require('../config.cjs');
+
+/** Filename-safe persona name: lowercase, hyphenated, matches the `.md` files on disk. */
+const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+const reportedIssues = new Set();
+
+function reportOverlayIssueOnce(cwd, agentType, overlayPath, message) {
+  const key = `${cwd}::${agentType}::${message}`;
+  if (reportedIssues.has(key)) return;
+  reportedIssues.add(key);
+  try {
+    const { appendError } = require('./opsErrorLog.cjs');
+    appendError({
+      cwd,
+      scope: 'personaMerge',
+      level: 'warn',
+      message: `project overlay ${overlayPath} for agentType '${agentType}' ${message} — ignored, using the global persona`,
+      meta: { agentType, overlayPath },
+    });
+  } catch { /* reporting must never break resolution */ }
+}
+
+/** Raw text of a validated persona path, or null on any miss. */
+function readRaw(candidate, validatePath) {
+  let real;
+  try {
+    real = validatePath(candidate);
+  } catch {
+    return null;
+  }
+  try {
+    return { path: real, text: fs.readFileSync(real, 'utf8') };
+  } catch {
+    return null;
+  }
+}
+
+/** True when the text opens a `---` frontmatter fence that splitFrontmatter could not parse. */
+function hasMalformedFrontmatter(text) {
+  return text.trimStart().startsWith('---') && splitFrontmatter(text).fmLineCount === 0;
+}
+
+/** Re-serializes merged frontmatter + body into `.md` text (used only when a merge actually happened). */
+function serializeMerged(fm, body) {
+  const lines = ['---'];
+  for (const [k, v] of Object.entries(fm)) lines.push(`${k}: ${v}`);
+  lines.push('---', '');
+  return `${lines.join('\n')}${body.trim()}\n`;
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} agentType
+ * @param {{ validatePath?: Function, resolvePersonaPaths?: Function, globalDir?: string, projectDir?: string }} [deps]
+ * @returns {null | {
+ *   fm: Record<string,string>, body: string, text: string, path: string,
+ *   overlayPath: string|null, globalPath: string|null,
+ *   fromOverlay: boolean, bodySource: 'overlay'|'global',
+ *   provenance: Record<string,'overlay'|'global'>, overlayIssue: string|null,
+ * }}
+ *   `path` is the file the BODY came from; `text` is that file's raw text when
+ *   no merge changed anything (so a full-body overlay resolves byte-identically
+ *   to the pre-merge behavior), else the re-serialized merged persona.
+ *   Null on invalid name / total miss. Never throws.
+ */
+function resolveMergedPersona(cwd, agentType, deps = {}) {
+  try {
+    if (!agentType || !PERSONA_NAME_RE.test(agentType)) return null;
+    const validatePath = deps.validatePath || configMgr.validatePath;
+    const resolvePaths = deps.resolvePersonaPaths || resolvePersonaPaths;
+    const { projectPath, globalPath } = resolvePaths(cwd, agentType, deps);
+
+    const overlayRaw = projectPath ? readRaw(projectPath, validatePath) : null;
+    const globalRaw = readRaw(globalPath, validatePath);
+
+    let overlayIssue = null;
+    let overlay = null;
+    if (overlayRaw) {
+      if (hasMalformedFrontmatter(overlayRaw.text)) {
+        overlayIssue = 'has malformed frontmatter (unclosed --- fence)';
+        reportOverlayIssueOnce(cwd, agentType, overlayRaw.path, overlayIssue);
+      } else {
+        overlay = { ...splitFrontmatter(overlayRaw.text), path: overlayRaw.path, text: overlayRaw.text };
+      }
+    }
+    const global = globalRaw ? { ...splitFrontmatter(globalRaw.text), path: globalRaw.path, text: globalRaw.text } : null;
+
+    const base = { overlayPath: overlay ? overlay.path : null, globalPath: global ? global.path : null, overlayIssue };
+
+    if (!overlay && !global) return null;
+    if (!overlay) {
+      const provenance = Object.fromEntries(Object.keys(global.fm).map((k) => [k, 'global']));
+      return { ...base, fm: global.fm, body: global.body, text: global.text, path: global.path, fromOverlay: false, bodySource: 'global', provenance };
+    }
+    if (!global) {
+      const provenance = Object.fromEntries(Object.keys(overlay.fm).map((k) => [k, 'overlay']));
+      return { ...base, fm: overlay.fm, body: overlay.body, text: overlay.text, path: overlay.path, fromOverlay: true, bodySource: 'overlay', provenance };
+    }
+
+    const fm = { ...global.fm };
+    const provenance = Object.fromEntries(Object.keys(global.fm).map((k) => [k, 'global']));
+    for (const [k, v] of Object.entries(overlay.fm)) {
+      if (typeof v !== 'string' || v.trim() === '') continue; // empty value == absent key
+      fm[k] = v;
+      provenance[k] = 'overlay';
+    }
+    const overlayHasBody = overlay.body.trim() !== '';
+    const body = overlayHasBody ? overlay.body : global.body;
+    const bodySource = overlayHasBody ? 'overlay' : 'global';
+    // A full-body overlay keeps its raw text (byte-identical to pre-merge); only a
+    // frontmatter-only overlay needs a synthesized merged text.
+    const text = overlayHasBody ? overlay.text : serializeMerged(fm, body);
+    return {
+      ...base,
+      fm,
+      body,
+      text,
+      path: overlayHasBody ? overlay.path : global.path,
+      fromOverlay: true,
+      bodySource,
+      provenance,
+    };
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { resolveMergedPersona, PERSONA_NAME_RE };

package/src/main/lib/prdCreate.cjs

@@ -30,7 +30,7 @@ const { fixChainDepthOf, baseSlugOf } = require('./fixChainDepth.cjs');
 const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentType.cjs');
 const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
-const { isIncomplete, resolveChainTerminals } = require('./prdDisposition.cjs');
+const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
 
 // A caller-supplied slug that already starts with its own `NN-` (e.g.
 // "254-perf-x") used to silently become the double-prefixed row
@@ -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, deliverable, artifactPaths,
+    implementationNotes, outOfScope, sourcePromptId, sourceTabId, tag, agentType, dependsOn, quietMachine, disposition, deliverable, artifactPaths, planId,
   } = 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}`);
+  // Durable wave identity — owned by createPrd() (never a caller input), so
+  // buildPlans groups by it instead of re-deriving from the live dependsOn graph.
+  if (isValidPlanId(planId)) fmLines.push(`planId: ${planId}`);
   // Artifact-only declaration — validated by createPrd() before this runs.
   if (deliverable) fmLines.push(`deliverable: ${deliverable}`);
   if (artifactPaths && artifactPaths.length) fmLines.push(`artifactPaths: [${artifactPaths.join(', ')}]`);
@@ -420,16 +423,18 @@ async function createPrd(input, remote) {
   // see later. A listPrds() read failure is skipped-with-a-warning, never a
   // write outage: an I/O hiccup on the read side must not block every PRD
   // write in the project.
+  let depRows = null;
   if (input.dependsOn && input.dependsOn.length) {
     let listing;
     try {
-      listing = await remote.listPrds({ cwd: input.cwd, limit: Number.MAX_SAFE_INTEGER });
+      listing = await remote.listPrds({ cwd: input.cwd, fields: 'full', limit: Number.MAX_SAFE_INTEGER });
     } catch (e) {
       console.warn(`[prdCreate] dependsOn validation skipped (listPrds failed): ${e?.message ?? e}`);
       listing = null;
     }
     if (listing) {
-      const candidateSlugs = (listing.prds ?? []).map((p) => p.slug);
+      depRows = listing.prds ?? [];
+      const candidateSlugs = depRows.map((p) => p.slug);
       for (const dep of input.dependsOn) {
         if (resolveDepSlug(dep, candidateSlugs).length > 0) continue;
         const near = findNearMatches(dep, candidateSlugs);
@@ -444,7 +449,20 @@ async function createPrd(input, remote) {
     }
   }
 
-  const body = buildPrdBody(input);
+  // planId is API-owned: any caller-supplied value is discarded. Inherited from the
+  // resolved dependencies (append terminals or explicit dependsOn) using the FK-check
+  // listing above; otherwise (first-ever / new-head / legacy deps) freshly minted.
+  let planId = null;
+  if (input.dependsOn && input.dependsOn.length && depRows) {
+    const inherited = resolveInheritedPlanId(input.dependsOn, depRows);
+    planId = inherited.planId;
+    if (inherited.diverged) {
+      console.warn(`[prdCreate] dependsOn spans plans ${inherited.diverged.join(', ')} — inheriting ${planId} (lowest-numbered dependency)`);
+    }
+  }
+  if (!planId) planId = mintPlanId();
+
+  const body = buildPrdBody({ ...input, planId });
   const writeResult = await remote.writePrd(filenameSlug, body, input.cwd);
   if (!writeResult?.ok) {
     return { ok: false, status: 500, error: writeResult?.error ?? 'write failed' };

package/src/main/lib/prdDisposition.cjs

@@ -28,6 +28,7 @@
  * the scheduler considers a row's real blockers at run time.
  */
 
+const crypto = require('node:crypto');
 const { resolveDepSlug } = require('./depSlugResolve.cjs');
 
 /** A row is "incomplete" (still part of the Epic's active plan) unless it
@@ -191,7 +192,52 @@ function computeDispositionRewrite({ slug, disposition, dependsOn, rows }) {
   return { ok: true, dependsOn: newDependsOn };
 }
 
+/** planId shape: a single frontmatter token, no commas/brackets/whitespace, so the
+ *  line-oriented parsers need no tokenizer. Anything else is treated as absent. */
+const PLAN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+function isValidPlanId(v) {
+  return typeof v === 'string' && PLAN_ID_RE.test(v);
+}
+
+/** Fresh, sortable, coordination-free plan id: `pl-<base36 ms>-<6 hex random>`. */
+function mintPlanId() {
+  return `pl-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+/**
+ * Resolve the planId a new PRD inherits from the PRDs it depends on. `depSlugs` are
+ * resolved against `rows` ({ slug, planId }) via the shared resolveDepSlug rule. Returns
+ * { planId, diverged } — planId is null when no dependency carries a valid one (caller
+ * mints). When dependencies carry two or more DIFFERENT planIds, the lowest-numbered
+ * dependency's wins (ties broken by slug) and `diverged` lists the distinct ids.
+ */
+function resolveInheritedPlanId(depSlugs, rows) {
+  const slugs = rows.map((r) => r.slug);
+  const seen = new Set();
+  const deps = [];
+  for (const d of depSlugs ?? []) {
+    for (const s of resolveDepSlug(d, slugs)) {
+      if (seen.has(s)) continue;
+      seen.add(s);
+      const row = rows.find((r) => r.slug === s);
+      if (row && isValidPlanId(row.planId)) deps.push(row);
+    }
+  }
+  if (!deps.length) return { planId: null, diverged: null };
+  const num = (slug) => {
+    const m = /^(\d+)-/.exec(slug);
+    return m ? Number(m[1]) : Number.MAX_SAFE_INTEGER;
+  };
+  deps.sort((a, b) => num(a.slug) - num(b.slug) || a.slug.localeCompare(b.slug));
+  const distinct = [...new Set(deps.map((r) => r.planId))];
+  return { planId: deps[0].planId, diverged: distinct.length > 1 ? distinct : null };
+}
+
 module.exports = {
+  isValidPlanId,
+  mintPlanId,
+  resolveInheritedPlanId,
   isIncomplete,
   resolveChainTerminals,
   wouldCreateCycle,

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', 'deliverable', 'artifactPaths']);
-const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition', 'deliverable', 'artifactPaths'];
+const RECOGNIZED_KEYS = new Set(['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition', 'planId', 'deliverable', 'artifactPaths']);
+const EMIT_ORDER = ['title', 'cwd', 'estimateMinutes', 'parallelGroup', 'sourcePromptId', 'sourceTabId', 'tag', 'agentType', 'createdVia', 'issuedAt', 'dependsOn', 'quietMachine', 'disposition', 'planId', 'deliverable', 'artifactPaths'];
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
 
 function indentOf(line) {
@@ -179,6 +179,10 @@ function applyKey(fm, key, after) {
       // a no-op line for the overwhelming majority of PRDs that omit it.
       if (v === true) fm.quietMachine = true;
       return;
+    case 'planId':
+      // Durable wave identity stamped by createPrd(); a garbage value is dropped.
+      if (typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(v)) fm.planId = v;
+      return;
     case 'disposition':
       // Wave-authoring decision ('append'/'new-head') — see
       // src/renderer/lib/prdFrontmatter.ts's mirror of this field for the