claude-code-session-manager 0.86.0 → 0.88.0

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

package/src/main/lib/usageCircuit.cjs

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * usageCircuit.cjs — a breaker over the /api/oauth/usage meter (PRD ss-02).
+ * Degraded mode is explicit, never a silent 0: repeated failures open the
+ * circuit with jittered backoff; degradedBudget() carries forward the last
+ * known-good BINDING window's utilization (never 0), pinning to 100 on a
+ * fresh executor-observed 429 and capping concurrency at 2. Pure Node.
+ *
+ * Kill switches (read live from process.env, so a test/operator can flip
+ * them without restarting anything that already holds a circuit instance):
+ *   SM_USAGE_CIRCUIT=0      — bypasses the breaker entirely: state() always
+ *                             reports 'closed' and recordFailure() never
+ *                             opens it. Escape hatch if the breaker itself
+ *                             is ever suspected of wedging dispatch.
+ *   SM_USAGE_DEGRADED_CAP=n — overrides degradedBudget()'s concurrencyCap
+ *                             outright (bypasses the normal min(cap, 2)),
+ *                             for an operator who needs a different ceiling
+ *                             while the meter is degraded.
+ */
+
+const FLOOR_MS = 30_000;
+const CAP_MS = 8 * 60 * 1000;
+
+/** Doubles from FLOOR_MS, capped at CAP_MS. 0/falsy prevMs starts at the floor. */
+function doubledBase(prevMs) {
+  return prevMs > 0 ? Math.min(prevMs * 2, CAP_MS) : FLOOR_MS;
+}
+
+/**
+ * Next backoff interval: doubles `prevMs` (floor FLOOR_MS, cap CAP_MS), then
+ * jitters by 0.5 + rand()*0.5 so concurrent instances don't retry in lockstep.
+ */
+function backoffWithJitter(prevMs) {
+  const base = doubledBase(prevMs);
+  return base * (0.5 + Math.random() * 0.5);
+}
+
+/**
+ * A cached reset timestamp is fresh only if it's strictly in the future
+ * relative to `now` — null/unparseable/at-or-before-now all read as stale,
+ * since a passed reset no longer describes a live window.
+ */
+function isResetFresh(iso, now) {
+  if (!iso) return false;
+  const resetMs = Date.parse(iso);
+  if (!Number.isFinite(resetMs)) return false;
+  const nowMs = now instanceof Date ? now.getTime() : Number(now);
+  if (!Number.isFinite(nowMs)) return false;
+  return resetMs > nowMs;
+}
+
+/**
+ * Which window is actually binding dispatch. Prefers `payload.limits[]`'s
+ * `is_active` entry (the richer per-window shape); falls back to the flat
+ * `five_hour` field when `limits[]` is absent, matching usage.cjs's shape.
+ */
+function bindingWindow(payload) {
+  if (payload && Array.isArray(payload.limits) && payload.limits.length) {
+    const active = payload.limits.find((l) => l && l.is_active);
+    if (active) {
+      return {
+        name: active.type || active.name || 'unknown',
+        utilization: active.utilization,
+        resets_at: active.resets_at ?? null,
+      };
+    }
+  }
+  const fh = payload && payload.five_hour;
+  return {
+    name: 'five_hour',
+    utilization: fh ? fh.utilization : undefined,
+    resets_at: fh ? fh.resets_at : null,
+  };
+}
+
+/**
+ * SM_USAGE_DEGRADED_CAP=<n> overrides the normal min(configuredCap, 2)
+ * ceiling outright — an operator escape hatch, not a default path. Falls
+ * through to the normal min(cap, 2) rule when unset/non-positive.
+ */
+function degradedConcurrencyCap(configuredCap) {
+  const override = Number(process.env.SM_USAGE_DEGRADED_CAP);
+  if (Number.isFinite(override) && override > 0) return override;
+  const cap = Number.isFinite(configuredCap) ? configuredCap : 2;
+  return Math.min(cap, 2);
+}
+
+/**
+ * Conservative budget to run on while the meter is down. utilization is
+ * carried forward from the last known-good BINDING window — never 0, which
+ * would read as "plenty of headroom" instead of "we don't know." A fresh
+ * executor-observed 429 (its own window not yet passed) pins utilization to
+ * 100 regardless of the stale cached value. concurrencyCap never exceeds 2
+ * (or SM_USAGE_DEGRADED_CAP, if set).
+ */
+function degradedBudget(lastGoodPayload, executorEvidence = {}) {
+  const window = bindingWindow(lastGoodPayload);
+  let utilization = Number.isFinite(window.utilization) && window.utilization > 0
+    ? window.utilization
+    : 100;
+
+  const concurrencyCap = degradedConcurrencyCap(executorEvidence.configuredCap);
+
+  if (executorEvidence.observed429 && isResetFresh(executorEvidence.resetsAt, executorEvidence.now)) {
+    utilization = 100;
+  }
+
+  return { utilization, concurrencyCap };
+}
+
+/** Wraps `fn` so concurrent callers awaiting an in-flight call share one promise. */
+function singleFlight(fn) {
+  let inFlight = null;
+  return function singleFlightWrapped(...args) {
+    if (inFlight) return inFlight;
+    inFlight = Promise.resolve(fn(...args)).finally(() => { inFlight = null; });
+    return inFlight;
+  };
+}
+
+/** SM_USAGE_CIRCUIT=0 (or 'false') bypasses the breaker entirely. */
+function breakerEnabled() {
+  const v = process.env.SM_USAGE_CIRCUIT;
+  return v == null || v === '' || (v !== '0' && String(v).toLowerCase() !== 'false');
+}
+
+/**
+ * Breaker state machine over the meter: closed -> open after 3 consecutive
+ * failures; open allows exactly one probe per backoff interval (half_open);
+ * a successful probe closes the circuit and resets backoff, a failed probe
+ * reopens it with backoff doubled.
+ */
+function createUsageCircuit({ now = () => Date.now() } = {}) {
+  let consecutiveFailures = 0;
+  let currentState = 'closed';
+  let backoffBaseMs = 0;
+  let nextProbeAtMs = 0;
+  let probeInFlight = false;
+  // ms timestamp the circuit most recently transitioned closed -> open; kept
+  // through half_open <-> open cycles of the SAME streak (a failed probe
+  // re-arms the timer but the meter has been down continuously since this
+  // timestamp), cleared only by recordSuccess. Feeds health.cjs's
+  // GREEN/YELLOW/RED ladder (open duration), not just a failure count.
+  let openedAtMs = null;
+
+  function scheduleNextProbe() {
+    const intervalMs = backoffWithJitter(backoffBaseMs);
+    backoffBaseMs = doubledBase(backoffBaseMs);
+    nextProbeAtMs = now() + intervalMs;
+  }
+
+  function state() {
+    if (!breakerEnabled()) return 'closed';
+    if (currentState === 'open' && !probeInFlight && now() >= nextProbeAtMs) {
+      currentState = 'half_open';
+      probeInFlight = true;
+    }
+    return currentState;
+  }
+
+  function recordFailure(kind) { // eslint-disable-line no-unused-vars
+    consecutiveFailures += 1;
+    if (!breakerEnabled()) return;
+    if (currentState === 'half_open') {
+      probeInFlight = false;
+      currentState = 'open';
+      scheduleNextProbe();
+      return;
+    }
+    if (currentState === 'closed' && consecutiveFailures >= 3) {
+      currentState = 'open';
+      openedAtMs = now();
+      scheduleNextProbe();
+    }
+  }
+
+  function recordSuccess(payload) { // eslint-disable-line no-unused-vars
+    consecutiveFailures = 0;
+    probeInFlight = false;
+    backoffBaseMs = 0;
+    currentState = 'closed';
+    openedAtMs = null;
+  }
+
+  /** ms timestamp this streak opened, or null while closed. */
+  function openedAt() {
+    return currentState === 'open' || currentState === 'half_open' ? openedAtMs : null;
+  }
+
+  function getConsecutiveFailures() {
+    return consecutiveFailures;
+  }
+
+  return { recordSuccess, recordFailure, state, openedAt, getConsecutiveFailures };
+}
+
+module.exports = {
+  createUsageCircuit,
+  backoffWithJitter,
+  isResetFresh,
+  bindingWindow,
+  degradedBudget,
+  degradedConcurrencyCap,
+  singleFlight,
+};

package/{scripts → src/main}/lib/watchdogHelpers.cjs

@@ -4,14 +4,11 @@
 // Testable without spawning the watchdog entry script.
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
+const schedulerPaths = require('./schedulerPaths.cjs');
+const { isRestartingMarkerActive } = require('./upgradeDrain.cjs');
 
 
-// Mirrors scheduler.cjs:215 (single source of truth there; kept in sync here).
-const DEFAULT_HEARTBEAT_PATH = path.join(
-  os.homedir(), '.claude', 'session-manager', 'scheduler-heartbeat.log',
-);
 
 // The in-app heartbeat ticks every 60 s; 3 missed ticks = stale.
 const DEFAULT_MAX_AGE_MS = 180_000;
@@ -40,7 +37,7 @@ const TAIL_BYTES = 4096;
  * Single source of truth for the file-read + reverse-scan logic; used by
  * readLastHeartbeatTs() and heartbeatFresh().
  */
-function readLastHeartbeat(heartbeatPath = DEFAULT_HEARTBEAT_PATH) {
+function readLastHeartbeat(heartbeatPath = schedulerPaths.heartbeatPath()) {
   let buf;
   try {
     const stat = fs.statSync(heartbeatPath);
@@ -79,7 +76,7 @@ function readLastHeartbeat(heartbeatPath = DEFAULT_HEARTBEAT_PATH) {
  * Returns the `ts` field (epoch ms) from the last heartbeat entry.
  * Returns null on missing / empty / unparseable file or missing ts field.
  */
-function readLastHeartbeatTs(heartbeatPath = DEFAULT_HEARTBEAT_PATH) {
+function readLastHeartbeatTs(heartbeatPath = schedulerPaths.heartbeatPath()) {
   const entry = readLastHeartbeat(heartbeatPath);
   return (entry !== null && typeof entry.ts === 'number') ? entry.ts : null;
 }
@@ -88,12 +85,43 @@ function readLastHeartbeatTs(heartbeatPath = DEFAULT_HEARTBEAT_PATH) {
  * heartbeatFresh(heartbeatPath?, maxAgeMs?) → boolean
  *
  * Returns true iff the last heartbeat ts is within maxAgeMs of `now`.
- * Missing / empty / unparseable file → false.
+ * Missing / empty / unparseable file → false. A `degraded: true` line (a
+ * heartbeat subsystem threw — see scheduler.cjs heartbeatTick) is NOT fresh:
+ * the loop ran but could not read state, so it must not disarm the watchdog.
  */
-function heartbeatFresh(heartbeatPath = DEFAULT_HEARTBEAT_PATH, maxAgeMs = DEFAULT_MAX_AGE_MS) {
-  const ts = readLastHeartbeatTs(heartbeatPath);
-  if (ts === null) return false;
-  return (Date.now() - ts) < maxAgeMs;
+function heartbeatFresh(heartbeatPath = schedulerPaths.heartbeatPath(), maxAgeMs = DEFAULT_MAX_AGE_MS) {
+  const entry = readLastHeartbeat(heartbeatPath);
+  if (entry === null || entry.degraded === true || typeof entry.ts !== 'number') return false;
+  return (Date.now() - entry.ts) < maxAgeMs;
+}
+
+const DEFAULT_DISPATCH_DEAD_MS = 30 * 60_000;
+
+/**
+ * evaluateDispatchLiveness(entry, now, { deadMs }?) → { dead, reason }
+ *
+ * Pure. Observability only — a logically-dead scheduler (wedged tick chain,
+ * leaked slots) still writes fresh heartbeats, so freshness alone can't see
+ * it. `dead` only when ALL hold: heartbeat fresh (not degraded, within
+ * DEFAULT_MAX_AGE_MS), dispatch.lastRunAt older than deadMs (absent/unparseable
+ * counts as older), pendingDispatchable > 0, runningCount === 0, not paused.
+ * Callers must NOT relaunch on this: the process is alive, and a relaunch
+ * would spawn a second app on top of it.
+ */
+function evaluateDispatchLiveness(entry, now = Date.now(), { deadMs = DEFAULT_DISPATCH_DEAD_MS } = {}) {
+  if (!entry || entry.degraded === true || typeof entry.ts !== 'number') {
+    return { dead: false, reason: 'no-fresh-heartbeat' };
+  }
+  if (now - entry.ts >= DEFAULT_MAX_AGE_MS) return { dead: false, reason: 'heartbeat-stale' };
+  const d = entry.dispatch;
+  if (!d || typeof d !== 'object') return { dead: false, reason: 'no-dispatch-field' };
+  if (d.paused) return { dead: false, reason: 'paused' };
+  if (d.drain) return { dead: false, reason: 'draining' };
+  if (!(d.pendingDispatchable > 0)) return { dead: false, reason: 'nothing-dispatchable' };
+  if (d.runningCount !== 0) return { dead: false, reason: 'jobs-running' };
+  const lastRunMs = Date.parse(d.lastRunAt ?? '');
+  if (Number.isFinite(lastRunMs) && now - lastRunMs <= deadMs) return { dead: false, reason: 'recent-dispatch' };
+  return { dead: true, reason: 'dispatch-dead' };
 }
 
 /**
@@ -132,12 +160,6 @@ function isPidAlive(pid) {
 // 60 s by scheduler.cjs's heartbeatInterval regardless of pause state) as the
 // liveness signal — no second heartbeat file.
 
-const DEFAULT_RELAUNCH_STATE_PATH = path.join(
-  os.homedir(), '.claude', 'session-manager', 'watchdog-relaunch-state.json',
-);
-const DEFAULT_RELAUNCH_LOG_PATH = path.join(
-  os.homedir(), '.claude', 'logs', 'scheduler-watchdog-relaunch.log',
-);
 const DEFAULT_RELAUNCH_DEBOUNCE_MS = 90_000;
 const DEFAULT_MAX_RELAUNCH_ATTEMPTS = 3;
 
@@ -150,7 +172,7 @@ const DEFAULT_MAX_RELAUNCH_ATTEMPTS = 3;
  * rather than relaunching on top of a live process.
  */
 function checkAppLiveness({
-  heartbeatPath = DEFAULT_HEARTBEAT_PATH,
+  heartbeatPath = schedulerPaths.heartbeatPath(),
   maxAgeMs = DEFAULT_MAX_AGE_MS,
 } = {}) {
   if (heartbeatFresh(heartbeatPath, maxAgeMs)) {
@@ -164,7 +186,7 @@ function checkAppLiveness({
 }
 
 /** Default { lastAttemptTs: null, attemptCount: 0 } on missing/unparseable state file. */
-function readRelaunchState(statePath = DEFAULT_RELAUNCH_STATE_PATH) {
+function readRelaunchState(statePath = schedulerPaths.watchdogRelaunchStatePath()) {
   try {
     const raw = JSON.parse(fs.readFileSync(statePath, 'utf8'));
     return {
@@ -203,7 +225,7 @@ function logRelaunchLine(logPath, message) {
  * (short-lived) process doesn't block on the launched app and the app
  * survives the watchdog exiting.
  */
-function defaultSpawnRelaunch({ logPath = DEFAULT_RELAUNCH_LOG_PATH } = {}) {
+function defaultSpawnRelaunch({ logPath = schedulerPaths.watchdogRelaunchLogPath() } = {}) {
   const { spawn } = require('node:child_process');
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
   const fd = fs.openSync(logPath, 'a');
@@ -236,14 +258,15 @@ function defaultSpawnRelaunch({ logPath = DEFAULT_RELAUNCH_LOG_PATH } = {}) {
  * intervenes or the app comes up some other way.
  */
 function maybeRelaunchApp({
-  heartbeatPath = DEFAULT_HEARTBEAT_PATH,
+  heartbeatPath = schedulerPaths.heartbeatPath(),
   maxAgeMs = DEFAULT_MAX_AGE_MS,
-  statePath = DEFAULT_RELAUNCH_STATE_PATH,
-  logPath = DEFAULT_RELAUNCH_LOG_PATH,
+  statePath = schedulerPaths.watchdogRelaunchStatePath(),
+  logPath = schedulerPaths.watchdogRelaunchLogPath(),
   debounceMs = DEFAULT_RELAUNCH_DEBOUNCE_MS,
   maxAttempts = DEFAULT_MAX_RELAUNCH_ATTEMPTS,
   now = Date.now(),
   spawnFn = defaultSpawnRelaunch,
+  restartingMarkerPath = schedulerPaths.restartingMarkerPath(),
 } = {}) {
   const liveness = checkAppLiveness({ heartbeatPath, maxAgeMs });
   const state = readRelaunchState(statePath);
@@ -255,6 +278,14 @@ function maybeRelaunchApp({
     return { relaunched: false, reason: 'alive', attemptCount: 0 };
   }
 
+  // A deliberate drain-restart is mid-exit: the old process is going away ON
+  // PURPOSE and its successor is booting. Relaunching now would race the
+  // single-instance lock. The marker's lifetime is bounded, so a restart that
+  // never comes up is picked up again once it expires.
+  if (isRestartingMarkerActive({ file: restartingMarkerPath, now })) {
+    return { relaunched: false, reason: 'restarting', attemptCount: state.attemptCount };
+  }
+
   if (state.attemptCount >= maxAttempts) {
     logRelaunchLine(
       logPath,
@@ -286,12 +317,6 @@ function maybeRelaunchApp({
 // walk/persist logic — this is just the once-per-day scheduling + lock
 // wrapper around it, tailored to being invoked repeatedly by a systemd timer.
 
-const DEFAULT_STAMP_PATH = path.join(
-  os.homedir(), '.claude', 'session-manager', 'history-rollup.stamp',
-);
-const DEFAULT_LOCK_PATH = path.join(
-  os.homedir(), '.claude', 'session-manager', 'history-rollup.lock',
-);
 const DEFAULT_LOCK_STALE_MS = 10 * 60 * 1000; // 10 min
 const DEFAULT_FINALIZE_BUDGET_MS = 60_000;
 
@@ -362,7 +387,7 @@ function releaseLock(lockPath) {
  *  dependency fails inside maybeFinalizeHistory's try/catch, not at require
  *  time for the whole watchdog script. */
 function defaultFinalizeClosedDays(opts) {
-  const { finalizeClosedDays } = require('../../src/main/historyAggregator.cjs');
+  const { finalizeClosedDays } = require('../historyAggregator.cjs');
   return finalizeClosedDays(opts);
 }
 
@@ -384,8 +409,8 @@ function defaultFinalizeClosedDays(opts) {
  *   finalizeFn  — injectable finalizeClosedDays for testing
  */
 async function maybeFinalizeHistory({
-  stampPath = DEFAULT_STAMP_PATH,
-  lockPath = DEFAULT_LOCK_PATH,
+  stampPath = schedulerPaths.historyRollupStampPath(),
+  lockPath = schedulerPaths.historyRollupLockPath(),
   staleLockMs = DEFAULT_LOCK_STALE_MS,
   budgetMs = DEFAULT_FINALIZE_BUDGET_MS,
   dryRun = process.env.SM_WATCHDOG_DRYRUN === '1',
@@ -423,6 +448,7 @@ module.exports = {
   readLastHeartbeat,
   readLastHeartbeatTs,
   heartbeatFresh,
+  evaluateDispatchLiveness,
   isPidAlive,
   localDateStr,
   maybeFinalizeHistory,
@@ -433,14 +459,21 @@ module.exports = {
   writeRelaunchState,
   defaultSpawnRelaunch,
   maybeRelaunchApp,
-  DEFAULT_HEARTBEAT_PATH,
   DEFAULT_MAX_AGE_MS,
-  DEFAULT_STAMP_PATH,
-  DEFAULT_LOCK_PATH,
+  DEFAULT_DISPATCH_DEAD_MS,
   DEFAULT_LOCK_STALE_MS,
   DEFAULT_FINALIZE_BUDGET_MS,
-  DEFAULT_RELAUNCH_STATE_PATH,
-  DEFAULT_RELAUNCH_LOG_PATH,
   DEFAULT_RELAUNCH_DEBOUNCE_MS,
   DEFAULT_MAX_RELAUNCH_ATTEMPTS,
 };
+
+// Lazy default-path getters (SM_SCHEDULER_HOME resolved at read, never at require).
+for (const [name, resolve] of [
+  ['DEFAULT_HEARTBEAT_PATH', schedulerPaths.heartbeatPath],
+  ['DEFAULT_STAMP_PATH', schedulerPaths.historyRollupStampPath],
+  ['DEFAULT_LOCK_PATH', schedulerPaths.historyRollupLockPath],
+  ['DEFAULT_RELAUNCH_STATE_PATH', schedulerPaths.watchdogRelaunchStatePath],
+  ['DEFAULT_RELAUNCH_LOG_PATH', schedulerPaths.watchdogRelaunchLogPath],
+]) {
+  Object.defineProperty(module.exports, name, { get: resolve, enumerable: true });
+}

package/src/main/lib/withTimeout.cjs

@@ -0,0 +1,33 @@
+/**
+ * withTimeout.cjs — bound an async body with a wall-clock budget.
+ *
+ * `withTimeout(promiseFactory, ms, onTimeout)` starts `promiseFactory()` and
+ * resolves with its result. If it has not settled after `ms`, `onTimeout()`
+ * is called and ITS return value becomes the resolved value; the original
+ * promise is abandoned (never cancelled — callers that must neutralise a
+ * late-resuming body do so with their own generation fence). The timer is
+ * always cleared on settle, and unref'd so it can never hold the process open.
+ * `ms <= 0` (or non-finite) disables the bound entirely.
+ *
+ * Plain Node module (no Electron deps).
+ */
+'use strict';
+
+function withTimeout(promiseFactory, ms, onTimeout) {
+  if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve().then(promiseFactory);
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      try { resolve(onTimeout()); } catch (e) { reject(e); }
+    }, ms);
+    if (typeof timer.unref === 'function') timer.unref();
+    Promise.resolve().then(promiseFactory).then(
+      (v) => { if (done) return; done = true; clearTimeout(timer); resolve(v); },
+      (e) => { if (done) return; done = true; clearTimeout(timer); reject(e); },
+    );
+  });
+}
+
+module.exports = { withTimeout };

package/src/main/mcpStatus.cjs

@@ -10,7 +10,8 @@
  */
 
 const { spawn } = require('node:child_process');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
+const { withProcRole } = require('./lib/cleanEnv.cjs');
 
 const PROBE_TIMEOUT_MS = 30_000;
 
@@ -56,7 +57,8 @@ function runProbe() {
     }
     let child;
     try {
-      child = spawn(bin, ['mcp', 'list'], { env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
+      const target = claudeSpawnTarget('aux', 'mcp-list', bin);
+      child = spawn(target.command, ['mcp', 'list'], { env: withProcRole(process.env, 'aux'), stdio: ['ignore', 'pipe', 'pipe'], ...(target.argv0 ? { argv0: target.argv0 } : {}) });
     } catch (e) {
       resolve({ ok: false, servers: [], error: e?.message || 'spawn error', checkedAt: Date.now() });
       return;