claude-rpc 0.3.11 → 0.6.0

package/src/daemon.js

@@ -1,32 +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
@@ -99,6 +138,12 @@ function buildActivity(opts = {}) {
     }
   }
 
+  // Apply privacy AFTER token resolution but BEFORE buildVars — so the
+  // template inputs ({project}, {currentFile}, etc.) already reflect the
+  // visibility decision. Sets state._privacy so we can short-circuit to
+  // clearActivity when visibility=hidden.
+  state = applyPrivacy(state, config);
+
   const vars = buildVars(state, config, opts.aggregate || aggregate);
   const p = config.presence || {};
 
@@ -127,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];
@@ -172,9 +223,12 @@ function buildActivity(opts = {}) {
   if (typeof config.activityType === 'number') activity.type = config.activityType;
 
   // Buttons: static configured set, optionally augmented with a per-project
-  // GitHub button when the current cwd has a github origin.
+  // GitHub button when the current cwd has a github origin. Privacy mode
+  // suppresses the GitHub button entirely (else clicking it leaks the
+  // project name we're trying to hide).
+  const isPrivacyConstrained = state._privacy && state._privacy.visibility !== 'public';
   const buttons = Array.isArray(p.buttons) ? p.buttons.slice() : [];
-  const gh = state.status !== 'stale' ? detectGithubUrl(state.cwd) : null;
+  const gh = (!isPrivacyConstrained && state.status !== 'stale') ? detectGithubUrl(state.cwd) : null;
   if (gh && !buttons.some((b) => /github\.com/i.test(b.url || ''))) {
     buttons.unshift({ label: 'View on GitHub →', url: gh });
   }
@@ -196,9 +250,14 @@ async function pushPresence() {
     let resolved = readState();
     resolved.liveSessions = liveSessions;
     resolved = applyIdle(resolved, config);
+    // Privacy can convert any state into a "hidden" verdict — give it the
+    // same treatment as hideWhenStale: a single clearActivity, deduped via
+    // lastPayloadHash so we don't spam the IPC.
+    resolved = applyPrivacy(resolved, config);
 
     const hideWhenStale = config.hideWhenStale !== false;
-    if (resolved.status === 'stale' && hideWhenStale) {
+    const privacyHidden = resolved._privacy?.visibility === 'hidden';
+    if ((resolved.status === 'stale' && hideWhenStale) || privacyHidden) {
       const stamp = 'cleared';
       if (lastPayloadHash === stamp) return;
       lastPayloadHash = stamp;
@@ -206,7 +265,8 @@ async function pushPresence() {
       // elapsed timer rather than counting from a previous session.
       effectiveSessionStart = null;
       await client.user.clearActivity();
-      log('Presence cleared (stale — Claude Code not running)');
+      const reason = privacyHidden ? 'privacy=hidden in this project' : 'stale — Claude Code not running';
+      log(`Presence cleared (${reason})`);
       return;
     }
 
@@ -227,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() {
@@ -259,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;
@@ -273,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 } = {}) {
@@ -290,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

@@ -0,0 +1,376 @@
+// `claude-rpc doctor` — one-shot diagnostic.
+//
+// Checks every common failure path users have hit in support and prints a
+// colored pass/fail/warn checklist with one-line fix hints. Self-contained:
+// no Discord IPC connection (just a brief probe), no side effects, safe to
+// run repeatedly. Exit code 0 when everything passes, 1 when any check fails.
+
+import { existsSync, readFileSync, statSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import {
+  IS_PACKAGED, IS_NPM_INSTALL, IS_INSTALLED,
+  CONFIG_PATH, CANONICAL_EXE, USER_CONFIG_DIR,
+  STATE_PATH, PID_PATH, LOG_PATH,
+  AGGREGATE_PATH, SCAN_CACHE_PATH,
+  CLAUDE_HOME, CLAUDE_PROJECTS, CLAUDE_SETTINGS,
+} from './paths.js';
+import { findLiveSessions } from './scanner.js';
+import { resolveVisibility, listPrivateCwds } from './privacy.js';
+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 = '') {
+  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) {
+  console.log(`\n${c.bold}${title}${c.reset}`);
+}
+
+// ── individual checks ────────────────────────────────────────────────────
+
+function checkNodeVersion() {
+  const major = Number((process.versions.node || '').split('.')[0] || 0);
+  if (major >= 18) {
+    check('Node.js version', 'pass', `${process.versions.node}`);
+  } else {
+    check('Node.js version', 'fail', `${process.versions.node} (need ≥18)`,
+      'install a newer Node from https://nodejs.org');
+  }
+}
+
+function checkMode() {
+  let mode, detail;
+  if (IS_PACKAGED) {
+    mode = 'pass';
+    detail = `packaged exe at ${process.execPath}`;
+  } else if (IS_NPM_INSTALL) {
+    mode = 'pass';
+    detail = 'npm install (global or local node_modules)';
+  } else {
+    mode = 'pass';
+    detail = 'dev source (cloned repo, no node_modules wrapper)';
+  }
+  check('execution mode', mode, detail);
+}
+
+function checkConfig() {
+  if (!existsSync(CONFIG_PATH)) {
+    check('config.json present', 'fail', CONFIG_PATH,
+      'run `claude-rpc setup` to seed a default config');
+    return null;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch (e) {
+    check('config.json present', 'fail', `parse error: ${e.message}`,
+      `open ${CONFIG_PATH} and fix the JSON syntax (or delete it and re-run setup)`);
+    return null;
+  }
+  check('config.json present', 'pass', CONFIG_PATH);
+
+  if (!cfg.clientId || cfg.clientId === '1234567890123456789') {
+    check('discord clientId set', 'fail', cfg.clientId || '(empty)',
+      `paste your discord application ID into ${CONFIG_PATH}`);
+  } else if (!/^\d{17,21}$/.test(String(cfg.clientId))) {
+    check('discord clientId set', 'warn', `${cfg.clientId} doesn't look like a snowflake`,
+      'discord application IDs are 17–21 digits');
+  } else {
+    check('discord clientId set', 'pass', String(cfg.clientId));
+  }
+
+  const hasByStatus = !!cfg.presence?.byStatus;
+  const hasRotation = Array.isArray(cfg.presence?.rotation) && cfg.presence.rotation.length > 0;
+  if (hasByStatus) {
+    check('presence schema', 'pass', 'byStatus block present (v0.3.6+ shape)');
+  } else if (hasRotation) {
+    check('presence schema', 'warn', 'legacy rotation only — no byStatus block',
+      'run `claude-rpc setup` again to migrate config into the byStatus shape');
+  } else {
+    check('presence schema', 'warn', 'no presence templates configured',
+      'either rotation or byStatus is needed for the card to render');
+  }
+  return cfg;
+}
+
+function checkClaudeHome() {
+  if (!existsSync(CLAUDE_HOME)) {
+    check('~/.claude exists', 'fail', CLAUDE_HOME,
+      'install claude code first — https://claude.com/claude-code');
+    return false;
+  }
+  check('~/.claude exists', 'pass', CLAUDE_HOME);
+  return true;
+}
+
+function checkClaudeProjects() {
+  if (!existsSync(CLAUDE_PROJECTS)) {
+    check('~/.claude/projects exists', 'warn', 'no transcripts on disk yet',
+      'open claude code and prompt once — the directory is created lazily');
+    return 0;
+  }
+  let count = 0;
+  try {
+    for (const proj of readdirSync(CLAUDE_PROJECTS)) {
+      for (const f of readdirSync(join(CLAUDE_PROJECTS, proj))) {
+        if (f.endsWith('.jsonl')) count++;
+      }
+    }
+  } 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' : '');
+  return count;
+}
+
+const HOOK_EVENTS = [
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
+  'Stop', 'SubagentStop', 'Notification', 'SessionEnd',
+];
+
+function isOurHookCommand(cmd) {
+  if (!cmd) return false;
+  return /claude-rpc/i.test(cmd) || /hook\.js/i.test(cmd);
+}
+
+function checkHooks() {
+  if (!existsSync(CLAUDE_SETTINGS)) {
+    check('hooks registered', 'fail', `${CLAUDE_SETTINGS} missing`,
+      'run `claude-rpc setup` to register hooks');
+    return;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(CLAUDE_SETTINGS, 'utf8'));
+  } catch (e) {
+    check('hooks registered', 'fail', `parse error: ${e.message}`,
+      `open ${CLAUDE_SETTINGS} and fix the JSON syntax`);
+    return;
+  }
+  const missing = [];
+  const stale = [];
+  for (const event of HOOK_EVENTS) {
+    const bucket = settings.hooks?.[event];
+    if (!Array.isArray(bucket) || bucket.length === 0) { missing.push(event); continue; }
+    const ours = bucket.flatMap((e) => e.hooks || []).find((h) => isOurHookCommand(h.command));
+    if (!ours) { missing.push(event); continue; }
+    if (IS_PACKAGED && !ours.command.includes(CANONICAL_EXE)) stale.push({ event, cmd: ours.command });
+    if (IS_NPM_INSTALL && !/\bclaude-rpc\b\s+hook\b/.test(ours.command)) stale.push({ event, cmd: ours.command });
+  }
+  if (missing.length === 0 && stale.length === 0) {
+    check(`hooks registered (${HOOK_EVENTS.length}/${HOOK_EVENTS.length})`, 'pass',
+      'all events wired against the current binary');
+  } else if (missing.length === HOOK_EVENTS.length) {
+    check('hooks registered', 'fail', 'no claude-rpc hooks found',
+      'run `claude-rpc setup` to register hooks');
+  } else if (missing.length > 0) {
+    check('hooks registered', 'warn', `missing: ${missing.join(', ')}`,
+      'run `claude-rpc setup` to add the missing events');
+  } else if (stale.length > 0) {
+    check('hooks registered', 'warn',
+      `${stale.length} pointing at an old binary path`,
+      'run `claude-rpc setup` to refresh hook commands against the current binary');
+  }
+}
+
+function checkCanonicalExe() {
+  if (!IS_PACKAGED) {
+    check('canonical exe', 'pass', `not applicable (${IS_NPM_INSTALL ? 'npm' : 'dev'} mode)`);
+    return;
+  }
+  if (existsSync(CANONICAL_EXE)) {
+    let size = '';
+    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}`,
+      'run `claude-rpc setup` to copy this binary to the canonical location');
+  }
+}
+
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function checkDaemon() {
+  if (!existsSync(PID_PATH)) {
+    check('daemon running', 'warn', 'no pid file',
+      'run `claude-rpc start` to launch the daemon');
+    return false;
+  }
+  const pid = Number(readFileSync(PID_PATH, 'utf8'));
+  if (!pid || !isAlive(pid)) {
+    check('daemon running', 'fail', `stale pid file (${pid})`,
+      'run `claude-rpc start` — old daemon died without cleaning up');
+    return false;
+  }
+  check('daemon running', 'pass', `pid ${pid}`);
+  return true;
+}
+
+function checkDaemonLog() {
+  if (!existsSync(LOG_PATH)) {
+    check('daemon log', 'warn', 'no log file yet',
+      'daemon will create this on first start');
+    return;
+  }
+  let st;
+  try { st = statSync(LOG_PATH); } catch {
+    check('daemon log', 'warn', 'unreadable');
+    return;
+  }
+  const ageMin = (Date.now() - st.mtimeMs) / 60_000;
+  const sizeKB = (st.size / 1024).toFixed(1);
+  // Look for "Discord RPC connected" in the tail to confirm Discord IPC.
+  let connected = false;
+  try {
+    const tail = readFileSync(LOG_PATH, 'utf8').split('\n').slice(-50).join('\n');
+    connected = /Discord RPC connected/i.test(tail);
+  } 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`);
+  } else {
+    check('discord IPC connection', 'warn',
+      `log shows no recent "connected" line`,
+      'is the discord desktop client running? rpc only works via desktop, not browser');
+  }
+}
+
+function checkState() {
+  if (!existsSync(STATE_PATH)) {
+    check('state.json', 'warn', 'not present', 'created by the first hook event');
+    return;
+  }
+  let state;
+  try { state = JSON.parse(readFileSync(STATE_PATH, 'utf8')); }
+  catch (e) {
+    check('state.json', 'fail', `parse error: ${e.message}`,
+      `delete ${STATE_PATH} and let the next hook event recreate it`);
+    return;
+  }
+  const ageMin = state.lastActivity
+    ? (Date.now() - state.lastActivity) / 60_000
+    : Infinity;
+  const ageLabel = ageMin === Infinity ? 'never' : `${ageMin.toFixed(1)} min ago`;
+  check('state.json fresh', 'pass', `status=${state.status} · last activity ${ageLabel}`);
+}
+
+function checkAggregate() {
+  if (!existsSync(AGGREGATE_PATH)) {
+    check('aggregate built', 'warn', 'never scanned',
+      'run `claude-rpc scan` to build lifetime stats from your transcripts');
+    return;
+  }
+  try {
+    const agg = JSON.parse(readFileSync(AGGREGATE_PATH, 'utf8'));
+    const hours = ((agg.activeMs || 0) / 3_600_000).toFixed(1);
+    const ageMin = (Date.now() - statSync(AGGREGATE_PATH).mtimeMs) / 60_000;
+    check('aggregate built', 'pass',
+      `${agg.sessions || 0} sessions · ${hours}h · refreshed ${ageMin.toFixed(0)} min ago`);
+  } catch (e) {
+    check('aggregate built', 'fail', `parse error: ${e.message}`,
+      'run `claude-rpc rescan` to rebuild the aggregate from scratch');
+  }
+}
+
+function checkPrivacy(cfg) {
+  try {
+    const cwd = process.cwd();
+    const { visibility, projectName, reason } = resolveVisibility(cwd, cfg || {});
+    const listed = listPrivateCwds();
+    const detail = projectName
+      ? `${visibility}  ·  alias=${projectName}  ·  ${reason}`
+      : `${visibility}  ·  ${reason}`;
+    const status = visibility === 'hidden' ? 'warn'
+                 : visibility === 'name-only' ? 'warn'
+                 : 'pass';
+    check('current directory visibility', status, detail);
+    if (listed.length) {
+      check('private-list entries', 'pass', `${listed.length} ${listed.length === 1 ? 'path' : 'paths'} marked private`);
+    } else {
+      check('private-list entries', 'pass', 'none');
+    }
+  } catch (e) {
+    check('privacy check', 'warn', `lookup failed: ${e.message}`);
+  }
+}
+
+function checkLiveSessions() {
+  try {
+    const live = findLiveSessions({ thresholdMs: 90_000 });
+    if (live.length === 0) {
+      check('live sessions', 'pass',
+        'none — claude code isn\'t actively writing a transcript right now');
+    } else {
+      const names = live.slice(0, 3).map((s) => `${s.project}(${s.ageSec}s)`).join(', ');
+      check('live sessions', 'pass', `${live.length} active: ${names}`);
+    }
+  } catch (e) {
+    check('live sessions', 'warn', `lookup failed: ${e.message}`);
+  }
+}
+
+function checkDataDir() {
+  if (!existsSync(USER_CONFIG_DIR)) {
+    check('user config dir', 'warn', `${USER_CONFIG_DIR} missing`,
+      'run `claude-rpc setup` — this is created automatically');
+    return;
+  }
+  check('user config dir', 'pass', USER_CONFIG_DIR);
+}
+
+// ── public entry point ──────────────────────────────────────────────────
+
+export function runDoctor() {
+  console.log(`${c.bold}${c.cyan}claude-rpc doctor${c.reset}  ${c.dim}— diagnostic checklist${c.reset}`);
+
+  section('Runtime');
+  checkNodeVersion();
+  checkMode();
+  checkCanonicalExe();
+
+  section('Config');
+  checkDataDir();
+  const cfg = checkConfig();
+
+  section('Claude Code');
+  if (checkClaudeHome()) {
+    checkClaudeProjects();
+    checkHooks();
+  }
+
+  section('Daemon');
+  checkDaemon();
+  checkDaemonLog();
+  checkState();
+
+  section('Data');
+  checkAggregate();
+  checkLiveSessions();
+
+  section('Privacy');
+  checkPrivacy(cfg);
+
+  // Summary
+  const { pass, fail, warn } = counters;
+  console.log('');
+  console.log(`  ${c.bold}Summary:${c.reset}  ${c.green}${pass} pass${c.reset}` +
+    (warn ? `  ${c.yellow}${warn} warn${c.reset}` : '') +
+    (fail ? `  ${c.red}${fail} fail${c.reset}` : ''));
+  if (fail === 0 && warn === 0) {
+    console.log(`  ${c.dim}everything looks good. if presence still isn't showing, restart discord.${c.reset}`);
+  } else if (fail === 0) {
+    console.log(`  ${c.dim}no failures — warnings are usually fixed by running \`claude-rpc setup\`.${c.reset}`);
+  }
+  console.log('');
+
+  return fail === 0 ? 0 : 1;
+}

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() {