claude-rpc 0.5.0 → 0.6.1

package/src/cli.js

@@ -8,7 +8,7 @@ import process from 'node:process';
 // code page on Win10 is 437/850, which displays many of our chars as `?`.
 // Hook events (no TTY) skip this — they don't print anything user-visible.
 if (process.platform === 'win32' && process.stdout.isTTY) {
-  try { spawnSync('chcp.com', ['65001'], { stdio: 'ignore', windowsHide: true }); } catch {}
+  try { spawnSync('chcp.com', ['65001'], { stdio: 'ignore', windowsHide: true }); } catch { /* chcp absent (Wine, custom shell) — accept whatever code page is set */ }
 }
 import { DAEMON_SCRIPT, PID_PATH, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, EXE_PATH, CANONICAL_EXE } from './paths.js';
 import { readState } from './state.js';
@@ -21,6 +21,9 @@ import { generateInsights } from './insights.js';
 import { badgeSvg } from './badge.js';
 import { fmtCost } from './pricing.js';
 import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
+import { loadConfig, hasUserConfig } from './config.js';
+import { VERSION } from './version.js';
+import { fail, EX_USER_ERROR, EX_BAD_STATE } from './ui.js';
 import { basename } from 'node:path';
 
 const cmd = process.argv[2];
@@ -246,7 +249,7 @@ function bar(val, max, width = 22) {
 function showStatus() {
   const state = readState();
   const aggregate = readAggregate();
-  const config = readJson(CONFIG_PATH, {});
+  const config = loadConfig();
   const live = findLiveSessions({ thresholdMs: 90_000 });
   state.liveSessions = live;
   const vars = buildVars(state, config, aggregate);
@@ -430,7 +433,7 @@ function showStatus() {
 function showToday() {
   const state = readState();
   const aggregate = readAggregate();
-  const config = readJson(CONFIG_PATH, {});
+  const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   const vars = buildVars(state, config, aggregate);
 
@@ -458,7 +461,7 @@ function showToday() {
 function showWeek() {
   const state = readState();
   const aggregate = readAggregate();
-  const config = readJson(CONFIG_PATH, {});
+  const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   const vars = buildVars(state, config, aggregate);
 
@@ -518,7 +521,7 @@ function statusColor(status) {
 function showPreview() {
   let state = readState();
   const aggregate = readAggregate();
-  const config = readJson(CONFIG_PATH, {});
+  const config = loadConfig();
   const live = findLiveSessions({ thresholdMs: 90_000 });
   state.liveSessions = live;
   state = applyIdle(state, config);
@@ -558,7 +561,7 @@ function showPreview() {
 // previous helper exactly: { vars: [sorted keys], live: <full vars object> }.
 function dumpVars() {
   let state = readState();
-  const config = readJson(CONFIG_PATH, {});
+  const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   state = applyIdle(state, config);
   const live = buildVars(state, config, readAggregate() || {});
@@ -597,14 +600,12 @@ function doScan(force = false) {
 function doBackfill(argv) {
   const path = argv[0];
   if (!path) {
-    console.log(`${c.red}✗${c.reset} usage: claude-rpc backfill <path>`);
-    console.log(`${c.dim}  scans the given directory recursively for .jsonl transcripts and${c.reset}`);
-    console.log(`${c.dim}  merges them into your aggregate.${c.reset}`);
-    process.exit(1);
+    fail('usage: claude-rpc backfill <path>',
+      { hint: 'point at any folder containing .jsonl transcripts (e.g. a backup of ~/.claude/projects)' });
   }
   if (!existsSync(path)) {
-    console.log(`${c.red}✗${c.reset} path doesn't exist: ${path}`);
-    process.exit(1);
+    fail(`path doesn't exist: ${path}`,
+      { hint: 'check the spelling, or run `claude-rpc doctor` to see where transcripts live' });
   }
   console.log(`${c.dim}Backfilling from${c.reset} ${c.cyan}${path}${c.reset}…`);
   const t0 = Date.now();
@@ -655,8 +656,7 @@ function doBadge(argv) {
   const opts = parseBadgeArgs(argv);
   const aggregate = readAggregate();
   if (!aggregate) {
-    console.error(`${c.yellow}No aggregate yet. Run ${c.cyan}claude-rpc scan${c.reset} first.`);
-    process.exit(1);
+    fail('no aggregate yet — nothing to render', { hint: 'run `claude-rpc scan` first', code: EX_BAD_STATE });
   }
   const svg = badgeSvg({ aggregate, metric: opts.metric, range: opts.range, label: opts.label });
   if (opts.out) {
@@ -684,8 +684,7 @@ async function doCard(argv) {
   const opts = parseCardArgs(argv);
   const aggregate = readAggregate();
   if (!aggregate) {
-    console.error(`${c.yellow}No aggregate yet. Run ${c.cyan}claude-rpc scan${c.reset} first.`);
-    process.exit(1);
+    fail('no aggregate yet — nothing to render', { hint: 'run `claude-rpc scan` first', code: EX_BAD_STATE });
   }
   const { renderCard } = await import('./card.js');
   const svg = renderCard(aggregate, { range: opts.range });
@@ -707,10 +706,6 @@ async function doCard(argv) {
 // Per-project overrides live in <project>/.claude-rpc.json and take priority
 // over the runtime list. See src/privacy.js for the full resolution chain.
 
-function loadConfigSafe() {
-  try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); } catch { return {}; }
-}
-
 function doPrivate() {
   const cwd = process.cwd();
   const list = addPrivateCwd(cwd);
@@ -731,7 +726,7 @@ function doPublic() {
 
 function doPrivacy() {
   const cwd = process.cwd();
-  const cfg = loadConfigSafe();
+  const cfg = loadConfig();
   const { visibility, projectName, reason } = resolveVisibility(cwd, cfg);
   const color = visibility === 'hidden' ? c.red : visibility === 'name-only' ? c.yellow : c.green;
   console.log('');
@@ -771,14 +766,85 @@ function tailLog() {
         // file rotated
         lastSize = buf.length;
       }
-    } catch {}
+    } catch { /* read race vs rotation — next watchFile tick recovers */ }
   });
 }
 
+// One-screen "where am I?" view. Goal: a user typing `claude-rpc` with no
+// args sees in <24 lines what's happening and the four most useful next
+// commands. Full command list lives behind --help.
+function overview() {
+  const setUp = hasUserConfig();
+  const cfg = loadConfig();
+  const pid = daemonPid();
+
+  console.log('');
+  console.log(`  ${c.bold}${c.magenta}◆ claude-rpc${c.reset}  ${c.dim}v${VERSION} — Discord Rich Presence for Claude Code${c.reset}`);
+  console.log('');
+
+  if (!setUp) {
+    console.log(`  ${c.yellow}○${c.reset} not configured yet`);
+    console.log('');
+    console.log(`  Run ${c.cyan}claude-rpc setup${c.reset} to get started.`);
+    console.log('');
+    console.log(`  ${c.dim}--help for the full command list${c.reset}`);
+    console.log('');
+    return;
+  }
+
+  // Status line: daemon up/down + project + model + status verb.
+  const state = readState();
+  const aggregate = readAggregate();
+  state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
+  const vars = buildVars(state, cfg, aggregate);
+  const dot = pid
+    ? `${c.green}●${c.reset} running ${c.dim}pid ${pid}${c.reset}`
+    : `${c.yellow}○${c.reset} ${c.dim}daemon not running${c.reset}`;
+  if (pid) {
+    console.log(`  ${dot}  ${c.gray}·${c.reset}  ${c.bold}${vars.modelPretty}${c.reset} in ${c.bold}${vars.project}${c.reset}  ${c.gray}·${c.reset}  ${statusColor(vars.status)}${vars.statusVerbose}${c.reset}`);
+  } else {
+    console.log(`  ${dot}`);
+  }
+
+  if (aggregate) {
+    console.log('');
+    console.log(`  ${c.dim}today  ${c.reset}${c.green}${vars.todayHours.padEnd(6)}${c.reset}${c.dim}active  ·  ${vars.todayPromptsLabel}  ·  ${vars.todayCostFmt}${c.reset}`);
+    console.log(`  ${c.dim}streak ${c.reset}${c.magenta}${String(vars.streak).padEnd(6)}${c.reset}${c.dim}${vars.streak === 1 ? 'day' : 'days'}  ·  longest ${vars.longestStreak}  ·  ${vars.allHours} all-time${c.reset}`);
+  } else {
+    console.log('');
+    console.log(`  ${c.dim}no stats yet — run ${c.reset}${c.cyan}claude-rpc scan${c.reset}${c.dim} to build aggregates${c.reset}`);
+  }
+
+  // Four most useful next commands. Doctor leads — it's the answer to
+  // "something looks wrong" without the user having to read anything.
+  console.log('');
+  const next = pid
+    ? [['status', 'full dashboard with heatmap'],
+       ['doctor', 'diagnose problems'],
+       ['serve',  'open the web dashboard'],
+       ['stop',   'stop the daemon']]
+    : (cfg.clientId && cfg.clientId !== '1234567890123456789')
+      ? [['start',  'launch the daemon'],
+         ['doctor', 'diagnose problems'],
+         ['status', 'show current stats'],
+         ['setup',  'register Claude Code hooks']]
+      : [['setup',  'install hooks and seed config'],
+         ['doctor', 'diagnose problems'],
+         ['start',  'launch the daemon'],
+         ['status', 'show current stats']];
+  for (const [name, desc] of next) {
+    console.log(`  ${c.cyan}${name.padEnd(8)}${c.reset}  ${c.dim}→${c.reset}  ${desc}`);
+  }
+  console.log('');
+  console.log(`  ${c.dim}--help for the full command list  ·  --version${c.reset}`);
+  console.log('');
+}
+
 function help() {
   const cmds = [
     ['setup',     'Install Claude Code hooks (~/.claude/settings.json)'],
     ['uninstall', 'Remove Claude Code hooks'],
+    ['upgrade-config', 'Re-run idempotent migrations on an existing config.json'],
     ['start',     'Start the Discord RPC daemon (detached)'],
     ['stop',      'Stop the daemon'],
     ['restart',   'Stop then start the daemon'],
@@ -815,6 +881,8 @@ function help() {
   console.log('');
   console.log(`  ${c.dim}Tip: ${c.reset}edit ${c.cyan}config.json${c.reset} to customize rotation frames. Run ${c.cyan}claude-rpc preview${c.reset} to see the result without Discord.`);
   console.log('');
+  console.log(`  ${c.dim}Exit codes:${c.reset} ${c.dim}0 ok · 1 user error · 2 system error · 3 wrong state${c.reset}`);
+  console.log('');
 }
 
 // Packaged exe: `claude-rpc.exe` with no args → first-run install + start.
@@ -827,9 +895,16 @@ const packagedDefault = IS_PACKAGED && !cmd;
 // top-level await.
 (async () => {
   switch (cmd) {
+    case '--version':
+    case '-V':
+    case '-v':        console.log(`claude-rpc ${VERSION}`); break;
+    case '--help':
+    case '-h':
+    case 'help':      help(); break;
     case 'setup':     await runInstall({ exePath: EXE_PATH || process.execPath, withStartup: false }); break;
     case 'install':   await runInstall({ exePath: EXE_PATH || process.execPath }); break;
     case 'uninstall': await runUninstall(); break;
+    case 'upgrade-config': migrateConfig(); break;
     case 'start':     startDaemon(); break;
     case 'stop':      stopDaemon(); break;
     case 'restart':   restartDaemon(); break;
@@ -895,7 +970,7 @@ const packagedDefault = IS_PACKAGED && !cmd;
             console.warn(`refresh skipped: ${e.message}`);
           }
           const wasRunning = stopDaemon({ quiet: true });
-          try { if (existsSync(STATE_PATH)) unlinkSync(STATE_PATH); } catch {}
+          try { if (existsSync(STATE_PATH)) unlinkSync(STATE_PATH); } catch { /* state.json locked or already gone — next hook will recreate it */ }
           if (wasRunning) {
             // Brief wait for the OS to release the pid file before we spawn.
             setTimeout(() => startDaemon(), 700);
@@ -903,8 +978,14 @@ const packagedDefault = IS_PACKAGED && !cmd;
             startDaemon();
           }
         }
+      } else if (!cmd) {
+        // True no-args invocation in dev/npm mode → one-screen overview.
+        // The packagedDefault branch above handles the SEA exe's "double-
+        // click with no args" install-and-start flow.
+        overview();
       } else {
-        help();
+        fail(`unknown command: ${cmd}`,
+          { hint: 'run `claude-rpc --help` for the full list', code: EX_USER_ERROR });
       }
     }
   }

package/src/config.js

@@ -0,0 +1,89 @@
+// Config loader. One place that knows how to:
+//
+//   1. Read the user's config.json from disk.
+//   2. Deep-merge it over DEFAULT_CONFIG so the user file only needs to
+//      hold *overrides* (a fresh user file is two lines: clientId and
+//      maybe appName).
+//   3. Survive bad JSON / missing files / wrong types without crashing.
+//      Bad input logs a one-line warning and falls back to defaults.
+//      Critical for the daemon — an Electron-GUI mid-edit save used to
+//      hard-exit it via daemon.js's `process.exit(1)`. No more.
+//
+// Merge rule: plain objects deep-merge, arrays REPLACE. Arrays-as-deep-
+// merge is rarely what anyone wants (a user rotation array becomes a
+// spliced franken-array of theirs + defaults). Replacing matches what
+// you'd expect from "I set this, it's mine."
+//
+// All callers (daemon, server/api, tui, cli) should go through
+// `loadConfig()` rather than reading CONFIG_PATH directly.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { CONFIG_PATH } from './paths.js';
+import { DEFAULT_CONFIG } from './default-config.js';
+
+// "Has the user run setup?" — a separate signal from `loadConfig` because
+// loadConfig now always returns merged defaults (the daemon needs them
+// even if the file isn't there yet). Callers that want to distinguish
+// "never been set up" from "everything default" check this instead.
+export function hasUserConfig(path = CONFIG_PATH) {
+  return existsSync(path);
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+// Deep-merge `over` onto `base`. Plain objects merge recursively; arrays
+// and primitives from `over` replace whatever was in `base`. Returns a
+// fresh object — neither input is mutated. Used for layering user config
+// over DEFAULT_CONFIG and (later) per-project overrides over user config.
+export function mergeConfig(base, over) {
+  if (over === undefined || over === null) return structuredClone(base);
+  if (!isPlainObject(base) || !isPlainObject(over)) return structuredClone(over);
+  const out = {};
+  const keys = new Set([...Object.keys(base), ...Object.keys(over)]);
+  for (const k of keys) {
+    const a = base[k];
+    const b = over[k];
+    if (b === undefined) {
+      out[k] = structuredClone(a);
+    } else if (isPlainObject(a) && isPlainObject(b)) {
+      out[k] = mergeConfig(a, b);
+    } else {
+      out[k] = structuredClone(b);
+    }
+  }
+  return out;
+}
+
+// Read + merge. `onError(message)` is called when the user config can't
+// be parsed — caller decides whether to log to stdout, daemon.log, or
+// nothing. Returning the merged-defaults object is the contract: never
+// throw, never exit. Worst case we render with shipped defaults.
+//
+// path defaults to CONFIG_PATH so all daemon-like callers can drop the
+// `readFileSync(CONFIG_PATH, ...)` boilerplate.
+export function loadConfig({ path = CONFIG_PATH, onError } = {}) {
+  if (!existsSync(path)) {
+    return mergeConfig(DEFAULT_CONFIG, {});
+  }
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (onError) onError(`config read failed at ${path}: ${e.message} — falling back to defaults`);
+    return mergeConfig(DEFAULT_CONFIG, {});
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    if (onError) onError(`config parse failed at ${path}: ${e.message} — falling back to defaults`);
+    return mergeConfig(DEFAULT_CONFIG, {});
+  }
+  if (!isPlainObject(parsed)) {
+    if (onError) onError(`config at ${path} is not an object — falling back to defaults`);
+    return mergeConfig(DEFAULT_CONFIG, {});
+  }
+  return mergeConfig(DEFAULT_CONFIG, parsed);
+}

package/src/daemon.js

@@ -1,33 +1,71 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, unlinkSync, watch, appendFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync, existsSync, unlinkSync, watch, appendFileSync, mkdirSync, statSync, renameSync } from 'node:fs';
 import { Client } from '@xhayper/discord-rpc';
 import { readState } from './state.js';
 import { buildVars, fillTemplate, framePasses, applyIdle } from './format.js';
 import { scan, readAggregate, findLiveSessions, readSessionTokens } from './scanner.js';
 import { detectGithubUrl } from './git.js';
 import { applyPrivacy } from './privacy.js';
+import { loadConfig } from './config.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH } from './paths.js';
 
 if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
 
+// Daemon log capped at 5MB. Same policy events.jsonl uses (see hook.js).
+// On rotation we move the existing log aside as `daemon.log.1` so the
+// last rotation's content is still available for `claude-rpc tail`.
+// One file's worth of history is enough — older logs have never been
+// useful in practice, and the daemon runs for weeks.
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
+
+function maybeRotateLog() {
+  try {
+    const st = statSync(LOG_PATH);
+    if (st.size <= LOG_ROTATE_BYTES) return;
+    renameSync(LOG_PATH, LOG_PATH + '.1');
+  } catch {
+    // No log file yet, or rename failed (another daemon is rotating
+    // simultaneously). Either case is safe to ignore — we'll just keep
+    // appending and try rotation again on the next write.
+  }
+}
+
 function log(...args) {
   const line = `[${new Date().toISOString()}] ${args.map((a) => typeof a === 'string' ? a : JSON.stringify(a)).join(' ')}\n`;
-  try { appendFileSync(LOG_PATH, line); } catch {}
+  maybeRotateLog();
+  try {
+    appendFileSync(LOG_PATH, line);
+  } catch {
+    // Disk full, permission denied, or LOG_PATH became invalid mid-run.
+    // The daemon must keep running regardless — Discord presence is more
+    // important than file logging.
+  }
   process.stdout.write(line);
 }
 
-function loadConfig() {
-  try { return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')); }
-  catch (e) { log('Failed to read config.json:', e.message); process.exit(1); }
+// Wrap loadConfig so a parse/IO failure logs once and the daemon keeps
+// running on baked-in defaults. The Electron settings GUI saves the file
+// atomically but mid-edit hand-edits used to brick the daemon — this is
+// the "no, just keep going with what we shipped" failsafe.
+function loadConfigWithLog() {
+  return loadConfig({ onError: (msg) => log(msg) });
 }
 
-let config = loadConfig();
+let config = loadConfigWithLog();
 let aggregate = readAggregate() || null;
 let liveSessions = [];
 let client = null;
 let connected = false;
 let lastPayloadHash = '';
 let reconnectTimer = null;
+// Exponential backoff for Discord reconnect: 5s → 10s → 20s → … → 300s cap.
+// Reset to RECONNECT_BASE_MS on a successful connect so the next outage
+// also starts gentle. Jitter (±30%) keeps multiple daemons (e.g. a user
+// running both packaged and dev simultaneously) from synchronizing
+// reconnect storms against Discord's IPC socket.
+const RECONNECT_BASE_MS = 5_000;
+const RECONNECT_CAP_MS  = 300_000;
+let reconnectDelayMs    = RECONNECT_BASE_MS;
 let rotationIndex = 0;
 let lastRotationAt = 0;
 // Stabilizes Discord's elapsed timer: applyIdle can synthesize a sessionStart
@@ -134,9 +172,15 @@ function buildActivity(opts = {}) {
   if (frame.details) activity.details = fillTemplate(frame.details, vars).slice(0, 128);
   if (frame.state) activity.state = fillTemplate(frame.state, vars).slice(0, 128);
 
-  // Image precedence: statusAssets[status] → modelAssets[modelMatch] → presence.largeImageKey.
-  // statusAssets lets the user swap the big image based on what Claude is doing
-  // (working/thinking/idle/stale/notification).
+  // ── Large-image precedence (single source of truth) ────────────────
+  //   1. statusAssets[status]      "working" gif when working, etc.
+  //   2. modelAssets[opus|sonnet|haiku|default]
+  //                                  per-model art (Opus/Sonnet/Haiku),
+  //                                  only consulted when statusAssets
+  //                                  doesn't match AND state isn't stale.
+  //   3. presence.largeImageKey    global fallback.
+  // smallImageKey separately resolves to the `{statusIcon}` template var
+  // (set via config.statusIcons) and is dropped entirely when empty.
   let largeKeyTpl = p.largeImageKey;
   if (config.statusAssets && config.statusAssets[state.status]) {
     largeKeyTpl = config.statusAssets[state.status];
@@ -243,26 +287,34 @@ async function connect() {
 
   client.on('ready', () => {
     connected = true;
+    // Reset backoff so the next outage also starts at RECONNECT_BASE_MS.
+    reconnectDelayMs = RECONNECT_BASE_MS;
     log('Discord RPC connected as', client.user?.username);
     lastPayloadHash = '';
     pushPresence();
   });
   client.on('disconnected', () => {
     connected = false;
-    log('Discord disconnected — retrying in 10s');
-    scheduleReconnect();
+    scheduleReconnect('Discord disconnected');
   });
   try { await client.login(); }
   catch (e) {
-    log('Discord login failed:', e.message, '— retrying in 10s. Is Discord desktop running?');
-    scheduleReconnect();
+    scheduleReconnect(`Discord login failed: ${e.message}`);
   }
 }
 
-function scheduleReconnect() {
+function scheduleReconnect(reason = 'reconnect') {
   connected = false;
   if (reconnectTimer) return;
-  reconnectTimer = setTimeout(() => { reconnectTimer = null; connect(); }, 10000);
+  // ±30% jitter on the current step. Cheap protection against
+  // synchronized reconnect storms from sibling daemons.
+  const jitter = 0.7 + Math.random() * 0.6;
+  const wait = Math.round(reconnectDelayMs * jitter);
+  log(`${reason} — retry in ${Math.round(wait / 1000)}s. Is Discord desktop running?`);
+  reconnectTimer = setTimeout(() => { reconnectTimer = null; connect(); }, wait);
+  // Step the base for the *next* failure. Cap at 5min so a long Discord
+  // outage doesn't push us into multi-hour silences.
+  reconnectDelayMs = Math.min(RECONNECT_CAP_MS, reconnectDelayMs * 2);
 }
 
 function watchFiles() {
@@ -275,8 +327,9 @@ function watchFiles() {
   }
   watch(CONFIG_PATH, () => {
     log('Config changed — reloading');
-    try { config = loadConfig(); lastPayloadHash = ''; pushPresence(); }
-    catch (e) { log('Reload failed:', e.message); }
+    config = loadConfigWithLog();
+    lastPayloadHash = '';
+    pushPresence();
   });
   if (existsSync(AGGREGATE_PATH)) {
     let aggTimer = null;
@@ -289,6 +342,44 @@ function watchFiles() {
       }, 250);
     });
   }
+
+  // Mtime-poll fallback. fs.watch on Windows occasionally drops events
+  // when the writer uses an atomic-rename pattern (which `state.js` does
+  // and the scanner does for aggregate.json). A 30s poll comparing
+  // last-seen mtime catches anything the watcher missed without making
+  // the watcher itself the bottleneck. No-op on Linux/macOS most of the
+  // time, but cheap enough to leave on everywhere.
+  let lastStateMtime = 0, lastAggMtime = 0;
+  setInterval(() => {
+    try {
+      if (existsSync(STATE_PATH)) {
+        const m = statSync(STATE_PATH).mtimeMs;
+        if (m > lastStateMtime) {
+          if (lastStateMtime !== 0) {
+            // The first observation is just the starting value; only
+            // log + push when we actually missed a watcher event.
+            log('state.json mtime advanced without a watcher event (poll fallback)');
+            pushPresence();
+          }
+          lastStateMtime = m;
+        }
+      }
+      if (existsSync(AGGREGATE_PATH)) {
+        const m = statSync(AGGREGATE_PATH).mtimeMs;
+        if (m > lastAggMtime) {
+          if (lastAggMtime !== 0) {
+            aggregate = readAggregate() || aggregate;
+            lastPayloadHash = '';
+            pushPresence();
+          }
+          lastAggMtime = m;
+        }
+      }
+    } catch {
+      // Stat fail mid-rotate of the watched file. The next tick will
+      // pick up the new mtime. Silent on purpose.
+    }
+  }, 30_000);
 }
 
 async function runBackgroundScan({ force = false } = {}) {
@@ -306,8 +397,11 @@ async function runBackgroundScan({ force = false } = {}) {
 
 function shutdown() {
   log('Shutting down…');
-  try { client?.destroy(); } catch {}
-  try { if (existsSync(PID_PATH)) unlinkSync(PID_PATH); } catch {}
+  // Both calls below are best-effort cleanup on the way out the door.
+  // If the IPC client is already half-dead or the PID file was removed
+  // by something else, we don't care — we're exiting anyway.
+  try { client?.destroy(); } catch { /* IPC already gone */ }
+  try { if (existsSync(PID_PATH)) unlinkSync(PID_PATH); } catch { /* race vs another shutdown */ }
   process.exit(0);
 }
 

package/src/doctor.js

@@ -16,37 +16,17 @@ import {
 } from './paths.js';
 import { findLiveSessions } from './scanner.js';
 import { resolveVisibility, listPrivateCwds } from './privacy.js';
-
-const TTY = process.stdout.isTTY && !process.env.NO_COLOR;
-const c = {
-  reset:  TTY ? '\x1b[0m'   : '',
-  dim:    TTY ? '\x1b[2m'   : '',
-  bold:   TTY ? '\x1b[1m'   : '',
-  red:    TTY ? '\x1b[31m'  : '',
-  green:  TTY ? '\x1b[32m'  : '',
-  yellow: TTY ? '\x1b[33m'  : '',
-  cyan:   TTY ? '\x1b[36m'  : '',
-  gray:   TTY ? '\x1b[90m'  : '',
-};
-
-const SYM_OK   = TTY ? `${c.green}✓${c.reset}` : '[ok]  ';
-const SYM_FAIL = TTY ? `${c.red}✗${c.reset}`   : '[fail]';
-const SYM_WARN = TTY ? `${c.yellow}!${c.reset}` : '[warn]';
-const SYM_INFO = TTY ? `${c.cyan}·${c.reset}`  : '[info]';
+import { c, check as uiCheck } from './ui.js';
 
 const counters = { pass: 0, fail: 0, warn: 0 };
 
+// Thin wrapper around the shared ui.check so we can keep counters local
+// to this module without exporting a stateful version from ui.js.
 function check(label, status, detail = '', hint = '') {
-  let sym;
-  if (status === 'pass')      { sym = SYM_OK;   counters.pass++; }
-  else if (status === 'fail') { sym = SYM_FAIL; counters.fail++; }
-  else if (status === 'warn') { sym = SYM_WARN; counters.warn++; }
-  else                          { sym = SYM_INFO; }
-  const tail = detail ? `  ${c.dim}${detail}${c.reset}` : '';
-  console.log(`  ${sym}  ${label}${tail}`);
-  if (hint && status !== 'pass') {
-    console.log(`        ${c.gray}↳ ${hint}${c.reset}`);
-  }
+  if      (status === 'pass') counters.pass++;
+  else if (status === 'fail') counters.fail++;
+  else if (status === 'warn') counters.warn++;
+  uiCheck(label, status, detail, hint);
 }
 
 function section(title) {
@@ -143,7 +123,7 @@ function checkClaudeProjects() {
         if (f.endsWith('.jsonl')) count++;
       }
     }
-  } catch {}
+  } catch { /* unreadable subdir — just report whatever we counted so far */ }
   check('claude transcripts visible', count > 0 ? 'pass' : 'warn',
     `${count} .jsonl ${count === 1 ? 'file' : 'files'}`,
     count === 0 ? 'open claude code and send a prompt — transcripts appear immediately' : '');
@@ -207,7 +187,7 @@ function checkCanonicalExe() {
   }
   if (existsSync(CANONICAL_EXE)) {
     let size = '';
-    try { size = `${(statSync(CANONICAL_EXE).size / 1024 / 1024).toFixed(1)} MB`; } catch {}
+    try { size = `${(statSync(CANONICAL_EXE).size / 1024 / 1024).toFixed(1)} MB`; } catch { /* stat failed, size stays blank */ }
     check('canonical exe installed', 'pass', `${CANONICAL_EXE} (${size})`);
   } else {
     check('canonical exe installed', 'fail', `missing: ${CANONICAL_EXE}`,
@@ -253,7 +233,7 @@ function checkDaemonLog() {
   try {
     const tail = readFileSync(LOG_PATH, 'utf8').split('\n').slice(-50).join('\n');
     connected = /Discord RPC connected/i.test(tail);
-  } catch {}
+  } catch { /* log unreadable — connected stays false, warn check renders */ }
   if (connected) {
     check('discord IPC connection', 'pass',
       `${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);

package/src/git.js

@@ -48,14 +48,14 @@ function readGitInfo(cwd) {
         if (leaf) out.repo = leaf;
       }
     }
-  } catch {}
+  } catch { /* missing/unreadable .git/config — out.repo stays at cwd basename */ }
 
   // HEAD → branch (or empty when detached).
   try {
     const head = readFileSync(join(gitDir, 'HEAD'), 'utf8').trim();
     const ref = head.match(/^ref:\s+refs\/heads\/(.+)$/);
     if (ref) out.branch = ref[1].trim();
-  } catch {}
+  } catch { /* missing/unreadable HEAD — leave branch blank, template will hide */ }
 
   return out;
 }

package/src/hook.js

@@ -16,7 +16,7 @@ function appendEvent(entry) {
       }
     }
     appendFileSync(EVENTS_LOG_PATH, JSON.stringify(entry) + '\n');
-  } catch {}
+  } catch { /* best-effort log: hooks must never fail because of an unwritable events.jsonl */ }
 }
 
 function readStdin() {