claude-code-session-manager 0.10.2 → 0.11.0

package/src/main/historyAggregator.cjs

@@ -105,6 +105,34 @@ async function parseJSONL(filePath, stat) {
   return acc;
 }
 
+/** Lightweight per-file meta: { firstTs, lastTs, inputTokens, outputTokens, skipped }.
+ *  Powers the `history:list-conversations` IPC used by the Overview detailed-
+ *  stats panel. Single-pass O(L) scan, only honors ts + usage blocks. */
+async function parseConversationMeta(filePath, stat) {
+  const meta = { firstTs: null, lastTs: null, inputTokens: 0, outputTokens: 0, skipped: false };
+  if (stat.size > MAX_FILE_BYTES) { meta.skipped = true; return meta; }
+  let text;
+  try { text = await fsp.readFile(filePath, 'utf8'); } catch { return meta; }
+  const lines = text.split('\n');
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    const ts = obj.ts ?? obj.timestamp;
+    if (ts) {
+      if (meta.firstTs === null) meta.firstTs = ts;
+      meta.lastTs = ts;
+    }
+    const usage = obj.usage ?? obj.message?.usage;
+    if (usage && typeof usage === 'object') {
+      if (typeof usage.inputTokens === 'number') meta.inputTokens += usage.inputTokens;
+      if (typeof usage.outputTokens === 'number') meta.outputTokens += usage.outputTokens;
+    }
+  }
+  return meta;
+}
+
 function registerHistoryAggregatorHandlers() {
   ipcMain.handle('history:aggregate', async (_e, rawReq) => {
     // Wire the historyAggregate schema (previously defined but never used).
@@ -208,6 +236,48 @@ function registerHistoryAggregatorHandlers() {
     const scannedMs = Date.now() - t0;
     return { rows, partial, scannedMs, skippedLargeFiles };
   });
+
+  /** Per-conversation metadata: one row per JSONL with derived duration +
+   *  token totals. Used by the Overview detailed-stats panel to compute
+   *  hourly/daily distribution + top-projects. */
+  ipcMain.handle('history:list-conversations', async () => {
+    const t0 = Date.now();
+    const conversations = [];
+    let projectEntries;
+    try {
+      projectEntries = await fsp.readdir(PROJECTS_DIR, { withFileTypes: true });
+    } catch {
+      return { conversations: [], scannedMs: Date.now() - t0 };
+    }
+    for (const ent of projectEntries) {
+      if (!ent.isDirectory()) continue;
+      const projectDir = path.join(PROJECTS_DIR, ent.name);
+      const projectFolder = '/' + ent.name.replace(/-/g, '/');
+      let files;
+      try { files = await fsp.readdir(projectDir, { withFileTypes: true }); } catch { continue; }
+      for (const f of files) {
+        if (!f.isFile() || !f.name.endsWith('.jsonl')) continue;
+        const filePath = path.join(projectDir, f.name);
+        let stat;
+        try { stat = await fsp.stat(filePath); } catch { continue; }
+        const meta = await parseConversationMeta(filePath, stat);
+        const firstTs = meta.firstTs || new Date(stat.mtimeMs).toISOString();
+        const duration =
+          meta.firstTs && meta.lastTs
+            ? Math.max(0, Date.parse(meta.lastTs) - Date.parse(meta.firstTs))
+            : undefined;
+        conversations.push({
+          timestamp: firstTs,
+          projectFolder,
+          stats: {
+            ...(duration !== undefined ? { duration } : {}),
+            estimatedTokens: meta.inputTokens + meta.outputTokens,
+          },
+        });
+      }
+    }
+    return { conversations, scannedMs: Date.now() - t0 };
+  });
 }
 
 module.exports = { registerHistoryAggregatorHandlers };

package/src/main/index.cjs

@@ -24,6 +24,12 @@ const otel = require('./otel.cjs');
 const otelSettings = require('./otelSettings.cjs');
 const { registerHistoryAggregatorHandlers } = require('./historyAggregator.cjs');
 const memoryTool = require('./memoryTool.cjs');
+const agentMemory = require('./agentMemory.cjs');
+const { registerDocEditorHandlers } = require('./docEditor.cjs');
+const git = require('./git.cjs');
+const superagent = require('./superagent.cjs');
+const { registerProjectSkillsHandlers } = require('./projectSkills.cjs');
+const filesIpc = require('./files.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { assertCwdInsideHome } = require('./lib/insideHome.cjs');
 
@@ -183,6 +189,7 @@ async function rebootApp() {
     scheduler.attachWindow(mainWindow);
     watchers.attachWindow(mainWindow);
     pluginInstall.attachWindow(mainWindow);
+    superagent.attachWindow(mainWindow);
     rebooting = false;
     return;
   }
@@ -241,6 +248,20 @@ function createWindow() {
     mainWindow.show();
   });
 
+  // Native right-click menu — Copy / Paste / Select All everywhere. Roles
+  // hook into Electron's built-in clipboard/selection plumbing, which xterm.js
+  // (and Monaco, and Tiptap) all participate in via the standard DOM
+  // selection API, so this single block covers Terminal + Doc Editor + plain
+  // text inputs without per-component wiring.
+  mainWindow.webContents.on('context-menu', (_e, params) => {
+    const items = [];
+    if (params.editFlags.canCopy) items.push({ label: 'Copy', role: 'copy' });
+    if (params.editFlags.canPaste) items.push({ label: 'Paste', role: 'paste' });
+    if (items.length) items.push({ type: 'separator' });
+    items.push({ label: 'Select All', role: 'selectAll' });
+    Menu.buildFromTemplate(items).popup({ window: mainWindow });
+  });
+
   const distIndex = path.join(__dirname, '..', '..', 'dist', 'index.html');
   const useDevServer = process.env.SM_DEV === '1';
   if (useDevServer) {
@@ -522,6 +543,44 @@ ipcMain.handle('app:open-in-editor', async (_e, payload) => {
   return { ok: false, error: 'no editor found' };
 });
 
+ipcMain.handle('app:open-external', async (_e, payload) => {
+  // URL filter mirrors setWindowOpenHandler at line ~631: without it, the
+  // renderer could be tricked into asking shell.openExternal to launch
+  // `file:///etc/passwd`, `javascript:…`, or `mailto:…`. Stick to web URLs.
+  const { url } = schemas.openExternal.parse(payload);
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    return { ok: false, error: 'only http/https URLs are allowed' };
+  }
+  await shell.openExternal(url);
+  return { ok: true };
+});
+
+ipcMain.handle('app:open-file-in-editor', async (_e, payload) => {
+  // Open a specific file (with optional line:col) in the user's editor.
+  // Distinct from app:open-in-editor above which opens a project root.
+  // GUI editors that support the goto-line flag (code/cursor/subl) get
+  // `-g file:line:col`; everything else falls back to opening the file alone.
+  const { path: p, line, col, editor } = schemas.openFileInEditor.parse(payload);
+  const home = os.homedir();
+  const abs = path.isAbsolute(p) ? p : path.resolve(home, p);
+  const err = checkInsideHome(abs);
+  if (err) throw new Error(err);
+  try { await fsp.access(abs); } catch { return { ok: false, error: `file not found: ${abs}` }; }
+  const candidates = (editor && editor !== 'auto')
+    ? [editor]
+    : [process.env.VISUAL, process.env.EDITOR, 'code', 'cursor', 'subl', 'nano'].filter(Boolean);
+  for (const cmd of candidates) {
+    if (!findCommand(cmd)) continue;
+    const supportsGoto = /^(code|cursor|subl)$/.test(cmd);
+    const target = (supportsGoto && line) ? `${abs}:${line}${col ? `:${col}` : ''}` : abs;
+    const args = supportsGoto ? ['-g', target] : [abs];
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', env: cleanChildEnv() });
+    child.unref();
+    return { ok: true, editor: cmd };
+  }
+  return { ok: false, error: 'no editor found' };
+});
+
 ipcMain.handle('app:open-in-finder', async (_e, payload) => {
   const { cwd } = schemas.openInFinder.parse(payload);
   const err = checkInsideHome(cwd);
@@ -577,6 +636,12 @@ queueOps.registerQueueOpsHandlers();
 registerHistoryAggregatorHandlers();
 pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
+agentMemory.registerAgentMemoryHandlers();
+registerDocEditorHandlers();
+git.register(ipcMain);
+superagent.registerSuperAgentHandlers();
+registerProjectSkillsHandlers();
+filesIpc.registerFilesHandlers();
 
 // OTEL telemetry export (opt-in via ~/.config/session-manager/otel.json).
 ipcMain.handle('otel:get-config', async () => otelSettings.load());
@@ -788,6 +853,7 @@ app.whenReady().then(async () => {
   scheduler.attachWindow(mainWindow);
   watchers.attachWindow(mainWindow);
   pluginInstall.attachWindow(mainWindow);
+  superagent.attachWindow(mainWindow);
   scheduler.init().catch((e) => {
     logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });

package/src/main/ipcSchemas.cjs

@@ -135,6 +135,17 @@ const openInEditor = z.object({
   editor: z.string().max(256).nullable().optional(),
 });
 
+const openExternal = z.object({
+  url: z.string().min(1).max(4096),
+});
+
+const openFileInEditor = z.object({
+  path: z.string().min(1).max(4096),
+  line: z.number().int().positive().optional(),
+  col: z.number().int().positive().optional(),
+  editor: z.string().max(256).nullable().optional(),
+});
+
 const openInFinder = z.object({
   cwd: z.string().min(1).max(4096),
 });
@@ -201,6 +212,36 @@ const memoryCreate = z.object({
   description: z.string().max(2048).optional(),
 }).strict();
 
+// ──────────────────────────────────────────── Per-subagent memory
+// Distinct from the workspace-scoped Memory tool: agentMemory is keyed by
+// subagent name (the .md filename in ~/.claude/agents/, e.g. "code-reviewer"),
+// not by cwd. Storage lives at ~/.claude/session-manager/agent-memory/<agentId>.json.
+// Regex caps must stay in lockstep with agentMemory.cjs AGENT_ID_RE / ENTRY_ID_RE.
+const AGENT_MEMORY_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const AGENT_MEMORY_CATEGORY = z.enum(['command', 'preference', 'pattern', 'failure', 'workflow']);
+const AGENT_MEMORY_MAX_BODY = 1024 * 1024; // 1 MiB — must match MAX_BODY_BYTES in agentMemory.cjs
+
+const agentMemoryList = z.object({
+  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
+}).strict();
+
+const agentMemoryGet = z.object({
+  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
+  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
+}).strict();
+
+const agentMemorySet = z.object({
+  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
+  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
+  body: z.string().max(AGENT_MEMORY_MAX_BODY),
+  category: AGENT_MEMORY_CATEGORY.optional(),
+}).strict();
+
+const agentMemoryDelete = z.object({
+  agentId: z.string().regex(AGENT_MEMORY_ID_RE),
+  entryId: z.string().regex(AGENT_MEMORY_ID_RE),
+}).strict();
+
 // ──────────────────────────────────────────── History
 const DATE_YYYY_MM_DD = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -272,6 +313,16 @@ const appGitBranch = z.object({
   cwd: z.string().min(1).max(4096),
 }).passthrough();
 
+// git:status / git:file-status — see src/main/git.cjs. cwd is validatePath'd
+// inside the handler (allowedRoots = home), so the schema only enforces shape.
+const gitStatus = z.object({
+  cwd: z.string().min(1).max(4096),
+}).passthrough();
+
+const gitFileStatus = z.object({
+  cwd: z.string().min(1).max(4096),
+}).passthrough();
+
 // Plugin install: mirrors pluginInstall.cjs SLUG_RE + length cap. Defense in
 // depth — install() re-checks; the schema rejects earlier.
 const PLUGIN_SLUG_RE = /^[a-z0-9\-/]+$/;
@@ -279,6 +330,20 @@ const pluginsInstall = z.object({
   slug: z.string().regex(PLUGIN_SLUG_RE).min(1).max(128),
 }).passthrough();
 
+// SuperAgent — "boss" run that writes a structured prompt to the active
+// tab's PTY. Bounds match the inline schemas in superagent.cjs; centralizing
+// here so the schema is the boundary fence rather than each handler.
+const superagentStart = z.object({
+  tabId: z.string().min(1).max(128),
+  prompt: z.string().min(1).max(8 * 1024),
+  specialistCount: z.number().int().min(1).max(8),
+  depth: z.enum(['quick', 'standard', 'deep']),
+}).strict();
+
+const superagentTabId = z.object({
+  tabId: z.string().min(1).max(128),
+}).strict();
+
 /**
  * Wrap an IPC handler with schema validation. Returns a new handler that
  * parses the payload before calling the original. On invalid payload throws
@@ -319,6 +384,8 @@ module.exports = {
     scheduleRetagPrd,
     setConfigSchema,
     openInEditor,
+    openExternal,
+    openFileInEditor,
     openInFinder,
     openInTerminal,
     archiveProject,
@@ -329,12 +396,20 @@ module.exports = {
     voiceSetRecording,
     appTestFireHook,
     appGitBranch,
+    gitStatus,
+    gitFileStatus,
     pluginsInstall,
+    superagentStart,
+    superagentTabId,
     memoryList,
     memoryRead,
     memoryWrite,
     memoryDelete,
     memoryCreate,
+    agentMemoryList,
+    agentMemoryGet,
+    agentMemorySet,
+    agentMemoryDelete,
     watchersAdd,
     watchersList,
     watchersRemove,

package/src/main/projectSkills.cjs

@@ -0,0 +1,124 @@
+/**
+ * ProjectSkills — per-project skill enable/disable state.
+ *
+ * Storage: <cwd>/.claude/project-skills.json
+ *   Format: { skills: Array<{ skillId: string; enabled: boolean }>, schemaVersion: 1 }
+ *
+ * Reads enumerate all skills under <cwd>/.claude/skills/ and <home>/.claude/skills/
+ * and merge their enable state from the project-local config. Skills not listed in
+ * the JSON default to `enabled: true` (i.e., opt-out per project).
+ *
+ * IPC:
+ *   - project-skills:get(cwd) -> SkillState[]
+ *   - project-skills:set(cwd, skillId, enabled) -> { ok: boolean }
+ *
+ * Atomic writes go through config.cjs::writeJson. cwd is validated via
+ * validatePath which constrains it to allowedRoots (home + registered project
+ * dirs).
+ */
+
+const { ipcMain } = require('electron');
+const path = require('node:path');
+const { z } = require('zod');
+const { readJson, writeJson, addAllowedRoot } = require('./config.cjs');
+
+const SCHEMA_VERSION = 1;
+
+function projectSkillsPath(cwd) {
+  return path.join(cwd, '.claude', 'project-skills.json');
+}
+
+/**
+ * Load the project-skills.json record for a cwd. Missing file => empty record.
+ * Returns { skills: Array<{skillId, enabled}>, schemaVersion }.
+ */
+async function loadRecord(cwd) {
+  const filePath = projectSkillsPath(cwd);
+  const r = await readJson(filePath);
+  if (!r.exists || !r.data || typeof r.data !== 'object') {
+    return { skills: [], schemaVersion: SCHEMA_VERSION };
+  }
+  const data = r.data;
+  const skills = Array.isArray(data.skills) ? data.skills : [];
+  // Filter for well-formed entries; tolerate corruption silently.
+  const clean = [];
+  const seen = new Set();
+  for (const s of skills) {
+    if (!s || typeof s.skillId !== 'string' || typeof s.enabled !== 'boolean') continue;
+    if (seen.has(s.skillId)) continue;
+    seen.add(s.skillId);
+    clean.push({ skillId: s.skillId, enabled: s.enabled });
+  }
+  return { skills: clean, schemaVersion: SCHEMA_VERSION };
+}
+
+async function saveRecord(cwd, record) {
+  const filePath = projectSkillsPath(cwd);
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    skills: record.skills,
+    savedAt: Date.now(),
+  };
+  return writeJson(filePath, payload);
+}
+
+/** Return the array of skill enable-states for a project cwd. */
+async function getProjectSkills(cwd) {
+  // Register cwd so writeJson is permitted under <cwd>/.claude.
+  addAllowedRoot(cwd);
+  const record = await loadRecord(cwd);
+  return record.skills;
+}
+
+/** Upsert a single skillId's enabled flag. */
+async function setProjectSkill(cwd, skillId, enabled) {
+  addAllowedRoot(cwd);
+  const record = await loadRecord(cwd);
+  const idx = record.skills.findIndex((s) => s.skillId === skillId);
+  if (idx >= 0) {
+    record.skills[idx] = { skillId, enabled };
+  } else {
+    record.skills.push({ skillId, enabled });
+  }
+  await saveRecord(cwd, record);
+  return { ok: true };
+}
+
+// ──────────────────────────────────────────── IPC schemas
+const projectSkillsCwd = z.object({
+  cwd: z.string().min(1).max(4096),
+});
+
+const projectSkillsSet = z.object({
+  cwd: z.string().min(1).max(4096),
+  skillId: z.string().min(1).max(256),
+  enabled: z.boolean(),
+});
+
+function validated(schema, handler) {
+  return (_event, payload) => {
+    const parsed = schema.parse(payload);
+    return handler(parsed);
+  };
+}
+
+function registerProjectSkillsHandlers() {
+  ipcMain.handle(
+    'project-skills:get',
+    validated(projectSkillsCwd, ({ cwd }) => getProjectSkills(cwd)),
+  );
+  ipcMain.handle(
+    'project-skills:set',
+    validated(projectSkillsSet, ({ cwd, skillId, enabled }) =>
+      setProjectSkill(cwd, skillId, enabled),
+    ),
+  );
+}
+
+module.exports = {
+  registerProjectSkillsHandlers,
+  // Exported for tests / direct use.
+  getProjectSkills,
+  setProjectSkill,
+  projectSkillsPath,
+};

package/src/main/scheduler.cjs

@@ -280,6 +280,81 @@ async function listPrdFiles() {
   return prdParser.listPrdFiles(PRDS_DIR);
 }
 
+/**
+ * Best-effort kill of a child claude PID that the previous app instance spawned
+ * but never reaped. Used by init() to clean up the orphan tree on boot.
+ *
+ * Safety:
+ *   - PID-recycling: between app death and this call, another process may have
+ *     reused the PID. We read /proc/<pid>/cmdline (Linux) or `ps -p` (macOS)
+ *     and only SIGTERM if the cmdline starts with the claude bin path.
+ *   - Detached process group: jobs are spawned with detached:true so we kill
+ *     -pid (the group). If the group leader is already gone, that fails
+ *     silently and we fall back to single-pid kill.
+ *   - Returns synchronously after issuing SIGTERM; a 5s SIGKILL follow-up is
+ *     scheduled via setTimeout to clean up any process ignoring SIGTERM.
+ *
+ * Returns: 'killed' (cmdline matched + signal sent), 'gone' (pid not alive),
+ *          'mismatch' (pid alive but cmdline doesn't look like claude),
+ *          'unknown' (couldn't read cmdline — leave the pid alone).
+ */
+function killOrphanClaudePid(pid) {
+  if (!pid || typeof pid !== 'number' || pid <= 1) return 'gone';
+  try { process.kill(pid, 0); } catch { return 'gone'; }
+  let cmdline = '';
+  try {
+    cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
+  } catch {
+    try {
+      const out = require('node:child_process').execSync(`ps -p ${pid} -o command=`, { encoding: 'utf8', stdio: ['ignore','pipe','ignore'] });
+      cmdline = out.trim();
+    } catch { return 'unknown'; }
+  }
+  if (!/\bclaude\b/.test(cmdline)) return 'mismatch';
+  try { process.kill(-pid, 'SIGTERM'); }
+  catch { try { process.kill(pid, 'SIGTERM'); } catch { /* race: died between checks */ } }
+  setTimeout(() => {
+    try { process.kill(pid, 0); } catch { return; /* already gone */ }
+    try { process.kill(-pid, 'SIGKILL'); }
+    catch { try { process.kill(pid, 'SIGKILL'); } catch { /* race */ } }
+  }, 5000).unref?.();
+  return 'killed';
+}
+
+/**
+ * Validate that a string is safe to pass as a child_process.spawn argv element.
+ *
+ * Node.js rejects argv strings containing NUL bytes with a cryptic error:
+ *   "The argument 'args[1]' must be a string without null bytes. Received '...'"
+ *
+ * The error message truncates the offending string at ~120 chars, so when it
+ * surfaces in the queue.json `error` field the user has no way to find the
+ * actual byte. The real incident (2026-05-21, PRD 03-doc-editor-foundation)
+ * was a single NUL inside backtick code-fence in the PRD body. Total wall-clock
+ * to diagnose: ~30min. This validator catches it pre-spawn and reports the
+ * file + offset + surrounding context.
+ *
+ * Also flags other ASCII control bytes (< 0x20 except TAB/LF/CR), since they
+ * are virtually always a typo or copy-paste artifact in a markdown PRD body
+ * and may cause subtle issues in claude's prompt tokenizer.
+ */
+function validatePromptForSpawn(body, srcLabel) {
+  for (let i = 0; i < body.length; i++) {
+    const code = body.charCodeAt(i);
+    if (code < 0x20 && code !== 0x09 && code !== 0x0A && code !== 0x0D) {
+      const start = Math.max(0, i - 20);
+      const end = Math.min(body.length, i + 20);
+      const ctx = body.slice(start, end).replace(/[\x00-\x1F]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+      const hex = code.toString(16).padStart(2, '0');
+      return {
+        ok: false,
+        error: `PRD body contains control char 0x${hex} at byte offset ${i} in ${srcLabel} (context: "${ctx}"). child_process.spawn would reject this with a truncated error message; remove the control char and re-queue.`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
 // ---------- queue reconciliation ----------
 
 /**
@@ -607,8 +682,9 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
 
   // Read full PRD body fresh from disk (queue stored only the preview).
   let prompt;
+  const prdPath = path.join(PRDS_DIR, `${job.slug}.md`);
   try {
-    const parsed = await parsePrd(path.join(PRDS_DIR, `${job.slug}.md`));
+    const parsed = await parsePrd(prdPath);
     prompt = parsed.body;
   } catch (e) {
     safeLog(`[scheduler] failed to read PRD: ${e?.message}\n`);
@@ -616,6 +692,14 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
     return { exitCode: -1, durationMs: 0, error: e?.message };
   }
 
+  const promptCheck = validatePromptForSpawn(prompt, prdPath);
+  if (!promptCheck.ok) {
+    safeLog(`[scheduler] ${promptCheck.error}\n`);
+    closeFd();
+    atomicWriteJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: promptCheck.error, startedAt, finishedAt: Date.now(), durationMs: 0 });
+    return { exitCode: -1, durationMs: 0, error: promptCheck.error, sessionId };
+  }
+
   return await new Promise((resolve) => {
     const claudeBin = resolveClaudeBin();
     // Strip Claude Code env and secrets that leak in when session-manager is
@@ -822,6 +906,28 @@ function pickNextBatch(allJobs, running, cap) {
   const pending = allJobs.filter((j) => j.status === 'pending' && !running.has(j.slug));
   if (pending.length === 0) return [];
 
+  // Lowest pending group (computed up-front so the failure gate can compare).
+  const lowestPendingGroup = pending.reduce(
+    (min, j) => Math.min(min, j.parallelGroup ?? 99),
+    Infinity,
+  );
+
+  // Cross-group failure gate: refuse to advance past a group with failed jobs.
+  // Without this, a failed foundation PRD (e.g. 03-doc-editor-foundation
+  // crashed with a NUL-byte spawn error on 2026-05-21) doesn't stop later
+  // groups (04, 05, 06...) from running and silently corrupting the project
+  // state. The user can re-queue the failed job (pending) or archive it to
+  // unblock the gate, but the default is to halt until the failure is
+  // acknowledged.
+  const blockingFailures = allJobs.filter((j) =>
+    j.status === 'failed' && (j.parallelGroup ?? 99) < lowestPendingGroup,
+  );
+  if (blockingFailures.length > 0) {
+    const slugs = blockingFailures.map((j) => j.slug).join(', ');
+    console.log(`[scheduler] failure-gate: holding g${lowestPendingGroup} — ${blockingFailures.length} failed job(s) in earlier groups [${slugs}]. Reset to pending or archive to unblock.`);
+    return [];
+  }
+
   // Groups with at least one job in flight: either tracked in runningSet
   // (this process spawned it) or still marked 'running' in queue.json
   // (persisted from a previous session that hasn't been orphan-reset yet).
@@ -839,11 +945,7 @@ function pickNextBatch(allJobs, running, cap) {
   const queueRunningCount = allJobs.filter((j) => j.status === 'running').length;
   const effectiveRunning = Math.max(running.size, queueRunningCount);
 
-  // Lowest pending group.
-  const lowestPendingGroup = pending.reduce(
-    (min, j) => Math.min(min, j.parallelGroup ?? 99),
-    Infinity,
-  );
+  // (lowestPendingGroup was computed up-front for the failure-gate check.)
 
   if (activeGroups.size > 0) {
     const lowestActive = Math.min(...activeGroups);
@@ -1002,6 +1104,12 @@ DO NOT attempt the fix. ONLY write the file. When the file exists, exit immediat
 
   const claudeBin = resolveClaudeBin();
   const childEnv = cleanChildEnv();
+  const investigationPromptCheck = validatePromptForSpawn(prompt, `<investigation prompt for ${failedJob.slug}>`);
+  if (!investigationPromptCheck.ok) {
+    try { fs.writeSync(fd, `\n[scheduler] ${investigationPromptCheck.error}\n`); } catch { /* */ }
+    try { fs.closeSync(fd); } catch { /* */ }
+    return;
+  }
   let child;
   try {
     child = spawn(claudeBin, [
@@ -1103,9 +1211,33 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     await broadcast();
 
     if (actuallyFailed && failedJobSnapshot) {
-      spawnInvestigation(failedJobSnapshot, runDir).catch((e) => {
-        console.error('[scheduler] spawnInvestigation error', job.slug, e);
-      });
+      // Transient-failure detector: SIGTERM/SIGKILL within 30s = almost
+      // always external kill (user-initiated app restart, OOM-kill, manual
+      // process kill). The PRD itself didn't fail; the run was interrupted
+      // before it could do meaningful work. Spawning an Opus investigator on
+      // these is wasted tokens AND pollutes the queue with redundant fix-PRDs
+      // (real example 2026-05-21: 07-agent-view-robot-rename-lasttool got
+      // SIGTERMed at 10s by an app restart, the rename had already been done
+      // anyway, and the auto-generated fix-PRD just sat in queue.json as
+      // noise). Auto-retry up to 2x before falling through to investigation.
+      const ec = failedJobSnapshot.exitCode;
+      const transient = (ec === 143 || ec === 137) && res.durationMs < 30_000;
+      const retries = failedJobSnapshot.transientRetries ?? 0;
+      if (transient && retries < 2) {
+        console.log(`[scheduler] transient failure (exit=${ec} dur=${res.durationMs}ms) — auto-retry ${retries + 1}/2 for ${job.slug}`);
+        await mutate((s) => {
+          const i = s.jobs.findIndex((x) => x.slug === job.slug);
+          if (i >= 0) {
+            resetJobFields(s.jobs[i], null);
+            s.jobs[i].transientRetries = retries + 1;
+          }
+        });
+        await broadcast();
+      } else {
+        spawnInvestigation(failedJobSnapshot, runDir).catch((e) => {
+          console.error('[scheduler] spawnInvestigation error', job.slug, e);
+        });
+      }
     }
   } catch (e) {
     console.error('[scheduler] spawnJob error', job.slug, e);
@@ -1529,12 +1661,24 @@ async function init() {
   bootedAt = Date.now();
 
   // Boot reconciliation: mark any job that was 'running' when the app died as
-  // 'failed'. mutate() creates queue.json from defaults if it doesn't exist.
+  // 'failed', AND kill its detached claude child if still alive. Without the
+  // kill step the child keeps running as a zombie writing to the project on
+  // its own schedule, which is exactly what happened on 2026-05-21 (PID 78230
+  // writing PRD 05's output while the scheduler thought the job was orphaned).
   await mutate((state) => {
     for (const j of state.jobs) {
       if (j.status === 'running') {
+        const pid = j.runtime?.pid;
+        let killNote = '';
+        if (pid) {
+          const result = killOrphanClaudePid(pid);
+          killNote = ` (orphan pid=${pid}: ${result})`;
+          if (result === 'killed') {
+            console.log(`[scheduler] boot: SIGTERM'd orphan claude pid=${pid} for ${j.slug}`);
+          }
+        }
         j.status = 'failed';
-        j.error = 'orphaned: app restarted while running';
+        j.error = `orphaned: app restarted while running${killNote}`;
         j.finishedAt = new Date().toISOString();
         delete j.runtime;
       }