claude-code-session-manager 0.104.1 → 0.105.0

package/src/main/pty.cjs

@@ -20,6 +20,7 @@ const { addAllowedRoot } = require('./config.cjs');
 const { aliasedShellBin } = require('./lib/smProcNames.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { checkInsideHome } = require('./lib/insideHome.cjs');
+const { defaultShell } = require('./lib/defaultShell.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const opsErrorLog = require('./lib/opsErrorLog.cjs');
 const { planEpicSpawn } = require('./lib/epicSpawnPlan.cjs');
@@ -35,6 +36,15 @@ const PKG_DIR = path.join(__dirname, '..', '..');
 // chatty sessions can't balloon main-process memory.
 const REPLAY_BUFFER_MAX = 256 * 1024;
 
+// Coalescing window for pty:data IPC sends. A busy terminal emits thousands
+// of tiny node-pty onData chunks/sec; each used to cost its own main->renderer
+// IPC serialization + xterm write task. Buffering for a few ms and flushing
+// once collapses that into a handful of sends/sec with no visible latency.
+const PTY_FLUSH_MS = 8;
+// Immediate-flush size cap so a single burst (e.g. `cat` on a big file) can't
+// grow the buffer unbounded while waiting for the timer.
+const PTY_FLUSH_MAX_BYTES = 64 * 1024;
+
 /**
  * ANSI-formatted terminal text explaining a native-module / immediate-exit
  * failure and exactly how to fix it. Written straight into the tab's output so
@@ -42,20 +52,39 @@ const REPLAY_BUFFER_MAX = 256 * 1024;
  */
 function nativeModuleHelp(reason) {
   const mac = process.platform === 'darwin';
-  const lines = [
+  const head = [
     '',
     `\x1b[1;33m[session-manager] Terminal could not start.\x1b[0m`,
     `\x1b[33m${reason}\x1b[0m`,
     '',
-    `This is almost always the node-pty native module not matching this`,
-    `Electron build. Rebuild it once:`,
+  ];
+  if (process.platform === 'win32') {
+    return (
+      [
+        ...head,
+        `This is almost always a damaged install (the node-pty native module`,
+        `is missing or does not match this build). Reinstall session-manager:`,
+        '',
+        `  - Installed app: run the latest installer again.`,
+        `  - npm package:   \x1b[36mnpm install -g claude-code-session-manager@latest\x1b[0m`,
+        '',
+        `Then quit and reopen session-manager.`,
+        '',
+      ].join('\r\n') + '\r\n'
+    );
+  }
+  const lines = [
+    ...head,
+    `node-pty ships prebuilt binaries for macOS, Linux and Windows on x64 and`,
+    `arm64. This machine is \x1b[36m${process.platform}-${process.arch}\x1b[0m. If the module failed to load, the`,
+    `install is probably damaged. Reinstall session-manager:`,
+    '',
+    `  \x1b[36mnpm i -g claude-code-session-manager@latest\x1b[0m`,
+    `  (or re-run the npx command)`,
     '',
-    `  \x1b[36mcd ${PKG_DIR}\x1b[0m`,
-    `  \x1b[36mnpx electron-rebuild -f -w node-pty\x1b[0m`,
+    `On any other platform node-pty compiles from source and needs build tools:`,
+    mac ? `  macOS: \x1b[36mxcode-select --install\x1b[0m` : `  Linux: build-essential + python3`,
     '',
-    mac ? `macOS: if the rebuild fails, install the compiler first:` : '',
-    mac ? `  \x1b[36mxcode-select --install\x1b[0m` : '',
-    mac ? '' : '',
     `Then quit and reopen session-manager.`,
     '',
   ].filter((l) => l !== '');
@@ -77,9 +106,35 @@ class PtyManager {
     // reload — would read as the session having been wiped. Bounded ring so a
     // long-lived session can't grow this without limit.
     this.buffers = new Map();
+    // tabId -> pending un-sent output, flushed on a timer or size cap (see
+    // PTY_FLUSH_MS / PTY_FLUSH_MAX_BYTES / #flushOutput below).
+    this.outBuffers = new Map();
+    this.flushTimers = new Map(); // tabId -> Timeout
     this.window = null;
   }
 
+  /** Send any pending buffered output for `tabId` now, and clear its timer. */
+  #flushOutput(tabId) {
+    const timer = this.flushTimers.get(tabId);
+    if (timer) {
+      clearTimeout(timer);
+      this.flushTimers.delete(tabId);
+    }
+    const pending = this.outBuffers.get(tabId);
+    if (pending) {
+      this.outBuffers.delete(tabId);
+      sendIfAlive(this.window, `pty:data:${tabId}`, pending);
+    }
+  }
+
+  /** Discard pending buffered output for `tabId` without sending (kill/dispose). */
+  #dropOutput(tabId) {
+    const timer = this.flushTimers.get(tabId);
+    if (timer) clearTimeout(timer);
+    this.flushTimers.delete(tabId);
+    this.outBuffers.delete(tabId);
+  }
+
   attachWindow(window) {
     this.window = window;
   }
@@ -175,8 +230,8 @@ class PtyManager {
       SM_PROJECT_ROOT: cwd,
     });
 
-    const shell = process.env.SHELL || '/bin/bash';
-    console.log('[pty] spawning shell', shell);
+    const shell = defaultShell({ platform: process.platform, env: process.env, exists: fs.existsSync });
+    console.log('[pty] spawning shell', shell.file);
     // Tab ID = claudeSessionId (see CLAUDE.md), and Chat/Terminal are two views over ONE session,
     // so this asks the same decision function chatRunner.cjs does (epicSpawnPlan.cjs). `cwd`
     // itself is NEVER repointed; only this actual PTY spawn option is (epicSpawnCwd.cjs's
@@ -220,7 +275,8 @@ class PtyManager {
       // job's descendants; no shell in a job's process tree is ever spawned
       // through here, so that detection is unaffected. Non-bash/zsh shells and
       // any alias failure fall back to the real path.
-      proc = pty.spawn(aliasedShellBin(shell), ['-il'], {
+      const shellFile = process.platform === 'win32' ? shell.file : aliasedShellBin(shell.file);
+      proc = pty.spawn(shellFile, shell.args, {
         name: 'xterm-256color',
         cols,
         rows,
@@ -251,7 +307,16 @@ class PtyManager {
     proc.onData((data) => {
       gotData = true;
       this.#appendReplay(tabId, data);
-      sendIfAlive(this.window, `pty:data:${tabId}`, data);
+      const next = (this.outBuffers.get(tabId) ?? '') + data;
+      if (next.length >= PTY_FLUSH_MAX_BYTES) {
+        this.outBuffers.set(tabId, next);
+        this.#flushOutput(tabId);
+      } else {
+        this.outBuffers.set(tabId, next);
+        if (!this.flushTimers.has(tabId)) {
+          this.flushTimers.set(tabId, setTimeout(() => this.#flushOutput(tabId), PTY_FLUSH_MS));
+        }
+      }
     });
 
     proc.onExit(({ exitCode, signal }) => {
@@ -262,8 +327,12 @@ class PtyManager {
         console.log('[pty] suppressed exit broadcast for killed tabId=', tabId);
         this.sessions.delete(tabId);
         this.buffers.delete(tabId);
+        this.#dropOutput(tabId);
         return;
       }
+      // Flush any still-buffered output BEFORE the exit event so the renderer
+      // sees every byte the process produced, in order.
+      this.#flushOutput(tabId);
       // Fast-exit detector: a shell that dies in <1.2s with a non-zero status
       // and never printed anything almost certainly couldn't exec (broken
       // node-pty spawn-helper / ABI on macOS). Explain it in the tab instead of
@@ -341,6 +410,7 @@ class PtyManager {
       }
       this.sessions.delete(tabId);
       this.buffers.delete(tabId);
+      this.#dropOutput(tabId);
     }
   }
 

package/src/main/runVerify.cjs

@@ -168,13 +168,14 @@ function parseLog(logPath) {
   try {
     text = fs.readFileSync(logPath, 'utf8');
   } catch (e) {
-    return { events: [], resultEvent: null, error: e.message };
+    return { events: [], resultEvent: null, error: e.message, transcriptCommitShas: [] };
   }
 
   const events = [];
   let resultEvent = null;
   let seq = 0;
   let transcriptCommitLanded = false;
+  const transcriptCommitShaSet = new Set();
 
   for (const line of text.split('\n')) {
     const trimmed = line.trim();
@@ -194,6 +195,8 @@ function parseLog(logPath) {
     }
     if (obj.tool_use_result?.gitOperation?.commit?.kind === 'committed') {
       transcriptCommitLanded = true;
+      const sha = obj.tool_use_result.gitOperation.commit.sha;
+      if (typeof sha === 'string' && sha) transcriptCommitShaSet.add(sha);
     }
 
     // Final result event.
@@ -245,7 +248,7 @@ function parseLog(logPath) {
     }
   }
 
-  return { events, resultEvent, error: null, transcriptCommitLanded };
+  return { events, resultEvent, error: null, transcriptCommitLanded, transcriptCommitShas: [...transcriptCommitShaSet] };
 }
 
 // Stable, narrow substrings of the harness's auto-background tool_result text
@@ -549,6 +552,28 @@ function scanSentinel(resultEvent, events) {
   return null;
 }
 
+/**
+ * One-line reason after `SCHEDULER_VERDICT: FAIL` (same two-source scan order
+ * as scanSentinel). Trimmed, capped at 300 chars; '' when absent.
+ */
+function scanSentinelReason(resultEvent, events) {
+  const RE = /^SCHEDULER_VERDICT:\s*FAIL\b[ \t]*([^\n]*)/m;
+  const clip = (m) => m[1].trim().slice(0, 300);
+  if (resultEvent && resultEvent.resultText) {
+    const m = resultEvent.resultText.match(RE);
+    if (m) return clip(m);
+  }
+  let lastToolResult = null;
+  for (const ev of events) {
+    if (ev.kind === 'tool_result') lastToolResult = ev;
+  }
+  if (lastToolResult && lastToolResult.content) {
+    const m = lastToolResult.content.match(RE);
+    if (m) return clip(m);
+  }
+  return '';
+}
+
 /**
  * Scan for a `FOREIGN_WIP_PATHS: <comma-separated paths>` evidence line —
  * the mandatory companion to a `SCHEDULER_VERDICT: BLOCKED_BY_FOREIGN_WIP`
@@ -1079,6 +1104,20 @@ async function verifyRun({
     // Scan for the SCHEDULER_VERDICT sentinel emitted by the finish protocol.
     const sentinel = scanSentinel(resultEvent, events);
 
+    // An explicit executor FAIL is always blocking — outranks every other
+    // verdict and every override below (early return). Transcript issues are
+    // kept as annotations so nothing is lost.
+    if (sentinel === 'fail') {
+      const failReason = scanSentinelReason(resultEvent, events);
+      const kept = [...annotations, ...issues.map((i) => ({ verdict: i.verdict, reason: i.reason }))];
+      return conclude(
+        'sentinel_fail',
+        'executor reported SCHEDULER_VERDICT: FAIL' + (failReason ? ': ' + failReason : ''),
+        'needs_review',
+        { sentinel, ...(kept.length ? { annotations: kept } : {}) },
+      );
+    }
+
     // Ground truth outranks heuristics: an exit-0 run that landed a commit
     // ATTRIBUTABLE TO THIS RUN (spawnJob's own guardHeadBefore/headAtExit
     // delta, or the repo-wide committedDuringRun window scan) and never
@@ -1377,6 +1416,7 @@ module.exports = {
   checkDeps,
   parseLog,
   scanSentinel,
+  scanSentinelReason,
   scanForeignWipPathsClaim,
   isMergeMainSlug,
   extractMergeMainPrNumber,

package/src/main/scheduler.cjs

@@ -82,6 +82,7 @@ const { isResetFresh, bindingWindow, degradedBudget } = require('./lib/usageCirc
 const { computeQueueHealth } = require('./lib/queueHealth.cjs');
 const { createLoadGate, topCpuConsumers } = require('./lib/loadGate.cjs');
 const { openLog, withChildAndLog } = require('./lib/childWithLog.cjs');
+const { killTree, detachedSpawnOpts } = require('./lib/killTree.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { createBroadcastCoalescer } = require('./lib/broadcastCoalescer.cjs');
 const prdParser = require('./scheduler/prdParser.cjs');
@@ -846,6 +847,51 @@ async function computeCommittedDuringRun(cwd, headBefore, headAfter, startedAt,
   return module.exports.committedInWindow(cwd, startedAt, untilIso);
 }
 
+/**
+ * Which commit does this run get credit for? A worktree-isolated run shares the
+ * main checkout with concurrent jobs, so a HEAD move there may be someone else's
+ * integration — credit comes only from this run's own integration result. An
+ * in-place run keeps the HEAD-delta / time-window behaviour.
+ */
+function resolveRunCommitAttribution({
+  ranInWorktree, integratedSha, headBefore, headAtExit, committedInWindow,
+  rangeCommits, transcriptCommitShas, siblingOverlap,
+}) {
+  if (ranInWorktree) {
+    const landedCommit = integratedSha || null;
+    return { landedCommit, committedDuringRun: Boolean(landedCommit) };
+  }
+  const shas = Array.isArray(transcriptCommitShas) ? transcriptCommitShas.filter(Boolean) : [];
+  if (shas.length === 0 && !siblingOverlap) {
+    const headMoved = Boolean(headBefore && headAtExit && headBefore !== headAtExit);
+    return {
+      landedCommit: headMoved ? headAtExit : null,
+      committedDuringRun: headMoved || Boolean(committedInWindow),
+    };
+  }
+  // Shared tree with possible siblings (or transcript evidence): credit only a
+  // commit in the range that this run's own transcript reported.
+  const own = (Array.isArray(rangeCommits) ? rangeCommits : [])
+    .find((c) => shas.some((sha) => c.startsWith(sha)));
+  const landedCommit = own || null;
+  return { landedCommit, committedDuringRun: Boolean(landedCommit) };
+}
+
+/** Full shas in `before..after` (newest first); [] on any error. Never throws. */
+function gitRangeCommits(cwd, before, after) {
+  return new Promise((resolve) => {
+    if (!cwd || !before || !after || before === after) { resolve([]); return; }
+    execFile(
+      'git', ['-C', cwd, 'rev-list', `${before}..${after}`],
+      { timeout: 10_000, windowsHide: true },
+      (err, out) => {
+        if (err) { resolve([]); return; }
+        resolve(String(out || '').split('\n').map((l) => l.trim()).filter(Boolean));
+      },
+    );
+  });
+}
+
 /**
  * Read-only check: is a job's `sm-job/<slug>` worktree branch already fully
  * integrated into `cwd`'s current HEAD — i.e. every commit on the branch is
@@ -2769,6 +2815,8 @@ function killOrphanClaudePid(pid, recordedIdentity = null) {
     && isDifferentProcess(recordedIdentity, procIdentityOf(pid))) {
     return 'mismatch';
   }
+  // win32 has no /proc or `ps`: the identity heuristic can't run, so never reap.
+  if (process.platform === 'win32') return 'unknown';
   let cmdline = '';
   try {
     cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').replace(/\0/g, ' ');
@@ -2779,12 +2827,10 @@ function killOrphanClaudePid(pid, recordedIdentity = null) {
     } 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 */ } }
+  killTree(pid, 'SIGTERM');
   setTimeout(() => {
     try { process.kill(pid, 0); } catch { return; /* already gone */ }
-    try { process.kill(-pid, 'SIGKILL'); }
-    catch { try { process.kill(pid, 'SIGKILL'); } catch { /* race */ } }
+    killTree(pid, 'SIGKILL');
   }, 5000).unref?.();
   return 'killed';
 }
@@ -6302,10 +6348,10 @@ async function executeJob(job, runDir, defaultCwd, onPid, execCwd, resumeTarget
           ...(jobSpawn.argv0 ? { argv0: jobSpawn.argv0 } : {}),
           // detached:true puts the child in its own process group so we can kill
           // the entire descendant tree (including any stray background bashes the
-          // agent spawned) with `process.kill(-pid)`. Without this, child.kill()
+          // agent spawned) with killTree(pid). Without this, child.kill()
           // only kills the immediate `claude` process, leaving orphaned subprocs
           // that keep the parent alive (the 2026-05-10 cellar-publish hang).
-          detached: true,
+          ...detachedSpawnOpts(),
         },
       },
       watchdogs: [resultTailWatchdog, deadmanWatchdog, idleTailWatchdog, budgetWatchdog],
@@ -7249,6 +7295,7 @@ async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPat
   let worktreeIntegrationDetail = null;
   let mergeAutoResolved = null;
   let mergeAutoResolvedPaths = null;
+  let integratedSha = null;
   try {
     worktreeLeftoverDirty = (await uncommitted(worktree.dir)) || [];
     // Salvage the worktree's full diff (tracked + untracked) to the run
@@ -7273,6 +7320,7 @@ async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPat
       worktreeIntegrationDetail = integration;
       console.error(`[scheduler] ${job.slug}: worktree branch integration FAILED (${integration.reason}) — branch ${worktree.branch} preserved in ${guardCwd} for manual recovery`);
     } else if (integration.integrated) {
+      integratedSha = integration.sha || null;
       console.log(`[scheduler] ${job.slug}: worktree branch ${worktree.branch} integrated into ${guardCwd}${integration.mergeCommit ? ' (merge commit)' : ' (fast-forward)'}`);
       if (integration.autoResolved) {
         mergeAutoResolved = integration.autoResolved;
@@ -7294,7 +7342,7 @@ async function finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPat
       await jw.cleanupJobWorktree({ cwd: guardCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
     } catch { /* already reported above */ }
   }
-  return { worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths };
+  return { worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha };
 }
 
 /**
@@ -7686,6 +7734,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
     // self-healed rather than silently looking like an ordinary merge.
     let mergeAutoResolved = null;
     let mergeAutoResolvedPaths = null;
+    let integratedSha = null;
     // A job's uncommitted-work patch, whichever isolation mode produced it —
     // set by EITHER branch below, never both (worktree.ok picks exactly one
     // shape for the whole run). Named generically (not "worktree...") because
@@ -7721,7 +7770,7 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
       }, reviewInRun);
     } finally {
       if (worktree.ok) {
-        ({ worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths } =
+        ({ worktreeLeftoverDirty, salvagePatch, worktreeIntegrationFailure, worktreeIntegrationDetail, mergeAutoResolved, mergeAutoResolvedPaths, integratedSha } =
           await finalizeJobWorktree({ job, runDir, worktree, guardCwd, carriedPaths }));
       } else {
         // In-place run (non-git cwd, cap reached, env-disabled, or a carry-over
@@ -7873,15 +7922,50 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
       // Used by the sentinel override: SCHEDULER_VERDICT: PASS + a landed
       // commit together override incidental transcript noise verdicts.
       const headAtExit = await gitHead(guardCwd);
-      const committedDuringRun = await computeCommittedDuringRun(
-        guardCwd,
-        guardHeadBefore,
+      // Worktree runs: attribution comes only from this run's own integration
+      // (a concurrent job's commit moving shared HEAD must not count).
+      const committedInWindow = worktree.ok
+        ? false
+        : await computeCommittedDuringRun(
+          guardCwd,
+          guardHeadBefore,
+          headAtExit,
+          job.startedAt,
+          new Date().toISOString(),
+        );
+      let rangeCommits = [];
+      let transcriptCommitShas = [];
+      let siblingOverlap = false;
+      if (!worktree.ok) {
+        rangeCommits = await gitRangeCommits(guardCwd, guardHeadBefore, headAtExit);
+        transcriptCommitShas = parseLog(path.join(runDir, `${job.slug}.log`)).transcriptCommitShas || [];
+        const overlapState = await readQueue().catch(() => ({ jobs: [] }));
+        const myStart = Date.parse(job.startedAt) || 0;
+        const myEnd = Date.now();
+        siblingOverlap = (overlapState.jobs || []).some((j) => {
+          if (j.slug === job.slug || (j.cwd || defaultCwd) !== guardCwd) return false;
+          if (j.status === 'running') return true;
+          const jStart = Date.parse(j.startedAt);
+          const jEnd = Date.parse(j.finishedAt);
+          if (!Number.isFinite(jStart) && !Number.isFinite(jEnd)) return false;
+          const s0 = Number.isFinite(jStart) ? jStart : jEnd;
+          const e0 = Number.isFinite(jEnd) ? jEnd : jStart;
+          return s0 <= myEnd && e0 >= myStart;
+        });
+      }
+      const attribution = resolveRunCommitAttribution({
+        ranInWorktree: Boolean(worktree.ok),
+        integratedSha,
+        headBefore: guardHeadBefore,
         headAtExit,
-        job.startedAt,
-        new Date().toISOString(),
-      );
-      if (guardHeadBefore && headAtExit && headAtExit !== guardHeadBefore) {
-        jobLandedCommitThisRun = headAtExit;
+        committedInWindow,
+        rangeCommits,
+        transcriptCommitShas,
+        siblingOverlap,
+      });
+      const committedDuringRun = attribution.committedDuringRun;
+      if (attribution.landedCommit) {
+        jobLandedCommitThisRun = attribution.landedCommit;
       }
 
       const prdPath = (await resolveVerifyPrdPath(job)) ?? archivedPrdPathForJob(job);
@@ -7955,7 +8039,9 @@ async function spawnJob(job, runId, runDir, defaultCwd, resumeTarget = null, sib
           (j) => j.slug !== job.slug && j.status === 'running' && (j.cwd || defaultCwd) === guardCwd,
         );
         const guardHeadAfter = await gitHead(guardCwd);
-        const jobSelfCommitted = guardHeadBefore && guardHeadAfter && guardHeadAfter !== guardHeadBefore;
+        const jobSelfCommitted = worktree.ok
+          ? Boolean(jobLandedCommitThisRun)
+          : guardHeadBefore && guardHeadAfter && guardHeadAfter !== guardHeadBefore;
         const guardVerdict = commitGuardVerdict({
           newlyDirty,
           siblingRunning,
@@ -9703,9 +9789,7 @@ function bootRowPid(j, logPathOf) {
 }
 
 function signalAdoptedGroup(pgid, signal, pid) {
-  try { process.kill(-pgid, signal); } catch {
-    try { process.kill(pid, signal); } catch { /* already dead */ }
-  }
+  if (!killTree(pgid, signal)) killTree(pid, signal);
 }
 
 async function superviseAdoptedRunsPass(jobs) {
@@ -13595,6 +13679,7 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
 module.exports = {
   reportSchedulerError,
   finalizeJobWorktree,
+  resolveRunCommitAttribution,
   worktreeIntegrationVerdict,
   guardedTick,
   rescheduleIntervalTick,

package/src/main/seedSchedulerMcp.cjs

@@ -38,6 +38,7 @@ const { spawn } = require('node:child_process');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
 const { writeJsonSync } = require('./config.cjs');
+const { nodeSpawnSpec } = require('./lib/appRuntime.cjs');
 
 const SERVER_NAME = 'session-manager-scheduler';
 const MAX_ATTEMPTS = 3; // give a transient first-boot failure a few chances
@@ -102,6 +103,14 @@ function scriptPathMissing() {
   }
 }
 
+/** argv for `claude mcp add`: system `node` in dev/npx, the app binary with
+ *  ELECTRON_RUN_AS_NODE=1 when packaged (an installer user may have no Node). */
+function mcpAddArgv(serverPath) {
+  const spec = nodeSpawnSpec(serverPath);
+  const envFlags = Object.entries(spec.env).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
+  return ['mcp', 'add', SERVER_NAME, '--scope', 'user', ...envFlags, '--', spec.command, ...spec.args];
+}
+
 /** Run `claude mcp add session-manager-scheduler --scope user -- node <serverPath>`.
  *  No shell:true — argv array passed directly to spawn. */
 function runClaudeMcpAdd(serverPath) {
@@ -111,7 +120,7 @@ function runClaudeMcpAdd(serverPath) {
     try {
       proc = spawn(
         target.command,
-        ['mcp', 'add', SERVER_NAME, '--scope', 'user', '--', 'node', serverPath],
+        mcpAddArgv(serverPath),
         {
           ...(target.argv0 ? { argv0: target.argv0 } : {}),
           cwd: os.homedir(),
@@ -200,4 +209,4 @@ async function seedSchedulerMcp({ logger = console, addFn = runClaudeMcpAdd, rem
   }
 }
 
-module.exports = { seedSchedulerMcp, markerPath, MAX_ATTEMPTS, serverScriptPath, SERVER_NAME };
+module.exports = { seedSchedulerMcp, mcpAddArgv, markerPath, MAX_ATTEMPTS, serverScriptPath, SERVER_NAME };

package/src/main/usage.cjs

@@ -244,7 +244,10 @@ async function networkFetchUsage() {
 
   if (result.kind === 'ok') {
     cache = { data: result.data, fetchedAt: Date.now(), sourceCredsExpiresAt: result.data.credentialsExpiresAt };
-    persistCache(cache).catch(() => {});
+    // Awaited so fetchUsage() never resolves while this write is still
+    // in-flight — a fire-and-forget write here outlived its test's afterEach
+    // rmSync of HOME, causing a flaky ENOTEMPTY under CPU load.
+    await persistCache(cache).catch(() => {});
     retryNotBeforeMs = 0;
     lastRateLimitedResult = null;
     circuit.recordSuccess(result.data);

package/src/preload/api.d.ts

@@ -1,5 +1,15 @@
 import type { PromptSession } from '../renderer/state/promptSessions';
 
+/** Mirrors the item shape returned by main/lib/prereqs.cjs checkPrereqs(). */
+export interface PrereqItem {
+  id: string;
+  label: string;
+  ok: boolean;
+  version: string | null;
+  detail: string | null;
+  fix: { command: string; shell: 'sh' | 'powershell'; url?: string } | null;
+}
+
 export interface ActionOutcome {
   ok: boolean;
   kind?: 'info' | 'warn' | 'error';
@@ -1550,6 +1560,10 @@ export interface SessionManagerAPI {
     /** Boot diagnostic — resolved claude binary path + whether it was found
      *  on disk (false means spawn will rely on PATH and may ENOENT). */
     claudeBinStatus: () => Promise<{ resolved: string; foundOnDisk: boolean }>;
+    /** Fresh prerequisite probe (git, claude CLI, auth, Git Bash on Windows). */
+    prereqs: () => Promise<PrereqItem[]>;
+    /** Opens the OS terminal running the item's official install command (looked up main-side by id). */
+    prereqsRunFix: (id: string) => Promise<{ ok: true; opener: string } | { ok: false; error: string }>;
     /** Boot diagnostic — assertCwdInsideHome(os.homedir()) result. ok=false
      *  on macOS symlinked-/Users mismatch and blocks all session spawns. */
     homeSelfCheck: () => Promise<{ ok: boolean; error?: string; realCwd?: string }>;

package/src/preload/index.cjs

@@ -20,6 +20,8 @@ contextBridge.exposeInMainWorld('api', {
     // Boot diagnostics (v0.10.1) — renderer polls at mount to surface
     // missing-claude-bin / home-symlink-mismatch as toasts.
     claudeBinStatus: () => ipcRenderer.invoke('app:claude-bin-status'),
+    prereqs: () => ipcRenderer.invoke('app:prereqs'),
+    prereqsRunFix: (id) => ipcRenderer.invoke('app:prereqs-run-fix', id),
     homeSelfCheck: () => ipcRenderer.invoke('app:home-self-check'),
     seedStatus: () => ipcRenderer.invoke('app:seed-status'),
     delegationReadiness: (cwd) => ipcRenderer.invoke('app:delegation-readiness', { cwd }),

package/src/seed/agents/validator.md

@@ -4,14 +4,14 @@ description: Validates a finished PLAN (the PRDs its validate PRD lists) once, a
 tools: Read, Grep, Glob, Bash
 model: sonnet
 title: Engineering — Plan Validator
-seedVersion: 2
+seedVersion: 3
 ---
 
 You are validator. You judge whether a plan's PRDs actually landed what they promised. You do not fix anything, you do not re-implement, you do not queue PRDs — your output is evidence and verdicts, read by the architect who owns the plan.
 
 ## Inputs
 
-Your PRD's `# Acceptance criteria` lists the plan's PRD slugs and where each PRD file lives (`session-manager-operations/scheduler/epics/<epic>/prds/` while queued, `prds-archived/` once terminal — locate by slug in either). Everything else comes from the working tree and `git log`.
+Your PRD's `# Acceptance criteria` lists the plan's PRD slugs. PRD files live under `$SM_PROJECT_ROOT/session-manager-operations/scheduler/epics/<epic>/` — `prds/` while queued, `prds-archived/` (or a timestamped subfolder of it) once terminal; find by slug, e.g. `find "$SM_PROJECT_ROOT/session-manager-operations/scheduler/epics/<epic>" -name '*<slug>.md'`. This folder is gitignored, so it is never present in the job worktree — don't look for it there. If a PRD file is missing, fall back to `$SM_PROJECT_ROOT/session-manager-operations/scheduler/state/queue.json` / `history.jsonl` for that slug's `landedCommit`, and record the missing file as a Minor (not Important) finding. Everything else comes from the working tree and `git log`.
 
 ## Procedure (in this order)
 

package/dist/assets/DataModel-BHcPa2nA.js

@@ -1 +0,0 @@
-import{ax as d,i as j,aj as $,a2 as g,ai as e,v as E,m as N,al as S,a3 as b,aB as T,a as p,_ as D,j as v,E as R}from"./index-DbR91Z5j.js";import{V}from"./ViewTabs-BQ_HbQFq.js";import"./monaco-editor-BW5C4Iv1.js";const _=[{key:"diagram",label:"Diagram"},{key:"tables",label:"Tables"}];function C(){const[s,t]=d.useState("diagram"),[a,i]=d.useState(null),[l,n]=d.useState(()=>new Set),c=d.useMemo(()=>j.filter(r=>!l.has(r.group)),[l]),m=d.useMemo(()=>$(c),[c]),o=r=>{n(x=>{const h=new Set(x);return h.has(r)?h.delete(r):h.add(r),h}),i(null)},u=a?g(a):null,y=r=>c.some(x=>x.id===r);return e.jsx(E,{toolbar:e.jsxs(e.Fragment,{children:[e.jsx(V,{options:_,active:s,onChange:t}),e.jsx(G,{hiddenGroups:l,onToggle:o}),e.jsxs("span",{className:"ml-auto text-fg-faint",children:[j.length," entities"]})]}),children:s==="diagram"?e.jsxs("div",{className:"h-full flex",children:[e.jsx("div",{className:"flex-1 min-w-0 overflow-auto",children:e.jsx(M,{layout:m,selectedId:a,onSelect:r=>i(x=>x===r?null:r)})}),e.jsx("div",{className:"w-96 shrink-0 border-l border-line overflow-y-auto",children:u?e.jsx(B,{entity:u,onSelectRelated:r=>y(r)?i(r):void 0}):e.jsx(N,{title:"select an entity",hint:"click a box in the diagram to see its storage, fields, and relations"})})]}):e.jsx(F,{})})}const L=d.memo(C);function G({hiddenGroups:s,onToggle:t}){return e.jsx("div",{className:"flex items-center gap-1.5 flex-wrap",children:v.map(a=>{const i=s.has(a.id);return e.jsxs("button",{onClick:()=>t(a.id),title:`${a.blurb} (${a.realm})`,className:`flex items-center gap-1 px-1.5 py-0.5 rounded border text-[10.5px] ${i?"border-line text-fg-faint opacity-50":"border-line text-fg-dim hover:text-fg"}`,children:[e.jsx("span",{className:`w-1.5 h-1.5 rounded-full ${a.tone.dot}`}),a.label,e.jsx("span",{className:"text-fg-faint",children:a.realm})]},a.id)})})}function M({layout:s,selectedId:t,onSelect:a}){const i=d.useMemo(()=>t?new Set(S(t)):null,[t]),l=n=>!!t&&(n.relation.from===t||n.relation.to===t);return s.boxes.length===0?e.jsx(N,{title:"no entities in view",hint:"toggle a group in the legend to show its entities"}):e.jsxs("div",{className:"relative p-4",style:{width:s.width+32,height:s.height+32},children:[e.jsxs("svg",{width:s.width,height:s.height,className:"absolute left-4 top-4 overflow-visible",children:[s.edges.map(n=>{const c=l(n);return e.jsx("path",{"data-testid":`erd-edge-${n.relation.from}-${n.relation.to}`,d:n.d,fill:"none",className:c?"stroke-accent":"stroke-line",strokeWidth:c?2:1,opacity:t&&!c?.25:1},`${n.relation.from}-${n.relation.to}-${n.relation.label}`)}),s.edges.map(n=>l(n)?e.jsx("text",{x:n.mx,y:n.my,textAnchor:"middle",className:"fill-fg-dim text-[10px]",children:n.relation.label},`label-${n.relation.from}-${n.relation.to}-${n.relation.label}`):null)]}),s.boxes.map(n=>e.jsx(O,{box:n,selected:n.id===t,dimmed:!!t&&n.id!==t&&!(i!=null&&i.has(n.id)),onClick:()=>a(n.id)},n.id))]})}function O({box:s,selected:t,dimmed:a,onClick:i}){const l=g(s.id),n=b(s.group),c=l.fields.slice(0,R),m=l.fields.length-c.length;return e.jsxs("button",{type:"button","data-testid":`erd-box-${s.id}`,onClick:i,className:`absolute text-left rounded border overflow-hidden bg-bg-hi ${t?"border-accent ring-1 ring-accent":"border-line"} ${a?"opacity-30":""}`,style:{left:s.x,top:s.y,width:s.w,height:s.h},children:[e.jsxs("div",{className:"px-2 py-1 border-b border-line flex items-center gap-1.5",children:[e.jsx("span",{className:`w-1.5 h-1.5 rounded-full shrink-0 ${n.tone.dot}`}),e.jsx("span",{className:"text-[11px] font-semibold text-fg truncate",children:l.name})]}),l.aka&&e.jsx("div",{className:"px-2 pt-0.5 text-[9.5px] text-fg-faint truncate",children:l.aka}),e.jsxs("div",{className:"px-2 py-0.5",children:[c.map(o=>e.jsxs("div",{className:"text-[9.5px] font-mono text-fg-dim truncate flex items-center gap-1",children:[o.key&&e.jsx("span",{className:"text-fg-faint",children:o.key}),e.jsx("span",{className:"truncate",children:o.name})]},o.name)),m>0&&e.jsxs("div",{className:"text-[9.5px] text-fg-faint italic",children:["+",m," more"]})]})]})}function w({fields:s}){return e.jsxs("table",{className:"w-full text-[11px] font-mono",children:[e.jsx("thead",{className:"text-fg-faint uppercase tracking-wide text-[9.5px]",children:e.jsxs("tr",{className:"border-b border-line",children:[e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"name"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"type"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"key"}),e.jsx("th",{className:"text-left font-normal px-2 py-1",children:"note"})]})}),e.jsx("tbody",{children:s.map(t=>e.jsxs("tr",{className:"border-b border-line/50",children:[e.jsxs("td",{className:"px-2 py-1 text-fg",children:[t.name,t.optional&&e.jsx("span",{className:"text-fg-faint",children:"?"})]}),e.jsx("td",{className:"px-2 py-1 text-fg-dim",children:t.type}),e.jsx("td",{className:"px-2 py-1",children:t.key&&e.jsxs(p,{tone:t.key==="pk"?"accent":"dim",children:[t.key,t.ref?` → ${t.ref}`:""]})}),e.jsx("td",{className:"px-2 py-1 text-fg-faint",children:t.note})]},t.name))})]})}function k({entity:s}){return e.jsxs("div",{className:"space-y-1 text-[11px]",children:[e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"path"}),e.jsx("span",{className:"font-mono text-fg-dim break-all",children:s.store.path})]}),e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"format"}),e.jsx("span",{className:"font-mono text-fg-dim",children:s.store.format})]}),s.store.writer&&e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"writer"}),e.jsxs(p,{tone:"accent",children:["single-writer: ",s.store.writer]})]}),e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:"text-fg-faint w-20 shrink-0",children:"definedIn"}),e.jsx("span",{className:"font-mono text-fg-dim break-all",children:s.store.definedIn})]})]})}function B({entity:s,onSelectRelated:t}){const a=b(s.group),i=T(s.id);return e.jsxs("div",{className:"p-3 space-y-3",children:[e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-1.5",children:[e.jsx("span",{className:`w-2 h-2 rounded-full ${a.tone.dot}`}),e.jsx("span",{className:"text-sm font-semibold text-fg",children:s.name})]}),s.aka&&e.jsx("div",{className:"text-[10.5px] text-fg-faint",children:s.aka}),e.jsx(p,{tone:"dim",className:"mt-1",children:a.label})]}),e.jsx("div",{className:"text-xs text-fg-dim leading-relaxed",children:s.summary}),e.jsxs("div",{children:[e.jsx(f,{children:"storage"}),e.jsx(k,{entity:s})]}),e.jsxs("div",{children:[e.jsx(f,{children:"fields"}),e.jsx(w,{fields:s.fields})]}),s.notes&&s.notes.length>0&&e.jsxs("div",{children:[e.jsx(f,{children:"notes"}),e.jsx("ul",{className:"list-disc pl-4 space-y-0.5 text-xs text-fg-dim",children:s.notes.map(l=>e.jsx("li",{children:l},l))})]}),e.jsxs("div",{children:[e.jsx(f,{children:"relations"}),i.length===0?e.jsx("div",{className:"text-xs text-fg-faint italic",children:"no relations"}):e.jsx("ul",{className:"space-y-1",children:i.map(l=>{const n=l.from===s.id?l.to:l.from,c=g(n);return e.jsxs("li",{className:"flex items-center gap-1.5 text-xs",children:[e.jsx("span",{className:"font-mono text-fg-faint w-10 shrink-0",children:D(l.cardinality)}),e.jsx("span",{className:"text-fg-dim",children:l.label}),l.via&&e.jsxs("span",{className:"font-mono text-[10px] text-fg-faint",children:["via ",l.via]}),e.jsx("button",{type:"button",onClick:()=>t(n),className:"ml-auto text-accent hover:underline font-mono",children:c.name})]},`${l.from}-${l.to}-${l.label}`)})})]})]})}function f({children:s}){return e.jsx("div",{className:"text-[10.5px] uppercase tracking-wide text-fg-faint mb-1 font-mono",children:s})}function F(){return e.jsx("div",{className:"p-4 space-y-6",children:v.map(s=>{const t=j.filter(a=>a.group===s.id);return t.length===0?null:e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-1.5 mb-2",children:[e.jsx("span",{className:`w-2 h-2 rounded-full ${s.tone.dot}`}),e.jsx("span",{className:"text-xs font-semibold text-fg",children:s.label}),e.jsx("span",{className:"text-[10.5px] text-fg-faint",children:s.realm})]}),e.jsx("div",{className:"grid grid-cols-1 xl:grid-cols-2 gap-3",children:t.map(a=>e.jsxs("div",{className:"border border-line rounded bg-bg-hi p-3 space-y-2",children:[e.jsxs("div",{children:[e.jsxs("div",{className:"flex items-center gap-2",children:[e.jsx("span",{className:"text-sm font-semibold text-fg",children:a.name}),a.aka&&e.jsx("span",{className:"text-[10.5px] text-fg-faint",children:a.aka})]}),e.jsx(p,{tone:"dim",className:"mt-1",children:s.label})]}),e.jsx("div",{className:"text-xs text-fg-dim leading-relaxed",children:a.summary}),e.jsx(k,{entity:a}),e.jsx(w,{fields:a.fields}),a.notes&&a.notes.length>0&&e.jsx("ul",{className:"list-disc pl-4 space-y-0.5 text-xs text-fg-dim",children:a.notes.map(i=>e.jsx("li",{children:i},i))})]},a.id))})]},s.id)})})}export{L as DataModel};