claude-code-session-manager 0.87.0 → 0.88.1

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 };

package/src/main/lib/upgradeDrain.cjs

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * upgradeDrain.cjs — restart as a REQUEST that drains first and never kills.
+ *
+ *   requestRestart()  → writes <schedulerHome>/restart-request.json (atomic).
+ *   evaluateDrain()   → PURE state machine: none | pause | wait | restart | abort.
+ *   scheduler.cjs     → runs it from the existing 60 s heartbeat interval (no
+ *                       new driver) and owns the `drain` field on the machine
+ *                       runtime file. `drain` is deliberately NOT `state.paused`:
+ *                       a rate-limit pause can't overwrite it and the manual-clear
+ *                       cooldown (isCooldownSuppressed) can't swallow it.
+ *
+ * Lifecycle: request → pause (drain.active) → wait (running/investigating rows
+ * finish; nothing new dispatches) → restart (zero busy, checked inside a mutate
+ * right before exit) | abort (deadline; retires the request, clears the drain).
+ * The request is stamped drainCompletedAt before exit; the next boot clears a
+ * leftover drain whose request is complete.
+ *
+ * A `restarting.json` marker with a bounded lifetime covers the deliberate exit
+ * window so scripts/scheduler-watchdog.cjs does not relaunch a second instance.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const schedulerPaths = require('./schedulerPaths.cjs');
+
+// Observed max job run is 240 min; 4 h converts a stuck drain to an abort.
+const DEFAULT_DRAIN_DEADLINE_MS = 4 * 60 * 60_000;
+// Long enough for a cold `npx` resolve + boot, short enough that a failed
+// relaunch is picked up by the watchdog again.
+const RESTARTING_MARKER_TTL_MS = 5 * 60_000;
+
+function writeJsonAtomicSync(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+function readJsonSafe(file) {
+  try {
+    const v = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return v && typeof v === 'object' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------- request file ----------
+
+function readRestartRequest(file = schedulerPaths.restartRequestPath()) {
+  return readJsonSafe(file);
+}
+
+/**
+ * requestRestart({reason, requestedBy}) → the request written. Idempotent: an
+ * already-pending (not completed) request is returned unchanged so a repeated
+ * click or the auto trigger can never reset the drain deadline.
+ */
+function requestRestart({ reason, requestedBy } = {}, { file = schedulerPaths.restartRequestPath(), now = Date.now() } = {}) {
+  const existing = readRestartRequest(file);
+  if (existing && !existing.drainCompletedAt) return existing;
+  const request = {
+    reason: typeof reason === 'string' && reason ? reason : 'unspecified',
+    requestedBy: typeof requestedBy === 'string' && requestedBy ? requestedBy : 'unknown',
+    requestedAt: new Date(now).toISOString(),
+  };
+  writeJsonAtomicSync(file, request);
+  return request;
+}
+
+/** Stamp drainCompletedAt (called immediately before exit). */
+function stampDrainCompleted(now = Date.now(), file = schedulerPaths.restartRequestPath()) {
+  const existing = readRestartRequest(file);
+  if (!existing) return null;
+  const stamped = { ...existing, drainCompletedAt: new Date(now).toISOString() };
+  writeJsonAtomicSync(file, stamped);
+  return stamped;
+}
+
+function retireRestartRequest(file = schedulerPaths.restartRequestPath()) {
+  try { fs.unlinkSync(file); } catch (e) { if (e?.code !== 'ENOENT') throw e; }
+}
+
+// ---------- pure state machine ----------
+
+/**
+ * queueBusyCount(jobs, extraInFlight?) → running + investigating rows, plus any
+ * in-memory investigations the queue file cannot see.
+ */
+function queueBusyCount(jobs, extraInFlight = 0) {
+  let n = 0;
+  for (const j of Array.isArray(jobs) ? jobs : []) {
+    if (j && (j.status === 'running' || j.status === 'investigating')) n++;
+  }
+  return n + (Number.isFinite(extraInFlight) ? extraInFlight : 0);
+}
+
+/**
+ * evaluateDrain({request, queueSnapshot, drainState, now, deadlineMs}) → {action, reason}
+ *
+ * queueSnapshot: { running, investigating } counts (in-memory investigations
+ * already folded in by the caller). drainState: the machine `drain` field
+ * (null / {active}). Pure — no IO, no clock.
+ *
+ *   no request, or request already completed     → none   (abort if a stale drain is still active)
+ *   deadline passed                              → abort
+ *   request pending, drain not yet active        → pause  (engage drain)
+ *   drain active, anything running/investigating → wait
+ *   drain active, zero busy                      → restart
+ */
+function evaluateDrain({ request, queueSnapshot, drainState, now, deadlineMs = DEFAULT_DRAIN_DEADLINE_MS } = {}) {
+  const active = Boolean(drainState && drainState.active);
+  if (!request || request.drainCompletedAt) {
+    return active && !request
+      ? { action: 'abort', reason: 'drain-without-request' }
+      : { action: 'none', reason: request ? 'request-complete' : 'no-request' };
+  }
+  const requestedMs = Date.parse(request.requestedAt ?? '');
+  if (Number.isFinite(requestedMs) && now - requestedMs >= deadlineMs) {
+    return { action: 'abort', reason: 'deadline' };
+  }
+  if (!active) return { action: 'pause', reason: 'engage' };
+  const busy = (queueSnapshot?.running ?? 0) + (queueSnapshot?.investigating ?? 0);
+  return busy > 0 ? { action: 'wait', reason: `busy:${busy}` } : { action: 'restart', reason: 'idle' };
+}
+
+/**
+ * bootDrainAction({drainState, request}) → 'clear' | 'keep' | 'none'.
+ * A drain whose request is complete (the restart happened) or gone is stale.
+ */
+function bootDrainAction({ drainState, request } = {}) {
+  if (!drainState || !drainState.active) return 'none';
+  if (!request || request.drainCompletedAt) return 'clear';
+  return 'keep';
+}
+
+/** The pause-like view every dispatch classifier must use: paused OR draining. */
+function effectivePaused(state) {
+  if (state?.paused) return state.paused;
+  return state?.drain?.active ? { reason: 'drain-for-upgrade' } : null;
+}
+
+// ---------- automatic trigger ----------
+
+/**
+ * installedBuildDiffers({running, installed}) — true only when BOTH shas are
+ * known and differ (an install/update already happened). Never consults npm.
+ */
+function installedBuildDiffers({ running, installed } = {}) {
+  return typeof running === 'string' && running !== ''
+    && typeof installed === 'string' && installed !== ''
+    && running !== installed;
+}
+
+// ---------- restarting marker (watchdog) ----------
+
+function markRestarting({ file = schedulerPaths.restartingMarkerPath(), now = Date.now(), ttlMs = RESTARTING_MARKER_TTL_MS } = {}) {
+  writeJsonAtomicSync(file, { pid: process.pid, at: now, expiresAt: now + ttlMs });
+}
+
+function clearRestartingMarker(file = schedulerPaths.restartingMarkerPath()) {
+  try { fs.unlinkSync(file); } catch { /* absent */ }
+}
+
+/** True while the marker exists and has not expired (bounded lifetime). */
+function isRestartingMarkerActive({ file = schedulerPaths.restartingMarkerPath(), now = Date.now() } = {}) {
+  const m = readJsonSafe(file);
+  return Boolean(m) && typeof m.expiresAt === 'number' && now < m.expiresAt;
+}
+
+module.exports = {
+  DEFAULT_DRAIN_DEADLINE_MS,
+  RESTARTING_MARKER_TTL_MS,
+  readRestartRequest,
+  requestRestart,
+  stampDrainCompleted,
+  retireRestartRequest,
+  queueBusyCount,
+  evaluateDrain,
+  bootDrainAction,
+  effectivePaused,
+  installedBuildDiffers,
+  markRestarting,
+  clearRestartingMarker,
+  isRestartingMarkerActive,
+};