claude-code-session-manager 0.86.0 → 0.88.0

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

@@ -0,0 +1,375 @@
+'use strict';
+
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/watchdog-helpers.test.cjs
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  heartbeatFresh,
+  evaluateDispatchLiveness,
+  readLastHeartbeat,
+  localDateStr,
+  maybeFinalizeHistory,
+  tryAcquireLock,
+  releaseLock,
+} = require('../watchdogHelpers.cjs');
+
+function tmpFile() {
+  return path.join(os.tmpdir(), `watchdog-test-${process.pid}-${Math.floor(Math.random() * 1e9)}.log`);
+}
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'watchdog-history-test-'));
+}
+
+function writeLines(p, lines) {
+  fs.writeFileSync(p, lines.join('\n') + '\n');
+}
+
+test('fresh ts (just now) → true', () => {
+  const p = tmpFile();
+  try {
+    writeLines(p, [JSON.stringify({ ts: Date.now(), counts: {}, paused: null })]);
+    assert.equal(heartbeatFresh(p, 180_000), true);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('stale ts (10 min old) → false', () => {
+  const p = tmpFile();
+  try {
+    const staleTs = Date.now() - 10 * 60 * 1000;
+    writeLines(p, [JSON.stringify({ ts: staleTs, counts: {}, paused: null })]);
+    assert.equal(heartbeatFresh(p, 180_000), false);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('missing file → false', () => {
+  const p = path.join(os.tmpdir(), 'watchdog-test-nonexistent-999999.log');
+  assert.equal(heartbeatFresh(p, 180_000), false);
+});
+
+test('garbage last line → false', () => {
+  const p = tmpFile();
+  try {
+    writeLines(p, ['not json at all!!!']);
+    assert.equal(heartbeatFresh(p, 180_000), false);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('last non-empty line wins (fresh after stale)', () => {
+  const p = tmpFile();
+  try {
+    const staleTs = Date.now() - 10 * 60 * 1000;
+    writeLines(p, [
+      JSON.stringify({ ts: staleTs }),
+      JSON.stringify({ ts: Date.now() }),
+    ]);
+    assert.equal(heartbeatFresh(p, 180_000), true);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('empty file → false', () => {
+  const p = tmpFile();
+  try {
+    fs.writeFileSync(p, '');
+    assert.equal(heartbeatFresh(p, 180_000), false);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('JSON line without ts field → false', () => {
+  const p = tmpFile();
+  try {
+    writeLines(p, [JSON.stringify({ counts: {}, paused: null })]);
+    assert.equal(heartbeatFresh(p, 180_000), false);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+// ── readLastHeartbeat ─────────────────────────────────────────────────────────
+
+test('readLastHeartbeat: returns full parsed object including pid', () => {
+  const p = tmpFile();
+  try {
+    const entry = { ts: Date.now(), pid: 12345, counts: {}, paused: null };
+    writeLines(p, [JSON.stringify(entry)]);
+    const result = readLastHeartbeat(p);
+    assert.equal(result.ts, entry.ts);
+    assert.equal(result.pid, 12345);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('readLastHeartbeat: returns null for missing file', () => {
+  const p = path.join(os.tmpdir(), 'watchdog-helpers-test-nonexistent-999999.log');
+  assert.equal(readLastHeartbeat(p), null);
+});
+
+test('readLastHeartbeat: returns null for empty file', () => {
+  const p = tmpFile();
+  try {
+    fs.writeFileSync(p, '');
+    assert.equal(readLastHeartbeat(p), null);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+test('readLastHeartbeat: returns object without pid for legacy entry', () => {
+  const p = tmpFile();
+  try {
+    const staleTs = Date.now() - 10 * 60 * 1000;
+    writeLines(p, [JSON.stringify({ ts: staleTs, counts: {}, paused: null })]);
+    const result = readLastHeartbeat(p);
+    assert.ok(result !== null);
+    assert.equal(result.ts, staleTs);
+    assert.equal(result.pid, undefined);
+  } finally {
+    try { fs.unlinkSync(p); } catch {}
+  }
+});
+
+// ── maybeFinalizeHistory: stamp gate ─────────────────────────────────────────
+
+test('maybeFinalizeHistory: same-day stamp → skip in O(1), finalizeFn never called', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    fs.writeFileSync(stampPath, localDateStr(), 'utf8');
+    let called = false;
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async () => { called = true; return { finalizedDates: [], partial: false }; },
+    });
+    assert.equal(called, false);
+    assert.equal(result.ran, false);
+    assert.equal(result.reason, 'already-finalized-today');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('maybeFinalizeHistory: new day (stale/missing stamp) → runs and stamps today', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    fs.writeFileSync(stampPath, '2000-01-01', 'utf8');
+    let called = false;
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async (opts) => { called = true; assert.equal(opts.budgetMs, 60_000); return { finalizedDates: ['2000-01-02'], partial: false }; },
+    });
+    assert.equal(called, true);
+    assert.equal(result.ran, true);
+    assert.equal(result.reason, 'finalized');
+    assert.equal(fs.readFileSync(stampPath, 'utf8').trim(), localDateStr());
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('maybeFinalizeHistory: missing stamp file → treated as new day, runs', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async () => ({ finalizedDates: [], partial: false }),
+    });
+    assert.equal(result.ran, true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── maybeFinalizeHistory: lock contention ────────────────────────────────────
+
+test('maybeFinalizeHistory: lock already held (fresh) by another caller → skip silently', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    // Simulate a concurrent holder (e.g. the in-app Electron boot pass).
+    assert.equal(tryAcquireLock(lockPath, 10 * 60 * 1000), true);
+    let called = false;
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async () => { called = true; return { finalizedDates: [], partial: false }; },
+    });
+    assert.equal(called, false);
+    assert.equal(result.ran, false);
+    assert.equal(result.reason, 'lock-contended');
+    // The other holder's lock must be untouched by the loser.
+    assert.equal(fs.existsSync(lockPath), true);
+  } finally {
+    releaseLock(path.join(dir, 'history-rollup.lock'));
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('maybeFinalizeHistory: stale lock (older than staleLockMs) is reclaimed and runs', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    fs.writeFileSync(lockPath, '99999', 'utf8');
+    const staleTime = new Date(Date.now() - 20 * 60 * 1000);
+    fs.utimesSync(lockPath, staleTime, staleTime);
+
+    let called = false;
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      staleLockMs: 10 * 60 * 1000,
+      finalizeFn: async () => { called = true; return { finalizedDates: [], partial: false }; },
+    });
+    assert.equal(called, true);
+    assert.equal(result.ran, true);
+    // Lock is released after the run.
+    assert.equal(fs.existsSync(lockPath), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('maybeFinalizeHistory: releases the lock even when finalizeFn throws', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    await assert.rejects(() => maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async () => { throw new Error('boom'); },
+    }));
+    assert.equal(fs.existsSync(lockPath), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── maybeFinalizeHistory: budget-partial ─────────────────────────────────────
+
+test('maybeFinalizeHistory: partial finalize (budget exceeded) does NOT stamp the day complete', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      finalizeFn: async () => ({ finalizedDates: [], partial: true }),
+    });
+    assert.equal(result.ran, true);
+    assert.equal(result.reason, 'partial');
+    assert.equal(fs.existsSync(stampPath), false);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ── maybeFinalizeHistory: dry run ────────────────────────────────────────────
+
+test('maybeFinalizeHistory: dryRun computes without stamping or requiring a write', async () => {
+  const dir = tmpDir();
+  try {
+    const stampPath = path.join(dir, 'history-rollup.stamp');
+    const lockPath = path.join(dir, 'history-rollup.lock');
+    let seenDryRun;
+    const result = await maybeFinalizeHistory({
+      stampPath,
+      lockPath,
+      dryRun: true,
+      finalizeFn: async (opts) => { seenDryRun = opts.dryRun; return { finalizedDates: ['2026-07-01'], partial: false }; },
+    });
+    assert.equal(seenDryRun, true);
+    assert.equal(result.ran, false);
+    assert.equal(result.reason, 'dry-run');
+    assert.deepEqual(result.finalizedDates, ['2026-07-01']);
+    assert.equal(fs.existsSync(stampPath), false);
+  } finally {
+    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

@@ -0,0 +1,266 @@
+'use strict';
+
+// Run: timeout 120 npx vitest run src/main/lib/__tests__/watchdog-relaunch.test.cjs
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  maybeRelaunchApp,
+  evaluateDispatchLiveness,
+  readLastHeartbeat,
+  readRelaunchState,
+  DEFAULT_MAX_RELAUNCH_ATTEMPTS,
+} = require('../watchdogHelpers.cjs');
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'watchdog-relaunch-test-'));
+}
+
+function writeHeartbeat(hbPath, tsMs, pid) {
+  fs.writeFileSync(hbPath, JSON.stringify({ ts: tsMs, pid }) + '\n');
+}
+
+function makeSpawnSpy() {
+  const calls = [];
+  const fn = (opts) => { calls.push(opts); };
+  fn.calls = calls;
+  return fn;
+}
+
+// heartbeatFresh() reads the real wall clock internally (no injectable `now`),
+// so every heartbeat ts below is anchored to actual Date.now() at test start —
+// only the `now` passed to maybeRelaunchApp (which drives debounce/cap math)
+// is offset from that same anchor.
+//
+// isPidAlive() treats EPERM (pid exists, owned by another user — e.g. pid 1)
+// as alive, so a genuinely-dead pid must actually be gone (ESRCH), not just
+// inaccessible. Spawn a short-lived same-user child and use its exited pid —
+// guaranteed ESRCH under our own uid, unlike a hardcoded low pid number.
+const DEAD_PID = (() => {
+  const result = spawnSync(process.execPath, ['-e', 'process.exit(0)']);
+  return result.pid;
+})();
+
+test('fresh heartbeat → no relaunch, no spawn', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const now = Date.now();
+    writeHeartbeat(hbPath, now - 1_000, DEAD_PID); // 1s old — fresh
+    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 });
+  }
+});
+
+test('stale heartbeat + dead pid → relaunch fires', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const now = Date.now();
+    writeHeartbeat(hbPath, now - 10 * 60_000, DEAD_PID);
+    const spawnFn = makeSpawnSpy();
+
+    const result = maybeRelaunchApp({
+      heartbeatPath: hbPath,
+      maxAgeMs: 180_000,
+      statePath,
+      debounceMs: 90_000,
+      now,
+      spawnFn,
+    });
+
+    assert.equal(result.relaunched, true);
+    assert.equal(result.attemptCount, 1);
+    assert.equal(spawnFn.calls.length, 1);
+
+    const state = readRelaunchState(statePath);
+    assert.equal(state.attemptCount, 1);
+    assert.equal(state.lastAttemptTs, now);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('stale heartbeat but debounce window not elapsed → no relaunch', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const now = Date.now();
+    writeHeartbeat(hbPath, now - 10 * 60_000, DEAD_PID);
+
+    // First tick: relaunch fires.
+    const spawnFn1 = makeSpawnSpy();
+    const first = maybeRelaunchApp({
+      heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, debounceMs: 90_000, now, spawnFn: spawnFn1,
+    });
+    assert.equal(first.relaunched, true);
+
+    // Second tick 30s later — inside the 90s debounce window.
+    const spawnFn2 = makeSpawnSpy();
+    const second = maybeRelaunchApp({
+      heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, debounceMs: 90_000, now: now + 30_000, spawnFn: spawnFn2,
+    });
+
+    assert.equal(second.relaunched, false);
+    assert.equal(second.reason, 'debounce');
+    assert.equal(spawnFn2.calls.length, 0);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('3 failed attempts → stops attempting and logs, no 4th attempt', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const logPath = path.join(dir, 'relaunch.log');
+    let now = Date.now();
+    writeHeartbeat(hbPath, now - 10 * 60_000, DEAD_PID); // stays stale/dead throughout
+
+    let lastResult;
+    for (let i = 0; i < DEFAULT_MAX_RELAUNCH_ATTEMPTS; i++) {
+      const spawnFn = makeSpawnSpy();
+      lastResult = maybeRelaunchApp({
+        heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, logPath, debounceMs: 90_000, now, spawnFn,
+      });
+      assert.equal(lastResult.relaunched, true, `attempt ${i + 1} should relaunch`);
+      assert.equal(spawnFn.calls.length, 1);
+      now += 100_000; // past the 90s debounce for the next tick
+    }
+
+    // 4th tick: capped — must NOT spawn again.
+    const spawnFn4 = makeSpawnSpy();
+    const fourth = maybeRelaunchApp({
+      heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, logPath, debounceMs: 90_000, now, spawnFn: spawnFn4,
+    });
+
+    assert.equal(fourth.relaunched, false);
+    assert.equal(fourth.reason, 'capped');
+    assert.equal(spawnFn4.calls.length, 0);
+    assert.equal(fourth.attemptCount, DEFAULT_MAX_RELAUNCH_ATTEMPTS);
+
+    const logContent = fs.readFileSync(logPath, 'utf8');
+    assert.match(logContent, /giving up/i);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('attemptCount resets to 0 once a fresh heartbeat is observed', () => {
+  const dir = tmpDir();
+  try {
+    const hbPath = path.join(dir, 'heartbeat.log');
+    const statePath = path.join(dir, 'state.json');
+    const now = Date.now();
+    writeHeartbeat(hbPath, now - 10 * 60_000, DEAD_PID);
+
+    const spawnFn = makeSpawnSpy();
+    maybeRelaunchApp({ heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, debounceMs: 90_000, now, spawnFn });
+    assert.equal(readRelaunchState(statePath).attemptCount, 1);
+
+    // App comes back up — fresh heartbeat observed on a later tick, recorded
+    // with this test process's own (guaranteed-alive) pid.
+    const later = now + 200_000;
+    writeHeartbeat(hbPath, later - 1_000, process.pid);
+    const result = maybeRelaunchApp({
+      heartbeatPath: hbPath, maxAgeMs: 180_000, statePath, debounceMs: 90_000, now: later, spawnFn,
+    });
+
+    assert.equal(result.relaunched, false);
+    assert.equal(result.reason, 'alive');
+    assert.equal(readRelaunchState(statePath).attemptCount, 0);
+  } finally {
+    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