claude-code-session-manager 0.87.0 → 0.88.1

package/src/main/lib/usageCircuit.cjs

@@ -6,6 +6,17 @@
  * 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;
@@ -63,12 +74,25 @@ function bindingWindow(payload) {
   };
 }
 
+/**
+ * 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.
+ * 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);
@@ -76,10 +100,7 @@ function degradedBudget(lastGoodPayload, executorEvidence = {}) {
     ? window.utilization
     : 100;
 
-  const configuredCap = Number.isFinite(executorEvidence.configuredCap)
-    ? executorEvidence.configuredCap
-    : 2;
-  const concurrencyCap = Math.min(configuredCap, 2);
+  const concurrencyCap = degradedConcurrencyCap(executorEvidence.configuredCap);
 
   if (executorEvidence.observed429 && isResetFresh(executorEvidence.resetsAt, executorEvidence.now)) {
     utilization = 100;
@@ -98,6 +119,12 @@ function singleFlight(fn) {
   };
 }
 
+/** 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);
@@ -110,6 +137,12 @@ function createUsageCircuit({ now = () => Date.now() } = {}) {
   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);
@@ -118,6 +151,7 @@ function createUsageCircuit({ now = () => Date.now() } = {}) {
   }
 
   function state() {
+    if (!breakerEnabled()) return 'closed';
     if (currentState === 'open' && !probeInFlight && now() >= nextProbeAtMs) {
       currentState = 'half_open';
       probeInFlight = true;
@@ -127,6 +161,7 @@ function createUsageCircuit({ now = () => Date.now() } = {}) {
 
   function recordFailure(kind) { // eslint-disable-line no-unused-vars
     consecutiveFailures += 1;
+    if (!breakerEnabled()) return;
     if (currentState === 'half_open') {
       probeInFlight = false;
       currentState = 'open';
@@ -135,6 +170,7 @@ function createUsageCircuit({ now = () => Date.now() } = {}) {
     }
     if (currentState === 'closed' && consecutiveFailures >= 3) {
       currentState = 'open';
+      openedAtMs = now();
       scheduleNextProbe();
     }
   }
@@ -144,9 +180,19 @@ function createUsageCircuit({ now = () => Date.now() } = {}) {
     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 };
+  return { recordSuccess, recordFailure, state, openedAt, getConsecutiveFailures };
 }
 
 module.exports = {
@@ -155,5 +201,6 @@ module.exports = {
   isResetFresh,
   bindingWindow,
   degradedBudget,
+  degradedConcurrencyCap,
   singleFlight,
 };

package/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;
 
@@ -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;

package/src/main/pluginInstall.cjs

@@ -31,7 +31,7 @@ const path = require('node:path');
 const os = require('node:os');
 const fs = require('node:fs');
 const { cleanChildEnv, pathWithUserBins } = require('./lib/cleanEnv.cjs');
-const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./lib/claudeBin.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { schemas } = require('./ipcSchemas.cjs');
 
@@ -88,9 +88,13 @@ function runStep({ slug, args, register, unregister }) {
       return;
     }
     const claudeBin = resolveClaudeBin();
+    // node-pty has NO `argv0` option, so the alias symlink is the only naming
+    // mechanism here — the comm is set, argv0 stays the alias path (which still
+    // contains the word `claude`). Do not try to pass argv0.
+    const { command } = claudeSpawnTarget('aux', 'plugin', claudeBin);
     let proc;
     try {
-      proc = pty.spawn(claudeBin, args, {
+      proc = pty.spawn(command, args, {
         name: 'xterm-256color',
         cols: 120,
         rows: 30,