claude-rpc 0.18.0 → 0.20.1

package/SECURITY.md

@@ -16,10 +16,10 @@ fetch-and-execute anywhere in `src/`.
 
 | Behavior | Where | Scope | Reversible? |
 | --- | --- | --- | --- |
-| Startup persistence | `src/install.js` → `addStartupEntry` | `HKCU` Run key, current user, no admin | Yes — `claude-rpc uninstall` / `removeStartupEntry` |
+| Startup persistence | `src/install.js` → `addStartupEntry` (Windows Run key); `src/hook.js` → `ensureDaemonRunning` (SessionStart self-heal, all platforms) | `HKCU` Run key (no admin) + a detached daemon (re)launched when you start a Claude Code session | Yes — `claude-rpc uninstall` / `removeStartupEntry`; disable self-heal with `autostart:false` |
 | Hook injection | `src/install.js` → `installHooks` | Only into Claude Code's own `settings.json`, only our own commands | Yes — `uninstallHooks` removes exactly what it added |
 | Outbound network | `src/community.js`, `src/gist.js`, `src/usage.js`, `src/notify.js`, `default-config.js` | Anonymous counters + (opt-in) profile/gist/webhook + own read-only OAuth-usage poll + GIF assets | Telemetry: `community off`. Profile: `profile off`. Gist/webhook: opt-in only. Usage: `usage.enabled:false`. |
-| Local subprocess | `reg.exe`, `wscript`, `git`, `gh`, `npm`, `claude`, `security`, notifiers | Static or escaped args, no shell interpolation of untrusted input | n/a |
+| Local subprocess | `reg.exe`, `wscript`, the daemon itself (`node`/packaged exe — via the Run key and the SessionStart self-heal), `git`, `gh`, `npm`, `claude`, `security`, notifiers | Static or escaped args, no shell interpolation of untrusted input | n/a |
 
 No credential access beyond the read-only Claude Code OAuth-token read for usage
 polling (§3d), no filesystem scanning outside `~/.claude-rpc` and Claude Code
@@ -47,8 +47,16 @@ HKCU\Software\Microsoft\Windows\CurrentVersion\Run
   not at wherever you happened to run the installer from — see
   `ensureCanonicalExe`.
 
-Non-Windows platforms get **no** persistence registration (`install()` warns
-and skips it).
+Non-Windows platforms get **no** Run-key/login registration (`install()` warns
+and skips it). Instead — on every platform, Windows included — the
+`SessionStart` hook **self-heals** the daemon: if none is running when you start
+a Claude Code session, the hook spawns one (detached, windowless), so presence
+is restored after a reboot, crash, or OS sleep exactly when you next use Claude.
+It is the same long-lived daemon launched the same way (`src/ensure-daemon.js` →
+`spawnDaemonDetached`), a no-op when a daemon is already running, and
+cooldown-guarded against spawn storms; the daemon's atomic single-instance claim
+reaps any duplicate. Disable it with `autostart:false` in config (then manage
+the daemon yourself via `claude-rpc start` / `stop`).
 
 ## 2. Hook injection into Claude Code
 
@@ -71,6 +79,11 @@ events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`,
   counters, and `git push`/`git commit` detection (for the "just shipped"
   card). It writes only to local state/log files. It does not read file
   *contents*, prompts, or responses beyond the usage counters Claude provides.
+- **`SessionStart` additionally self-heals the daemon:** if none is running it
+  spawns the (detached) daemon so presence is assured cross-platform — see §1
+  and `ensureDaemonRunning`. Best-effort, gated by `autostart` (default on). It
+  is the **only** hook event that launches a process; every other event just
+  writes state and acks.
 - **Scope:** the installer only ever touches entries whose command matches
   `isOurHookCommand` (contains `claude-rpc` or `hook.js`). It will not modify,
   reorder, or delete anyone else's hooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-rpc",
-  "version": "0.18.0",
+  "version": "0.20.1",
   "description": "Discord Rich Presence for Claude Code — live model, project, tokens, and lifetime stats driven by Claude Code's hook system.",
   "type": "module",
   "license": "MIT",

package/src/badge.js

@@ -3,6 +3,7 @@
 
 import { dayKey } from './scanner.js';
 import { fmtCost } from './pricing.js';
+import { fmtNum, fmtHours as fmtHoursLabel } from './fmt.js';
 
 const COLORS = {
   hours:  { left: '#555', right: '#4c1' },     // green
@@ -58,22 +59,6 @@ function rangeLabel(range) {
 
 export { rangeToDays, rangeLabel, pickWindow };
 
-function fmtHoursLabel(ms) {
-  if (!ms) return '0h';
-  const h = ms / 3_600_000;
-  if (h < 1) return `${Math.round(h * 60)}m`;
-  if (h < 10) return `${h.toFixed(1)}h`;
-  return `${Math.round(h)}h`;
-}
-
-function fmtNum(n) {
-  if (!n) return '0';
-  if (n < 1000) return String(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`;
-}
-
 // Compute label/value pair for the requested metric.
 function valueFor(aggregate, metric, range) {
   const a = aggregate || {};

package/src/card.js

@@ -15,6 +15,7 @@ import { dayKey } from './scanner.js';
 import { fmtCost } from './pricing.js';
 import { rangeToDays, rangeLabel, pickWindow } from './badge.js';
 import { VERSION } from './version.js';
+import { fmtNum, fmtHours } from './fmt.js';
 
 const W = 880;
 const H = 540;
@@ -45,22 +46,6 @@ function escapeXml(s) {
     .replace(/"/g, '"');
 }
 
-function fmtNum(n) {
-  if (!n) return '0';
-  if (n < 1000) return String(Math.round(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 fmtHours(ms) {
-  if (!ms || ms < 0) return '0h';
-  const h = ms / 3_600_000;
-  if (h < 1) return `${Math.round(h * 60)}m`;
-  if (h < 10) return `${h.toFixed(1)}h`;
-  return `${Math.round(h)}h`;
-}
-
 function rangeTitle(range) {
   const rl = rangeLabel(range);
   if (rl === 'all-time') return 'on claude';
@@ -103,7 +88,9 @@ function topWeekday(aggregate) {
   const wd = aggregate?.byWeekday || {};
   let best = null;
   for (const [k, v] of Object.entries(wd)) {
-    if (!best || (v.activeMs || 0) > (best.ms || 0)) best = { day: Number(k), ms: v.activeMs || 0 };
+    const day = Number(k);
+    if (!Number.isInteger(day) || day < 0 || day > 6) continue; // out-of-range key → skip, no blank name + stray "(3h)"
+    if (!best || (v.activeMs || 0) > (best.ms || 0)) best = { day, ms: v.activeMs || 0 };
   }
   return best;
 }
@@ -133,6 +120,7 @@ function peakHourLabel(aggregate) {
   const ph = aggregate?.peakHour;
   if (!ph || ph.hour == null) return null;
   const h = Number(ph.hour);
+  if (!Number.isInteger(h) || h < 0 || h > 23) return null; // corrupt aggregate → no label, not "99:00"/"NaN:00"
   return `${String(h).padStart(2, '0')}:00`;
 }
 

package/src/cli.js

@@ -10,10 +10,11 @@ import process from 'node:process';
 if (process.platform === 'win32' && process.stdout.isTTY) {
   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, IS_NPX, EXE_PATH, CANONICAL_EXE } from './paths.js';
-import { readState } from './state.js';
+import { DAEMON_SCRIPT, PID_PATH, STATE_PATH, LOG_PATH, AGGREGATE_PATH, CONFIG_PATH, IS_PACKAGED, IS_NPX, EXE_PATH } from './paths.js';
+import { readActiveState } from './state.js';
 import { buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } from './format.js';
 import { scan, readAggregate, findLiveSessions, dayKey, weekKey } from './scanner.js';
+import { weekGrid } from './week.js';
 import { runHookCli } from './hook.js';
 import { install as runInstall, uninstall as runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro } from './install.js';
 import { startTui } from './tui.js';
@@ -25,6 +26,7 @@ import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } f
 import { parseDuration, setPause, clearPause, pauseUntil } from './pause.js';
 import { readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } from './usage.js';
 import { loadConfig, hasUserConfig } from './config.js';
+import { spawnDaemonDetached } from './ensure-daemon.js';
 import * as lb from './leaderboard.js';
 import { VERSION } from './version.js';
 import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
@@ -62,7 +64,7 @@ function readJson(path, fallback) {
 // (`profile set`, `community on`, `link`, …). mkdirSync first.
 function writeUserConfig(userCfg) {
   mkdirSync(dirname(CONFIG_PATH), { recursive: true });
-  writeUserConfig(userCfg);
+  writeFileSync(CONFIG_PATH, JSON.stringify(userCfg, null, 2) + '\n');
 }
 
 // Validate a flag's value taken with `argv[++i]`. A value that's missing or
@@ -95,18 +97,39 @@ function startDaemon({ quiet = false } = {}) {
     if (!quiet) console.log(`  ${c.yellow}!${c.reset}  ${'daemon running'.padEnd(16)}${c.dim}already up (pid ${pid}) · bounce it with ${c.reset}${c.cyan}claude-rpc restart${c.reset}`);
     return false;
   }
-  // In packaged mode the "daemon script" is the exe itself with a subcommand;
-  // in dev mode it's the src/daemon.js path passed to node. Prefer the
-  // canonical exe when it exists so we don't keep the user's Downloads copy
-  // locked open — the canonical install is the long-lived path.
-  const exe = (IS_PACKAGED && existsSync(CANONICAL_EXE)) ? CANONICAL_EXE : process.execPath;
-  const args = IS_PACKAGED ? ['daemon'] : [DAEMON_SCRIPT];
-  const child = spawn(exe, args, { detached: true, stdio: 'ignore', windowsHide: true });
-  child.unref();
+  // Shared spawn recipe (canonical-exe preference, detached, windowless, error
+  // listener) lives in ensure-daemon.spawnDaemonDetached so the CLI and the
+  // self-healing hook launch the daemon identically.
+  const child = spawnDaemonDetached();
+  if (!child || !child.pid) {
+    if (!quiet) console.log(`  ${c.red}✗${c.reset}  ${'daemon start'.padEnd(16)}${c.dim}spawn failed — check ${shortPath(LOG_PATH)} or run ${c.reset}${c.cyan}claude-rpc doctor${c.reset}`);
+    return false;
+  }
   if (!quiet) console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
   return true;
 }
 
+// Confirm a freshly-spawned daemon actually came up, instead of trusting the
+// detached spawn (it can die a millisecond later — single-instance loss, a bad
+// path, a startup throw). Polls the pid file for liveness, since the daemon
+// claims it early in startup. Interactive callers (`start`) await this so the
+// user gets honest "it's up" / "it didn't come up" feedback rather than a
+// success message for a daemon that's already gone.
+async function confirmDaemonUp({ timeoutMs = 3000, intervalMs = 100 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    if (daemonPid()) {
+      console.log(`  ${c.green}✓${c.reset}  ${'daemon confirmed'.padEnd(16)}${c.dim}up — connecting to Discord${c.reset}`);
+      return true;
+    }
+    if (Date.now() >= deadline) {
+      console.log(`  ${c.yellow}!${c.reset}  ${'daemon check'.padEnd(16)}${c.dim}not up yet — see ${shortPath(LOG_PATH)} or run ${c.reset}${c.cyan}claude-rpc doctor${c.reset}`);
+      return false;
+    }
+  }
+}
+
 function stopDaemon({ quiet = false } = {}) {
   const pid = daemonPid();
   if (!pid) { if (!quiet) console.log(`  ${c.cyan}·${c.reset}  daemon not running`); return false; }
@@ -346,7 +369,7 @@ function todayBoxLines(vars, aggregate) {
 }
 
 function showStatus() {
-  const state = readState();
+  const state = readActiveState();
   const aggregate = readAggregate();
   const config = loadConfig();
   const live = findLiveSessions({ thresholdMs: 90_000 });
@@ -528,7 +551,7 @@ function showStatus() {
 }
 
 function showToday() {
-  const state = readState();
+  const state = readActiveState();
   const aggregate = readAggregate();
   const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
@@ -561,7 +584,7 @@ function showToday() {
 }
 
 function showWeek() {
-  const state = readState();
+  const state = readActiveState();
   const aggregate = readAggregate();
   const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
@@ -593,22 +616,7 @@ function showWeek() {
 
   // Current ISO week (Mon → Sun). Future days show "—".
   if (aggregate?.byDay) {
-    const now = new Date();
-    now.setHours(0, 0, 0, 0);
-    const monday = new Date(now);
-    monday.setDate(monday.getDate() - ((monday.getDay() + 6) % 7));
-    const days = [];
-    for (let i = 0; i < 7; i++) {
-      const d = new Date(monday);
-      d.setDate(d.getDate() + i);
-      const k = dayKey(d.getTime());
-      const dayName = ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'][d.getDay()];
-      const ms = aggregate.byDay[k]?.activeMs || 0;
-      const isFuture = d > now;
-      const isToday = k === dayKey(now.getTime());
-      days.push({ label: `${dayName} ${k.slice(5)}`, ms, isFuture, isToday });
-    }
-    const maxMs = Math.max(...days.map((d) => d.ms)) || 1;
+    const { days, maxMs } = weekGrid(aggregate.byDay);
     const lines = days.map(({ label, ms, isFuture, isToday }) => {
       if (isFuture) return `${c.dim}${label.padEnd(12)} ${'·'.repeat(22)}     —${c.reset}`;
       const h = ms / 3_600_000;
@@ -681,7 +689,7 @@ function statusColor(status) {
 }
 
 function showPreview() {
-  let state = readState();
+  let state = readActiveState();
   const aggregate = readAggregate();
   const config = loadConfig();
   const live = findLiveSessions({ thresholdMs: 90_000 });
@@ -744,7 +752,7 @@ function showPreview() {
 // dashboard having to inline-eval ESM source. Output shape matches the
 // previous helper exactly: { vars: [sorted keys], live: <full vars object> }.
 function dumpVars() {
-  let state = readState();
+  let state = readActiveState();
   const config = loadConfig();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   state = applyIdle(state, config);
@@ -971,7 +979,7 @@ async function doGithubStat(argv) {
 // Build the live template-variable table the way the daemon does — current
 // state + idle/stale resolution + aggregate. Shared by statusline/session-card.
 function liveVars() {
-  const state = readState();
+  const state = readActiveState();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   const config = loadConfig();
   const resolved = applyIdle(state, config);
@@ -1837,7 +1845,7 @@ function overview() {
   }
 
   // Status line: daemon up/down + project + model + status verb.
-  const state = readState();
+  const state = readActiveState();
   const aggregate = readAggregate();
   state.liveSessions = findLiveSessions({ thresholdMs: 90_000 });
   state.usage = readUsageCache();
@@ -2012,6 +2020,7 @@ process.on('unhandledRejection', (e) => {
             const child = spawn(process.execPath, [script || DAEMON_SCRIPT], {
               detached: true, stdio: 'ignore', windowsHide: true,
             });
+            child.on('error', () => {}); // never let a spawn ENOENT bubble as an unhandled crash
             child.unref();
             console.log(`  ${c.green}✓${c.reset}  ${'daemon launched'.padEnd(16)}${c.dim}pid ${c.reset}${c.cyan}${child.pid}${c.reset}${c.dim} · log ${shortPath(LOG_PATH)}${c.reset}`);
           } else {
@@ -2031,7 +2040,7 @@ process.on('unhandledRejection', (e) => {
     case 'upgrade-config':
       if (!migrateConfig()) console.log(`  ${c.green}✓${c.reset}  config already current — nothing to migrate`);
       break;
-    case 'start':     startDaemon(); break;
+    case 'start':     if (startDaemon()) await confirmDaemonUp(); break;
     case 'stop':      stopDaemon(); break;
     case 'restart':   restartDaemon(); break;
     case 'status': {

package/src/daemon.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { writeFileSync, readFileSync, existsSync, unlinkSync, watch, appendFileSync, mkdirSync, statSync, renameSync } from 'node:fs';
+import { existsSync, unlinkSync, watch, appendFileSync, mkdirSync, statSync, renameSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
 import { Client } from './discord-ipc.js';
 import { readState, sweepStaleStateTmp, listSessionStates, sweepStaleSessionStates } from './state.js';
-import { makeRotationCursor, pickFrames, selectFrame, resolveLargeImageKey, shouldShowGithubButton, pickActiveSession } from './presence.js';
+import { makeRotationCursor, pickFrames, selectFrame, resolveLargeImageKey, shouldShowGithubButton, pickActiveSession, throttleDecision } from './presence.js';
 import { buildVars, fillTemplate, framePasses, applyIdle, applyShipped, applyTrigger } from './format.js';
 import { scan, readAggregate, findLiveSessions, readSessionTokens } from './scanner.js';
 import { detectGithubUrl } from './git.js';
@@ -16,6 +16,7 @@ import { humanProject } from './format.js';
 import { CONFIG_PATH, STATE_PATH, PID_PATH, LOG_PATH, STATE_DIR, AGGREGATE_PATH, PAUSE_PATH } from './paths.js';
 import { readUsageCache, pollUsage } from './usage.js';
 import { pollDecision, pollIntervalMs } from './watch-poll.js';
+import { claimSingleInstance } from './ensure-daemon.js';
 
 if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true });
 
@@ -51,6 +52,19 @@ function log(...args) {
   process.stdout.write(line);
 }
 
+// Last-resort resilience. A presence daemon is best-effort and long-lived — it
+// must never die from an unexpected error in a non-critical path (a scan edge
+// case, a transient IPC oddity, a stray rejection). Log and keep running:
+// staying up is the entire point, and the periodic ticks/watchdog re-converge
+// from almost anything. Installed before any other startup work so even a boot
+// error is captured rather than killing us silently.
+process.on('uncaughtException', (e) => {
+  try { log('uncaughtException (continuing):', e?.stack || e?.message || String(e)); } catch { /* logging itself failed — nothing more we can do */ }
+});
+process.on('unhandledRejection', (e) => {
+  try { log('unhandledRejection (continuing):', e?.stack || e?.message || String(e)); } catch { /* see above */ }
+});
+
 // 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
@@ -78,7 +92,22 @@ let aggregate = readAggregate() || null;
 let liveSessions = [];
 let client = null;
 let connected = false;
-let lastPayloadHash = '';
+let connecting = false; // login() in flight — see the watchdog note in connect()
+// ── Outbound presence throttle ──────────────────────────────────────────────
+// Discord rate-limits SET_ACTIVITY hard (~5 writes per 20s); a burst past it
+// makes the client blank the presence until the writes stop — the actual
+// mechanism behind "the card sometimes looks buggy", since Claude fires hooks
+// in flurries. We never write faster than activityGapMs(): the first change
+// after a quiet gap goes out at once, and changes inside the gap coalesce to
+// the LATEST and flush once when it expires. See presence.throttleDecision.
+// `lastSentHash` is what we believe is on the wire — advanced ONLY after a
+// confirmed write, so a dropped/rate-limited write self-heals on the next push
+// instead of being recorded as success and stranded (the old optimistic-hash
+// bug, which stuck the card on a stale frame).
+let lastSentHash = '';
+let lastSentAt = 0;       // ms of the last write ATTEMPT (success or fail → back off either way)
+let pendingSend = null;   // { kind, activity, hash, logMsg } coalesced during the gap; latest wins
+let flushTimer = null;
 // Last status we acted on for outbound side-effects (webhook / desktop notify).
 // Tracked separately from the render hash so we fire once per transition.
 let lastNotifiedStatus = null;
@@ -104,25 +133,19 @@ let displayedSessionId = null;
 // either case would make startTimestamp jump on every rotation.
 let effectiveSessionStart = null;
 
-// Single-instance guard. The CLI checks before spawning, but off-path launches
-// (a login-startup entry racing a manual start; a packaged exe beside a dev
-// run) could start a second daemon that fights over setActivity every ~4s and
-// double-counts the additive community total. If a live daemon already owns the
-// PID file, step aside; a stale PID (owner gone) means take over.
-try {
-  if (existsSync(PID_PATH)) {
-    const existing = parseInt(readFileSync(PID_PATH, 'utf8'), 10);
-    if (existing && existing !== process.pid) {
-      let alive = false;
-      try { process.kill(existing, 0); alive = true; } catch { /* stale PID — take over */ }
-      if (alive) {
-        log(`Another daemon (pid ${existing}) is already running — exiting.`);
-        process.exit(0);
-      }
-    }
-  }
-} catch { /* unreadable PID file — fall through and claim it */ }
-writeFileSync(PID_PATH, String(process.pid));
+// Single-instance guard — an ATOMIC claim (see ensure-daemon.claimSingleInstance).
+// Many launchers can fire at once now that the SessionStart hook self-heals the
+// daemon: a manual `start`, a Windows Run entry, and several concurrent sessions'
+// hooks could all spawn a daemon in the same instant. A second daemon would
+// fight over setActivity every ~4s and double-count the additive community
+// total. The old read-then-write guard had a window where two starters both saw
+// "no live owner" and both wrote their pid; the exclusive-create claim closes it
+// so exactly one survives. A live owner → we exit; a stale pid → we reclaim it.
+const ownerPid = claimSingleInstance();
+if (ownerPid) {
+  log(`Another daemon (pid ${ownerPid}) is already running — exiting.`);
+  process.exit(0);
+}
 
 // Reclaim any per-pid state tmp files orphaned by a hard-killed writer, plus
 // per-session state files from sessions that ended long ago.
@@ -329,7 +352,12 @@ function fireStatusSideEffects(resolved, suppressed = false) {
   }
 }
 
-async function pushPresence() {
+// Compute the desired presence for the current state and hand it to the
+// throttle. Called from many triggers (hook-driven state changes, the periodic
+// tick, config/scan/session refreshes); transmit() collapses that into at most
+// one Discord write per activityGapMs(), so callers never have to think about
+// the rate limit. Best-effort throughout — presence must never crash the daemon.
+function pushPresence() {
   if (!connected || !client?.user) return;
   try {
     // Resolve state ONCE — this same object decides clear-vs-push, drives the
@@ -341,7 +369,7 @@ async function pushPresence() {
     const privacyHidden = resolved._privacy?.visibility === 'hidden';
     // Global snooze (`claude-rpc pause`) — clears the card while the deadline
     // is in the future. Re-checked every tick, so expiry resumes presence
-    // automatically (the 'cleared' stamp differs from the next frame's hash).
+    // automatically (the next frame's hash differs from the cleared sentinel).
     const pausedUntil = pauseUntil();
     const suppressed = privacyHidden || !!pausedUntil || (resolved.status === 'stale' && hideWhenStale);
 
@@ -352,44 +380,100 @@ async function pushPresence() {
     fireStatusSideEffects(resolved, suppressed);
 
     if (suppressed) {
-      const stamp = 'cleared';
-      if (lastPayloadHash === stamp) return;
-      lastPayloadHash = stamp;
       // Wipe effectiveSessionStart so the next active push gets a fresh
       // elapsed timer rather than counting from a previous session.
       effectiveSessionStart = null;
-      await client.user.clearActivity();
       const reason = pausedUntil
         ? `paused until ${new Date(pausedUntil).toLocaleTimeString()}`
         : privacyHidden ? 'privacy=hidden in this project' : 'stale — Claude Code not running';
-      log(`Presence cleared (${reason})`);
+      transmit('clear', null, `Presence cleared (${reason})`);
       return;
     }
 
     const activity = buildActivity({ resolved });
-    const hash = JSON.stringify(activity);
-    if (hash === lastPayloadHash) return;
-    lastPayloadHash = hash;
-    await client.user.setActivity(activity);
-    log('Presence updated:', activity.details || '-', '|', activity.state || '-');
+    transmit('set', activity, `Presence updated: ${activity.details || '-'} | ${activity.state || '-'}`);
+  } catch (e) {
+    log('pushPresence failed:', e.message);
+  }
+}
+
+// Minimum gap between Discord writes, read live so a config reload takes effect.
+// Floored at 2s as a sanity minimum; the 4s default keeps us under Discord's
+// ~5-per-20s SET_ACTIVITY limit (see default-config.minActivityGapMs).
+function activityGapMs() {
+  return Math.max(2000, config.minActivityGapMs || 4000);
+}
+
+// Sentinel for a clear — can never collide with a real activity hash, since
+// JSON.stringify of an activity object always begins with '{'.
+const CLEAR_HASH = 'cleared';
+
+// Route a desired payload (kind:'set'|'clear') through the rate-limit throttle.
+// 'send' writes now; 'defer' stashes the LATEST payload and arms a single flush
+// timer; 'skip' means the wire already shows this exact frame.
+function transmit(kind, activity, logMsg) {
+  const hash = kind === 'clear' ? CLEAR_HASH : JSON.stringify(activity);
+  const d = throttleDecision({
+    hash, lastSentHash, lastSentAt,
+    now: Date.now(), gapMs: activityGapMs(), flushPending: !!flushTimer,
+  });
+  if (d.action === 'skip') { pendingSend = null; return; }
+  if (d.action === 'send') { doSend({ kind, activity, hash, logMsg }); return; }
+  // defer — remember the LATEST payload and flush it once when the gap expires.
+  pendingSend = { kind, activity, hash, logMsg };
+  if (!flushTimer) {
+    flushTimer = setTimeout(flushPendingSend, d.waitMs);
+    if (flushTimer.unref) flushTimer.unref();
+  }
+}
+
+function flushPendingSend() {
+  flushTimer = null;
+  const p = pendingSend;
+  pendingSend = null;
+  if (!p || !connected || !client?.user) return;
+  if (p.hash === lastSentHash) return; // state reverted to what's already shown
+  doSend(p);
+}
+
+// The single point that actually writes to Discord. lastSentAt advances on every
+// ATTEMPT (so a failure backs off a full gap before retrying); lastSentHash
+// advances ONLY on success — a dropped/rate-limited write is therefore retried
+// by the next push rather than being recorded as success and stranded.
+async function doSend({ kind, activity, hash, logMsg }) {
+  lastSentAt = Date.now();
+  try {
+    if (kind === 'clear') await client.user.clearActivity();
+    else await client.user.setActivity(activity);
+    lastSentHash = hash;
+    log(logMsg);
   } catch (e) {
     log('setActivity failed:', e.message, '|', e.stack?.split('\n').slice(0, 3).join(' | '));
-    // A failed setActivity usually means the IPC pipe died WITHOUT the client
-    // emitting a 'disconnected' event (Discord restart, socket reset, OS
-    // sleep). Left alone, `connected` stays true and the daemon goes silently
-    // dark forever. Tear the client down and force a backoff reconnect so we
-    // self-heal. Guarded to connection-shaped errors so a one-off API hiccup
-    // doesn't needlessly bounce a healthy socket.
+    // A failed write usually means the IPC pipe died WITHOUT a 'disconnected'
+    // event (Discord restart, socket reset, OS sleep). Left alone, `connected`
+    // stays true and the daemon goes silently dark forever. Tear down and force
+    // a backoff reconnect so we self-heal — guarded to connection-shaped errors
+    // so a one-off app error (e.g. a rate-limit rejection) just waits for the
+    // next push's retry instead of needlessly bouncing a healthy socket.
     if (isConnectionError(e)) {
       log('setActivity error looks connection-level — forcing reconnect');
       connected = false;
-      lastPayloadHash = '';
+      resetTransmit();
       try { client?.destroy(); } catch { /* already gone */ }
       scheduleReconnect('setActivity failed');
     }
   }
 }
 
+// Force the next pushPresence to write even if the activity is byte-identical,
+// and drop any queued flush. Called when an input changed (config/aggregate/
+// scan/sessions) or the connection bounced — the new frame must go out fresh.
+function resetTransmit() {
+  lastSentHash = '';
+  pendingSend = null;
+  if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
+}
+
 // Heuristic: does this error indicate the IPC transport itself is dead
 // (vs. a transient/application-level failure)? Matches the common broken-pipe
 // / closed-socket shapes from our IPC client (src/discord-ipc.js) and the net
@@ -405,6 +489,10 @@ function isConnectionError(e) {
 
 async function connect() {
   if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+  // While login() is in flight, connected===false and reconnectTimer===null
+  // both hold, so the watchdog's "down, nothing pending" branch would spawn a
+  // second connect() that overwrites `client` and orphans this socket. Block it.
+  connecting = true;
   client = new Client({ clientId: config.clientId, transport: { type: 'ipc' } });
 
   client.on('ready', () => {
@@ -412,7 +500,7 @@ async function connect() {
     // 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 = '';
+    resetTransmit();
     pushPresence();
   });
   client.on('disconnected', () => {
@@ -422,6 +510,8 @@ async function connect() {
   try { await client.login(); }
   catch (e) {
     scheduleReconnect(`Discord login failed: ${e.message}`);
+  } finally {
+    connecting = false;
   }
 }
 
@@ -452,12 +542,12 @@ function watchFiles() {
     { path: CONFIG_PATH, label: 'config', onChange: () => {
       log('Config changed — reloading');
       config = loadConfigWithLog();
-      lastPayloadHash = '';
+      resetTransmit();
       pushPresence();
     } },
     { path: AGGREGATE_PATH, label: 'aggregate', onChange: () => {
       aggregate = readAggregate() || aggregate;
-      lastPayloadHash = '';
+      resetTransmit();
       pushPresence();
     } },
   ];
@@ -535,7 +625,7 @@ async function runBackgroundScan({ force = false } = {}) {
     const { aggregate: agg, scanned, skipped, removed, total } = scan({ force });
     aggregate = agg;
     log(`Scan complete: ${scanned} parsed / ${skipped} cached / ${removed} removed / ${total} total in ${Date.now() - t0}ms — allHours=${(agg.activeMs / 3_600_000).toFixed(1)}, sessions=${agg.sessions}, tokens=${(agg.inputTokens + agg.outputTokens)}`);
-    lastPayloadHash = '';
+    resetTransmit();
     pushPresence();
   } catch (e) {
     log('Scan failed:', e.message);
@@ -587,7 +677,7 @@ function refreshLiveSessions() {
     liveSessions = next;
     if (next.length !== prevCount) {
       log('Concurrent sessions:', next.length, next.map((s) => `${s.project}(${s.ageSec}s)`).join(', '));
-      lastPayloadHash = '';
+      resetTransmit();
       pushPresence();
     }
   } catch (e) {
@@ -609,7 +699,7 @@ const HEALTH_CHECK_MS = 30_000;
 setInterval(() => {
   try {
     // Half-open: flag says connected but there's no usable user handle.
-    if (connected && !client?.user) {
+    if (connected && !client?.user && !connecting) {
       log('Watchdog: connected but no user handle — forcing reconnect');
       connected = false;
       try { client?.destroy(); } catch { /* already gone */ }
@@ -618,7 +708,7 @@ setInterval(() => {
     }
     // Down with nothing scheduled to bring us back. scheduleReconnect is a
     // no-op when a timer is already pending, so this can't stack retries.
-    if (!connected && !reconnectTimer) {
+    if (!connected && !reconnectTimer && !connecting) {
       log('Watchdog: disconnected with no reconnect pending — forcing reconnect');
       scheduleReconnect('watchdog: no retry pending');
     }