claude-rpc 0.18.0 → 0.20.1

package/src/default-config.js

@@ -14,6 +14,20 @@ export const DEFAULT_CONFIG = {
   appName: "Claude Code",
   updateIntervalMs: 4000,
   rotationIntervalMs: 12000,
+  // Self-heal: the SessionStart hook (re)starts the daemon whenever it isn't
+  // already running, so presence is assured whenever you use Claude Code —
+  // surviving reboots, crashes, OS sleep, and platforms with no login-autostart
+  // entry (macOS/Linux). Set false to disable that and manage the daemon
+  // yourself with `claude-rpc start` / `stop`.
+  autostart: true,
+  // Minimum gap (ms) between Discord SET_ACTIVITY writes. Discord hard-limits
+  // activity updates (~5 per 20s); blowing past it makes the client EMPTY the
+  // presence and stop updating until the writes stop. Claude Code fires hooks
+  // in bursts, so the daemon coalesces rapid changes and never writes faster
+  // than this — the first change after a quiet gap goes out at once, the rest
+  // collapse to the latest and flush when the gap expires. 4s stays safely
+  // under the limit; lower values risk Discord throttling the card.
+  minActivityGapMs: 4000,
   rescanIntervalSec: 300,
   idleThresholdSec: 60,
   // Time (minutes) of no hook activity AND no live transcripts on disk before

package/src/discord-ipc.js

@@ -32,6 +32,9 @@ export const OP_PING = 3;
 export const OP_PONG = 4;
 
 const CONNECT_TIMEOUT_MS = 10_000; // matches @xhayper's connect() timeout
+// Per-candidate connect timeout: a socket file whose peer accepts then stalls
+// must not wedge discovery of the real Discord socket behind it.
+const SOCKET_CONNECT_TIMEOUT_MS = 1500;
 
 // Same resolution order @xhayper used: XDG_RUNTIME_DIR → TMPDIR → TMP → TEMP → /tmp.
 function getTempDir() {
@@ -171,14 +174,18 @@ export class Client extends EventEmitter {
     for (const p of paths) {
       const socket = await new Promise((resolve) => {
         const s = net.createConnection(p);
-        const onErr = () => {
+        let timer = null;
+        const cleanup = () => {
+          clearTimeout(timer);
           s.removeListener('connect', onOk);
-          resolve(null);
-        };
-        const onOk = () => {
           s.removeListener('error', onErr);
-          resolve(s);
         };
+        const onErr = () => { cleanup(); resolve(null); };
+        const onOk = () => { cleanup(); resolve(s); };
+        // A peer that accepts then stalls would otherwise never settle this
+        // candidate and block the rest each discovery cycle (and leak the fd).
+        timer = setTimeout(() => { cleanup(); s.destroy(); resolve(null); }, SOCKET_CONNECT_TIMEOUT_MS);
+        if (typeof timer === 'object' && 'unref' in timer) timer.unref();
         s.once('connect', onOk);
         s.once('error', onErr);
       });

package/src/doctor.js

@@ -18,6 +18,7 @@ import { findLiveSessions } from './scanner.js';
 import { detectGithubUrl } from './git.js';
 import { resolveVisibility, listPrivateCwds, detectGithubPrivate } from './privacy.js';
 import { readClaudeCredentials, readUsageCache } from './usage.js';
+import { EVENTS as HOOK_EVENTS, isOurHook } from './install.js';
 import { c, check as uiCheck } from './ui.js';
 
 const counters = { pass: 0, fail: 0, warn: 0 };
@@ -82,6 +83,28 @@ function checkMode() {
   check('execution mode', mode, detail);
 }
 
+// Pure classifiers — extracted so doctor's decision logic is unit-testable
+// without spawning the full filesystem diagnostic. The check* wrappers below
+// pair these with the actual reads + check() output.
+const PLACEHOLDER_CLIENT_ID = '1234567890123456789';
+
+// '' / the seed placeholder → 'unset'; not a 17–21 digit snowflake → 'malformed'.
+export function classifyClientId(clientId) {
+  if (!clientId || clientId === PLACEHOLDER_CLIENT_ID) return 'unset';
+  if (!/^\d{17,21}$/.test(String(clientId))) return 'malformed';
+  return 'ok';
+}
+
+// Most-recent-wins IPC state inferred from the daemon log tail: 'up'/'down'/'unknown'.
+export function ipcStateFromLog(logText) {
+  let ipc = 'unknown';
+  for (const line of String(logText || '').split('\n').slice(-80)) {
+    if (/Discord RPC connected|Presence updated|Presence cleared/i.test(line)) ipc = 'up';
+    else if (/retry in \d+s|login failed|Discord disconnected/i.test(line)) ipc = 'down';
+  }
+  return ipc;
+}
+
 function checkConfig() {
   if (!existsSync(CONFIG_PATH)) {
     check('config.json present', 'fail', CONFIG_PATH,
@@ -98,10 +121,11 @@ function checkConfig() {
   }
   check('config.json present', 'pass', CONFIG_PATH);
 
-  if (!cfg.clientId || cfg.clientId === '1234567890123456789') {
+  const clientIdClass = classifyClientId(cfg.clientId);
+  if (clientIdClass === 'unset') {
     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))) {
+  } else if (clientIdClass === 'malformed') {
     check('discord clientId set', 'warn', `${cfg.clientId} doesn't look like a snowflake`,
       'discord application IDs are 17–21 digits');
   } else {
@@ -152,16 +176,6 @@ function checkClaudeProjects() {
   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`,
@@ -181,7 +195,7 @@ function checkHooks() {
   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));
+    const ours = bucket.flatMap((e) => e.hooks || []).find((h) => isOurHook(h));
     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 });
@@ -259,12 +273,8 @@ function checkDaemonLog() {
   // Ns" / "login failed" / "disconnected" line means it dropped. Whichever
   // happened most recently wins.
   let ipc = 'unknown';
-  try {
-    for (const line of readFileSync(LOG_PATH, 'utf8').split('\n').slice(-80)) {
-      if (/Discord RPC connected|Presence updated|Presence cleared/i.test(line)) ipc = 'up';
-      else if (/retry in \d+s|login failed|Discord disconnected/i.test(line)) ipc = 'down';
-    }
-  } catch { /* log unreadable — ipc stays 'unknown', warn renders */ }
+  try { ipc = ipcStateFromLog(readFileSync(LOG_PATH, 'utf8')); }
+  catch { /* log unreadable — ipc stays 'unknown', warn renders */ }
   if (ipc === 'up') {
     check('discord IPC connection', 'pass',
       `connected · ${sizeKB} KB log · last write ${ageMin.toFixed(1)} min ago`);

package/src/ensure-daemon.js

@@ -0,0 +1,127 @@
+// Daemon-lifecycle primitives shared by the CLI (`start`), the daemon itself
+// (single-instance guard), and the hook (self-heal on SessionStart). Kept in a
+// tiny dependency-light module so the hook — which runs on every Claude Code
+// event and must stay fast and crash-proof — can import the spawn recipe
+// without pulling in cli.js's UI stack.
+//
+// The "ultra assured startup" story lives here: the daemon comes up whenever a
+// Claude Code session starts (ensureDaemonRunning, called from the hook), and a
+// race-proof claim (claimSingleInstance, called by the daemon) guarantees that
+// no matter how many launchers fire at once — a manual `start`, a Windows Run
+// entry, several SessionStart hooks from concurrent sessions — exactly one
+// daemon survives.
+
+import { spawn } from 'node:child_process';
+import {
+  openSync, closeSync, writeFileSync, readFileSync, unlinkSync, existsSync, statSync, mkdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { PID_PATH, STATE_DIR, DAEMON_SCRIPT, CANONICAL_EXE, IS_PACKAGED } from './paths.js';
+
+// mtime of this marker = last time any launcher attempted a spawn. A short
+// cooldown stops concurrent SessionStart hooks (several sessions opening at
+// once) and any startup crash-loop from spawning a swarm of throwaway daemons —
+// the single-instance claim would reap them, but not spawning them is cheaper.
+const SPAWN_MARKER = join(STATE_DIR, 'daemon-spawn.ts');
+const SPAWN_COOLDOWN_MS = 15_000;
+
+// True if `pid` names a live process. process.kill(pid,0) sends no signal — it
+// just probes: ESRCH → gone, EPERM → exists but owned by someone else (still
+// alive). 0/NaN is never alive.
+export function isAlive(pid) {
+  if (!pid || !Number.isFinite(pid)) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; }
+}
+
+export function readPid(pidPath = PID_PATH) {
+  try { return Number(readFileSync(pidPath, 'utf8')) || 0; }
+  catch { return 0; }
+}
+
+// The pid of the live daemon, or 0 if none is running.
+export function daemonAlive(pidPath = PID_PATH) {
+  const pid = readPid(pidPath);
+  return pid && isAlive(pid) ? pid : 0;
+}
+
+// The single source of truth for HOW to launch the daemon, shared by every
+// launcher so the CLI and the hook spawn it identically:
+//   packaged → "<canonical exe>" daemon   (prefer the canonical install over a
+//              transient Downloads copy so we don't keep that file locked open)
+//   dev/npm  → "<node>" "<abs daemon.js>" (PATH-independent — process.execPath
+//              is the very node already running us)
+// Always detached + windowless + stdio-ignored so it outlives the launcher and
+// never pops a console. Returns the child (caller reads .pid) or null on a
+// synchronous spawn failure.
+export function spawnDaemonDetached() {
+  const exe = (IS_PACKAGED && existsSync(CANONICAL_EXE)) ? CANONICAL_EXE : process.execPath;
+  const args = IS_PACKAGED ? ['daemon'] : [DAEMON_SCRIPT];
+  try {
+    const child = spawn(exe, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    // An async spawn failure (ENOENT on the exe) emits 'error'; with no listener
+    // Node rethrows it as an unhandled exception that can take down the launcher.
+    // Swallow — the caller verifies liveness via the pid file, not the child.
+    child.on('error', () => {});
+    child.unref();
+    return child;
+  } catch {
+    return null;
+  }
+}
+
+// Pure decision for the hook's self-heal: should THIS SessionStart spawn a
+// daemon? Separated from the side effects so it's unit-testable.
+export function shouldSpawnDaemon({ autostart, daemonPid, lastAttemptMs, now, cooldownMs }) {
+  if (autostart === false) return false;                                  // explicit opt-out
+  if (daemonPid) return false;                                            // already running
+  if (lastAttemptMs && now - lastAttemptMs < cooldownMs) return false;    // within the cooldown
+  return true;
+}
+
+// Self-heal entry point, called by the SessionStart hook. Best-effort and fast:
+// if no daemon is running (reboot, crash, OS sleep, closed terminal — or simply
+// a platform with no login-autostart entry), bring one up. Stamps the cooldown
+// marker BEFORE spawning so sibling SessionStart hooks racing this one skip
+// instead of each launching a throwaway. Returns the spawned child, or null.
+export function ensureDaemonRunning({ autostart = true, now = Date.now(), cooldownMs = SPAWN_COOLDOWN_MS } = {}) {
+  let lastAttemptMs = 0;
+  try { if (existsSync(SPAWN_MARKER)) lastAttemptMs = statSync(SPAWN_MARKER).mtimeMs; } catch { /* unreadable — treat as never */ }
+  if (!shouldSpawnDaemon({ autostart, daemonPid: daemonAlive(), lastAttemptMs, now, cooldownMs })) return null;
+  try { mkdirSync(STATE_DIR, { recursive: true }); } catch { /* exists / unwritable */ }
+  try { writeFileSync(SPAWN_MARKER, String(now)); } catch { /* best-effort cooldown */ }
+  return spawnDaemonDetached();
+}
+
+// Atomic single-instance claim, called once by the daemon at startup. Returns
+// the pid of an already-running daemon (caller should exit), or null when WE
+// now own the pid file. The exclusive-create ('wx') makes the pid file itself
+// the mutex: only one of N simultaneously-starting daemons can create it; the
+// losers read the winner's live pid and step aside. A stale file (dead owner,
+// empty, or our own recycled pid) is reclaimed and the create retried — so a
+// crashed daemon never blocks its successor.
+export function claimSingleInstance({ pidPath = PID_PATH, pid = process.pid, alive = isAlive } = {}) {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    let fd;
+    try {
+      fd = openSync(pidPath, 'wx'); // atomic: throws EEXIST if the file already exists
+    } catch (e) {
+      if (e.code !== 'EEXIST') {
+        // Unexpected (perms, missing dir). Best-effort write and take ownership
+        // rather than refusing to start.
+        try { writeFileSync(pidPath, String(pid)); } catch { /* unwritable — run lockless */ }
+        return null;
+      }
+      let owner = 0;
+      try { owner = Number(readFileSync(pidPath, 'utf8')) || 0; } catch { /* mid-write — reclaim */ }
+      if (owner && owner !== pid && alive(owner)) return owner; // a live daemon already owns it
+      try { unlinkSync(pidPath); } catch { /* a racer reclaimed it first */ }
+      continue; // retry the exclusive create
+    }
+    try { writeFileSync(fd, String(pid)); } finally { try { closeSync(fd); } catch { /* already closed */ } }
+    return null; // we created the file → we are THE daemon
+  }
+  // Repeatedly lost the reclaim race (extreme contention) — proceed best-effort.
+  try { writeFileSync(pidPath, String(pid)); } catch { /* unwritable */ }
+  return null;
+}

package/src/fmt.js

@@ -0,0 +1,33 @@
+// Canonical number/duration formatters shared across the card, badge, profile,
+// insights and the live presence engine (format.js re-exports these). Single
+// source of truth so tier-boundary rounding behaves identically everywhere —
+// the copies had drifted (sub-1000 rounding, a missing Billion tier).
+//
+// NOTE: worker/src/badge.js keeps a byte-for-byte copy of fmtNum — the worker
+// deploys dependency-free and can't import across the package boundary. Keep
+// the two in sync; test/format.test.js pins fmtNum's tier behavior.
+
+// Compact integer: 999 → "999", 1_500 → "1.5k", 1_500_000 → "1.50M", up to "B".
+// The unit is chosen from the ROUNDED value, so 999_999 → "1.00M" (not the old
+// "1000.0k") and 999_999_999 → "1.00B".
+export function fmtNum(n) {
+  if (!n) return '0';
+  const neg = n < 0 ? '-' : '';
+  const v = Math.abs(n);
+  if (v < 1000) return neg + Math.round(v);
+  for (const [suf, div, prec] of [['k', 1e3, 1], ['M', 1e6, 2], ['B', 1e9, 2]]) {
+    const s = (v / div).toFixed(prec);
+    if (Number(s) < 1000) return neg + s + suf;
+  }
+  return neg + (v / 1e9).toFixed(2) + 'B'; // ≥ ~1e12 stays in the B tier
+}
+
+// Duration from ms: <60m → "42m", <10h → "2.5h", else "12h". Rounds to whole
+// minutes first so 59.7m → "1.0h" (not the old "60m").
+export function fmtHours(ms) {
+  if (!ms || ms < 0) return '0h';
+  const mins = Math.round(ms / 60_000);
+  if (mins < 60) return `${mins}m`;
+  const hours = mins / 60;
+  return hours < 10 ? `${hours.toFixed(1)}h` : `${Math.round(hours)}h`;
+}

package/src/format.js

@@ -4,6 +4,7 @@ import { fmtCost } from './pricing.js';
 import { languageOf } from './languages.js';
 import { detectGitBranch, detectGitRepo } from './git.js';
 import { fmtResetTime, fmtResetDay } from './usage.js';
+import { fmtNum, fmtHours } from './fmt.js';
 
 const WEEKDAY_NAMES = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
@@ -33,14 +34,6 @@ function fmtHourLocal(ms) {
   return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
 }
 
-function fmtNum(n) {
-  if (!n) return '0';
-  if (n < 1000) return `${n}`;
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-  if (n < 1_000_000_000) return `${(n / 1_000_000).toFixed(2)}M`;
-  return `${(n / 1_000_000_000).toFixed(2)}B`;
-}
-
 function fmtDuration(ms) {
   if (!ms || ms < 0) return '0s';
   const s = Math.floor(ms / 1000);
@@ -69,14 +62,6 @@ function fmtToolElapsed(ms) {
   return `${h}h ${m}m`;
 }
 
-function fmtHours(ms) {
-  if (!ms || ms < 0) return '0h';
-  const hours = ms / 3_600_000;
-  if (hours < 1) return `${Math.round(hours * 60)}m`;
-  if (hours < 10) return `${hours.toFixed(1)}h`;
-  return `${Math.round(hours)}h`;
-}
-
 function plural(n, sing, plur) {
   const word = n === 1 ? sing : (plur || `${sing}s`);
   return `${fmtNum(n)} ${word}`;
@@ -223,9 +208,11 @@ export function buildVars(state, config, aggregate) {
   // leak to anyone viewing the card. Fall back to the configured app name.
   const cwdIsLeaky = looksLikeUsernameLeak(state.cwd);
   const safeCwd = cwdIsLeaky ? '' : (state.cwd || '');
-  const projectPretty = cwdIsLeaky
-    ? (config?.appName || 'Claude Code')
-    : (humanProject(state.cwd) || 'Claude Code');
+  const appName = config?.appName || 'Claude Code';
+  // Project label with the home-dir/username-leak guard applied — shared by the
+  // single-session label and the concurrent list so neither renders "lucas".
+  const safeProject = (cwd) => looksLikeUsernameLeak(cwd) ? appName : (humanProject(cwd) || appName);
+  const projectPretty = safeProject(state.cwd);
   const currentToolPretty = humanTool(state.currentTool);
   const modelPretty = humanModel(state.model);
 
@@ -244,7 +231,7 @@ export function buildVars(state, config, aggregate) {
   const concurrentOther = Math.max(0, concurrent - 1);
   const concurrentListPretty = liveSessions
     .slice(0, 3)
-    .map((s) => (typeof s === 'string' ? humanProject(s) : humanProject(s.cwd || s.project || '')))
+    .map((s) => safeProject(typeof s === 'string' ? s : (s.cwd || s.project || '')))
     .filter(Boolean)
     .join(', ') || '—';
 
@@ -517,7 +504,7 @@ export function buildVars(state, config, aggregate) {
     gitRepo,
 
     // ── App identity (v0.3.6) ───────────────────────────────────
-    appName: config?.appName || 'Claude Code',
+    appName,
 
     // Literal single space — handy for blanking a line without `requires`.
     empty: ' ',

package/src/hook.js

@@ -4,6 +4,8 @@ import { dirname } from 'node:path';
 import { updateState, resetState, pushUnique, shortFile } from './state.js';
 import { detectLastCommitSubject, detectGitBranch } from './git.js';
 import { EVENTS_LOG_PATH } from './paths.js';
+import { loadConfig } from './config.js';
+import { ensureDaemonRunning } from './ensure-daemon.js';
 
 // Precedence when a command ships more than one way (`git commit && git push`
 // → push). Highest first.
@@ -153,6 +155,20 @@ export function processHookEvent(event, input = {}) {
         model: input.model?.id || input.model || 'claude',
         status: 'idle',
       });
+      // Self-heal the daemon. A reboot, crash, OS sleep, or closed terminal can
+      // leave nothing running, so the card silently never appears — and on
+      // macOS/Linux there's no login-autostart entry at all (only Windows wires
+      // a Run key). Every Claude Code session begins with this hook, so make it
+      // (best-effort) guarantee the daemon is up: presence is then assured
+      // exactly when you're using Claude, on every platform. ensureDaemonRunning
+      // is a no-op when a daemon is already alive and is cooldown-guarded against
+      // spawn storms; the daemon's atomic claim reaps any duplicate. Opt out
+      // with `autostart:false` in config.
+      try {
+        let autostart = true;
+        try { autostart = loadConfig().autostart !== false; } catch { /* unreadable config — default on */ }
+        ensureDaemonRunning({ autostart });
+      } catch { /* presence is best-effort — never break the user's turn */ }
       break;
     }
     case 'UserPromptSubmit': {

package/src/insights.js

@@ -4,24 +4,10 @@
 
 import { dayKey, weekKey } from './scanner.js';
 import { fmtCost } from './pricing.js';
+import { fmtNum, fmtHours } from './fmt.js';
 
 const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
 
-function fmtHours(ms) {
-  if (!ms || ms < 0) return '0h';
-  const hours = ms / 3_600_000;
-  if (hours < 1) return `${Math.round(hours * 60)}m`;
-  if (hours < 10) return `${hours.toFixed(1)}h`;
-  return `${Math.round(hours)}h`;
-}
-
-function fmtNum(n) {
-  if (!n) return '0';
-  if (n < 1000) return `${n}`;
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-  return `${(n / 1_000_000).toFixed(2)}M`;
-}
-
 function pct(n) {
   const sign = n >= 0 ? '+' : '−';
   return `${sign}${Math.round(Math.abs(n) * 100)}%`;

package/src/install.js

@@ -52,7 +52,7 @@ function dirtyStep(sym, label, detail = '', log = console.log) {
 }
 function noop(fact) { noopFacts.push(fact); }
 
-const EVENTS = [
+export const EVENTS = [
   'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse',
   'Stop', 'SubagentStop', 'Notification', 'SessionEnd', 'PreCompact',
 ];
@@ -69,7 +69,18 @@ function writeJson(p, d) {
 
 function isOurHookCommand(cmd) {
   if (!cmd) return false;
-  return /claude-rpc/i.test(cmd) || /hook\.js/i.test(cmd);
+  if (/claude-rpc/i.test(cmd)) return true;
+  // Dev-mode hooks point at THIS install's hook.js by absolute path. Match that
+  // exact path — NOT any `hook.js`, which could be a third-party tool's hook we
+  // must never rewrite or delete.
+  return cmd.includes(HOOK_SCRIPT.replace(/\\/g, '/'));
+}
+
+// A hook entry we own. Tagged entries are recognized regardless of command
+// shape or clone-dir name; command-matching is the legacy fallback for entries
+// written before tagging.
+export function isOurHook(h) {
+  return !!h && (h._claudeRpc === true || isOurHookCommand(h.command));
 }
 
 export function installHooks(exePath) {
@@ -81,24 +92,29 @@ export function installHooks(exePath) {
   //   npm     → `claude-rpc hook <event>`       (bin shim resolves through PATH;
   //              survives `npm update` and nvm version switches)
   //   dev     → `node "<src/hook.js>" <event>`  (cloned-source iteration)
+  // Hook commands must resolve under Claude Code's hook shell — `/bin/sh` with a
+  // minimal PATH that, under nvm, has neither `claude-rpc` nor `node` on it (no
+  // system node). So use the ABSOLUTE node (process.execPath) + absolute hook.js
+  // for both npm and dev installs; only the packaged exe is self-contained. This
+  // survives `npm update` (HOOK_SCRIPT is stable) and an nvm version switch (nvm
+  // keeps prior versions on disk); re-run setup only if that node is removed.
+  const node = process.execPath.replace(/\\/g, '/');
   const cmdFor = IS_PACKAGED
     ? (event) => `"${exePath}" hook ${event}`
-    : IS_NPM_INSTALL
-      ? (event) => `claude-rpc hook ${event}`
-      : (event) => `node "${HOOK_SCRIPT.replace(/\\/g, '/')}" ${event}`;
+    : (event) => `"${node}" "${HOOK_SCRIPT.replace(/\\/g, '/')}" ${event}`;
 
   for (const event of EVENTS) {
     const bucket = settings.hooks[event] = settings.hooks[event] || [];
     const wanted = cmdFor(event);
     const existingEntry = bucket.find((b) =>
-      Array.isArray(b.hooks) && b.hooks.some((h) => isOurHookCommand(h.command))
+      Array.isArray(b.hooks) && b.hooks.some((h) => isOurHook(h))
     );
     if (existingEntry) {
       existingEntry.hooks = existingEntry.hooks.map((h) =>
-        isOurHookCommand(h.command) ? { ...h, command: wanted } : h
+        isOurHook(h) ? { ...h, command: wanted, _claudeRpc: true } : h
       );
     } else {
-      bucket.push({ matcher: '', hooks: [{ type: 'command', command: wanted }] });
+      bucket.push({ matcher: '', hooks: [{ type: 'command', command: wanted, _claudeRpc: true }] });
     }
   }
   if (JSON.stringify(settings.hooks) === before) {
@@ -117,7 +133,7 @@ export function uninstallHooks() {
     const bucket = settings.hooks[event];
     if (!Array.isArray(bucket)) continue;
     settings.hooks[event] = bucket
-      .map((entry) => ({ ...entry, hooks: (entry.hooks || []).filter((h) => !isOurHookCommand(h.command)) }))
+      .map((entry) => ({ ...entry, hooks: (entry.hooks || []).filter((h) => !isOurHook(h)) }))
       .filter((entry) => (entry.hooks || []).length > 0);
     if (settings.hooks[event].length === 0) delete settings.hooks[event];
   }
@@ -421,7 +437,7 @@ export function migrateConfig({ silent = false } = {}) {
   // anyone who added a custom frame is left entirely alone.
   const frameId = (f) => (Array.isArray(f?.requires) && f.requires.length)
     ? 'r:' + [...f.requires].map(String).sort().join('|')
-    : 't:' + (f?.details ?? '') + '' + (f?.state ?? '');
+    : 't:' + (f?.details ?? '') + '\x00' + (f?.state ?? '');
   const dflBy = DEFAULT_CONFIG.presence?.byStatus || {};
   const usrBy = cfg.presence.byStatus || {};
   let framesAdded = 0;
@@ -453,18 +469,12 @@ export function migrateConfig({ silent = false } = {}) {
 // command and report success, leaving the user to discover the breakage
 // the next time they open Claude Code. Returns { ok, detail }.
 function verifyHookPipe(exePath) {
-  const cmd  = IS_PACKAGED ? exePath
-              : IS_NPM_INSTALL ? 'claude-rpc'
-              : process.execPath;
-  const args = IS_PACKAGED || IS_NPM_INSTALL
-              ? ['hook', 'SessionStart']
-              : [HOOK_SCRIPT, 'SessionStart'];
-  // Windows + npm-install: the global bin is `claude-rpc.cmd` (a batch shim),
-  // and Node's spawn doesn't apply PATHEXT — calling `claude-rpc` raw fails
-  // with ENOENT. shell:true makes cmd.exe do the resolution, mirroring how
-  // Claude Code actually invokes the hook string at runtime. Args are static
-  // and trusted; no injection surface.
-  const useShell = IS_NPM_INSTALL && process.platform === 'win32';
+  // Spawn exactly what installHooks wired: the packaged exe, or the absolute
+  // node + hook.js. Both are absolute, so there's no PATH/PATHEXT/shell
+  // resolution — it works under the same minimal hook shell Claude Code uses
+  // (the reason the old `claude-rpc` / bare-`node` forms failed under nvm).
+  const cmd  = IS_PACKAGED ? exePath : process.execPath;
+  const args = IS_PACKAGED ? ['hook', 'SessionStart'] : [HOOK_SCRIPT, 'SessionStart'];
   let result;
   try {
     result = spawnSync(cmd, args, {
@@ -472,7 +482,6 @@ function verifyHookPipe(exePath) {
       encoding: 'utf8',
       timeout: 3000,
       windowsHide: true,
-      shell: useShell,
     });
   } catch (e) {
     return { ok: false, detail: `spawn failed: ${e.message}` };
@@ -481,8 +490,14 @@ function verifyHookPipe(exePath) {
   if (result.status !== 0) {
     return { ok: false, detail: `hook exit ${result.status}: ${(result.stderr || '').trim().slice(0, 120)}` };
   }
-  if (!result.stdout.includes('"continue"')) {
-    return { ok: false, detail: `unexpected hook output: ${result.stdout.trim().slice(0, 120)}` };
+  // Parse the ack and assert the actual contract (a JSON object with
+  // continue:true) rather than substring-matching the bytes "continue" anywhere
+  // in stdout.
+  let ack;
+  try { ack = JSON.parse((result.stdout || '').trim()); }
+  catch { return { ok: false, detail: `non-JSON hook output: ${(result.stdout || '').trim().slice(0, 120)}` }; }
+  if (ack?.continue !== true) {
+    return { ok: false, detail: `hook ack missing continue:true: ${(result.stdout || '').trim().slice(0, 120)}` };
   }
   return { ok: true, detail: 'SessionStart round-trip succeeded' };
 }

package/src/leaderboard.js

@@ -29,7 +29,11 @@ export function isValidHandle(input) {
 // trim, bound the length. Returns null for empty input.
 export function cleanDisplayName(input, max = 40) {
   if (!input || typeof input !== 'string') return null;
-  const name = input.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, max);
+  // Strip control chars (C0/DEL/C1), zero-width, and bidi overrides so a name
+  // can't visually corrupt or spoof the shared board. Denylist by code point -
+  // CJK, emoji and accents still pass. Mirrored in the worker's cleanName.
+  const ok = (c) => !(c < 32 || (c >= 0x7f && c <= 0x9f) || (c >= 0x200b && c <= 0x200f) || (c >= 0x202a && c <= 0x202e) || (c >= 0x2066 && c <= 0x2069) || c === 0xfeff);
+  const name = [...input].filter((ch) => ok(ch.codePointAt(0))).join('').trim().slice(0, max);
   return name || null;
 }
 

package/src/mcp.js

@@ -114,6 +114,9 @@ export function callTool(name, getAgg = readAggregate) {
  */
 export function runMcpServer({ input = process.stdin, output = process.stdout } = {}) {
   let buf = '';
+  const MAX_BUF = 4 * 1024 * 1024; // hard cap on a single un-terminated line
+  const DEFAULT_PROTOCOL = '2024-11-05';
+  const SUPPORTED_PROTOCOLS = new Set([DEFAULT_PROTOCOL, '2025-03-26', '2025-06-18']);
   const send = (msg) => output.write(JSON.stringify(msg) + '\n');
   const reply = (id, result) => send({ jsonrpc: '2.0', id, result });
   const replyErr = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
@@ -121,8 +124,12 @@ export function runMcpServer({ input = process.stdin, output = process.stdout }
   function handle(msg) {
     const { id, method, params } = msg;
     if (method === 'initialize') {
+      // Echo the client's protocol version when we recognize it; otherwise fall
+      // back to our baseline (our surface — initialize/tools/*/ping — is stable
+      // across these revisions).
+      const requested = params?.protocolVersion;
       return reply(id, {
-        protocolVersion: '2024-11-05',
+        protocolVersion: SUPPORTED_PROTOCOLS.has(requested) ? requested : DEFAULT_PROTOCOL,
         capabilities: { tools: {} },
         serverInfo: { name: 'claude-rpc', version: VERSION },
       });
@@ -159,7 +166,14 @@ export function runMcpServer({ input = process.stdin, output = process.stdout }
       try { msg = JSON.parse(line); } catch { continue; }
       try { handle(msg); } catch (e) { process.stderr.write(`mcp handler error: ${e.message}\n`); }
     }
+    // A single line larger than the cap (no newline yet) would grow buf without
+    // bound — drop the partial and resync on the next newline.
+    if (buf.length > MAX_BUF) {
+      process.stderr.write(`mcp: dropping oversized line (>${MAX_BUF} bytes)\n`);
+      buf = '';
+    }
   });
   input.on('end', () => process.exit(0));
+  input.on('error', () => process.exit(0));
   process.stderr.write(`claude-rpc MCP server v${VERSION} ready (stdio)\n`);
 }

package/src/notify.js

@@ -29,7 +29,7 @@ export function sanitizeLabel(s) {
  * @param {string} [body] - Notification body text.
  * @returns {boolean} true if a notifier was spawned, false on failure.
  */
-export function desktopNotify(title, body = '') {
+export function desktopNotify(title, body = '', { spawn: spawnFn = spawn } = {}) {
   try {
     const p = platform();
     // A missing notifier binary (e.g. no `notify-send`) makes spawn emit an
@@ -43,15 +43,15 @@ export function desktopNotify(title, body = '') {
     };
     if (p === 'darwin') {
       const script = `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`;
-      swallow(spawn('osascript', ['-e', script], { stdio: 'ignore', detached: true }));
+      swallow(spawnFn('osascript', ['-e', script], { stdio: 'ignore', detached: true }));
     } else if (p === 'win32') {
       const script = `Add-Type -AssemblyName System.Windows.Forms;`
         + `$n=New-Object System.Windows.Forms.NotifyIcon;`
         + `$n.Icon=[System.Drawing.SystemIcons]::Information;$n.Visible=$true;`
         + `$n.ShowBalloonTip(5000, ${JSON.stringify(title)}, ${JSON.stringify(body)}, 'Info')`;
-      swallow(spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], { stdio: 'ignore', detached: true, windowsHide: true }));
+      swallow(spawnFn('powershell', ['-NoProfile', '-NonInteractive', '-Command', script], { stdio: 'ignore', detached: true, windowsHide: true }));
     } else {
-      swallow(spawn('notify-send', ['-a', 'Claude Code', title, body], { stdio: 'ignore', detached: true }));
+      swallow(spawnFn('notify-send', ['-a', 'Claude Code', title, body], { stdio: 'ignore', detached: true }));
     }
     return true;
   } catch {