claude-code-session-manager 0.87.0 → 0.88.1

package/src/main/lib/__tests__/schedulerRuntimeState.test.cjs

@@ -0,0 +1,56 @@
+// schedulerRuntimeState.cjs + quietMachineLease.cjs — fail-closed expiry.
+const assert = require('node:assert');
+const state = require('../schedulerRuntimeState.cjs');
+const lease = require('../quietMachineLease.cjs');
+
+const NOW = 10_000_000;
+const GRACE = 10 * 60 * 1000;
+
+beforeEach(() => { state.__resetForTests(); lease.__resetForTests(); });
+afterEach(() => { state.__resetForTests(); lease.__resetForTests(); });
+
+test('lease: expires only when holder not running AND past grace', () => {
+  lease.acquire('q', { claimedAt: NOW - GRACE - 1 });
+  assert.equal(lease.expireDead({ liveSlugs: new Set(['q']), now: NOW, graceMs: GRACE }), false, 'running row keeps it');
+  assert.equal(lease.isHeld(), true);
+  assert.equal(lease.expireDead({ liveSlugs: new Set(), now: NOW, graceMs: GRACE }), true);
+  assert.equal(lease.isHeld(), false);
+});
+
+test('lease: inside the grace window or claimed after the pass began is kept', () => {
+  lease.acquire('q', { claimedAt: NOW - 1000 });
+  assert.equal(lease.expireDead({ liveSlugs: new Set(), now: NOW, graceMs: GRACE }), false);
+  lease.release('q');
+  lease.acquire('q', { claimedAt: NOW + 10 });
+  assert.equal(lease.expireDead({ liveSlugs: new Set(), now: NOW, graceMs: GRACE }), false);
+  assert.equal(lease.isHeld(), true);
+});
+
+test('investigations: set semantics, no double reservation, idempotent release', () => {
+  assert.equal(state.reserveInvestigation('a'), true);
+  assert.equal(state.reserveInvestigation('a'), false);
+  assert.equal(state.investigationCount(), 1);
+  assert.equal(state.releaseInvestigation('a'), true);
+  assert.equal(state.releaseInvestigation('a'), false);
+  assert.equal(state.investigationCount(), 0);
+});
+
+test('investigations: dead stamped pid with no investigating row expires; live pid/row survives', () => {
+  state.reserveInvestigation('dead', { claimedAt: NOW - 1000 });
+  state.stampInvestigationPid('dead', 111);
+  state.reserveInvestigation('alive', { claimedAt: NOW - 1000 });
+  state.stampInvestigationPid('alive', 222);
+  state.reserveInvestigation('rowlive', { claimedAt: NOW - 2 * GRACE });
+  const out = state.expireDeadInvestigations({
+    liveSlugs: new Set(['rowlive']), pidAlive: (p) => p === 222, now: NOW, graceMs: GRACE,
+  });
+  assert.deepEqual(out, ['dead']);
+  assert.equal(state.investigationCount(), 2);
+});
+
+test('investigations: pidless reservation expires past grace only', () => {
+  state.reserveInvestigation('old', { claimedAt: NOW - GRACE - 1 });
+  state.reserveInvestigation('fresh', { claimedAt: NOW - 1000 });
+  const out = state.expireDeadInvestigations({ liveSlugs: new Set(), pidAlive: () => false, now: NOW, graceMs: GRACE });
+  assert.deepEqual(out, ['old']);
+});

package/src/main/lib/__tests__/sessionSlots.test.cjs

@@ -97,3 +97,48 @@ test('snapshot names holders for attribution', () => {
   assert.equal(snap.inUse, 2);
   assert.deepEqual(snap.holders.map((h) => h.owner).sort(), ['chat:tab-1', 'scheduler:42-fix-thing']);
 });
+
+// ── expireDead: fail-closed release of provably-dead scheduler reservations ──
+const NOW = 10_000_000;
+const GRACE = 10 * 60 * 1000;
+
+test('expireDead: stamped dead pid with no live row is released', () => {
+  const t = slots.acquire('scheduler:a', { claimedAt: NOW - 1000 });
+  slots.stampPid(t, 4242);
+  const out = slots.expireDead({ liveSlugs: new Set(), pidAlive: () => false, now: NOW, graceMs: GRACE });
+  assert.deepEqual(out, ['scheduler:a']);
+  assert.equal(slots.inUse(), 0);
+});
+
+test('expireDead: a live pid or a live row keeps the token', () => {
+  const t1 = slots.acquire('scheduler:a', { claimedAt: NOW - 2 * GRACE });
+  slots.stampPid(t1, 4242);
+  const t2 = slots.acquire('scheduler:b', { claimedAt: NOW - 2 * GRACE });
+  slots.expireDead({ liveSlugs: new Set(['b']), pidAlive: () => true, now: NOW, graceMs: GRACE });
+  assert.equal(slots.inUse(), 2, 'live pid (a) and live row (b) both survive');
+  assert.ok(t1 && t2);
+});
+
+test('expireDead: pidless token expires only past the grace window', () => {
+  slots.acquire('scheduler:old', { claimedAt: NOW - GRACE - 1 });
+  slots.acquire('scheduler:fresh', { claimedAt: NOW - GRACE + 1000 });
+  const out = slots.expireDead({ liveSlugs: new Set(), pidAlive: () => false, now: NOW, graceMs: GRACE });
+  assert.deepEqual(out, ['scheduler:old']);
+  assert.equal(slots.inUse(), 1);
+});
+
+test('expireDead: chat and project-brief tokens are never touched', () => {
+  slots.acquire('chat:tab1', { claimedAt: 0 });
+  slots.acquire('project-brief:x', { claimedAt: 0 });
+  const out = slots.expireDead({ liveSlugs: new Set(), pidAlive: () => false, now: NOW, graceMs: GRACE });
+  assert.deepEqual(out, []);
+  assert.equal(slots.inUse(), 2);
+});
+
+test('expireDead: a mid-launch reservation (claimed after the pass began) survives even with a dead pid', () => {
+  const t = slots.acquire('scheduler:mid', { claimedAt: NOW + 5 });
+  slots.stampPid(t, 4242);
+  const out = slots.expireDead({ liveSlugs: new Set(), pidAlive: () => false, now: NOW, graceMs: GRACE });
+  assert.deepEqual(out, []);
+  assert.equal(slots.inUse(), 1);
+});

package/src/main/lib/__tests__/telemetryBacklog.test.cjs

@@ -183,7 +183,7 @@ test('duplicate cwds across tabs are visited once; a missing cwd is skipped with
 
 test('an ephemeral epic-worktree cwd is never scanned as its own project', async () => {
   const home = await mkHome();
-  const ephemeral = path.join(os.tmpdir(), 'session-manager-epic-worktrees', 'abc123', 'psess-xyz');
+  const ephemeral = path.join(process.env.SM_WORKTREE_ROOT || os.tmpdir(), 'session-manager-epic-worktrees', 'abc123', 'psess-xyz');
   const opsDir = path.join(ephemeral, 'session-manager-operations', 'logs');
   fs.mkdirSync(opsDir, { recursive: true });
   fs.writeFileSync(path.join(opsDir, `errors-${recentDateStr()}.jsonl`), JSON.stringify(errLine(1)) + '\n');

package/src/main/lib/__tests__/upgradeDrain.test.cjs

@@ -0,0 +1,130 @@
+'use strict';
+
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/upgradeDrain.test.cjs
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const ud = require('../upgradeDrain.cjs');
+
+const T0 = Date.parse('2026-09-18T00:00:00Z');
+const req = (extra = {}) => ({ reason: 'r', requestedBy: 'u', requestedAt: new Date(T0).toISOString(), ...extra });
+const ev = (o) => ud.evaluateDrain({ now: T0 + 1000, ...o }).action;
+
+function tmp() { return fs.mkdtempSync(path.join(os.tmpdir(), 'upgrade-drain-')); }
+
+describe('evaluateDrain state machine', () => {
+  test('no request → none', () => {
+    assert.equal(ev({ request: null, queueSnapshot: { running: 2 }, drainState: null }), 'none');
+  });
+  test('pending request, drain not active → pause (even when idle)', () => {
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 0, investigating: 0 }, drainState: null }), 'pause');
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 3 }, drainState: null }), 'pause');
+  });
+  test('drain active + running or investigating → wait', () => {
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 1, investigating: 0 }, drainState: { active: true } }), 'wait');
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 0, investigating: 1 }, drainState: { active: true } }), 'wait');
+  });
+  test('drain active + zero busy → restart', () => {
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 0, investigating: 0 }, drainState: { active: true } }), 'restart');
+  });
+  test('deadline converts to abort, default 4 h', () => {
+    const now = T0 + ud.DEFAULT_DRAIN_DEADLINE_MS;
+    assert.equal(ud.DEFAULT_DRAIN_DEADLINE_MS, 4 * 60 * 60_000);
+    assert.equal(ud.evaluateDrain({ request: req(), queueSnapshot: { running: 1 }, drainState: { active: true }, now }).action, 'abort');
+    assert.equal(ud.evaluateDrain({ request: req(), queueSnapshot: { running: 1 }, drainState: { active: true }, now: now - 1 }).action, 'wait');
+    assert.equal(ud.evaluateDrain({ request: req(), queueSnapshot: {}, drainState: { active: true }, now: T0 + 500, deadlineMs: 100 }).action, 'abort');
+  });
+  test('completed request → none; stale drain without request → abort', () => {
+    assert.equal(ev({ request: req({ drainCompletedAt: 'x' }), queueSnapshot: {}, drainState: { active: true } }), 'none');
+    assert.equal(ev({ request: null, queueSnapshot: {}, drainState: { active: true } }), 'abort');
+  });
+  test('a rate-limit pause during a drain does not change the verdict: drain is its own field', () => {
+    // evaluateDrain never sees state.paused; a rate_limit pause overwriting
+    // `paused` leaves the drain field (and the verdict) untouched.
+    const state = { paused: { reason: 'rate_limit' }, drain: { active: true } };
+    assert.equal(ev({ request: req(), queueSnapshot: { running: 0, investigating: 0 }, drainState: state.drain }), 'restart');
+    assert.equal(ud.effectivePaused(state).reason, 'rate_limit');
+    assert.equal(ud.effectivePaused({ paused: null, drain: { active: true } }).reason, 'drain-for-upgrade');
+    assert.equal(ud.effectivePaused({ paused: null, drain: null }), null);
+  });
+});
+
+describe('request file lifecycle', () => {
+  test('requestRestart writes atomically and is idempotent while pending', () => {
+    const dir = tmp();
+    try {
+      const file = path.join(dir, 'restart-request.json');
+      const a = ud.requestRestart({ reason: 'x', requestedBy: 'user' }, { file, now: T0 });
+      const b = ud.requestRestart({ reason: 'y', requestedBy: 'auto' }, { file, now: T0 + 5000 });
+      assert.deepEqual(b, a, 'a second request must not reset the deadline');
+      assert.deepEqual(fs.readdirSync(dir), ['restart-request.json'], 'no tmp file left behind');
+      assert.equal(ud.readRestartRequest(file).requestedBy, 'user');
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  });
+  test('stampDrainCompleted marks it; a new request after completion starts fresh', () => {
+    const dir = tmp();
+    try {
+      const file = path.join(dir, 'restart-request.json');
+      ud.requestRestart({ reason: 'x', requestedBy: 'u' }, { file, now: T0 });
+      assert.ok(ud.stampDrainCompleted(T0 + 1, file).drainCompletedAt);
+      const fresh = ud.requestRestart({ reason: 'again', requestedBy: 'u' }, { file, now: T0 + 9 });
+      assert.equal(fresh.reason, 'again');
+      assert.equal(fresh.drainCompletedAt, undefined);
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  });
+  test('abort retires the request file', () => {
+    const dir = tmp();
+    try {
+      const file = path.join(dir, 'restart-request.json');
+      ud.requestRestart({ reason: 'x', requestedBy: 'u' }, { file, now: T0 });
+      ud.retireRestartRequest(file);
+      assert.equal(ud.readRestartRequest(file), null);
+      ud.retireRestartRequest(file); // absent → no throw
+      // With the request gone, a re-evaluation is 'none' — no abort flap.
+      assert.equal(ev({ request: ud.readRestartRequest(file), queueSnapshot: {}, drainState: null }), 'none');
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  });
+});
+
+describe('boot', () => {
+  test('clears a leftover drain whose request is complete or gone; keeps a pending one', () => {
+    assert.equal(ud.bootDrainAction({ drainState: { active: true }, request: req({ drainCompletedAt: 'x' }) }), 'clear');
+    assert.equal(ud.bootDrainAction({ drainState: { active: true }, request: null }), 'clear');
+    assert.equal(ud.bootDrainAction({ drainState: { active: true }, request: req() }), 'keep');
+    assert.equal(ud.bootDrainAction({ drainState: null, request: req() }), 'none');
+  });
+});
+
+describe('automatic trigger', () => {
+  test('only when both shas are known and differ — never from npm', () => {
+    assert.equal(ud.installedBuildDiffers({ running: 'aaa', installed: 'bbb' }), true);
+    assert.equal(ud.installedBuildDiffers({ running: 'aaa', installed: 'aaa' }), false);
+    assert.equal(ud.installedBuildDiffers({ running: null, installed: 'bbb' }), false);
+    assert.equal(ud.installedBuildDiffers({ running: 'aaa', installed: null }), false);
+  });
+});
+
+describe('queueBusyCount', () => {
+  test('counts running + investigating only', () => {
+    const jobs = [{ status: 'running' }, { status: 'investigating' }, { status: 'pending' }, { status: 'needs_review' }];
+    assert.equal(ud.queueBusyCount(jobs), 2);
+    assert.equal(ud.queueBusyCount(jobs, 1), 3);
+  });
+});
+
+describe('restarting marker', () => {
+  test('active until expiry, then lapses', () => {
+    const dir = tmp();
+    try {
+      const file = path.join(dir, 'restarting.json');
+      assert.equal(ud.isRestartingMarkerActive({ file, now: T0 }), false);
+      ud.markRestarting({ file, now: T0, ttlMs: 1000 });
+      assert.equal(ud.isRestartingMarkerActive({ file, now: T0 + 999 }), true);
+      assert.equal(ud.isRestartingMarkerActive({ file, now: T0 + 1000 }), false);
+      ud.clearRestartingMarker(file);
+      assert.equal(ud.isRestartingMarkerActive({ file, now: T0 }), false);
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  });
+});

package/src/main/lib/__tests__/usageCircuit.test.cjs

@@ -208,6 +208,67 @@ test('singleFlight: concurrent callers share the same in-flight promise, fn invo
   await p3;
 });
 
+test('openedAt: null while closed, stamped the moment it opens, stays stamped through a failed half_open probe, clears on success', () => {
+  let nowMs = 1000;
+  const circuit = createUsageCircuit({ now: () => nowMs });
+  assert.strictEqual(circuit.openedAt(), null);
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  assert.strictEqual(circuit.openedAt(), null); // still closed, 2 of 3
+  circuit.recordFailure('a');
+  assert.strictEqual(circuit.state(), 'open');
+  assert.strictEqual(circuit.openedAt(), 1000);
+
+  nowMs += 60 * 60 * 1000;
+  assert.strictEqual(circuit.state(), 'half_open');
+  assert.strictEqual(circuit.openedAt(), 1000); // unchanged through the probe
+
+  circuit.recordFailure('a'); // failed probe -> reopens
+  assert.strictEqual(circuit.state(), 'open');
+  assert.strictEqual(circuit.openedAt(), 1000); // still the ORIGINAL open time, not re-stamped
+
+  circuit.recordSuccess({});
+  assert.strictEqual(circuit.openedAt(), null);
+});
+
+test('getConsecutiveFailures: tracks failures, resets on success', () => {
+  const circuit = createUsageCircuit({ now: () => 0 });
+  assert.strictEqual(circuit.getConsecutiveFailures(), 0);
+  circuit.recordFailure('a');
+  circuit.recordFailure('a');
+  assert.strictEqual(circuit.getConsecutiveFailures(), 2);
+  circuit.recordSuccess({});
+  assert.strictEqual(circuit.getConsecutiveFailures(), 0);
+});
+
+test('SM_USAGE_CIRCUIT=0 bypasses the breaker entirely: state stays closed no matter how many failures', () => {
+  const prev = process.env.SM_USAGE_CIRCUIT;
+  process.env.SM_USAGE_CIRCUIT = '0';
+  try {
+    const circuit = createUsageCircuit({ now: () => 0 });
+    circuit.recordFailure('a');
+    circuit.recordFailure('a');
+    circuit.recordFailure('a');
+    circuit.recordFailure('a');
+    assert.strictEqual(circuit.state(), 'closed');
+    assert.strictEqual(circuit.openedAt(), null);
+  } finally {
+    if (prev === undefined) delete process.env.SM_USAGE_CIRCUIT; else process.env.SM_USAGE_CIRCUIT = prev;
+  }
+});
+
+test('SM_USAGE_DEGRADED_CAP overrides degradedBudget concurrencyCap outright, bypassing min(cap, 2)', () => {
+  const prev = process.env.SM_USAGE_DEGRADED_CAP;
+  process.env.SM_USAGE_DEGRADED_CAP = '7';
+  try {
+    const payload = { five_hour: { utilization: 30, resets_at: null } };
+    const { concurrencyCap } = degradedBudget(payload, { configuredCap: 2 });
+    assert.strictEqual(concurrencyCap, 7);
+  } finally {
+    if (prev === undefined) delete process.env.SM_USAGE_DEGRADED_CAP; else process.env.SM_USAGE_DEGRADED_CAP = prev;
+  }
+});
+
 test('singleFlight: de-dupes even when fn rejects, next call gets a fresh attempt', async () => {
   let calls = 0;
   const fn = () => (calls++ === 0 ? Promise.reject(new Error('boom')) : Promise.resolve('ok'));

package/src/main/lib/__tests__/watchdog-helpers.test.cjs

@@ -8,6 +8,7 @@ const os = require('node:os');
 const path = require('node:path');
 const {
   heartbeatFresh,
+  evaluateDispatchLiveness,
   readLastHeartbeat,
   localDateStr,
   maybeFinalizeHistory,
@@ -310,3 +311,65 @@ test('maybeFinalizeHistory: dryRun computes without stamping or requiring a writ
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+describe('evaluateDispatchLiveness', () => {
+  const now = 10_000_000_000;
+  const deadMs = 30 * 60_000;
+  const base = () => ({
+    ts: now - 1_000,
+    dispatch: {
+      lastDispatchAttemptAt: new Date(now - 1_000).toISOString(),
+      lastRunAt: new Date(now - deadMs - 60_000).toISOString(),
+      lastTickReason: 'held',
+      pendingDispatchable: 3,
+      runningCount: 0,
+      paused: false,
+    },
+  });
+
+  test('all conditions met → dead', () => {
+    assert.deepEqual(evaluateDispatchLiveness(base(), now, { deadMs }), { dead: true, reason: 'dispatch-dead' });
+  });
+
+  test('default deadMs is 30 min', () => {
+    assert.equal(evaluateDispatchLiveness(base(), now).dead, true);
+    const e = base();
+    e.dispatch.lastRunAt = new Date(now - 29 * 60_000).toISOString();
+    assert.equal(evaluateDispatchLiveness(e, now).dead, false);
+  });
+
+  test('each condition is conjunctive', () => {
+    const recent = base(); recent.dispatch.lastRunAt = new Date(now - 60_000).toISOString();
+    const none = base(); none.dispatch.pendingDispatchable = 0;
+    const running = base(); running.dispatch.runningCount = 1;
+    const stale = base(); stale.ts = now - 10 * 60_000;
+    for (const e of [recent, none, running, stale]) {
+      assert.equal(evaluateDispatchLiveness(e, now, { deadMs }).dead, false);
+    }
+  });
+
+  test('never-dispatched (null lastRunAt) counts as older than deadMs', () => {
+    const e = base(); e.dispatch.lastRunAt = null;
+    assert.equal(evaluateDispatchLiveness(e, now, { deadMs }).dead, true);
+  });
+
+  test('paused suppresses', () => {
+    const e = base(); e.dispatch.paused = true;
+    assert.deepEqual(evaluateDispatchLiveness(e, now, { deadMs }), { dead: false, reason: 'paused' });
+  });
+
+  test('drained queue (nothing dispatchable) suppresses', () => {
+    const e = base(); e.dispatch.pendingDispatchable = 0;
+    assert.equal(evaluateDispatchLiveness(e, now, { deadMs }).reason, 'nothing-dispatchable');
+  });
+
+  test('a degraded line is ignored', () => {
+    const e = { ...base(), degraded: true, errors: [] };
+    assert.equal(evaluateDispatchLiveness(e, now, { deadMs }).dead, false);
+  });
+
+  test('null entry / missing dispatch field → not dead', () => {
+    assert.equal(evaluateDispatchLiveness(null, now).dead, false);
+    assert.equal(evaluateDispatchLiveness({ ts: now }, now).dead, false);
+  });
+});

package/src/main/lib/__tests__/watchdog-relaunch.test.cjs

@@ -9,6 +9,8 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const {
   maybeRelaunchApp,
+  evaluateDispatchLiveness,
+  readLastHeartbeat,
   readRelaunchState,
   DEFAULT_MAX_RELAUNCH_ATTEMPTS,
 } = require('../watchdogHelpers.cjs');
@@ -191,3 +193,74 @@ test('attemptCount resets to 0 once a fresh heartbeat is observed', () => {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('dispatch-dead (fresh heartbeat, dead dispatch chain) never relaunches', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const now = Date.now();
+    fs.writeFileSync(hbPath, JSON.stringify({
+      ts: now - 1_000,
+      pid: process.pid,
+      dispatch: {
+        lastDispatchAttemptAt: new Date(now - 1_000).toISOString(),
+        lastRunAt: new Date(now - 2 * 60 * 60_000).toISOString(),
+        lastTickReason: 'held',
+        pendingDispatchable: 5,
+        runningCount: 0,
+        paused: false,
+      },
+    }) + '\n');
+    assert.equal(evaluateDispatchLiveness(readLastHeartbeat(hbPath), now).dead, true);
+
+    const spawnFn = makeSpawnSpy();
+    const result = maybeRelaunchApp({ heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, now, spawnFn });
+    assert.equal(result.relaunched, false);
+    assert.equal(result.reason, 'alive');
+    assert.equal(spawnFn.calls.length, 0);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── restarting marker (drain-restart exit window) ───────────────────────────
+
+test('stale heartbeat + active restarting marker → no relaunch; expired marker → relaunch', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const markerPath = path.join(dir, 'restarting.json');
+    const now = Date.now();
+    writeHeartbeat(hbPath, now - 10 * 60_000, DEAD_PID);
+    fs.writeFileSync(markerPath, JSON.stringify({ pid: DEAD_PID, at: now - 1_000, expiresAt: now + 60_000 }));
+    const spawnFn = makeSpawnSpy();
+
+    const held = maybeRelaunchApp({ heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, restartingMarkerPath: markerPath, now, spawnFn });
+    assert.equal(held.relaunched, false);
+    assert.equal(held.reason, 'restarting');
+    assert.equal(spawnFn.calls.length, 0);
+    assert.equal(fs.existsSync(statePath), false, 'a held relaunch must not burn an attempt');
+
+    // Bounded lifetime: once the marker expires the watchdog resumes duty.
+    const lapsed = maybeRelaunchApp({ heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, restartingMarkerPath: markerPath, now: now + 61_000, spawnFn });
+    assert.equal(lapsed.relaunched, true);
+    assert.equal(spawnFn.calls.length, 1);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('fresh heartbeat carrying dispatch.drain is not dispatch-dead', () => {
+  const now = Date.now();
+  const entry = {
+    ts: now - 1_000,
+    dispatch: {
+      lastRunAt: new Date(now - 5 * 60 * 60_000).toISOString(),
+      pendingDispatchable: 5, runningCount: 0, paused: false,
+      drain: { since: new Date(now - 60_000).toISOString(), requestedAt: new Date(now - 60_000).toISOString() },
+    },
+  };
+  assert.deepEqual(evaluateDispatchLiveness(entry, now), { dead: false, reason: 'draining' });
+});

package/src/main/lib/activeIndexRebuild.cjs

@@ -48,9 +48,7 @@ function listMirrorFiles(dir) {
  * `skipped` — file names not turned into a row.
  * `reasons` — `{ [fileName]: humanReadableReason }`, one entry per skipped
  *   file. A file is never guessed at: no mirrored `status` is a skip, not a
- *   fabricated 'unknown' row (see scripts/mirror-epic-status.cjs for the
- *   only place that vocabulary is deliberately introduced, for the
- *   migration's own back-fill bookkeeping).
+ *   fabricated 'unknown' row.
  *
  * `events` and `tombstones` from the existing on-disk index (if any) are
  * carried through completely untouched — this function only ever

package/src/main/lib/activeSessions.cjs

@@ -13,6 +13,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('./gitWorktree.cjs');
 const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
+const { classifyCwd, worktreeMainRootOf } = require('./cwdClassify.cjs');
 
 const HOME = os.homedir();
 const TMPDIR = os.tmpdir();
@@ -32,7 +33,7 @@ const TMPDIR = os.tmpdir();
 //     could not — e.g. a bare, .git-less worktree-root directory.
 const TMP_DROP_ROOTS = {
   exactDropCwds: [TMPDIR],
-  prefixDropRoots: [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root],
+  get prefixDropRoots() { return [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root]; },
 };
 
 // Transcript reads only need the last line with a `cwd` field — a few dozen
@@ -55,7 +56,10 @@ const MAX_CWDS = 50;
 // fine: a project already in the list stays in the list) plus a short TTL
 // as the backstop for everything else. Same mtime-keyed idiom as
 // scheduler/prdParser.cjs's dirCache and queueHistory.cjs's historyCacheKey.
-const CACHE_TTL_MS = 30_000;
+// TTL sits above the 60 s dispatch-loop interval (scheduler POLL_INTERVAL_MS) so
+// one pass never re-scans cold. Cached arrays are frozen — shared, never mutated.
+const CACHE_TTL_MS = 120_000;
+const EMPTY_CWDS = Object.freeze([]);
 const cwdScanCache = new Map(); // key -> { dirMtimeMs, cachedAt, result }
 
 /** Forces the next activeProjectCwds/allProjectCwds call to rescan. */
@@ -79,93 +83,16 @@ function bustProjectCwdCache() {
 // signal survives instead of being silently lost.
 const OPS_DIRNAME = OPS_ROOT_DIR;
 
-// Bound on the ancestor walk in worktreeMainRootOf — well past any real
-// filesystem depth, purely to guarantee termination without relying on
-// reaching '/' (e.g. a symlink loop or an unusually deep path).
-const MAX_WORKTREE_WALK = 40;
-
-const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
-
-/**
- * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
- * linked `git worktree` (job/epic worktrees under os.tmpdir(), or a
- * user-made one anywhere). Walks UP from cwd looking for a `.git` entry:
- *   - `.git` is a FILE (linked worktree) whose first line is
- *     `gitdir: <main>/.git/worktrees/<name>` → returns <main>.
- *   - `.git` is a DIRECTORY (already the main tree) → returns that ancestor.
- *   - nothing found within MAX_WORKTREE_WALK levels → returns null.
- * Pure fs, synchronous, never throws — any unexpected shape (garbled file,
- * unreadable entry, gitdir path without the worktrees marker) yields null so
- * the caller leaves the cwd unchanged rather than guessing.
- */
-function worktreeMainRootOf(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < MAX_WORKTREE_WALK; i++) {
-    const gitPath = path.join(dir, '.git');
-    let stat;
-    try {
-      stat = fs.statSync(gitPath);
-    } catch {
-      stat = null;
-    }
-    if (stat) {
-      if (stat.isDirectory()) return dir;
-      if (stat.isFile()) {
-        let body;
-        try {
-          body = fs.readFileSync(gitPath, 'utf8');
-        } catch {
-          return null;
-        }
-        const firstLine = body.split('\n', 1)[0].trim();
-        const prefix = 'gitdir:';
-        if (!firstLine.startsWith(prefix)) return null;
-        const gitdir = firstLine.slice(prefix.length).trim();
-        const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
-        if (markerIdx <= 0) return null;
-        const candidateMain = gitdir.slice(0, markerIdx);
-        const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
-        // Round-trip verification: gitdir's content is a plain file that
-        // anything on disk could have written (e.g. a nested `.git` file
-        // tracked inside an untrusted repo), so it must not be trusted to
-        // redirect callers to an arbitrary attacker-chosen absolute path.
-        // A genuine linked worktree's admin dir back-references the exact
-        // `.git` FILE we are resolving via its own `gitdir` pointer file —
-        // require that round trip before accepting candidateMain.
-        if (!worktreeName) return null;
-        const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
-        let backRef;
-        try {
-          backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
-        } catch {
-          return null;
-        }
-        if (path.resolve(backRef) !== path.resolve(gitPath)) return null;
-        return candidateMain;
-      }
-      return null;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-  return null;
-}
-
 /**
  * projectRootOf(cwd) → the project root for a cwd that may sit inside an ops
  * tree and/or a linked git worktree. Returns cwd unchanged when neither
- * applies. Only the FIRST ops-dir occurrence matters — a nested stray ops
- * root is itself the bug, never a project. The ops-dir truncation runs
- * first, then the worktree resolution, so a cwd deep inside a worktree's OWN
- * ops tree still lands on the real project's main root.
+ * applies, or when the worktree cannot be proven (kind `unknown` — callers that
+ * WRITE must consult classifyCwd; this stays total so dispatch never breaks).
+ * The classification itself (outermost ops truncation, then worktree
+ * resolution) lives in cwdClassify.cjs.
  */
 function projectRootOf(cwd) {
-  const parts = cwd.split(path.sep);
-  const i = parts.indexOf(OPS_DIRNAME);
-  const truncated = i > 0 ? (parts.slice(0, i).join(path.sep) || path.sep) : cwd;
-  const mainRoot = worktreeMainRootOf(truncated);
-  return mainRoot || truncated;
+  return classifyCwd(cwd).projectRoot ?? cwd;
 }
 
 /**
@@ -221,7 +148,7 @@ function activeProjectCwds(maxAgeMin = 90, {
     // this key must not survive to be handed back once the dir later
     // appears — drop it rather than caching this empty result.
     cwdScanCache.delete(cacheKey);
-    return [];
+    return EMPTY_CWDS;
   }
   const cached = cwdScanCache.get(cacheKey);
   const now0 = Date.now();
@@ -241,14 +168,18 @@ function activeProjectCwds(maxAgeMin = 90, {
     // Normalize an ops-internal cwd up to its project root BEFORE any of the
     // checks below — the stray-ops-root incident (see OPS_DIRNAME above) got
     // through precisely because such a path is absolute and does exist.
-    const cwd = projectRootOf(rawCwd);
+    const classified = classifyCwd(rawCwd);
+    // `unknown` (a .git file we cannot resolve) is non-registrable: registering
+    // it would hand every consumer a project whose ops writes are refused.
+    if (classified.kind === 'unknown') return;
+    const cwd = classified.projectRoot;
     // Must be ABSOLUTE. A relative fragment would pass the statSync below
     // whenever it happens to resolve against THIS process's own cwd, and
     // every consumer (queueStore.projectStateDir, prdLocations) then joins
     // it into an ops-root path that lands somewhere arbitrary. Callers key
     // whole per-project state off these strings — a project is a cwd, and a
     // cwd is an absolute path.
-    if (!path.isAbsolute(cwd)) return;
+    if (!cwd || !path.isAbsolute(cwd)) return;
     // Drop-guard of last resort: a cwd that is (or sits inside) a known
     // worktree-scratch root after projectRootOf's normalization is one
     // worktreeMainRootOf could not resolve to a main tree — never a real
@@ -270,7 +201,7 @@ function activeProjectCwds(maxAgeMin = 90, {
 
   // Scan ~/.claude/projects/*/  transcript *.jsonl files.
   let slugs;
-  try { slugs = fs.readdirSync(projectsDir); } catch { cwdScanCache.delete(cacheKey); return result; }
+  try { slugs = fs.readdirSync(projectsDir); } catch { cwdScanCache.delete(cacheKey); return Object.freeze(result); }
 
   for (const slug of slugs) {
     if (result.length >= maxCwds) break;
@@ -305,6 +236,7 @@ function activeProjectCwds(maxAgeMin = 90, {
     }
   }
 
+  Object.freeze(result);
   cwdScanCache.set(cacheKey, { dirMtimeMs, cachedAt: now0, result });
   return result;
 }