claude-code-session-manager 0.98.0 → 0.101.0

package/src/main/lib/instanceLock.cjs

@@ -30,6 +30,7 @@ const path = require('node:path');
 const { identity, isDifferentProcess } = require('./procIdentity.cjs');
 const { instanceLockPath } = require('./schedulerPaths.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
+const { pidAlive: pidAliveCore } = require('./pidAlive.cjs');
 
 // Env override is for unit tests only (isolates the lock from the real
 // ~/.claude of the machine running the suite).
@@ -38,15 +39,11 @@ function lockPath() {
     || instanceLockPath();
 }
 
+// Thin alias over pidAlive.cjs's shared pidAlive() — kept as its own named
+// export (rather than inlining the require at every call site) so existing
+// imports of `pidAlive` from this module keep working unchanged.
 function pidAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (e) {
-    // EPERM = alive but not ours; ESRCH = dead.
-    return e && e.code === 'EPERM';
-  }
+  return pidAliveCore(pid);
 }
 
 function readLock() {

package/src/main/lib/launchFailure.cjs

@@ -40,6 +40,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { readTail } = require('./fileTail.cjs');
+const atomicFs = require('./atomicFs.cjs');
 
 const LAUNCH_FAILURE_KINDS = Object.freeze({
   /** HTTP 400 naming a thinking/effort/config parameter the model rejects — the issue-#11 signature. */
@@ -329,9 +330,7 @@ function writeOutcomeSidecar(runDir, slug, outcome) {
   if (!runDir || !slug) return null;
   const p = path.join(runDir, `${slug}.outcome.json`);
   try {
-    const tmp = `${p}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify({ slug, writtenAt: new Date().toISOString(), ...outcome }, null, 2));
-    fs.renameSync(tmp, p);
+    atomicFs.writeJsonAtomicSync(p, { slug, writtenAt: new Date().toISOString(), ...outcome }, { newline: false });
     return p;
   } catch {
     return null;

package/src/main/lib/macroLibrary.cjs

@@ -0,0 +1,480 @@
+'use strict';
+
+/**
+ * macroLibrary.cjs — the global, machine-local Macro library.
+ *
+ * A Macro is a one-click sidebar "HOT KEYS" button that starts a new session
+ * with a preset Agent + Tag + Initial Prompt (e.g. label "Build the Project",
+ * agent `builder`, tag `build`, prompt "Build and publish this project").
+ * Each macro lists which projects show it.
+ *
+ * Store: `~/.claude/session-manager/macros.json`, `{ version: 1, macros: Macro[] }`.
+ * The path is fixed; every exported function accepts an optional
+ * `{ filePath }` ONLY so tests can inject a temp file — IPC handlers never
+ * forward renderer input as a path.
+ *
+ * Reads are tolerant: invalid entries are dropped individually (one
+ * console.warn per read). A missing file triggers the one-time migration. An
+ * UNPARSEABLE file is never treated as missing: it is renamed to
+ * `macros.json.corrupt-<timestamp>` (kept for recovery), a warning is logged,
+ * and a fresh empty store is written WITHOUT re-running migration.
+ * Writes go through writeJsonAtomic and are serialized by an in-module
+ * promise chain so concurrent saves never clobber each other.
+ *
+ * One-time migration: when macros.json does not exist, listMacros seeds it
+ * from the retired Agent Library persona frontmatter (`action:`,
+ * `actionLabel:`, `projects:`). On success the file is written (even with
+ * `macros: []`) so migration never reruns; if listing personas throws, nothing
+ * is written and the next call retries.
+ *
+ * `projects` entries are absolute project cwds or the literal '*' (every
+ * project). setMacroProject cannot narrow a '*' macro: it returns
+ * `{ ok: false, error: 'macro is shown in every project' }`.
+ *
+ * Plain Node, no Electron imports.
+ */
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { z } = require('zod');
+const { writeJsonAtomic } = require('./atomicFs.cjs');
+const { EpicTagSchema } = require('./promptSessionSchema.cjs');
+const { WORK_TYPES } = require('./workTypeLibrary.cjs');
+const { PERSONA_NAME_RE } = require('./personaMerge.cjs');
+const { schedulerHome } = require('./schedulerPaths.cjs');
+const { BUILTIN_MACROS } = require('./builtinMacros.cjs');
+
+const ALL_PROJECTS = '*';
+const STORE_VERSION = 1;
+
+const MacroIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, 'invalid macro id');
+const MacroLabelSchema = z.string().trim().min(1).max(60);
+const MacroAgentNameSchema = z.string().regex(PERSONA_NAME_RE, 'agent name must be lowercase, hyphenated (e.g. "my-agent")');
+const MacroPromptSchema = z.string().trim().min(1).max(8000);
+const AbsolutePathSchema = z.string().max(1024).refine(
+  (v) => !v.includes('\0') && path.isAbsolute(v),
+  'must be an absolute path',
+);
+const MacroProjectEntrySchema = z.union([z.literal(ALL_PROJECTS), AbsolutePathSchema]);
+const MacroProjectsSchema = z.array(MacroProjectEntrySchema).max(200);
+const MacroSurfaceSchema = z.enum(['sessions', 'project-home']);
+
+const MacroSchema = z.object({
+  id: MacroIdSchema,
+  label: MacroLabelSchema,
+  agentName: MacroAgentNameSchema,
+  tag: EpicTagSchema,
+  prompt: MacroPromptSchema,
+  projects: MacroProjectsSchema,
+  surface: MacroSurfaceSchema.default('sessions'),
+  builtin: z.boolean().optional(),
+  builtinVersion: z.number().int().optional(),
+  createdAt: z.string().min(1).max(64),
+  updatedAt: z.string().min(1).max(64),
+});
+
+const MacroSaveSchema = z.object({
+  id: MacroIdSchema.optional(),
+  label: MacroLabelSchema,
+  agentName: MacroAgentNameSchema,
+  tag: EpicTagSchema,
+  prompt: MacroPromptSchema,
+  // Omitted (not merely `[]`) means "leave projects unchanged" on update, so a
+  // label/prompt-only edit of a macro (builtin or otherwise) can't silently
+  // wipe its visibility back to no projects. `undefined` on create means [].
+  projects: MacroProjectsSchema.optional(),
+  surface: MacroSurfaceSchema.optional(),
+});
+
+const MacroDeleteSchema = z.object({ id: MacroIdSchema });
+
+const MacroSetProjectSchema = z.object({
+  id: MacroIdSchema,
+  cwd: AbsolutePathSchema,
+  enabled: z.boolean(),
+});
+
+function defaultFilePath() {
+  return path.join(schedulerHome(), 'macros.json');
+}
+
+function resolvePath(opts) {
+  return (opts && opts.filePath) || defaultFilePath();
+}
+
+/**
+ * Canonical cwd form. MUST match the renderer's `normalizeCwd`
+ * (src/renderer/lib/knownProjectAggregate.ts): trim, collapse repeated `/`,
+ * strip trailing `/` (root stays `/`). '*' passes through.
+ */
+function normalizeCwd(cwd) {
+  if (typeof cwd !== 'string' || cwd === ALL_PROJECTS) return cwd;
+  const collapsed = cwd.trim().replace(/\/{2,}/g, '/');
+  if (collapsed === '/') return '/';
+  return collapsed.replace(/\/+$/, '');
+}
+
+function normalizeProjects(projects) {
+  const out = [];
+  for (const p of projects || []) {
+    const n = normalizeCwd(p);
+    if (!out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+function slugify(label) {
+  const s = String(label).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48).replace(/-+$/g, '');
+  return s || 'macro';
+}
+
+function newId(label, taken) {
+  for (let i = 0; i < 20; i++) {
+    const id = `${slugify(label)}-${crypto.randomBytes(3).toString('hex')}`;
+    if (!taken.has(id)) return id;
+  }
+  return `${slugify(label)}-${crypto.randomUUID()}`.slice(0, 64);
+}
+
+// --- serialized writes ------------------------------------------------------
+
+let writeChain = Promise.resolve();
+function serialize(fn) {
+  const run = writeChain.then(fn, fn);
+  writeChain = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+// --- read -------------------------------------------------------------------
+
+/**
+ * Pure read. Returns `{ state: 'missing' | 'corrupt' | 'unreadable' | 'ok', macros }`.
+ * 'corrupt' = file exists but is not a JSON object; 'unreadable' = any other fs error.
+ */
+async function readStore(filePath) {
+  let text;
+  try {
+    text = await fsp.readFile(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: 'missing', macros: [] };
+    console.warn(`[macroLibrary] cannot read ${filePath}:`, err && err.message);
+    return { state: 'unreadable', macros: [] };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return { state: 'corrupt', macros: [] };
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { state: 'corrupt', macros: [] };
+  const list = Array.isArray(raw.macros) ? raw.macros : [];
+  const macros = [];
+  let dropped = 0;
+  const seen = new Set();
+  for (const entry of list) {
+    const normalized = entry && typeof entry === 'object' && Array.isArray(entry.projects)
+      ? { ...entry, projects: normalizeProjects(entry.projects) }
+      : entry;
+    const r = MacroSchema.safeParse(normalized);
+    if (r.success && !seen.has(r.data.id)) {
+      seen.add(r.data.id);
+      macros.push(r.data);
+    } else {
+      dropped++;
+    }
+  }
+  if (dropped > 0 || !Array.isArray(raw.macros)) {
+    console.warn(`[macroLibrary] dropped ${dropped} invalid macro entr${dropped === 1 ? 'y' : 'ies'} from ${filePath}`);
+  }
+  return { state: 'ok', macros };
+}
+
+async function writeStore(filePath, macros) {
+  await writeJsonAtomic(filePath, { version: STORE_VERSION, macros });
+}
+
+function resolveBuiltins(opts) {
+  return opts && Object.prototype.hasOwnProperty.call(opts, 'builtins') ? opts.builtins : BUILTIN_MACROS;
+}
+
+/**
+ * Pure. Seeds any `builtins` entry missing from `macros` (as `builtin: true`),
+ * and upgrades a stored built-in that is behind the shipped `builtinVersion`
+ * AND was never user-edited (`updatedAt === createdAt`). A user-edited
+ * built-in is left untouched. Returns `{ macros, changed }`.
+ */
+function ensureBuiltins(macros, builtins) {
+  if (!builtins || builtins.length === 0) return { macros, changed: false };
+  let changed = false;
+  const next = macros.slice();
+  const now = new Date().toISOString();
+  for (const b of builtins) {
+    const idx = next.findIndex((m) => m.id === b.id);
+    if (idx === -1) {
+      next.push({
+        id: b.id,
+        label: b.label,
+        agentName: b.agentName,
+        tag: b.tag,
+        prompt: b.prompt,
+        projects: b.projects.slice(),
+        surface: b.surface,
+        builtin: true,
+        builtinVersion: b.builtinVersion,
+        createdAt: now,
+        updatedAt: now,
+      });
+      changed = true;
+      continue;
+    }
+    const stored = next[idx];
+    const storedVersion = stored.builtinVersion || 0;
+    const neverEdited = stored.updatedAt === stored.createdAt;
+    if (storedVersion < b.builtinVersion && neverEdited) {
+      next[idx] = {
+        ...stored,
+        label: b.label,
+        agentName: b.agentName,
+        tag: b.tag,
+        prompt: b.prompt,
+        surface: b.surface,
+        builtinVersion: b.builtinVersion,
+        updatedAt: stored.createdAt,
+      };
+      changed = true;
+    }
+  }
+  return { macros: next, changed };
+}
+
+/** Apply builtin seeding/upgrades, writing only when something changed. */
+async function applyBuiltins(filePath, macros, opts) {
+  const { macros: next, changed } = ensureBuiltins(macros, resolveBuiltins(opts));
+  if (!changed) return { macros, failed: false };
+  try {
+    await writeStore(filePath, next);
+  } catch (err) {
+    console.warn('[macroLibrary] could not persist built-in macro seeding:', err && err.message);
+    return { macros, failed: false };
+  }
+  return { macros: next, failed: false };
+}
+
+// --- migration --------------------------------------------------------------
+
+function isValidProject(p) {
+  return p === ALL_PROJECTS || AbsolutePathSchema.safeParse(p).success;
+}
+
+function personasToMacros(personas, now) {
+  const macros = [];
+  const taken = new Set();
+  for (const p of personas || []) {
+    if (!p || typeof p.name !== 'string') continue;
+    const declared = Array.isArray(p.projects) ? p.projects.filter((x) => typeof x === 'string' && x.trim()) : [];
+    const normalized = normalizeProjects(declared);
+    const projects = normalized.filter(isValidProject);
+    const skipped = normalized.filter((x) => !isValidProject(x));
+    if (skipped.length > 0) {
+      console.warn(`[macroLibrary] persona "${p.name}": skipped non-absolute project entries: ${skipped.join(', ')}`);
+    }
+    const prompt = (p.action && String(p.action).trim()) || (p.description && String(p.description).trim()) || '';
+    if (projects.length === 0 || !prompt) continue;
+    // First persona tag in canonical TAG_LIBRARY order (WORK_TYPES mirrors it), else 'discussion'.
+    const personaTags = Array.isArray(p.tags) ? p.tags : [];
+    const tag = WORK_TYPES.find((t) => personaTags.includes(t)) || 'discussion';
+    const label = String(p.actionLabel || p.name).trim().slice(0, 60);
+    const candidate = {
+      id: newId(label, taken),
+      label,
+      agentName: p.name,
+      tag,
+      prompt: prompt.slice(0, 8000),
+      projects,
+      createdAt: now,
+      updatedAt: now,
+    };
+    const r = MacroSchema.safeParse(candidate);
+    if (!r.success) continue;
+    taken.add(r.data.id);
+    macros.push(r.data);
+  }
+  return macros;
+}
+
+/** Returns the migrated macros, or `null` on failure (caller must NOT write). */
+async function migrateFromPersonas(opts) {
+  try {
+    const listPersonas = (opts && opts.listPersonas) || require('../agentLibrary.cjs').listPersonas;
+    const personas = await listPersonas();
+    return personasToMacros(personas, new Date().toISOString());
+  } catch (err) {
+    console.warn('[macroLibrary] persona migration failed; will retry on next call:', err && err.message);
+    return null;
+  }
+}
+
+/**
+ * Load the store, repairing it as needed. MUST run inside `serialize`.
+ * Returns `{ macros, failed }`; `failed` means nothing was persisted and the
+ * caller must not write (migration failed / file unreadable / quarantine failed).
+ */
+async function loadStore(filePath, opts) {
+  const cur = await readStore(filePath);
+  if (cur.state === 'ok') return applyBuiltins(filePath, cur.macros, opts);
+  if (cur.state === 'unreadable') return { macros: [], failed: true };
+  if (cur.state === 'corrupt') {
+    const quarantine = `${filePath}.corrupt-${Date.now()}`;
+    try {
+      await fsp.rename(filePath, quarantine);
+    } catch (err) {
+      console.warn(`[macroLibrary] ${filePath} is unparseable and could not be preserved:`, err && err.message);
+      return { macros: [], failed: true };
+    }
+    console.warn(`[macroLibrary] ${filePath} is unparseable; preserved as ${quarantine}, starting with an empty library`);
+    try {
+      await writeStore(filePath, []);
+    } catch (err) {
+      console.warn('[macroLibrary] could not write fresh macros.json:', err && err.message);
+      return { macros: [], failed: true };
+    }
+    return applyBuiltins(filePath, [], opts);
+  }
+  // missing: migrate once
+  const seeded = await migrateFromPersonas(opts);
+  if (seeded === null) return { macros: [], failed: true };
+  try {
+    await writeStore(filePath, seeded);
+  } catch (err) {
+    console.warn('[macroLibrary] could not write migrated macros.json:', err && err.message);
+    return { macros: seeded, failed: true };
+  }
+  return applyBuiltins(filePath, seeded, opts);
+}
+
+// --- public API -------------------------------------------------------------
+
+/** @returns {Promise<Macro[]>} */
+async function listMacros(opts = {}) {
+  const filePath = resolvePath(opts);
+  const first = await readStore(filePath);
+  if (first.state === 'ok') {
+    const { changed } = ensureBuiltins(first.macros, resolveBuiltins(opts));
+    if (!changed) return first.macros;
+  }
+  // Missing/corrupt/needs-seeding: repair inside the write chain so racing callers don't double-seed.
+  return serialize(async () => (await loadStore(filePath, opts)).macros);
+}
+
+/** Load for a write; refuse to write over a store that could not be loaded. */
+async function loadForWrite(filePath, opts) {
+  const { macros, failed } = await loadStore(filePath, opts);
+  if (failed) throw new Error('macro library unavailable (migration or read failed); try again');
+  return macros;
+}
+
+/**
+ * Create (no id) or update (id) a macro. Returns the saved Macro.
+ * Throws on invalid input or unknown id.
+ */
+async function saveMacro(input, opts = {}) {
+  const parsed = MacroSaveSchema.parse(input);
+  const filePath = resolvePath(opts);
+  return serialize(async () => {
+    const macros = await loadForWrite(filePath, opts);
+    const now = new Date().toISOString();
+    let saved;
+    if (parsed.id) {
+      const idx = macros.findIndex((m) => m.id === parsed.id);
+      if (idx === -1) throw new Error(`macro not found: ${parsed.id}`);
+      const projects = parsed.projects !== undefined ? normalizeProjects(parsed.projects) : macros[idx].projects;
+      saved = {
+        ...macros[idx],
+        label: parsed.label,
+        agentName: parsed.agentName,
+        tag: parsed.tag,
+        prompt: parsed.prompt,
+        projects,
+        surface: parsed.surface ?? macros[idx].surface,
+        updatedAt: now,
+      };
+      macros[idx] = saved;
+    } else {
+      const projects = parsed.projects !== undefined ? normalizeProjects(parsed.projects) : [];
+      saved = {
+        id: newId(parsed.label, new Set(macros.map((m) => m.id))),
+        label: parsed.label,
+        agentName: parsed.agentName,
+        tag: parsed.tag,
+        prompt: parsed.prompt,
+        projects,
+        surface: parsed.surface ?? 'sessions',
+        createdAt: now,
+        updatedAt: now,
+      };
+      macros.push(saved);
+    }
+    await writeStore(filePath, macros);
+    return saved;
+  });
+}
+
+/** Idempotent: deleting an unknown id is still `{ ok: true }`. */
+async function deleteMacro(input, opts = {}) {
+  const { id } = MacroDeleteSchema.parse(input);
+  const filePath = resolvePath(opts);
+  return serialize(async () => {
+    const macros = await loadForWrite(filePath, opts);
+    const target = macros.find((m) => m.id === id);
+    if (target && target.builtin) throw new Error('built-in macros cannot be deleted');
+    const next = macros.filter((m) => m.id !== id);
+    if (next.length !== macros.length) await writeStore(filePath, next);
+    return { ok: true };
+  });
+}
+
+/**
+ * Add/remove one project cwd on a macro. Returns `{ ok: true, macro }` or
+ * `{ ok: false, error }`. A macro with '*' is shown everywhere and cannot be
+ * narrowed here: `{ ok: false, error: 'macro is shown in every project' }`
+ * (enabled=true on a '*' macro is a no-op success).
+ */
+async function setMacroProject(input, opts = {}) {
+  const { id, cwd, enabled } = MacroSetProjectSchema.parse(input);
+  const filePath = resolvePath(opts);
+  const target = normalizeCwd(cwd);
+  return serialize(async () => {
+    const macros = await loadForWrite(filePath, opts);
+    const idx = macros.findIndex((m) => m.id === id);
+    if (idx === -1) return { ok: false, error: `macro not found: ${id}` };
+    const macro = macros[idx];
+    if (macro.projects.includes(ALL_PROJECTS)) {
+      if (enabled) return { ok: true, macro };
+      return { ok: false, error: 'macro is shown in every project' };
+    }
+    if (macro.builtin && !enabled) return { ok: false, error: 'built-in macro visibility cannot be narrowed' };
+    const has = macro.projects.includes(target);
+    if (enabled === has) return { ok: true, macro };
+    const projects = enabled ? [...macro.projects, target] : macro.projects.filter((p) => p !== target);
+    if (projects.length > 200) return { ok: false, error: 'too many projects' };
+    const updated = { ...macro, projects, updatedAt: new Date().toISOString() };
+    macros[idx] = updated;
+    await writeStore(filePath, macros);
+    return { ok: true, macro: updated };
+  });
+}
+
+module.exports = {
+  ALL_PROJECTS,
+  MacroSchema,
+  MacroSaveSchema,
+  MacroDeleteSchema,
+  MacroSetProjectSchema,
+  listMacros,
+  saveMacro,
+  deleteMacro,
+  setMacroProject,
+  defaultFilePath,
+  ensureBuiltins,
+};

package/src/main/lib/mcpToolCatalog.cjs

@@ -45,7 +45,7 @@ const MCP_TOOL_CATALOG = [
     whenToUse: 'Use after diagnosing why a job is stuck (e.g. via scheduler_get_prd/scheduler_list_jobs) and deciding it should re-run from pending.',
     whenNotToUse: 'Do not use as a first move on a "needs_review" job without reading it first — reset just clears status, it does not answer the question the job raised.',
     exampleArgs: { slug: 'add-mcp-tool-catalog', force: false },
-    notes: 'Refuses a job whose status is already "completed" unless force:true is passed — resetting a completed job re-executes already-shipped work.',
+    notes: 'force:true is needed to reset a job whose status is already "completed" or "skipped" — resetting a completed job re-executes already-shipped work; resetting a skipped job overrides the scheduler\'s (or a human\'s) choice not to run it.',
   },
   {
     name: 'scheduler_pause',
@@ -101,7 +101,14 @@ const MCP_TOOL_CATALOG = [
       + '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 "..".',
+      + 'no path may contain "..". '
+      + '`gate` and `files` are REQUIRED on every call — the tool refuses a call missing either. `gate` lists '
+      + '1-10 commands that prove this PRD is done (each starting with `timeout <seconds>`, joined with `&&`, '
+      + 'no shell metacharacters), or exactly `["none"]` for a PRD with no runnable check; the scheduler '
+      + 're-runs these commands and reads them back from the rendered `# Gate` section verbatim, so a stray '
+      + '```gate fence anywhere else in the PRD text is rejected. `files` lists the 1-50 repo-relative files '
+      + 'or folders this PRD may change; PRDs that can run at the same time must not share a file — chain '
+      + 'them with `dependsOn` instead.',
     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 '
@@ -120,10 +127,12 @@ const MCP_TOOL_CATALOG = [
     exampleArgs: {
       title: 'Add unit tests for the retry backoff helper',
       cwd: '/home/bilko/Projects/session-manager',
-      estimateMinutes: 30,
+      estimateMinutes: 10,
       goal: 'Cover retryWithBackoff.cjs edge cases (zero retries, max-delay clamp) that currently have no test.',
-      acceptanceCriteria: ['New test file exercises zero-retry and max-delay-clamp cases', 'timeout 300 npm run typecheck passes', 'timeout 600 npm run test:unit passes'],
+      acceptanceCriteria: ['New test file exercises zero-retry and max-delay-clamp cases', 'Typecheck passes', 'Unit tests pass'],
       implementationNotes: 'See src/main/lib/retryWithBackoff.cjs and its existing __tests__ sibling for the pattern to extend.',
+      gate: ['timeout 300 npm run typecheck', 'timeout 600 npm run test:unit'],
+      files: ['src/main/lib/retryWithBackoff.cjs', 'src/main/lib/__tests__/retryWithBackoff.test.cjs'],
       sourcePromptId: 'epic-id-of-an-already-approved-session',
     },
     notes: 'See /develop.',
@@ -155,17 +164,17 @@ const MCP_TOOL_CATALOG = [
   {
     name: 'scheduler_update_prd',
     group: 'scheduler',
-    purpose: "THE ONLY SUPPORTED WAY to edit a NOT-yet-running PRD's frontmatter and/or body via the session-manager "
-      + 'app\'s admin API. Refuses once a queue row exists for the slug and its status is anything but "pending" '
-      + '(running/completed/failed/needs_review) — editing the spec under a live or already-finished executor is refused, '
-      + 'not silently applied. Only recognized frontmatter keys (title, cwd, estimateMinutes, parallelGroup, '
+    purpose: "THE ONLY SUPPORTED WAY to edit a PRD's frontmatter and/or body. Works while the job is pending, "
+      + 'quarantined, needs_review, failed or skipped, or has no queue row yet. Refuses a running job (wait, or '
+      + 'cancel it first) and a completed one (queue a new PRD). '
+      + 'Only recognized frontmatter keys (title, cwd, estimateMinutes, parallelGroup, '
       + 'sourcePromptId, sourceTabId, tag, dependsOn) may be patched; unrecognized keys round-trip unchanged. '
       + 'Patching dependsOn to a non-empty array replaces it wholesale (validated against existing PRD slugs, '
       + 'same resolver scheduler_create_prd uses); patching it to an explicit empty array CLEARS the dependency — '
       + 'the safe way to fix a wrong dependsOn without archiving (which marks the PRD completed and wrongly frees its dependents).',
-    whenToUse: 'Use to correct a PRD scope/estimate/tag before it starts running — e.g. before resetting a needs_review job whose spec needs to change.',
-    whenNotToUse: 'Do not use once the job is running or terminal (completed/failed/needs_review) without first resetting it back to pending — the route refuses the edit.',
-    exampleArgs: { slug: 'add-mcp-tool-catalog', frontmatter: { estimateMinutes: 45 } },
+    whenToUse: 'Use to fix a PRD\'s spec before it runs, or to fix a parked (needs_review or failed) or skipped PRD before you reset it with scheduler_reset_job.',
+    whenNotToUse: 'Do not use on a running or completed job. Do not reset first and edit second: the reset job can start before the edit lands.',
+    exampleArgs: { slug: 'add-mcp-tool-catalog', frontmatter: { estimateMinutes: 8 } },
     notes: null,
   },
   {
@@ -197,7 +206,7 @@ const MCP_TOOL_CATALOG = [
       + "parallelGroup changes, its NN- filename prefix) via the session-manager app's admin API.",
     whenToUse: 'Use to correct an estimate or renumber a PRD file after it was created.',
     whenNotToUse: 'Do not use parallelGroup as an ordering/dependency barrier — it is only a unique-per-PRD display hint; use dependsOn on scheduler_create_prd/scheduler_update_prd for real ordering.',
-    exampleArgs: { items: [{ slug: 'add-mcp-tool-catalog', estimateMinutes: 30 }] },
+    exampleArgs: { items: [{ slug: 'add-mcp-tool-catalog', estimateMinutes: 10 }] },
     notes: null,
   },
   {
@@ -261,6 +270,29 @@ const MCP_TOOL_CATALOG = [
     exampleArgs: { cwd: '/home/bilko/Projects/session-manager', html: '<!DOCTYPE html><html><body><h1>Example</h1></body></html>' },
     notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted.",
   },
+  {
+    name: 'project_demo_video_write',
+    group: 'project-home',
+    purpose: "Write this project's 30-second demo video — ONE self-contained HTML/JS document — to "
+      + "session-manager-operations/project-pages/demo-video/index.html via the session-manager app's admin API. "
+      + 'The only write path for the demo video.',
+    whenToUse: 'Use when asked to generate or refresh the demo video. Compose the whole document yourself '
+      + '(inline <style>/<script>, data: URIs for assets, CSS/JS-driven animation) from what is really true about '
+      + 'the project, declare its length with <meta name="sm-demo-duration" content="N"> (5-30 seconds), then '
+      + 'pass the full document as `html`.',
+    whenNotToUse: 'Never fabricate content — every claim must trace to something concrete in the project. The '
+      + 'document must be self-contained and non-network-capable: the call is rejected for empty input, more than '
+      + '2MB, any <script src>, <link href="http…">, @import, or url(http…) (no remote references); any '
+      + 'fetch/XMLHttpRequest/WebSocket/EventSource/sendBeacon/dynamic import/importScripts/<iframe>/<object>/'
+      + '<embed>/window.open/http(s)-pointing src or href (no network-capable APIs); or a missing/out-of-range '
+      + 'sm-demo-duration meta tag.',
+    exampleArgs: {
+      cwd: '/home/bilko/Projects/session-manager',
+      html: '<!DOCTYPE html><html><head><meta name="sm-demo-duration" content="30"></head><body><h1>Example</h1></body></html>',
+    },
+    notes: "cwd is optional — defaults to the calling session's own project root (SM_PROJECT_ROOT or process.cwd()) when omitted. "
+      + 'The document is CSP-stamped after it is written, so the viewer sandbox is the real network fence — these checks are defence in depth.',
+  },
   {
     name: 'session_manager_help',
     group: 'help',
@@ -295,11 +327,11 @@ const MCP_RECIPES = [
     id: 'unstick-needs-review-job',
     title: 'Unstick a job stuck in needs_review',
     steps: [
-      'Call scheduler_list_prds with status:"needs_review" (or scheduler_list_jobs) to find the stuck slug.',
-      'Call scheduler_get_prd with that slug to read its full frontmatter + body and understand the question it raised.',
-      'If the PRD spec needs to change, call scheduler_update_prd with the slug and a frontmatter/body patch — this is only accepted while the job is not yet running or terminal.',
-      'Call scheduler_reset_job with { slug } to clear the needs_review status back to pending — force is only required if the job had already reached "completed".',
-      'The next scheduler reconcile pass re-queues the job; confirm with scheduler_list_jobs or scheduler_list_prds.',
+      'Call scheduler_list_prds with status:"needs_review" (or scheduler_list_jobs) to find the slug.',
+      'Call scheduler_get_prd with that slug to read the PRD and why it parked.',
+      'If the spec is wrong, call scheduler_update_prd with the slug and a frontmatter/body patch. It works while the job is pending, quarantined, needs_review, failed or skipped.',
+      'Then call scheduler_reset_job with { slug } to set the job back to pending. Pass force:true when the job is skipped. Always edit first, then reset: a reset job can start on the next tick.',
+      'The next scheduler pass runs it again. Confirm with scheduler_list_jobs or scheduler_list_prds.',
     ],
   },
   {

package/src/main/lib/needsReviewLedger.cjs

@@ -60,7 +60,7 @@ function classifyLadderRung({ source, reason } = {}) {
   if (s === 'spawnInvestigation:start' || s === 'spawnJob:auto-promote' || s === 'reverifyNeedsReview:auto-promote') {
     return 'auto-fix';
   }
-  if (s === 'reverifyNeedsReview:heal' || s === 'needsReviewAutoResolve') return 'reverify';
+  if (s === 'reverifyNeedsReview:heal' || s === 'needsReviewAutoResolve' || s === 'gateAuthoritative') return 'reverify';
   // No transitionJob call site resolves needs_review with a 'quarantine'
   // source today (performLeftoverQuarantine cleans up leftover paths without
   // itself changing job.status — the row stays needs_review until a later