claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/runLogRetention.cjs

@@ -12,7 +12,8 @@
  *
  * Directory shape: one subdirectory per tick (`RUNS_DIR/<iso-ts>/`, minted by
  * scheduler.cjs's pickRunDir), which commonly holds MANY different PRD
- * slugs' artifacts side by side — `<slug>.log`, `<slug>.meta.json`, and an
+ * slugs' artifacts side by side — `<slug>.log`, `<slug>.meta.json`, the
+ * `<slug>.supervisor.json` dispatch record (jobSupervisorRecord.cjs), and an
  * optional `root-cause-<slug>.md` (rcaReport.cjs) per slug. Retention is
  * therefore computed per (runId, slug) ENTRY, not per directory: a directory
  * is only "fully removable" once every entry it holds is independently
@@ -131,7 +132,7 @@ function scanRunEntries(runsDir) {
     for (const metaFile of metaFiles) {
       const slug = metaFile.slice(0, -META_SUFFIX.length);
       const relatedNames = files.filter(
-        (f) => f === metaFile || f === `${slug}.log` || f === `root-cause-${slug}.md`
+        (f) => f === metaFile || f === `${slug}.log` || f === `${slug}.supervisor.json` || f === `root-cause-${slug}.md`
       );
 
       let sizeBytes = 0;

package/src/main/lib/scheduleJobSchema.cjs

@@ -1,6 +1,6 @@
 /**
  * Canonical runtime schema for a ScheduleJob record, mirroring the TS
- * `ScheduleJob` interface at src/preload/api.d.ts:375-422 field-for-field.
+ * `ScheduleJob` interface (`ScheduleJob` in src/preload/api.d.ts) field-for-field.
  *
  * Modelled directly on promptSessionSchema.cjs's "zod schema asserted at the
  * main-process boundary" pattern: the Epic entity has had this guarantee
@@ -52,7 +52,7 @@ const ScheduleJobStatusHistoryEntrySchema = z
   .passthrough();
 
 // Only `slug` and `status` are required. Every other ScheduleJob field
-// (src/preload/api.d.ts:375-422) is declared here for documentation and type
+// (`ScheduleJob` in src/preload/api.d.ts) is declared here for documentation and type
 // checking when present, but kept optional: a job row moves through several
 // legitimate partial shapes across its life (freshly minted with nulls,
 // mid-run with runtime fields, terminal with exitCode/error) and plenty of
@@ -124,6 +124,14 @@ const ScheduleJobSchema = z
     // finalize (both the normal completion path and reapDeadRunningJobs).
     dispatchPhase: z.string().optional(),
     dispatchPhaseAt: z.string().optional(),
+    // needs_review episode bookkeeping (needsReviewLedger.cjs / PRD: needs_review
+    // durability): stamped by scheduleJobTransitions.cjs the instant a job
+    // transitions INTO 'needs_review', so the RESOLUTION line written when it
+    // later transitions back OUT can reference the same runId and compute a
+    // truthful dwell time — same lifecycle as heldReason/dispatchPhase (stamped
+    // at entry, deleted at resolution).
+    needsReviewEntryRunId: z.string().nullable().optional(),
+    needsReviewEnteredAt: z.string().nullable().optional(),
   })
   .passthrough();
 

package/src/main/lib/scheduleJobTransitions.cjs

@@ -32,6 +32,8 @@
 
 const { appendAuditEvent } = require('./auditLog.cjs');
 const telemetryCounters = require('./telemetryCounters.cjs');
+const queueHistory = require('./queueHistory.cjs');
+const { buildNeedsReviewEntryLine, buildNeedsReviewResolutionLine } = require('./needsReviewLedger.cjs');
 
 // A run genuinely finished when it leaves 'running' for one of these —
 // distinct from every other legal edge in LEGAL_TRANSITIONS (retries,
@@ -195,6 +197,64 @@ function transitionJob(job, toStatus, { reason, source, allowAnyFrom = false } =
     telemetryCounters.trackSchedulerJobFinish({ status: toStatus });
   }
 
+  // needs_review ledger (PRD: needs_review durability). This IS the single
+  // funnel every needs_review transition — entry or resolution — passes
+  // through (see this file's own header comment: transitionJob is the ONE
+  // place `status` is assigned), so hooking here, rather than any one of
+  // needs_review's several distinct entry call sites in scheduler.cjs,
+  // guarantees no path can bypass it.
+  //
+  // Fire-and-forget, exactly like every other best-effort side-channel write
+  // in this codebase (rcaReport.cjs, auditLog.cjs's own posture) — a ledger
+  // write failure must never fail or delay the transition it's recording.
+  // 'investigating' is a PAUSE, not a resolution, when it's reached FROM
+  // needs_review: spawnInvestigation always restores the job to exactly the
+  // status it left (a snapshot taken before the pause), so
+  // needs_review -> investigating -> needs_review is one continuous episode,
+  // not two. Without this check, the pause mints a spurious 'auto-fix'
+  // resolution mid-episode, then the resume mints a spurious fresh entry
+  // that overwrites the original episode's runId/enteredAt/reason in the
+  // ledger's by-key maps (keyed on slug+runId) — corrupting byLadderRung and
+  // understating dwell time. Detected via the stamped episode fields
+  // themselves rather than the transition's source string, since the same
+  // 'investigating' status is also reached fresh from 'failed' (a job that
+  // was never parked needs_review at all, and has no episode to pause).
+  const isNeedsReviewPause = from === 'needs_review' && toStatus === 'investigating';
+  const pausedEpisodeOpen = job.needsReviewEntryRunId !== undefined;
+  const isNeedsReviewResume = from === 'investigating' && pausedEpisodeOpen;
+
+  if (toStatus === 'needs_review' && from !== 'needs_review' && !isNeedsReviewResume) {
+    // ENTRY: stamp the episode's runId/enteredAt on the job itself so the
+    // RESOLUTION line (below) can reference the SAME runId even if the job's
+    // own `runId` is reassigned in between (e.g. a resume-recovery
+    // re-dispatch mints a fresh one before this episode resolves).
+    job.needsReviewEntryRunId = job.runId ?? null;
+    job.needsReviewEnteredAt = entry.at;
+    queueHistory.appendHistory([buildNeedsReviewEntryLine(job, entry)]).catch((e) => {
+      console.error('[scheduleJobTransitions] failed to append needs_review entry', e?.message ?? String(e));
+    });
+  } else if (
+    (from === 'needs_review' && toStatus !== 'needs_review' && !isNeedsReviewPause)
+    || (isNeedsReviewResume && toStatus !== 'needs_review')
+  ) {
+    // RESOLUTION: read the episode stamped at entry, then clear it — the
+    // episode is over regardless of what this resolution line looks like.
+    // The `isNeedsReviewResume` arm covers an episode that paused for
+    // investigation and is now resolving to something other than
+    // needs_review (e.g. the investigation actually fixed it) — the episode
+    // stamps were deliberately left untouched across the pause, so this
+    // still references the ORIGINAL entry time, not the pause's.
+    const episode = { runId: job.needsReviewEntryRunId ?? null, enteredAt: job.needsReviewEnteredAt ?? null };
+    delete job.needsReviewEntryRunId;
+    delete job.needsReviewEnteredAt;
+    queueHistory.appendHistory([buildNeedsReviewResolutionLine(job, entry, episode)]).catch((e) => {
+      console.error('[scheduleJobTransitions] failed to append needs_review resolution', e?.message ?? String(e));
+    });
+  }
+  // else: isNeedsReviewPause (needs_review -> investigating), or
+  // isNeedsReviewResume && toStatus === 'needs_review' (investigating ->
+  // needs_review, still the same open episode) — intentionally a no-op.
+
   return true;
 }
 

package/src/main/lib/schedulerBatch.cjs

@@ -75,7 +75,7 @@ function dedupeCycles(cycles) {
   return out;
 }
 
-function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
+function makeDepResolver(projectJobs, satisfiedSlugs = new Set()) {
   const rowBySlug = new Map(projectJobs.map((j) => [j.slug, j]));
   const rowsByBareSlug = new Map();
   for (const j of projectJobs) {
@@ -102,6 +102,31 @@ function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
     }
     return satisfiedBareSlugs.has(bareSlug(slug));
   };
+  return { rowsForDep, isKnownSatisfied };
+}
+
+/**
+ * findUnresolvableDepRoots(projectJobs, satisfiedSlugs) → string[]
+ *
+ * Pure. The dep slugs that name NO live row and NO completion/archive record
+ * — the roots findBlockingDep holds as 'unresolved'. Unlike a failed/pending
+ * dep row, nothing in the queue will ever change one of these; only a human
+ * (or a restored record) can. Sorted, de-duplicated. O(jobs + deps).
+ */
+function findUnresolvableDepRoots(projectJobs, satisfiedSlugs = new Set()) {
+  const { rowsForDep, isKnownSatisfied } = makeDepResolver(projectJobs, satisfiedSlugs);
+  const roots = new Set();
+  for (const j of projectJobs) {
+    if (j.status !== 'pending') continue;
+    for (const dep of j.dependsOn ?? []) {
+      if (rowsForDep(dep).length === 0 && !isKnownSatisfied(dep)) roots.add(dep);
+    }
+  }
+  return [...roots].sort();
+}
+
+function findBlockingDep(job, projectJobs, satisfiedSlugs = new Set()) {
+  const { rowsForDep, isKnownSatisfied } = makeDepResolver(projectJobs, satisfiedSlugs);
   // A dep row is blocking unless it's 'completed', OR it's a 'skipped' row
   // stamped `needsReviewAutoResolvedSkip` — the bounded needs_review
   // auto-resolve terminal decision (scheduler.cjs's
@@ -658,6 +683,6 @@ function findStarvedProjects(jobs, now, thresholdMs) {
 }
 
 module.exports = {
-  pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, DEFAULT_PROJECT_CWD,
+  pickForProject, pickNextBatch, enqueueTimestamp, findStarvedProjects, findBlockingDep, findUnresolvableDepRoots, DEFAULT_PROJECT_CWD,
   DEP_HISTORY_FAIL_OPEN,
 };

package/src/main/lib/schedulerConfig.cjs

@@ -56,6 +56,16 @@ module.exports = {
   // (pause/resume, job start/finish/reap/reset) bypass this via
   // broadcast({ flush: true }).
   BROADCAST_COALESCE_MS: 200,
+  // reconcile() pass duration above which a single warn-level breakdown is
+  // logged (per-phase ms, PRD file count, resolved dir count) — the only
+  // evidence trail for a slow pass otherwise requires hand-timing the scan
+  // from a throwaway script. Baseline measured 2026-09-13 on a machine with
+  // ~160 PRD dirs: allProjectCwds() ~270ms x5/pass, resolvePrdsDirs()
+  // ~430ms, historyTerminalBySlug() ~418ms over 784 entries — a healthy pass
+  // today is comfortably under 2s; this should trip well before a
+  // regression back toward those numbers compounds into the reported
+  // "schedule.state timed out after 5000ms" toast.
+  RECONCILE_SLOW_PASS_MS: 2_000,
   // Terminal (completed/failed) jobs older than this move from queue.json's
   // hot jobs[] into the append-only history.jsonl sidecar. See
   // src/main/lib/queueHistory.cjs.
@@ -109,6 +119,20 @@ module.exports = {
   // SM_JOB_OVERRUN_FLOOR_MINUTES.
   JOB_OVERRUN_FLOOR_MS: 45 * 60_000,
 
+  // Wall-clock KILL budget (distinct from JOB_OVERRUN_FACTOR/JOB_OVERRUN_FLOOR_MS
+  // above, which only ever ESCALATE — log + audit, deliberately never kill).
+  // This one ACTS: a RUNNING job past `budgetMs = clamp(estimateMinutes *
+  // JOB_BUDGET_FACTOR, JOB_BUDGET_FLOOR_MS, JOB_BUDGET_CEILING_MS)` is
+  // SIGTERMed and parked needs_review. Calibrated against 606 run-meta
+  // records since 2026-08-25: p50=13m, p90=60m, max=240m, against a
+  // concurrencyCap of 4 — two 4h outliers hold half the machine's dispatch
+  // capacity for an afternoon with nothing noticing or acting on it. Override
+  // with SM_JOB_BUDGET_FACTOR / SM_JOB_BUDGET_FLOOR_MINUTES /
+  // SM_JOB_BUDGET_CEILING_MINUTES.
+  JOB_BUDGET_FACTOR: 3,
+  JOB_BUDGET_FLOOR_MS: 45 * 60_000,
+  JOB_BUDGET_CEILING_MS: 180 * 60_000,
+
   // A 'running' row with no runtime.pid recorded (spawnJob's status:running
   // mutate at scheduler.cjs:~3524 landed, but the pid-bearing runtime={}
   // mutate that follows executeJob's spawn callback never did — the spawn

package/src/main/lib/schedulerPaths.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * schedulerPaths.cjs — single resolver for every machine-wide, home-rooted
+ * scheduler path. Plain Node (no electron) so queueStore.cjs and the watchdog
+ * can load it.
+ *
+ * Every export is a LAZY function: the root is read from the environment at
+ * point of use, never at require time, so a test (or a second instance) that
+ * sets SM_SCHEDULER_HOME redirects ALL scheduler state — queue shards, machine
+ * state, runs, PRDs, heartbeat, slot config, admin token — with no
+ * half-redirect. SM_SCHEDULER_HOME set on the app propagates to spawned
+ * executor jobs BY DESIGN (children inherit env), so a redirected app runs
+ * redirected jobs.
+ *
+ * Worktree roots are NOT under schedulerHome (they live on the tmp filesystem)
+ * but are resolved here all the same, via SM_WORKTREE_ROOT (else os.tmpdir()),
+ * so the job and epic roots always move together under one override.
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+
+function isUnder(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Test-time fail-closed guard (same shape as opsOwnership.assertOpsWrite): under
+ * vitest (process.env.VITEST) a resolved path must sit under SM_SCHEDULER_HOME,
+ * SM_WORKTREE_ROOT, or os.tmpdir() — anything else is a LIVE root (real ~/.claude,
+ * real home) that a unit test must never touch. Returns `resolved` so resolvers
+ * can `return assertNotLiveRoot(...)`. O(#roots) per call.
+ */
+function assertNotLiveRoot(resolved, resolverName) {
+  if (!process.env.VITEST) return resolved;
+  // Narrow, per-test opt-in for a READ-ONLY probe of this machine's real user config
+  // (health-delegation-chain.test.cjs). Never set it around anything that writes or sweeps.
+  if (process.env.SM_ALLOW_LIVE_ROOT_READS === '1') return resolved;
+  // HOLE CLOSED (2026-09-18 defaultCwd leak): the allow-list below is env-derived, and so was
+  // the notion of "live" — both follow process.env.HOME / SM_SCHEDULER_HOME, which a test (or an
+  // env inherited from the live app) freely reassigns. A live SM_SCHEDULER_HOME therefore
+  // ALLOW-LISTED the very root the guard exists to refuse, and a HOME swapped mid-test moved
+  // "live" out from under it. The passwd-database home (os.userInfo(), immune to $HOME) is the
+  // one anchor a test cannot rewrite: nothing under its ~/.claude may be touched, whatever the
+  // allow-list says.
+  if (isLivePasswdRoot(resolved)) throw liveRootError(resolved, resolverName);
+  const roots = [process.env.SM_SCHEDULER_HOME, process.env.SM_WORKTREE_ROOT, os.tmpdir()].filter(Boolean);
+  if (roots.some((r) => isUnder(resolved, r))) return resolved;
+  throw liveRootError(resolved, resolverName);
+}
+
+function liveRootError(resolved, resolverName) {
+  return new Error(
+    `schedulerPaths.${resolverName}() resolved to live root ${resolved} under vitest — ` +
+    'set SM_SCHEDULER_HOME / SM_WORKTREE_ROOT / HOME to a temp dir (tests/setup/schedulerSandbox.cjs does this per run)',
+  );
+}
+
+/** True when `resolved` sits under the passwd-home's ~/.claude (HOME-env independent). */
+function isLivePasswdRoot(resolved) {
+  let home;
+  try { home = os.userInfo().homedir; } catch { return false; }
+  if (!home) return false;
+  // A sandbox that genuinely lives under the passwd home's tmp is not live; only ~/.claude is.
+  return isUnder(resolved, path.join(home, '.claude'));
+}
+
+/** SM_SCHEDULER_HOME, else ~/.claude/session-manager. */
+function schedulerHome() {
+  return assertNotLiveRoot(
+    process.env.SM_SCHEDULER_HOME || path.join(os.homedir(), '.claude', 'session-manager'),
+    'schedulerHome',
+  );
+}
+
+/** ~/.claude — Claude Code's own config dir (NOT redirected by SM_SCHEDULER_HOME). */
+function claudeHome() { return assertNotLiveRoot(path.join(os.homedir(), '.claude'), 'claudeHome'); }
+function claudeProjectsDir() { return assertNotLiveRoot(path.join(claudeHome(), 'projects'), 'claudeProjectsDir'); }
+
+function scheduledPlansRoot() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduled-plans'), 'scheduledPlansRoot'); }
+function runsDir() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'runs'), 'runsDir'); }
+function prdsRoot() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'prds'), 'prdsRoot'); }
+function machineStatePath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-machine.json'), 'machineStatePath'); }
+function legacyQueuePath() { return assertNotLiveRoot(path.join(scheduledPlansRoot(), 'queue.json'), 'legacyQueuePath'); }
+function schedulerStatePath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-state.json'), 'schedulerStatePath'); }
+function heartbeatPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'scheduler-heartbeat.log'), 'heartbeatPath'); }
+function sessionSlotsConfigPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'session-slots-config.json'), 'sessionSlotsConfigPath'); }
+function watchdogLogsDir() { return assertNotLiveRoot(path.join(schedulerHome(), 'logs'), 'watchdogLogsDir'); }
+function restartRequestPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'restart-request.json'), 'restartRequestPath'); }
+function restartingMarkerPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'restarting.json'), 'restartingMarkerPath'); }
+function watchdogRelaunchStatePath() { return assertNotLiveRoot(path.join(schedulerHome(), 'watchdog-relaunch-state.json'), 'watchdogRelaunchStatePath'); }
+// Sibling of schedulerHome() (i.e. ~/.claude/logs by default), not inside it.
+function watchdogRelaunchLogPath() {
+  return assertNotLiveRoot(
+    path.join(path.dirname(schedulerHome()), 'logs', 'scheduler-watchdog-relaunch.log'),
+    'watchdogRelaunchLogPath',
+  );
+}
+function historyRollupStampPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'history-rollup.stamp'), 'historyRollupStampPath'); }
+function historyRollupLockPath() { return assertNotLiveRoot(path.join(schedulerHome(), 'history-rollup.lock'), 'historyRollupLockPath'); }
+function historyRollupPath() { return path.join(schedulerHome(), 'history-rollup.jsonl'); }
+function auditLogPath() { return path.join(schedulerHome(), 'audit-log.jsonl'); }
+function procnamesRoot() { return path.join(schedulerHome(), 'procnames'); }
+/** Legacy global history sidecar (read-only; new appends go to per-project shards). */
+function queueHistoryPath() { return path.join(scheduledPlansRoot(), 'history.jsonl'); }
+function instanceLockPath() { return path.join(schedulerHome(), 'scheduler-owner.lock'); }
+/** Where heap snapshots are written — the scheduler home itself. */
+function heapSnapshotDir() { return schedulerHome(); }
+
+/** SM_WORKTREE_ROOT, else os.tmpdir() — the parent of every managed worktree root. */
+function worktreeBase() { return assertNotLiveRoot(process.env.SM_WORKTREE_ROOT || os.tmpdir(), 'worktreeBase'); }
+
+/** Managed worktree root for `kind` ('job' | 'epic'), resolved fresh on every call. */
+function worktreeRoot(kind) {
+  return assertNotLiveRoot(path.join(worktreeBase(), `session-manager-${kind}-worktrees`), 'worktreeRoot');
+}
+
+/**
+ * Mode-aware admin token path, resolved fresh on every call. Precedence:
+ * SM_ADMIN_TOKEN_PATH (explicit override) > SM_DEV > SM_E2E > production file.
+ * index.cjs treats SM_DEV and SM_E2E as one OR'd boolean; if both are set the
+ * SM_DEV path wins (arbitrary but harmless — real launches set one).
+ */
+function adminTokenPath() {
+  if (process.env.SM_ADMIN_TOKEN_PATH) return assertNotLiveRoot(process.env.SM_ADMIN_TOKEN_PATH, 'adminTokenPath');
+  if (process.env.SM_DEV === '1') return assertNotLiveRoot(path.join(schedulerHome(), 'admin-api.dev.json'), 'adminTokenPath');
+  if (process.env.SM_E2E === '1') return assertNotLiveRoot(path.join(schedulerHome(), 'admin-api.e2e.json'), 'adminTokenPath');
+  return assertNotLiveRoot(path.join(schedulerHome(), 'admin-api.json'), 'adminTokenPath');
+}
+
+/**
+ * cwd that machine-level scheduler errors are attributed to (they have no
+ * owning project). SM_SCHEDULER_LOG_CWD, else the literal
+ * ~/Projects/session-manager — deliberately NOT inferred from process.cwd().
+ */
+function machineStateLogCwd() {
+  return assertNotLiveRoot(
+    process.env.SM_SCHEDULER_LOG_CWD || path.join(os.homedir(), 'Projects', 'session-manager'),
+    'machineStateLogCwd',
+  );
+}
+
+module.exports = {
+  assertNotLiveRoot,
+  claudeHome,
+  claudeProjectsDir,
+  schedulerHome,
+  scheduledPlansRoot,
+  runsDir,
+  prdsRoot,
+  machineStatePath,
+  legacyQueuePath,
+  schedulerStatePath,
+  heartbeatPath,
+  sessionSlotsConfigPath,
+  adminTokenPath,
+  machineStateLogCwd,
+  worktreeBase,
+  worktreeRoot,
+  watchdogLogsDir,
+  restartRequestPath,
+  restartingMarkerPath,
+  watchdogRelaunchStatePath,
+  watchdogRelaunchLogPath,
+  historyRollupStampPath,
+  historyRollupLockPath,
+  historyRollupPath,
+  auditLogPath,
+  procnamesRoot,
+  queueHistoryPath,
+  instanceLockPath,
+  heapSnapshotDir,
+};

package/src/main/lib/schedulerRuntimeState.cjs

@@ -0,0 +1,59 @@
+/**
+ * schedulerRuntimeState.cjs — process-local runtime reservations that used to
+ * be bare ++/-- counters in scheduler.cjs. The auto-fix investigation cap is
+ * now a Map of slug → { claimedAt, pid } so a reservation stranded by a
+ * promise that never settles can be expired when its owner is provably dead
+ * (reservationExpiry.isProvablyDead), instead of shrinking the cap forever.
+ */
+'use strict';
+
+const { appendAuditEvent } = require('./auditLog.cjs');
+const { isProvablyDead, DEFAULT_GRACE_MS } = require('./reservationExpiry.cjs');
+
+const investigations = new Map(); // slug -> { claimedAt, pid }
+
+function investigationCount() { return investigations.size; }
+
+/** reserveInvestigation(slug) — false if already reserved. Cap checks stay with the caller. */
+function reserveInvestigation(slug, { claimedAt = Date.now() } = {}) {
+  const key = String(slug);
+  if (investigations.has(key)) return false;
+  investigations.set(key, { claimedAt, pid: null });
+  return true;
+}
+
+function stampInvestigationPid(slug, pid) {
+  const r = investigations.get(String(slug));
+  if (!r || !Number.isInteger(pid) || pid <= 0) return false;
+  r.pid = pid;
+  return true;
+}
+
+/** releaseInvestigation — idempotent; returns whether a reservation was removed. */
+function releaseInvestigation(slug) {
+  return investigations.delete(String(slug));
+}
+
+/** Expire investigations whose slug has no `investigating` row and whose owner is provably dead. */
+function expireDeadInvestigations({ liveSlugs, pidAlive, now = Date.now(), graceMs = DEFAULT_GRACE_MS } = {}) {
+  const live = liveSlugs instanceof Set ? liveSlugs : new Set(liveSlugs || []);
+  const expired = [];
+  for (const [slug, r] of [...investigations]) {
+    if (!isProvablyDead(r, { live: live.has(slug), pidAlive, now, graceMs })) continue;
+    investigations.delete(slug);
+    expired.push(slug);
+    appendAuditEvent('investigation_reservation_expired', { slug, pid: r.pid });
+  }
+  return expired;
+}
+
+function __resetForTests() { investigations.clear(); }
+
+module.exports = {
+  investigationCount,
+  reserveInvestigation,
+  stampInvestigationPid,
+  releaseInvestigation,
+  expireDeadInvestigations,
+  __resetForTests,
+};

package/src/main/lib/sessionSlots.cjs

@@ -25,14 +25,15 @@
 
 const crypto = require('node:crypto');
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const { sessionSlotsConfigPath } = require('./schedulerPaths.cjs');
+const { appendAuditEvent } = require('./auditLog.cjs');
+const { isProvablyDead, DEFAULT_GRACE_MS } = require('./reservationExpiry.cjs');
 
 const MIN_SLOTS = 0;
 const MAX_SLOTS = 10;
 const DEFAULT_SLOTS = 5;
 
-const CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'session-slots-config.json');
 
 function clamp(n) {
   return Math.min(MAX_SLOTS, Math.max(MIN_SLOTS, n));
@@ -40,7 +41,7 @@ function clamp(n) {
 
 function readPersistedCap() {
   try {
-    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const raw = fs.readFileSync(sessionSlotsConfigPath(), 'utf8');
     const parsed = JSON.parse(raw);
     const cap = Number(parsed.cap);
     return Number.isFinite(cap) ? clamp(Math.trunc(cap)) : DEFAULT_SLOTS;
@@ -55,10 +56,11 @@ function setCap(cap) {
   if (!Number.isFinite(n) || Math.trunc(n) !== n || n < MIN_SLOTS || n > MAX_SLOTS) {
     throw new Error(`sessionSlots.setCap: cap must be an integer in [${MIN_SLOTS}, ${MAX_SLOTS}]`);
   }
-  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
-  const tmp = `${CONFIG_PATH}.${process.pid}.${Date.now()}.tmp`;
+  const configPath = sessionSlotsConfigPath();
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.${process.pid}.${Date.now()}.tmp`;
   fs.writeFileSync(tmp, JSON.stringify({ cap: n }, null, 2));
-  fs.renameSync(tmp, CONFIG_PATH);
+  fs.renameSync(tmp, configPath);
   for (const fn of listeners) {
     try { fn(); } catch { /* a consumer's pump error is its own problem */ }
   }
@@ -73,7 +75,7 @@ function totalSlots() {
   return readPersistedCap();
 }
 
-// token → { owner, at }
+// token → { owner, at, claimedAt (ms), pid (null until stampPid) }
 const holders = new Map();
 
 function inUse() {
@@ -89,13 +91,47 @@ function available() {
  * `owner` is a diagnostic label ("scheduler:<slug>", "chat:<tabId>") shown in
  * snapshot() so a stuck holder is attributable.
  */
-function acquire(owner) {
+function acquire(owner, { claimedAt = Date.now() } = {}) {
   if (holders.size >= totalSlots()) return null;
   const token = crypto.randomUUID();
-  holders.set(token, { owner: String(owner || 'unknown'), at: new Date().toISOString() });
+  holders.set(token, { owner: String(owner || 'unknown'), at: new Date(claimedAt).toISOString(), claimedAt, pid: null });
   return token;
 }
 
+/** stampPid(token, pid) — record the child pid once known, so expireDead can prove death by pid. */
+function stampPid(token, pid) {
+  const h = holders.get(token);
+  if (!h || !Number.isInteger(pid) || pid <= 0) return false;
+  h.pid = pid;
+  return true;
+}
+
+/**
+ * expireDead — release `scheduler:` reservations whose owner is provably dead
+ * (see reservationExpiry.isProvablyDead). `chat:` / `project-brief:` tokens are
+ * never touched. Accounting only: no process is signalled. Returns the released
+ * owners. Each release is audited once (the token is gone after release).
+ * @param {{ liveSlugs: Set<string>, pidAlive?: Function, now?: number, graceMs?: number }} opts
+ */
+function expireDead({ liveSlugs, pidAlive, now = Date.now(), graceMs = DEFAULT_GRACE_MS } = {}) {
+  const live = liveSlugs instanceof Set ? liveSlugs : new Set(liveSlugs || []);
+  const expired = [];
+  for (const [token, h] of [...holders]) {
+    if (!h.owner.startsWith('scheduler:')) continue;
+    const slug = h.owner.slice('scheduler:'.length);
+    if (!isProvablyDead(h, { live: live.has(slug), pidAlive, now, graceMs })) continue;
+    holders.delete(token);
+    expired.push(h.owner);
+    appendAuditEvent('slot_reservation_expired', { owner: h.owner, pid: h.pid, claimedAt: h.at });
+  }
+  if (expired.length) {
+    for (const fn of listeners) {
+      try { fn(); } catch { /* a consumer's pump error is its own problem */ }
+    }
+  }
+  return expired;
+}
+
 // Release listeners: each consumer registers its own "a slot freed — try to
 // start work" pump so a scheduler release wakes the chat lane and vice versa.
 // Also fired when the cap itself increases (setCap), for the same reason.
@@ -143,6 +179,8 @@ module.exports = {
   inUse,
   available,
   acquire,
+  stampPid,
+  expireDead,
   release,
   subscribe,
   snapshot,

package/src/main/lib/smProcNames.cjs

@@ -0,0 +1,51 @@
+/**
+ * smProcNames.cjs — kernel `comm` names for the processes Session Manager
+ * itself leaves in the user's process list (pn-03). `claude` children are
+ * named separately (procName.cjs smArgv0 / pn-02).
+ *
+ * Every name is <= 15 chars (Linux TASK_COMM_LEN). `session-manager` is
+ * EXACTLY 15, so NEVER derive another name from it by suffixing — it would
+ * truncate back to `session-manager` and be indistinguishable from main.
+ */
+'use strict';
+
+const path = require('node:path');
+const { aliasBinFor } = require('./procName.cjs');
+
+const PROC_NAMES = Object.freeze({
+  main: 'session-manager',
+  mcpServer: 'sm-mcp-server',
+  watchdog: 'sm-watchdog',
+  inhibitHold: 'sm-inhibit-hold',
+  shell: 'sm-shell',
+});
+
+// Shells whose argv0-basename behaviour (sh/rsh/ksh emulation, $0-branching rc
+// files) is known to be safe under the `sm-shell` alias. Anything else spawns
+// the real path — never guess at another shell's argv0 semantics.
+const ALIASABLE_SHELLS = new Set(['bash', 'zsh']);
+
+/**
+ * On Linux Node's process.title setter calls prctl(PR_SET_NAME), changing
+ * `comm`. It overwrites the argv memory region, but process.argv is a JS
+ * array copied at startup and is unaffected. Never throws.
+ */
+function setProcessTitle(name) {
+  try { process.title = name; } catch { /* naming must never break boot */ }
+}
+
+/** Alias `shell` as `sm-shell` iff it is bash/zsh; otherwise return it unchanged. Fail-open. */
+function aliasedShellBin(shell) {
+  try {
+    if (typeof shell !== 'string' || !shell) return shell;
+    if (!ALIASABLE_SHELLS.has(path.basename(shell))) return shell;
+    return aliasBinFor(shell, PROC_NAMES.shell);
+  } catch { return shell; }
+}
+
+/** `sh` aliased as `sm-inhibit-hold` for the systemd-inhibit poll holder. Fail-open. */
+function inhibitHolderShell() {
+  try { return aliasBinFor('/bin/sh', PROC_NAMES.inhibitHold); } catch { return '/bin/sh'; }
+}
+
+module.exports = { PROC_NAMES, ALIASABLE_SHELLS, setProcessTitle, aliasedShellBin, inhibitHolderShell };