claude-code-session-manager 0.87.0 → 0.88.0

package/src/main/health.cjs

@@ -11,14 +11,18 @@ const os = require('node:os');
 const { execFileSync } = require('node:child_process');
 const { POLL_INTERVAL_MS, loadGateThreshold } = require('./lib/schedulerConfig.cjs');
 const { opsPath } = require('./lib/opsOwnership.cjs');
+const { effectivePaused } = require('./lib/upgradeDrain.cjs');
 const { checkPersonaImports } = require('./lib/personaImportHealth.cjs');
 const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
 const { resolvePrdsDirs } = require('./lib/prdLocations.cjs');
 const { migratePrds } = require('./lib/prdMigration.cjs');
 const queueStore = require('./lib/queueStore.cjs');
-const { computeStallSummary, SCHEDULER_STATE_PATH, FAILURE_STREAK_WARN_THRESHOLD, classifyQueueStarvation, STARVE_ESCALATION_MS } = require('./scheduler.cjs');
-const { findStarvedProjects } = require('./lib/schedulerBatch.cjs');
-const { AUDIT_LOG_PATH } = require('./lib/auditLog.cjs');
+const schedulerPaths = require('./lib/schedulerPaths.cjs');
+const { evaluateDispatchLiveness } = require('./lib/watchdogHelpers.cjs');
+const { computeStallSummary, computeDepHistorySatisfaction, FAILURE_STREAK_ESCALATION_MS, classifyQueueStarvation, launchBlockedSlugs, STARVE_ESCALATION_MS, REVERIFY_INTERVAL_MS } = require('./scheduler.cjs');
+const { findStarvedProjects, findUnresolvableDepRoots, DEFAULT_PROJECT_CWD, DEP_HISTORY_FAIL_OPEN } = require('./lib/schedulerBatch.cjs');
+const { auditLogPath, readTail } = require('./lib/auditLog.cjs');
+const { resolveBuildIdentity } = require('./lib/buildIdentity.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 const { allProjectCwds } = require('./lib/activeSessions.cjs');
 
@@ -40,6 +44,7 @@ const TICK_STALL_THRESHOLD_MS = TICK_STALL_MULTIPLIER * POLL_INTERVAL_MS;
 // scheduler-heartbeat.log is only appended to while Electron is running, so
 // a stale line here is silent-on-purpose, not evidence of anything.
 const HEARTBEAT_STALE_MS = 5 * 60_000;
+const AUDIT_TAIL_BYTES = 1024 * 1024;
 
 function runCheck(cmd, cwd = PROJECT_ROOT) {
   try {
@@ -72,6 +77,7 @@ function readFreshHeartbeat(heartbeatPath) {
   } catch {
     return null;
   }
+  if (entry.degraded === true) return null; // a subsystem threw — utilization was not read
   if (typeof entry.ts !== 'number' || Date.now() - entry.ts > HEARTBEAT_STALE_MS) return null;
   return entry;
 }
@@ -92,7 +98,7 @@ function evaluateTickLiveness(queueState, heartbeat, now, runningCount) {
     ?? (() => { try { return require('./lib/sessionSlots.cjs').totalSlots(); } catch { return Infinity; } })();
 
   if (pending.length === 0) return { stalled: false, reason: 'no-pending-jobs' };
-  if (queueState.paused) return { stalled: false, reason: 'paused' };
+  if (effectivePaused(queueState)) return { stalled: false, reason: queueState.paused ? 'paused' : 'draining' };
   if (config.enabled === false) return { stalled: false, reason: 'disabled' };
   if (running >= concurrencyCap) return { stalled: false, reason: 'at-capacity' };
   // 'manual' means the operator fires batches by hand — the scheduler is not
@@ -375,27 +381,50 @@ function evaluateEpicIndexHealth(cwds) {
 // not a failure, matches evaluatePrdMigrationHealth's fail-open-on-absence
 // spirit. Kept separate from the fs-touching check() call site, same pattern
 // as every other evaluate* helper in this file.
-function evaluateUsagePollerHealth(state, threshold = FAILURE_STREAK_WARN_THRESHOLD) {
+//
+// Ladder is driven by the shared usageCircuit's OWN open/closed state and
+// how long it's been open (usageCircuitState/usageCircuitOpenedAt, persisted
+// by scheduler.cjs's persistSchedulerState — this process never holds the
+// live in-memory circuit itself) — not a binary consecutiveFailures<5 check,
+// which used to read GREEN right up until the exact failure that also fired
+// the one-time WARN, then stayed flatly non-GREEN forever after with no way
+// to tell "just tripped" from "down for hours" apart:
+//   GREEN  — circuit closed (or half_open probing after a fresh backoff).
+//   YELLOW — circuit open, less than FAILURE_STREAK_ESCALATION_MS (30 min).
+//            Still `ok: true` — the circuit's OWN open threshold (3
+//            consecutive failures, usageCircuit.cjs) is lower than the old
+//            5-failure WARN, so treating YELLOW as `ok: false` here would
+//            silently tighten the overall `npm run health` rollup's failure
+//            bar from 5 down to 3. Graceful degradation (the whole point of
+//            the breaker) should not itself read as a critical failure.
+//   RED    — circuit open for FAILURE_STREAK_ESCALATION_MS or longer —
+//            `ok: false`, matching the same 30-minute threshold the
+//            escalation ladder (warnFailureStreakIfNeeded) re-alerts on.
+function evaluateUsagePollerHealth(state, redThresholdMs = FAILURE_STREAK_ESCALATION_MS) {
   if (!state || typeof state !== 'object') return { ok: true, applicable: false };
   const consecutiveFailures = typeof state.consecutiveFailures === 'number' ? state.consecutiveFailures : 0;
   const backoffMs = typeof state.backoffMs === 'number' ? state.backoffMs : null;
   const lastPollAt = typeof state.lastPollAt === 'number' ? state.lastPollAt : null;
-  // Trips at the SAME count as scheduler.cjs's shouldWarnFailureStreak
-  // (`consecutiveFailures >= threshold`) — the WARN and this non-GREEN must
-  // fire together, not one failure apart, or an operator sees the log line
-  // while the health dashboard still reads green.
-  const ok = consecutiveFailures < threshold;
+  const circuitState = typeof state.usageCircuitState === 'string' ? state.usageCircuitState : 'closed';
+  const openedAt = typeof state.usageCircuitOpenedAt === 'number' ? state.usageCircuitOpenedAt : null;
+
+  if (circuitState !== 'open' && circuitState !== 'half_open') {
+    return { ok: true, applicable: true, color: 'GREEN', consecutiveFailures, backoffMs, lastPollAt };
+  }
+
+  const openMs = openedAt ? Math.max(0, Date.now() - openedAt) : 0;
+  const color = openMs >= redThresholdMs ? 'RED' : 'YELLOW';
   return {
-    ok,
+    ok: color !== 'RED',
     applicable: true,
+    color,
     consecutiveFailures,
     backoffMs,
     lastPollAt,
-    threshold,
-    ...(ok ? {} : {
-      message: `usage/rate-limit poller has ${consecutiveFailures} consecutive failures `
-        + `(threshold ${threshold}), backoffMs=${backoffMs} — see logs scope=scheduler`,
-    }),
+    openedAt,
+    openMs,
+    message: `usage/rate-limit poller circuit is ${circuitState}, open for ${Math.round(openMs / 60_000)}m (${color}) — `
+      + `${consecutiveFailures} consecutive failures, backoffMs=${backoffMs} — see logs scope=scheduler`,
   };
 }
 
@@ -416,6 +445,10 @@ function evaluateUsagePollerHealth(state, threshold = FAILURE_STREAK_WARN_THRESH
 // OWN forcing threshold; this is the "even the watchdog isn't helping
 // anymore" signal a human needs to see.
 const DISPATCH_STALL_THRESHOLD_MS = 2 * 60 * 60_000;
+// Early-warning tier off the SAME launch-keyed clock (lastRunAt — a batch
+// actually launched): still ok:true, but flagged so a slow leak surfaces
+// well before the 2-hour cold-report threshold.
+const DISPATCH_WARN_THRESHOLD_MS = 15 * 60_000;
 
 /**
  * evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs) →
@@ -430,14 +463,18 @@ const DISPATCH_STALL_THRESHOLD_MS = 2 * 60 * 60_000;
  * `blocked` verdict therefore stays `ok: true` (never trips the health gate)
  * but is still reported by name so it isn't silently invisible either.
  */
-function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs = DISPATCH_STALL_THRESHOLD_MS) {
+function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs = DISPATCH_STALL_THRESHOLD_MS, warnMs = DISPATCH_WARN_THRESHOLD_MS) {
+  // Clock = lastRunAt (launches), never lastDispatchAttemptAt (loop-alive
+  // heartbeat, refreshed by ticks that launch nothing). Cold process: no
+  // in-memory pause/boot stamps to fold in. Breaker-held rows count blocked.
   const verdict = classifyQueueStarvation({
     jobs: queueState?.jobs,
-    paused: queueState?.paused,
+    paused: effectivePaused(queueState),
     runningCount,
-    lastRunAtMs: Date.parse(queueState?.lastDispatchAttemptAt ?? ''),
+    lastRunAtMs: Date.parse(queueState?.lastRunAt ?? ''),
+    heldSlugs: launchBlockedSlugs(queueState?.jobs, queueState?.launchBlocks),
     now,
-    thresholdMs,
+    thresholdMs: Math.min(warnMs, thresholdMs),
   });
   if (!verdict) return { ok: true };
   if (verdict.kind === 'blocked') {
@@ -445,18 +482,79 @@ function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs
       ok: true,
       blocked: true,
       pending: verdict.pending,
-      message: `${verdict.pending} pending job(s) behind a blocked dependsOn chain — dispatch cannot help, needs a human`,
+      message: `${verdict.pending} pending job(s) behind a blocked dependsOn chain or open launch breaker — dispatch cannot help, needs a human`,
     };
   }
   const ageMin = Math.round(verdict.idleMs / 60_000);
+  const critical = verdict.idleMs >= thresholdMs;
   return {
-    ok: false,
-    starved: true,
+    ok: !critical,
+    ...(critical ? { starved: true } : { warn: true }),
     pending: verdict.pending,
     dispatchable: verdict.dispatchable,
     idleMs: verdict.idleMs,
-    message: `${verdict.dispatchable} dispatchable pending job(s), 0 running, no dispatch attempt in ~${ageMin}m `
-      + `(threshold ${Math.round(thresholdMs / 60_000)}m) — dispatch appears stuck`,
+    message: `${verdict.dispatchable} dispatchable pending job(s), 0 running, no launch in ~${ageMin}m `
+      + (critical
+        ? `(threshold ${Math.round(thresholdMs / 60_000)}m) — dispatch appears stuck`
+        : `(warn at ${Math.round(warnMs / 60_000)}m, fail at ${Math.round(thresholdMs / 60_000)}m) — dispatch may be stalling`),
+  };
+}
+
+/**
+ * evaluateUnresolvableDepHealth(jobs, satisfiedSlugsByCwd) →
+ *   { ok, projects?: [{ cwd, roots, pending }], message? }
+ *
+ * Pure. A project whose EVERY pending row is held (directly or transitively)
+ * behind a dependsOn slug that names no live row and no history/archive
+ * record is fully blocked with a healthy engine — the 2026-09-18 fo-01 stall
+ * (21 pending rows, 0 running, one archived root, every other component
+ * GREEN). classifyQueueStarvation's 'blocked' kind cannot see this shape (it
+ * only walks failed/skipped ROWS), and evaluateQueueDispatchHealth keeps
+ * 'blocked' ok:true by design, so this is the component that fails it, naming
+ * the root slug(s). Reuses the picker's own resolver (findUnresolvableDepRoots)
+ * so health can never disagree with what dispatch actually holds. A project
+ * with anything running, or any dispatchable pending row, is not fully blocked.
+ * O(jobs + deps) per project; a fail-open project (history unreadable) is skipped.
+ */
+function evaluateUnresolvableDepHealth(jobs, satisfiedSlugsByCwd) {
+  const byCwd = new Map();
+  for (const j of Array.isArray(jobs) ? jobs : []) {
+    if (!j) continue;
+    const cwd = j.cwd || DEFAULT_PROJECT_CWD;
+    if (!byCwd.has(cwd)) byCwd.set(cwd, []);
+    byCwd.get(cwd).push(j);
+  }
+  const projects = [];
+  for (const [cwd, rows] of byCwd) {
+    const satisfied = satisfiedSlugsByCwd?.get?.(cwd) ?? new Set();
+    if (satisfied === DEP_HISTORY_FAIL_OPEN) continue;
+    const pending = rows.filter((j) => j.status === 'pending');
+    if (pending.length === 0 || rows.some((j) => j.status === 'running')) continue;
+    const roots = findUnresolvableDepRoots(rows, satisfied);
+    if (roots.length === 0) continue;
+    const rootSet = new Set(roots);
+    const bare = (x) => String(x ?? '').replace(/^\d+-/, '');
+    const held = new Set();
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const j of pending) {
+        if (held.has(j.slug)) continue;
+        const isHeld = (j.dependsOn ?? []).some((d) => rootSet.has(d)
+          || pending.some((p) => held.has(p.slug) && (p.slug === d || bare(p.slug) === bare(d))));
+        if (isHeld) { held.add(j.slug); grew = true; }
+      }
+    }
+    if (held.size === pending.length) projects.push({ cwd, roots, pending: pending.length });
+  }
+  if (projects.length === 0) return { ok: true };
+  return {
+    ok: false,
+    projects,
+    message: projects
+      .map((p) => `${p.cwd}: all ${p.pending} pending job(s) held behind unresolvable dependsOn root ${p.roots.join(', ')} `
+        + '(no live row, no history/archive record) — restore its completion record or fix the dependsOn')
+      .join('; '),
   };
 }
 
@@ -472,12 +570,9 @@ function evaluateQueueDispatchHealth(queueState, runningCount, now, thresholdMs
  * Missing/unreadable log → {} (no reasons known yet), never a throw.
  */
 function latestStarveEscalationReasons(auditLogPath) {
-  let lines;
-  try {
-    lines = fs.readFileSync(auditLogPath, 'utf8').split('\n').filter(Boolean);
-  } catch {
-    return {};
-  }
+  // Bounded reverse tail — the log is never rotated (28 MB+), and the latest
+  // escalation per cwd is by definition recent.
+  const lines = readTail(AUDIT_TAIL_BYTES, auditLogPath);
   const byCwd = {};
   for (const line of lines) {
     let rec;
@@ -491,6 +586,24 @@ function latestStarveEscalationReasons(auditLogPath) {
   return byCwd;
 }
 
+/**
+ * evaluateBuildFreshness({running, installedOnDisk, repoHead}) → component
+ *
+ * Pure; each input is a short git sha or null. restartNeeded: the on-disk
+ * install differs from what the live heartbeat says is running. publishNeeded:
+ * repo HEAD differs from the installed build. Both are reported, neither is
+ * critical (never flips status.ok).
+ */
+function evaluateBuildFreshness({ running = null, installedOnDisk = null, repoHead = null } = {}) {
+  const differs = (a, b) => !!a && !!b && !(a.startsWith(b) || b.startsWith(a));
+  const restartNeeded = differs(running, installedOnDisk);
+  const publishNeeded = differs(repoHead, installedOnDisk);
+  const notes = [];
+  if (restartNeeded) notes.push(`restart needed: running ${running}, installed ${installedOnDisk}`);
+  if (publishNeeded) notes.push(`publish needed: repo HEAD ${repoHead}, installed ${installedOnDisk}`);
+  return { ok: true, running, installedOnDisk, repoHead, restartNeeded, publishNeeded, ...(notes.length ? { note: notes.join('; ') } : {}) };
+}
+
 /**
  * evaluateStarveEscalationHealth(jobs, now, thresholdMs, escalationReasons)
  *   → { ok, projects?, message? }
@@ -532,6 +645,69 @@ function loadUsagePollerState(statePath) {
   }
 }
 
+/**
+ * evaluateBlockingParkHealth(jobs, now, thresholdMs = REVERIFY_INTERVAL_MS) →
+ *   { ok, parks?: [{ cwd, slug, verdict, ageMs, dependents }], message? }
+ *
+ * Pure. A `needs_review` row parked longer than one full periodic-reverify
+ * interval that STILL holds >= 1 pending dependent (transitively, through
+ * pending rows, via dependsOn — exact or bare slug, same matching as the
+ * picker) is a silently-blocking park: the self-heal ladder had a full pass
+ * and did not release it. 2026-09-18: 1229-fo-03 held 19 of 20 pending rows
+ * while every other component read GREEN. Parked-since is the row's last
+ * `to: needs_review` statusHistory entry (fallback finishedAt); a row with no
+ * recoverable timestamp is skipped rather than guessed at. O(jobs + deps).
+ */
+function evaluateBlockingParkHealth(jobs, now, thresholdMs = REVERIFY_INTERVAL_MS) {
+  const rows = (Array.isArray(jobs) ? jobs : []).filter(Boolean);
+  const bare = (x) => String(x ?? '').replace(/^\d+-/, '');
+  const byCwd = new Map();
+  for (const j of rows) {
+    const cwd = j.cwd || DEFAULT_PROJECT_CWD;
+    if (!byCwd.has(cwd)) byCwd.set(cwd, []);
+    byCwd.get(cwd).push(j);
+  }
+  const parks = [];
+  for (const [cwd, group] of byCwd) {
+    const pending = group.filter((j) => j.status === 'pending');
+    if (pending.length === 0) continue;
+    for (const park of group) {
+      if (park.status !== 'needs_review') continue;
+      const history = Array.isArray(park.statusHistory) ? park.statusHistory : [];
+      let at = null;
+      for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i]?.to === 'needs_review') { at = history[i].at; break; }
+      }
+      const since = Date.parse(at ?? park.finishedAt ?? '');
+      if (Number.isNaN(since) || now - since <= thresholdMs) continue;
+      const held = new Set();
+      const heldBy = (d, root) => root.slug === d || bare(root.slug) === bare(d);
+      let grew = true;
+      while (grew) {
+        grew = false;
+        for (const j of pending) {
+          if (held.has(j.slug)) continue;
+          if ((j.dependsOn ?? []).some((d) => heldBy(d, park) || pending.some((p) => held.has(p.slug) && heldBy(d, p)))) {
+            held.add(j.slug);
+            grew = true;
+          }
+        }
+      }
+      if (held.size > 0) parks.push({ cwd, slug: park.slug, verdict: park.verifierVerdict ?? null, ageMs: now - since, dependents: held.size });
+    }
+  }
+  if (parks.length === 0) return { ok: true };
+  return {
+    ok: false,
+    parks,
+    message: parks
+      .map((p) => `${p.slug} (${p.cwd}) parked needs_review${p.verdict ? `/${p.verdict}` : ''} for ${Math.round(p.ageMs / 60_000)}m `
+        + `(> one ${Math.round(REVERIFY_INTERVAL_MS / 60_000)}m reverify interval) is blocking ${p.dependents} pending dependent(s) — `
+        + 'the self-heal ladder did not release it; resolve it or scheduler_reset_job')
+      .join('; '),
+  };
+}
+
 async function check() {
   const start = Date.now();
   const status = {
@@ -577,7 +753,7 @@ async function check() {
   };
 
   // 2. Check config directory exists and is writable.
-  const configDir = path.join(os.homedir(), '.claude');
+  const configDir = schedulerPaths.claudeHome();
   try {
     await fsp.access(configDir, fs.constants.R_OK | fs.constants.W_OK);
     const stat = await fsp.stat(configDir);
@@ -599,11 +775,14 @@ async function check() {
   // 3. Check scheduler state (federated, 2026-07-31): machine runtime file +
   // per-project job shards merged via queueStore — the retired global
   // queue.json is no longer consulted.
-  const queuePath = queueStore.MACHINE_STATE_PATH;
+  const queuePath = schedulerPaths.machineStatePath();
   let queueState = null;
   try {
     queueState = queueStore.readMergedSync();
     if (queueState.unreadable) throw new Error(queueState.unreadable);
+    for (const u of queueState.unreadableCwds ?? []) {
+      status.issues.push(`Scheduler queue shard quarantined for ${u.cwd}: ${u.error} — that project is skipped until it reads clean`);
+    }
     // A torn scheduler-machine.json is now recovered rather than halting
     // dispatch (queueStore.cjs's findLongestValidJsonPrefix) — but recovery
     // happening at all means the file failed to parse moments ago, which is
@@ -626,11 +805,7 @@ async function check() {
     const quarantinedCount = Object.values(queueState.jobs || {}).filter(
       (j) => j.status === 'quarantined'
     ).length;
-    const heartbeatPath = path.join(
-      os.homedir(),
-      '.claude/session-manager/scheduler-heartbeat.log'
-    );
-    const heartbeat = readFreshHeartbeat(heartbeatPath);
+    const heartbeat = readFreshHeartbeat(schedulerPaths.heartbeatPath());
     const liveness = evaluateTickLiveness(queueState, heartbeat, Date.now(), runningCount);
 
     // Per-project rollup (PRD: monitoring must not collapse per-project
@@ -647,10 +822,13 @@ async function check() {
       .map(([cwd]) => cwd);
 
     status.components.scheduler_queue = {
-      ok: !liveness.stalled && projectsPastThreshold.length === 0 && !queueState.machineStateRecovered,
+      ok: !liveness.stalled && projectsPastThreshold.length === 0 && !queueState.machineStateRecovered
+        && (queueState.unreadableCwds ?? []).length === 0,
       path: queuePath,
       jobs: Object.keys(queueState.jobs || {}).length,
       running: runningCount,
+      // Deliberate restart drain (lib/upgradeDrain.cjs) — reported so it is never read as a stall.
+      drain: queueState.drain?.active ? { since: queueState.drain.since ?? null, requestedAt: queueState.drain.requestedAt ?? null } : null,
       failed: failedCount,
       needsReview: needsReviewCount,
       quarantined: quarantinedCount,
@@ -658,6 +836,7 @@ async function check() {
       perProjectStall,
       tickLiveness: liveness.reason,
       machineStateRecovered: queueState.machineStateRecovered ?? false,
+      quarantinedCwds: (queueState.unreadableCwds ?? []).map((u) => u.cwd),
       machineStateRecoveryMode: queueState.machineStateRecoveryMode ?? null,
       // Informational only (PRD 1085): current 1-min loadavg per core vs the
       // launch-gate threshold, so a "nothing is launching" report can be
@@ -694,10 +873,31 @@ async function check() {
         );
       }
     }
+    // Same classification the external watchdog logs (observability only).
+    const dispatchLiveness = evaluateDispatchLiveness(heartbeat, now);
+    status.components.scheduler_queue.dispatchLiveness = dispatchLiveness;
+    if (dispatchLiveness.dead) {
+      status.issues.push('Scheduler dispatch appears dead: heartbeat is fresh but nothing has launched in 30m+ with dispatchable work pending and nothing running');
+    }
     status.components.queue_dispatch = evaluateQueueDispatchHealth(queueState, runningCount, now);
     if (!status.components.queue_dispatch.ok || status.components.queue_dispatch.blocked) {
       status.issues.push(`Queue dispatch: ${status.components.queue_dispatch.message}`);
     }
+    try {
+      status.components.queue_dep_roots = evaluateUnresolvableDepHealth(
+        queueState.jobs, await computeDepHistorySatisfaction(queueState),
+      );
+    } catch (e) {
+      status.components.queue_dep_roots = { ok: true, error: `dep-root check failed: ${e?.message}` };
+    }
+    if (!status.components.queue_dep_roots.ok) {
+      status.issues.push(`Queue dependsOn: ${status.components.queue_dep_roots.message}`);
+    }
+
+    status.components.blocking_parks = evaluateBlockingParkHealth(queueState.jobs, now);
+    if (!status.components.blocking_parks.ok) {
+      status.issues.push(`Blocking park: ${status.components.blocking_parks.message}`);
+    }
 
     // Per-project starve escalation (bounded consequence for project_starved
     // — see runStarveEscalationSweep in scheduler.cjs). Distinct from
@@ -705,7 +905,7 @@ async function check() {
     // "has any ONE project been starved past the LATER escalation threshold",
     // the exact condition the 2026-09-12 19h Bilko starve went unreported by.
     status.components.project_starve_escalation = evaluateStarveEscalationHealth(
-      queueState.jobs, now, STARVE_ESCALATION_MS, latestStarveEscalationReasons(AUDIT_LOG_PATH),
+      queueState.jobs, now, STARVE_ESCALATION_MS, latestStarveEscalationReasons(auditLogPath()),
     );
     if (!status.components.project_starve_escalation.ok) {
       status.issues.push(status.components.project_starve_escalation.message);
@@ -746,7 +946,7 @@ async function check() {
   // failure. A CORRUPT file (the torn-write class fixed for the sibling
   // scheduler-machine.json in f56bdc0) is NOT the same as missing — surfaced
   // as non-GREEN rather than fail-open, via loadUsagePollerState below.
-  const loaded = loadUsagePollerState(SCHEDULER_STATE_PATH);
+  const loaded = loadUsagePollerState(schedulerPaths.schedulerStatePath());
   if (loaded.missing) {
     status.components.usage_poller = { ok: true, applicable: false };
   } else if (loaded.errorMessage) {
@@ -790,10 +990,7 @@ async function check() {
   // of a stale installed build vs. the git repo — it fires regardless of
   // *why* the build is stale (the 2026-07-31 burrow-project ENOENT + the
   // 223-file/189-resurrected-job incident both trace back to this).
-  const legacyPrdsDir = path.join(
-    os.homedir(),
-    '.claude/session-manager/scheduled-plans/prds'
-  );
+  const legacyPrdsDir = schedulerPaths.prdsRoot();
   try {
     const migrationResult = await migratePrds(legacyPrdsDir);
     status.components.prd_migration = evaluatePrdMigrationHealth(migrationResult, legacyPrdsDir);
@@ -809,7 +1006,7 @@ async function check() {
   }
 
   // 5. Check transcripts directory (where live session logs are tailed).
-  const projectsDir = path.join(os.homedir(), '.claude/projects');
+  const projectsDir = schedulerPaths.claudeProjectsDir();
   try {
     await fsp.access(projectsDir, fs.constants.R_OK);
     status.components.transcripts_dir = {
@@ -826,10 +1023,7 @@ async function check() {
   }
 
   // 6. Check session-manager's own logs (informational, not blocking).
-  const smLogsDir = path.join(
-    os.homedir(),
-    '.claude/session-manager/logs'
-  );
+  const smLogsDir = schedulerPaths.watchdogLogsDir();
   let logAge = null;
   try {
     const files = await fsp.readdir(smLogsDir);
@@ -944,11 +1138,29 @@ async function check() {
     status.issues.push(`Epic index health check failed: ${e.message}`);
   }
 
+  // 6.7. Build freshness (informational): running heartbeat vs installed
+  // build-info vs repo HEAD.
+  try {
+    let repoHead = null;
+    try {
+      repoHead = execFileSync('git', ['-C', PROJECT_ROOT, 'rev-parse', '--short', 'HEAD'], {
+        timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim() || null;
+    } catch { /* not a git checkout */ }
+    status.components.build = evaluateBuildFreshness({
+      running: readFreshHeartbeat(schedulerPaths.heartbeatPath())?.build?.codeSha ?? null,
+      installedOnDisk: resolveBuildIdentity().codeSha ?? null,
+      repoHead,
+    });
+  } catch (e) {
+    status.components.build = { ok: true, error: e.message };
+  }
+
   // 7. Summary scoring: ok if all critical components pass.
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'queue_dispatch', 'project_starve_escalation', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'queue_dispatch', 'queue_dep_roots', 'blocking_parks', 'project_starve_escalation', 'usage_poller', 'prd_migration', 'claude_md_budget', 'delegation_chain'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -980,9 +1192,13 @@ module.exports = {
   evaluateUsagePollerHealth,
   loadUsagePollerState,
   evaluateQueueDispatchHealth,
+  evaluateUnresolvableDepHealth,
+  evaluateBlockingParkHealth,
   evaluateStarveEscalationHealth,
+  evaluateBuildFreshness,
   latestStarveEscalationReasons,
   DISPATCH_STALL_THRESHOLD_MS,
+  DISPATCH_WARN_THRESHOLD_MS,
   TICK_STALL_THRESHOLD_MS,
   HEARTBEAT_STALE_MS,
 };

package/src/main/heapSnapshot.cjs

@@ -23,8 +23,8 @@
 'use strict';
 
 const path = require('node:path');
-const os = require('node:os');
 const fsp = require('node:fs/promises');
+const { heapSnapshotDir } = require('./lib/schedulerPaths.cjs');
 
 const CHANNEL = 'diagnostics:heap-snapshot';
 const DEFAULT_TIMEOUT_MS = 3 * 60 * 1000; // 3 min — snapshots can be multi-hundred-MB
@@ -34,7 +34,7 @@ function isEnabled() {
 }
 
 function snapshotDir() {
-  return path.join(os.homedir(), '.claude', 'session-manager');
+  return heapSnapshotDir();
 }
 
 function timestampedFilename(now = new Date()) {

package/src/main/historyAggregator.cjs

@@ -643,7 +643,7 @@ function resetIntradayRegistryForTests() {
 /**
  * Pure walk-and-parse step (no rollup write) — split out from
  * refreshIntradayToday() so it can be benchmarked read-only against the real
- * ~/.claude/projects (see scripts/bench-intraday-walk.cjs) without touching
+ * ~/.claude/projects without touching
  * the rollup file on disk.
  */
 async function computeIntradayBuckets() {