claude-code-session-manager 0.87.0 → 0.88.1

package/src/main/lib/ephemeralCwd.cjs

@@ -35,44 +35,23 @@
  * unrelated use that a blanket match would wrongly refuse.
  */
 
-const os = require('node:os');
 const path = require('node:path');
-const { worktreeMainRootOf } = require('./activeSessions.cjs');
-const { KIND_CONFIG } = require('./gitWorktree.cjs');
-
-const TMPDIR = path.resolve(os.tmpdir());
-const MANAGED_WORKTREE_ROOTS = [KIND_CONFIG.job.root, KIND_CONFIG.epic.root].map((p) => path.resolve(p));
-
-function isExactlyTmpdir(absCwd) {
-  return absCwd === TMPDIR;
-}
-
-function isUnderManagedWorktreeRoot(absCwd) {
-  return MANAGED_WORKTREE_ROOTS.some((root) => {
-    const rel = path.relative(root, absCwd);
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-  });
-}
-
-function isLinkedWorktreeRoot(absCwd) {
-  const mainRoot = worktreeMainRootOf(absCwd);
-  return Boolean(mainRoot) && path.resolve(mainRoot) !== absCwd;
-}
+const { classifyCwd } = require('./cwdClassify.cjs');
 
 /**
  * isEphemeralCwd(cwd) → true when `cwd` must never have ops state written
  * into it (tmpdir-resident, or a linked git worktree root). Pure, synchronous,
  * never throws — an unresolvable or non-absolute cwd is treated as NOT
  * ephemeral so this predicate only ever adds refusals, never masks the
- * existing "cwd must be absolute" checks callers already perform.
+ * existing "cwd must be absolute" checks callers already perform. The
+ * unprovable-worktree case is NOT ephemeral here: it is kind `unknown`, which
+ * opsOwnership.assertOpsWrite refuses separately (writes only — dispatch and
+ * reads stay open).
  */
 function isEphemeralCwd(cwd) {
   if (!cwd || typeof cwd !== 'string' || !path.isAbsolute(cwd)) return false;
-  const absCwd = path.resolve(cwd);
-  if (isExactlyTmpdir(absCwd)) return true;
-  if (isUnderManagedWorktreeRoot(absCwd)) return true;
-  if (isLinkedWorktreeRoot(absCwd)) return true;
-  return false;
+  const { kind } = classifyCwd(path.resolve(cwd));
+  return kind === 'ephemeral' || kind === 'worktree';
 }
 
 module.exports = { isEphemeralCwd };

package/src/main/lib/gitWorktree.cjs

@@ -55,6 +55,7 @@ const os = require('node:os');
 const crypto = require('node:crypto');
 const { execFile } = require('node:child_process');
 const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 // Per-kind configuration. Roots are kept OUTSIDE any project's own tree
 // (os.tmpdir(), not `<cwd>/.git/...`) so a managed worktree never shows up in
@@ -86,7 +87,7 @@ const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 // days, same rationale as defaultMax above.
 const KIND_CONFIG = {
   job: {
-    root: path.join(os.tmpdir(), 'session-manager-job-worktrees'),
+    get root() { return schedulerPaths.worktreeRoot('job'); },
     branchPrefix: 'sm-job/',
     disableEnv: 'SM_JOB_WORKTREE_DISABLE',
     maxEnv: 'SM_JOB_WORKTREE_MAX',
@@ -95,7 +96,7 @@ const KIND_CONFIG = {
     defaultStaleSweepAgeMs: 24 * 60 * 60 * 1000,
   },
   epic: {
-    root: path.join(os.tmpdir(), 'session-manager-epic-worktrees'),
+    get root() { return schedulerPaths.worktreeRoot('epic'); },
     branchPrefix: 'sm-epic/',
     disableEnv: 'SM_EPIC_WORKTREE_DISABLE',
     maxEnv: 'SM_EPIC_WORKTREE_MAX',
@@ -184,6 +185,13 @@ function isUnderRoot(p, root) {
 // corrected down to match reality when it's proven to have leaked.
 const activeWorktreeCount = { job: 0, epic: 0 };
 
+// Registered checkouts this process created and has not yet cleaned up:
+// dir -> { kind, branch }. Lets `expireDeadWorktreeRegistrations` prove a
+// counted checkout is dead (no cwd holder + terminal row) and release its
+// count — accounting only, never a kill or an rm.
+const registeredCheckouts = new Map();
+const expiredCheckoutDirs = new Set(); // released by expiry, awaiting their (late) cleanupWorktree
+
 // Per-kind promise chain used as a simple async mutex (see `withKindLock`)
 // so the cap-check-and-reserve decision in `reserveWorktreeSlot` — which now
 // sometimes needs to `await` a fresh on-disk observation — stays a single
@@ -216,6 +224,46 @@ function execGit(args, { cwd, timeout = 20_000 } = {}) {
   });
 }
 
+// Unquote a single git porcelain v1 path token. Git wraps a path in double
+// quotes and C-style-escapes it (\", \\, \t, \n, and \NNN octal per raw UTF-8
+// byte) whenever it contains a double quote, backslash, control character, or
+// any byte >= 0x80 (core.quotepath's default "ASCII-safe" behavior) — a plain
+// path with none of those passes through untouched. Pure. Lives here (not
+// scheduler.cjs, which also parses porcelain output) because scheduler.cjs
+// requires this module — the reverse would be circular — and every porcelain
+// consumer in either file must unquote a path before treating it as a real
+// on-disk path (fs.existsSync, a pathspec, a Set membership check).
+function unquotePorcelainPath(raw) {
+  if (raw.length < 2 || raw[0] !== '"' || raw[raw.length - 1] !== '"') return raw;
+  const inner = raw.slice(1, -1);
+  const bytes = [];
+  const simpleEscapes = { '"': 0x22, '\\': 0x5c, n: 0x0a, t: 0x09, r: 0x0d, a: 0x07, b: 0x08, f: 0x0c, v: 0x0b };
+  for (let i = 0; i < inner.length; i += 1) {
+    const c = inner[i];
+    if (c === '\\' && i + 1 < inner.length) {
+      const next = inner[i + 1];
+      if (Object.prototype.hasOwnProperty.call(simpleEscapes, next)) {
+        bytes.push(simpleEscapes[next]);
+        i += 1;
+      } else if (next >= '0' && next <= '7') {
+        let octal = '';
+        let j = i + 1;
+        while (j < inner.length && octal.length < 3 && inner[j] >= '0' && inner[j] <= '7') {
+          octal += inner[j];
+          j += 1;
+        }
+        bytes.push(parseInt(octal, 8) & 0xff);
+        i = j - 1;
+      } else {
+        bytes.push(c.charCodeAt(0));
+      }
+    } else {
+      for (const b of Buffer.from(c, 'utf8')) bytes.push(b);
+    }
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
 async function isGitRepo(cwd) {
   if (!cwd) return false;
   try {
@@ -282,11 +330,11 @@ async function removeWorktreeDir(cwd, dir) {
     /* best-effort */
   }
   const parentDir = path.dirname(dir);
-  // Guard against ever rmdir-ing os.tmpdir() itself — every real caller's
+  // Guard against ever rmdir-ing the worktree base (os.tmpdir() or SM_WORKTREE_ROOT) itself — every real caller's
   // `dir` is `<kind root>/<hash>/<key>`, so `parentDir` is always the hash
   // dir, never the tmpdir root, but this keeps the guarantee explicit rather
   // than relying solely on call-site discipline.
-  if (parentDir === os.tmpdir()) return;
+  if (parentDir === schedulerPaths.worktreeBase()) return;
   try {
     const remaining = await fsp.readdir(parentDir);
     if (remaining.length === 0) await fsp.rmdir(parentDir);
@@ -526,7 +574,11 @@ async function captureAndCarryBaseDiff({ cwd, dir }) {
     if (stat.size === 0) return { ok: true, paths: [] };
 
     try {
-      await execGit(['apply', '--binary', patchFile], { cwd: dir, timeout: 30_000 });
+      // Same 120s ceiling as the capture step above: applying a patch large
+      // enough to need that long to generate can just as easily need that
+      // long to apply — leaving this at the old 30s reintroduces the same
+      // large-dirty-tree degrade-to-shared-tree failure one call later.
+      await execGit(['apply', '--binary', patchFile], { cwd: dir, timeout: 120_000 });
     } catch (e) {
       return { ok: false, reason: `git apply failed: ${(e && (e.stderrText || e.message)) || e}` };
     }
@@ -800,9 +852,31 @@ async function createWorktree({ kind, cwd, key }) {
     carriedPaths = carry.paths;
   }
 
+  registeredCheckouts.set(dir, { kind, branch });
   return { ok: true, dir, branch, baseCwd: cwd, carriedPaths };
 }
 
+/**
+ * Release the count of any registered checkout whose branch has no live
+ * holder (no process cwd under its dir) AND whose row is terminal
+ * (`isTerminalBranch(branch)`). Fail-closed: an unknown/live row or a live
+ * holder keeps the count. Returns the expired dirs. O(registered) plus one
+ * /proc scan.
+ */
+function expireDeadWorktreeRegistrations({ isTerminalBranch, holders = listCwdHolders() } = {}) {
+  const expired = [];
+  if (typeof isTerminalBranch !== 'function') return expired;
+  for (const [dir, reg] of [...registeredCheckouts]) {
+    if (hasLiveHolder(dir, holders)) continue;
+    if (!isTerminalBranch(reg.branch)) continue;
+    registeredCheckouts.delete(dir);
+    expiredCheckoutDirs.add(dir);
+    activeWorktreeCount[reg.kind] = Math.max(0, activeWorktreeCount[reg.kind] - 1);
+    expired.push(dir);
+  }
+  return expired;
+}
+
 /**
  * True iff every path in `paths` has working-tree content in `cwd`
  * byte-identical to its committed blob on `branch`. Used both by the
@@ -1064,7 +1138,10 @@ async function cleanupWorktree({ kind, cwd, dir, branch, keepBranch }) {
     try { await execGit(['branch', '-D', branch], { cwd, timeout: 10_000 }); } catch { /* already gone */ }
   }
   try { await execGit(['worktree', 'prune'], { cwd, timeout: 10_000 }); } catch { /* best effort */ }
-  activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
+  // A checkout the expiry pass already released must not be counted down twice.
+  const alreadyExpired = dir ? expiredCheckoutDirs.delete(dir) : false;
+  if (dir) registeredCheckouts.delete(dir);
+  if (!alreadyExpired) activeWorktreeCount[kind] = Math.max(0, activeWorktreeCount[kind] - 1);
 }
 
 /**
@@ -1143,7 +1220,12 @@ async function salvageDirtyDelta({ cwd, paths, outFile }) {
     for (const line of String(statusOut || '').split('\n')) {
       if (!line) continue;
       const code = line.slice(0, 2);
-      const p = line.slice(3);
+      // Unquote before use: a raw quoted+C-escaped token (any path with a
+      // quote, backslash, control char, or non-ASCII byte) is not a real
+      // on-disk path — passing it straight through as a pathspec to the
+      // `git diff` calls below silently fails to match the real file,
+      // dropping that path's content out of the salvaged patch entirely.
+      const p = unquotePorcelainPath(line.slice(3));
       if (!p) continue;
       if (code === '??') untrackedPaths.push(p);
       else trackedPaths.push(p);
@@ -1301,7 +1383,10 @@ async function reclaimTerminalJobOrphans({ cwd, terminalSlugs, isLive }) {
     } catch {
       continue; // can't prove the checkout is clean-of-real-work — never assume
     }
-    const dirtyPaths = statusOut.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+    const dirtyPaths = statusOut.split('\n')
+      .filter((l) => l.length > 0)
+      .map((l) => unquotePorcelainPath(l.slice(3).trim()))
+      .filter(Boolean);
     const opsOnly = dirtyPaths.every(
       (p) => p === OPS_ROOT_DIR || p.startsWith(`${OPS_ROOT_DIR}/`)
     );
@@ -1432,6 +1517,7 @@ module.exports = {
   getMaxConcurrentWorktrees,
   getStaleSweepAgeMs,
   isGitRepo,
+  unquotePorcelainPath,
   isBaseTreeClean,
   worktreeDirFor,
   branchNameFor,
@@ -1454,6 +1540,7 @@ module.exports = {
   mainTreeFromWorktreeGitFile,
   getObservedWorktreeCount,
   reserveWorktreeSlot,
+  expireDeadWorktreeRegistrations,
   reclaimTerminalJobOrphans,
   // Job-kind convenience wrappers — same call shape jobWorktree.cjs has
   // always exposed.

package/src/main/lib/guardShims.cjs

@@ -1,6 +1,6 @@
 /**
- * guardShims.cjs — stable, app-upgrade-proof indirection for the three
- * PreToolUse guard hooks that delegationReadiness.cjs installs into an
+ * guardShims.cjs — stable, app-upgrade-proof indirection for every
+ * PreToolUse guard hook (each name in GUARD_NAMES) that delegationReadiness.cjs installs into an
  * adopting project's `.claude/settings.json`.
  *
  * Why this exists: those installers used to bake
@@ -66,7 +66,7 @@ require(path.join(ptr.appRoot, 'scripts', 'hooks', '${guardName}'));
 }
 
 /**
- * Write the pointer file + all three shims under `homeDir`. Idempotent: a
+ * Write the pointer file + every shim in GUARD_NAMES under `homeDir`. Idempotent: a
  * re-run with the same `appRoot` produces byte-identical files; a re-run with
  * a DIFFERENT `appRoot` (an app upgrade) rewrites only the pointer, which is
  * exactly what lets already-installed project hooks follow the upgrade with

package/src/main/lib/historyRollup.cjs

@@ -26,10 +26,9 @@
 'use strict';
 
 const path = require('node:path');
-const os = require('node:os');
 const config = require('../config.cjs');
 
-const ROLLUP_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'history-rollup.jsonl');
+const { historyRollupPath } = require('./schedulerPaths.cjs');
 const COMPACT_THRESHOLD_BYTES = 5 * 1024 * 1024;
 
 const TOTALS_MODEL_ID = '';
@@ -75,7 +74,7 @@ function mergeRollupLines(lines) {
  * only want data lines should filter on modelId/projectDir.
  */
 async function readRollup(fromDate, toDate) {
-  const { exists, text } = await config.readText(ROLLUP_PATH);
+  const { exists, text } = await config.readText(historyRollupPath());
   if (!exists || !text) return new Map();
   const merged = mergeRollupLines(text.split('\n'));
   const filtered = new Map();
@@ -108,7 +107,7 @@ function isDateFinalized(mergedMap, date) {
 async function appendRollupDays(entries) {
   if (!entries || entries.length === 0) return;
 
-  const real = config.validatePath(ROLLUP_PATH);
+  const real = config.validatePath(historyRollupPath());
   config.validateWrite(real);
   const fsp = require('node:fs/promises');
   await fsp.mkdir(path.dirname(real), { recursive: true });
@@ -125,15 +124,15 @@ async function appendRollupDays(entries) {
 
 /** Dedupe the rollup file down to its last-write-wins merged lines. */
 async function compact() {
-  const { exists, text } = await config.readText(ROLLUP_PATH);
+  const { exists, text } = await config.readText(historyRollupPath());
   if (!exists || !text) return;
   const merged = mergeRollupLines(text.split('\n'));
   const rewritten = Array.from(merged.values()).map((b) => JSON.stringify(b)).join('\n') + '\n';
-  await config.writeTextAtomic(ROLLUP_PATH, rewritten);
+  await config.writeTextAtomic(historyRollupPath(), rewritten);
 }
 
 module.exports = {
-  ROLLUP_PATH,
+  historyRollupPath,
   COMPACT_THRESHOLD_BYTES,
   TOTALS_MODEL_ID,
   FINALIZED_MODEL_ID,

package/src/main/lib/instanceLock.cjs

@@ -26,14 +26,16 @@
 'use strict';
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { identity, isDifferentProcess } = require('./procIdentity.cjs');
+const { instanceLockPath } = require('./schedulerPaths.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
 
 // Env override is for unit tests only (isolates the lock from the real
 // ~/.claude of the machine running the suite).
 function lockPath() {
   return process.env.SM_SCHEDULER_LOCK_PATH
-    || path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-owner.lock');
+    || instanceLockPath();
 }
 
 function pidAlive(pid) {
@@ -58,7 +60,11 @@ function readLock() {
 }
 
 function writeLockExclusive() {
-  const body = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+  const body = JSON.stringify({
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    identity: identity(process.pid),
+  });
   fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
   // 'wx' = atomic create-or-fail — two racing instances cannot both win.
   fs.writeFileSync(lockPath(), body, { flag: 'wx', mode: 0o600 });
@@ -67,14 +73,35 @@ function writeLockExclusive() {
 /**
  * Try to become the machine's scheduler owner.
  * Returns { owner: true } or { owner: false, holderPid } — never throws.
+ *
+ * A holder pid that is alive is normally respected — but if the lock body
+ * carries a COMPLETE recorded identity that provably differs from the live
+ * process now holding that pid (procIdentity.isDifferentProcess), the pid
+ * was recycled after a hard crash: today's bare pidAlive() check would pin
+ * ownership on that unrelated live process forever. That case is treated as
+ * stale and the lock is broken (audited as `stale_lock_broken`). A missing
+ * identity (legacy lock body, or an unreadable /proc on either side) is
+ * fail-closed to "not different" — i.e. today's pid-only behaviour.
  */
 function acquireSchedulerOwnership() {
   for (let attempt = 0; attempt < 2; attempt++) {
     const existing = readLock();
     if (existing && existing.pid !== process.pid && pidAlive(existing.pid)) {
-      return { owner: false, holderPid: existing.pid };
+      const liveIdentity = identity(existing.pid);
+      if (!isDifferentProcess(existing.identity, liveIdentity)) {
+        return { owner: false, holderPid: existing.pid };
+      }
+      appendAuditEvent('stale_lock_broken', {
+        path: lockPath(),
+        recordedPid: existing.pid,
+        recordedStartedAt: existing.startedAt ?? null,
+        recordedIdentity: existing.identity ?? null,
+        liveIdentity,
+      });
     }
-    // Missing, unreadable, our own, or stale (holder pid dead) — take it.
+    // Missing, unreadable, our own, stale (holder pid dead), or a recorded
+    // identity proven different from the live process at that recycled pid
+    // — take it.
     try {
       if (existing || fs.existsSync(lockPath())) fs.unlinkSync(lockPath());
     } catch { /* raced with another breaker — retry loop below settles it */ }

package/src/main/lib/jobSupervisorRecord.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * jobSupervisorRecord.cjs — the one authoritative, SYNCHRONOUS record of a
+ * dispatch, written at the same point scheduler.cjs logs `[scheduler] spawned
+ * pid=`.
+ *
+ * Before this, the only durable trace of a dispatch was runtime={pid,...},
+ * written asynchronously by a mutate() inside the onPid callback, and the run
+ * dir held only the log until an exit path wrote meta.json. A booting process
+ * therefore had nothing to tell "my run, still alive" from "dead" and fell
+ * back to a ladder of inferences. `<runDir>/<slug>.supervisor.json` is that
+ * missing fact.
+ *
+ * Plain Node, no electron. The run dir is machine-wide scheduler state (not
+ * an ops namespace), so queueStore's writeJsonAtomicSync is the right writer.
+ * This module never signals a process and adds no cap accounting.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { writeJsonAtomicSync } = require('./queueStore.cjs');
+const { isDifferentProcess } = require('./procIdentity.cjs');
+
+const SUFFIX = '.supervisor.json';
+const META_SUFFIX = '.meta.json';
+const INVESTIGATION_EXIT_RE = /\[scheduler\] investigation exit code=/;
+const EXIT_TAIL_BYTES = 8 * 1024;
+
+function recordPath(runDir, slug) {
+  return path.join(runDir, `${slug}${SUFFIX}`);
+}
+
+/**
+ * Writes `<runDir>/<slug>.supervisor.json` atomically. Throws on failure —
+ * the caller owns the "never fail the dispatch" try/catch. `kind` defaults to
+ * "job"; an investigation probe passes kind: "investigation" (and a slug of
+ * `<failedSlug>.investigation`, so it never overwrites the failed job's own
+ * record in the shared run dir).
+ */
+function writeSupervisorRecord({
+  runDir, slug, cwd, runId, pid, pgid, identity, execCwd, worktreeDir, worktreeBranch,
+  sessionId, startedAt, budgetMs, maxDurationMs, idleKillMs, schedulerPid, codeSha, kind,
+}) {
+  if (!runDir || !slug) throw new Error('writeSupervisorRecord: runDir and slug are required');
+  const record = {
+    kind: kind || 'job',
+    slug, cwd: cwd ?? null, runId: runId ?? null,
+    pid: pid ?? null, pgid: pgid ?? null, identity: identity ?? null,
+    execCwd: execCwd ?? null, worktreeDir: worktreeDir ?? null, worktreeBranch: worktreeBranch ?? null,
+    sessionId: sessionId ?? null, startedAt: startedAt ?? null,
+    budgetMs: budgetMs ?? null, maxDurationMs: maxDurationMs ?? null, idleKillMs: idleKillMs ?? null,
+    schedulerPid: schedulerPid ?? null, codeSha: codeSha ?? null,
+  };
+  writeJsonAtomicSync(recordPath(runDir, slug), record);
+  return record;
+}
+
+/** Returns the parsed record, or null when absent/unparseable. Never throws. */
+function readSupervisorRecord(runDir, slug) {
+  try {
+    const rec = JSON.parse(fs.readFileSync(recordPath(runDir, slug), 'utf8'));
+    return rec && typeof rec === 'object' ? rec : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when the run has a durable exit marker: `<slug>.meta.json` for a job,
+ * the `investigation exit code=` log line for a probe. This is what separates
+ * "exited" from "dead" — a dead pid with no marker never got to write one.
+ */
+function hasExitMarker(runDir, record) {
+  try {
+    if (record.kind === 'investigation') {
+      const failedSlug = String(record.slug).replace(/\.investigation$/, '');
+      const logPath = path.join(runDir, `${failedSlug}.investigation.log`);
+      const { size } = fs.statSync(logPath);
+      const fd = fs.openSync(logPath, 'r');
+      try {
+        const len = Math.min(size, EXIT_TAIL_BYTES);
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, size - len);
+        return INVESTIGATION_EXIT_RE.test(buf.toString('utf8'));
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+    return fs.existsSync(path.join(runDir, `${record.slug}${META_SUFFIX}`));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every record under `runsDir/<runId>/` whose file was written within
+ * maxAgeMs and which has no exit marker yet. Each entry is the record plus
+ * `runDir`. Never throws; an unreadable dir yields [].
+ * Complexity: O(run dirs + files in recent dirs).
+ */
+function listLiveSupervisorRecords(runsDir, { maxAgeMs, now = Date.now() } = {}) {
+  const out = [];
+  let dirs;
+  try { dirs = fs.readdirSync(runsDir, { withFileTypes: true }); } catch { return out; }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const runDir = path.join(runsDir, d.name);
+    let files;
+    try { files = fs.readdirSync(runDir); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith(SUFFIX)) continue;
+      try {
+        if (Number.isFinite(maxAgeMs) && now - fs.statSync(path.join(runDir, f)).mtimeMs > maxAgeMs) continue;
+        const record = readSupervisorRecord(runDir, f.slice(0, -SUFFIX.length));
+        if (!record || hasExitMarker(runDir, record)) continue;
+        out.push({ ...record, runDir });
+      } catch { /* raced with a delete — skip */ }
+    }
+  }
+  return out;
+}
+
+/**
+ * Pure. What should a booting process do with this record?
+ *   - not alive + exit marker   → 'exited'   (finished; outcome is on disk)
+ *   - not alive, no marker      → 'dead'     (died without writing an outcome)
+ *   - alive, different process  → 'foreign-pid' (pid recycled; never ours)
+ *   - alive, ours, past budget or log stalled past idleKillMs → 'over-budget'
+ *   - alive, ours               → 'adopt'
+ * `identity` is the live probe of record.pid; isDifferentProcess is
+ * fail-closed, so an incomplete identity on either side reads as "same".
+ */
+function classifyAdoption(record, { identity, pidAlive, logMtimeMs, exitMarker, now = Date.now() } = {}) {
+  if (!pidAlive) return exitMarker ? 'exited' : 'dead';
+  if (exitMarker) return 'exited';
+  if (isDifferentProcess(record.identity, identity)) return 'foreign-pid';
+  const ceiling = record.budgetMs > 0 ? record.budgetMs : (record.maxDurationMs > 0 ? record.maxDurationMs : 0);
+  if (ceiling > 0 && Number.isFinite(record.startedAt) && now - record.startedAt > ceiling) return 'over-budget';
+  if (record.idleKillMs > 0 && Number.isFinite(logMtimeMs) && now - logMtimeMs > record.idleKillMs) return 'over-budget';
+  return 'adopt';
+}
+
+module.exports = {
+  writeSupervisorRecord, readSupervisorRecord, listLiveSupervisorRecords, classifyAdoption, hasExitMarker,
+  SUFFIX,
+};

package/src/main/lib/jobWorktreeBootLive.cjs

@@ -22,15 +22,19 @@
  */
 
 /**
- * @param {{ bootJobs: Array<object>, claudePidAlive: (pid: number) => boolean, hasLiveHolder: (dir: string, holders?: Set<string>) => boolean, cwdHolders?: Set<string> }} deps
+ * `rowPid(job)` resolves a running row's pid; scheduler.cjs passes the same
+ * supervisor-record → runtime.pid → run-log ladder partitionBootOrphans uses,
+ * so the two boot passes agree. Default: runtime.pid alone.
+ *
+ * @param {{ bootJobs: Array<object>, claudePidAlive: (pid: number) => boolean, hasLiveHolder: (dir: string, holders?: Set<string>) => boolean, cwdHolders?: Set<string>, rowPid?: (job: object) => number|null }} deps
  * @returns {(slug: string, entry: { worktree: string, branch: string|null }) => boolean}
  */
-function buildJobWorktreeIsLive({ bootJobs, claudePidAlive, hasLiveHolder, cwdHolders }) {
+function buildJobWorktreeIsLive({ bootJobs, claudePidAlive, hasLiveHolder, cwdHolders, rowPid = (j) => j.runtime && j.runtime.pid }) {
   const runningPidBySlug = new Map();
   for (const j of Array.isArray(bootJobs) ? bootJobs : []) {
-    if (j && j.status === 'running' && j.runtime && j.runtime.pid) {
-      runningPidBySlug.set(j.slug, j.runtime.pid);
-    }
+    if (!j || j.status !== 'running') continue;
+    const pid = rowPid(j);
+    if (pid) runningPidBySlug.set(j.slug, pid);
   }
 
   return function isLive(slug, entry) {

package/src/main/lib/localAdminHttp.cjs

@@ -32,40 +32,20 @@
 'use strict';
 
 const http = require('node:http');
-const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const fsp = require('node:fs/promises');
 const config = require('../config.cjs');
-
-const TOKEN_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.json');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 /**
- * Mode-aware token file path, resolved fresh on every call (not cached at
+ * Mode-aware token file path, resolved fresh on every call (never cached at
  * module load) so a dev/e2e launch never collides with a production
- * instance's admin-api.json. index.cjs treats SM_DEV and SM_E2E as one OR'd
- * `isDev` boolean with no ordering between them; if both happen to be set,
- * this resolves to the SM_DEV path (checked first below) — an arbitrary but
- * harmless tie-break, since real launches only ever set one or the other.
+ * instance's admin-api.json. The SM_ADMIN_TOKEN_PATH / SM_DEV / SM_E2E ladder
+ * lives in schedulerPaths.adminTokenPath() (the SM_ADMIN_TOKEN_PATH override
+ * exists because unit tests once overwrote the live app's port+token).
  */
-function resolveTokenPath() {
-  // Explicit override, highest priority. Exists because the unit tests call
-  // createAdminHttp().start() directly with neither SM_DEV nor SM_E2E set,
-  // which resolved to the PRODUCTION admin-api.json and overwrote the
-  // running app's port+token with a throwaway test server's — silently
-  // orphaning scheduler-mcp-server.cjs's access to the live app until the
-  // next app restart (confirmed live 2026-08-01: `npm run test:unit` made
-  // every scheduler_* MCP tool report "app is not running"). Tests point
-  // this at a tmp file; production never sets it.
-  if (process.env.SM_ADMIN_TOKEN_PATH) return process.env.SM_ADMIN_TOKEN_PATH;
-  if (process.env.SM_DEV === '1') {
-    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.dev.json');
-  }
-  if (process.env.SM_E2E === '1') {
-    return path.join(os.homedir(), '.claude', 'session-manager', 'admin-api.e2e.json');
-  }
-  return TOKEN_PATH;
-}
+const resolveTokenPath = schedulerPaths.adminTokenPath;
 
 // Reserved health-check path, handled directly (not via registerRoute) so
 // start()'s post-boot self-check never depends on route-registration order
@@ -238,9 +218,11 @@ function createAdminHttp() {
 
 module.exports = {
   createAdminHttp,
-  TOKEN_PATH,
   resolveTokenPath,
   timingSafeEqualStrings,
   readBody,
   sendJson,
 };
+
+// Lazy getter (the token path is mode-aware and env-driven; never frozen at require).
+Object.defineProperty(module.exports, 'TOKEN_PATH', { get: () => schedulerPaths.adminTokenPath(), enumerable: true });