claude-rpc 0.19.1 → 0.20.2

package/README.md

@@ -1,16 +1,21 @@
 <div align="center">
 
-<img src="https://cdn.qualit.ly/clawd-working-building.gif" width="120" alt="working" />
-<img src="https://cdn.qualit.ly/clawd-working-typing.gif" width="120" alt="thinking" />
-<img src="https://cdn.qualit.ly/clawd-notification.gif" width="120" alt="notification" />
-<img src="https://cdn.qualit.ly/clawd-sleeping.gif" width="120" alt="idle" />
+<img src="docs/header.svg" width="820" alt="claude-rpc — Discord Rich Presence for Claude Code: live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires. Install with: npx claude-rpc setup" />
 
-# claude-rpc
+<br/><br/>
 
-**Discord Rich Presence (RPC) for [Claude Code](https://claude.com/claude-code).**
-Your live model, project, current tool, tokens, and lifetime stats — in your Discord profile. Driven by the hooks Claude Code already fires. Zero polling between sessions.
+<img src="https://cdn.qualit.ly/clawd-working-building.gif" width="104" alt="working" />
+<img src="https://cdn.qualit.ly/clawd-working-typing.gif" width="104" alt="thinking" />
+<img src="https://cdn.qualit.ly/clawd-notification.gif" width="104" alt="waiting on you" />
+<img src="https://cdn.qualit.ly/clawd-sleeping.gif" width="104" alt="idle" />
 
-**→ [claude-rpc.vercel.app](https://claude-rpc.vercel.app)** — what it looks like, in one page.
+<sub>the card's live states — <b>working</b> · <b>thinking</b> · <b>waiting</b> · <b>idle</b></sub>
+
+<br/>
+
+**Discord Rich Presence for [Claude Code](https://claude.com/claude-code)** — your live model, project, tokens, and lifetime stats, driven by the hooks Claude Code already fires.
+
+**[claude-rpc.vercel.app →](https://claude-rpc.vercel.app)** — see it in one page.
 
 [![community · sessions](https://claude-rpc-totals.claude-rpc.workers.dev/sessions.svg)](#community-totals) &nbsp; [![community · tokens](https://claude-rpc-totals.claude-rpc.workers.dev/tokens.svg)](#community-totals)
 
@@ -144,7 +149,11 @@ claude-rpc card  --range year                 --out year-on-claude.svg
 ```
 
 <div align="center">
-  <img src="site/examples/year-on-claude.svg" width="560" alt="Year-on-claude card — hours, prompts, tokens, lines, cost, daily activity strip" />
+  <img src="site/examples/week-on-claude.svg"  width="270" alt="Week-on-claude summary card" />
+  <img src="site/examples/month-on-claude.svg" width="270" alt="Month-on-claude summary card" />
+  <img src="site/examples/year-on-claude.svg"  width="270" alt="Year-on-claude summary card — hours, prompts, tokens, lines, cost, daily activity strip" />
+  <br/>
+  <sub><code>card --range week · month · year</code> (also <code>all</code>) — live at <code>/api/card.svg</code> while the daemon's up</sub>
 </div>
 
 `badge --gist` writes the SVG to your own GitHub gist (creates one on first run, updates it after — id remembered in `config.json`). The URL printed back is README-ready and updates every time you re-run the command. Uses `gh` if available, else `GH_TOKEN` with `gist` scope.
@@ -173,21 +182,9 @@ For a complete account of the sensitive things claude-rpc does — startup persi
 
 ## three pieces, glued by json files
 
-```
-   Claude Code                                          Discord desktop
-        │                                                     ▲
-        │ lifecycle event (stdin JSON)                        │ IPC frame
-        ▼                                                     │
-   ┌──────────┐    state.json    ┌──────────┐                 │
-   │ hook.js  │ ───────────────▶ │ daemon.js│ ────────────────┘
-   └──────────┘                  └──────────┘
-                                       ▲
-                                       │ aggregate.json
-                                       │
-                                ┌────────────┐
-                                │ scanner.js │ ◀── ~/.claude/projects/*.jsonl
-                                └────────────┘
-```
+<div align="center">
+  <img src="docs/architecture.svg" width="760" alt="Architecture: Claude Code fires a lifecycle event (stdin JSON) into hook.js, which writes state.json; daemon.js reads it and pushes an IPC frame to the Discord desktop client. scanner.js reads the ~/.claude/projects transcripts and feeds aggregate.json into daemon.js." />
+</div>
 
 No database, no message bus, no background polling when Claude Code isn't running. State on disk you can `cat` and `jq`. **Zero runtime dependencies** — even the Discord Rich Presence IPC client is hand-rolled (`src/discord-ipc.js`).
 
@@ -263,6 +260,13 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 
 ## commands
 
+`claude-rpc --help` lists them all — and after `setup` you rarely need any.
+
+<details>
+<summary><b>full command reference</b></summary>
+
+<br/>
+
 | Command          | What it does |
 | ---------------- | ------------ |
 | `setup`          | Install Claude Code hooks (test-fires one synthetic SessionStart to prove the pipe works) |
@@ -295,19 +299,28 @@ The full default config is in [`src/default-config.js`](src/default-config.js)
 
 Exit codes: `0` ok · `1` user error · `2` system error · `3` wrong state. `--version` and `--help` work as expected.
 
+</details>
+
 ## troubleshooting
 
-**First step is always `claude-rpc doctor`.** It checks Node version, hook registration, daemon liveness, Discord IPC connection, aggregate freshness, and privacy resolution — with a one-line fix hint per failure.
+**First step is always `claude-rpc doctor`** — it checks Node, hook registration, daemon liveness, Discord IPC, aggregate freshness, and privacy resolution, with a one-line fix hint per failure.
+
+<details>
+<summary><b>common issues</b></summary>
+
+<br/>
 
 - **Discord doesn't show anything.** Discord *desktop* must be running. The browser client doesn't expose the local IPC bridge. `claude-rpc tail` shows what the daemon is actually doing.
 - **Hooks don't fire.** `claude-rpc setup` re-registers them and now test-fires a synthetic `SessionStart` end-to-end, so a broken hook command surfaces immediately. Restart Claude Code afterwards so it re-reads its hook config.
 - **Config error.** Bad JSON in `config.json` no longer crashes anything — the daemon logs one line and falls back to baked defaults. `claude-rpc tail` shows the parse error verbatim.
 - **Old binary path baked into hooks.** Common after manual exe replacement. `claude-rpc setup` rewrites hook entries to point at the canonical install location.
 
+</details>
+
 ## development
 
 ```sh
-npm test                  # 270+ tests, ~2s
+npm test                  # 430+ tests, ~2s
 npm run lint              # eslint over src + test
 npm run start             # run daemon in foreground
 npm run serve             # web dashboard against your real data
@@ -315,9 +328,7 @@ npm run dashboard         # Electron settings GUI (dev mode)
 npm run build:exe         # SEA single-file binary for the current OS
 ```
 
-Tests are `node --test` with zero deps. The CI pipeline ([release.yml](.github/workflows/release.yml)) runs the suite (plus the Cloudflare Worker's own tests) across Node 18/20/22 and gates the matrix build and the npm publish behind it. Every pure/logic module in `src/*.js` is unit-tested, including the MCP transport and the SVG renderers; the long-running daemon, the TUI, and the CLI dispatcher are covered by integration and manual smoke testing rather than unit tests.
-
-Where the project is headed (and what it will deliberately never do) lives in [`ROADMAP.md`](ROADMAP.md).
+Tests are `node --test`, zero deps; CI ([release.yml](.github/workflows/release.yml)) runs the suite (+ the Worker's) across Node 18/20/22 and gates the matrix build and npm publish. Where the project's headed (and what it'll deliberately never do): [`ROADMAP.md`](ROADMAP.md).
 
 ## license
 

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.19.1",
+  "version": "0.20.2",
   "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/cli.js

@@ -10,23 +10,59 @@ 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 { 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';
-import { generateInsights } from './insights.js';
-import { maybeNudge, pickTodayMilestone } from './nudge.js';
-import { badgeSvg } from './badge.js';
-import { fmtCost } from './pricing.js';
-import { addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } from './privacy.js';
 import { parseDuration, setPause, clearPause, pauseUntil } from './pause.js';
-import { readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } from './usage.js';
 import { loadConfig, hasUserConfig } from './config.js';
-import * as lb from './leaderboard.js';
+import { spawnDaemonDetached } from './ensure-daemon.js';
+
+// ── Lazy-loaded heavy module graph ───────────────────────────────────────────
+// format→scanner→pricing→languages→git→usage (plus install/tui/insights/nudge/
+// badge/privacy/leaderboard) is ~60ms of module-load that the fast-exit commands
+// (--version, --help, start, stop, restart) never touch. We declare the bindings
+// here and fill them via loadStats() only for commands that actually fan out into
+// the stats/format/install code, so daemon-control and version stay near-instant.
+// (The repo already lazy-imports cold deps like doctor.js/card.js/mcp.js inside
+// their handlers — this just extends that to the graph the main switch needs.)
+let buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum;
+let scan, readAggregate, findLiveSessions, dayKey, weekKey;
+let weekGrid;
+let runInstall, runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro;
+let startTui;
+let generateInsights;
+let maybeNudge, pickTodayMilestone;
+let badgeSvg;
+let fmtCost;
+let addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility;
+let readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay;
+let lb;
+
+let statsLoaded = false;
+async function loadStats() {
+  if (statsLoaded) return;
+  // Load the graph concurrently — these are all leaf-ish modules with no
+  // ordering dependency, so Promise.all beats a sequential import chain.
+  const [fmt, scn, wk, inst, tui, ins, ndg, bdg, prc, priv, usg, leaderboard] = await Promise.all([
+    import('./format.js'), import('./scanner.js'), import('./week.js'),
+    import('./install.js'), import('./tui.js'), import('./insights.js'),
+    import('./nudge.js'), import('./badge.js'), import('./pricing.js'),
+    import('./privacy.js'), import('./usage.js'), import('./leaderboard.js'),
+  ]);
+  ({ buildVars, fillTemplate, humanProject, humanTool, applyIdle, framePasses, fmtNum } = fmt);
+  ({ scan, readAggregate, findLiveSessions, dayKey, weekKey } = scn);
+  ({ weekGrid } = wk);
+  ({ install: runInstall, uninstall: runUninstall, isInstalled, migrateConfig, installHooks, ensureCanonicalExe, installMcp, uninstallMcp, setupOutro } = inst);
+  ({ startTui } = tui);
+  ({ generateInsights } = ins);
+  ({ maybeNudge, pickTodayMilestone } = ndg);
+  ({ badgeSvg } = bdg);
+  ({ fmtCost } = prc);
+  ({ addPrivateCwd, removePrivateCwd, listPrivateCwds, resolveVisibility } = priv);
+  ({ readUsageCache, fetchUsage, writeUsageCache, fmtResetTime, fmtResetDay } = usg);
+  lb = leaderboard;
+  statsLoaded = true;
+}
 import { VERSION } from './version.js';
 import { fail, tailLines, heat, sparkline, fmtDelta, topPercentile, EX_USER_ERROR, EX_BAD_STATE, EX_SYS_ERROR } from './ui.js';
 import { randomUUID } from 'node:crypto';
@@ -96,18 +132,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; }
@@ -1950,6 +2007,12 @@ process.on('unhandledRejection', (e) => {
 // ESM (dev) and CommonJS (esbuild → SEA bundle) — CJS doesn't allow
 // top-level await.
 (async () => {
+  // Fast-exit commands touch none of the lazy stats/format/install graph, so
+  // skip the module load and keep them instant. Everything else loads it once
+  // up front, which makes every binding available to the handlers below exactly
+  // as before. (daemon/serve/wrapped/hook only dynamic-import their own module.)
+  const FAST_PATHS = new Set(['--version', '-V', '-v', '--help', '-h', 'help', 'start', 'stop', 'restart', 'hook', 'daemon', 'serve', 'wrapped']);
+  if (!FAST_PATHS.has(cmd)) await loadStats();
   switch (cmd) {
     case '--version':
     case '-V':
@@ -1998,6 +2061,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 {
@@ -2017,7 +2081,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
@@ -79,7 +93,21 @@ let liveSessions = [];
 let client = null;
 let connected = false;
 let connecting = false; // login() in flight — see the watchdog note in connect()
-let lastPayloadHash = '';
+// ── 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;
@@ -105,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.
@@ -330,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
@@ -342,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);
 
@@ -353,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
@@ -417,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', () => {
@@ -459,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();
     } },
   ];
@@ -542,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);
@@ -594,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) {

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/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/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/presence.js

@@ -96,6 +96,30 @@ export function shouldShowGithubButton(p, state) {
   return true;
 }
 
+// Decide how to transmit a candidate presence payload without tripping Discord's
+// SET_ACTIVITY rate limit. Discord hard-limits activity writes (~5 per 20s) and
+// punishes a burst — calling it ~10× in 5s makes the client EMPTY the presence
+// and stop updating until the writes stop (discord-api-docs#668). Claude Code
+// fires PreToolUse/PostToolUse hooks back-to-back through a flurry of quick
+// Reads/Edits, so the daemon would otherwise write many times a second. The
+// Game SDK claims to coalesce-and-queue for you; raw IPC (what we speak) gives
+// no such cushion, so we throttle ourselves.
+//
+// This is the leading+trailing decision — pure so it's unit-testable; the daemon
+// owns the wall clock, the last-sent bookkeeping, and the flush timer:
+//   - 'skip'  : byte-identical to what's already on the wire — do nothing
+//   - 'send'  : the gap has elapsed and nothing is queued — write immediately
+//               (snappy idle→thinking→working transitions)
+//   - 'defer' : inside the gap, or a flush is already queued — coalesce to the
+//               LATEST payload and let the caller flush it in `waitMs`, so the
+//               final state of every burst still lands, once, under the limit
+export function throttleDecision({ hash, lastSentHash, lastSentAt, now, gapMs, flushPending }) {
+  if (hash === lastSentHash) return { action: 'skip', waitMs: 0 };
+  const waitMs = Math.max(0, (lastSentAt || 0) + gapMs - now);
+  if (waitMs === 0 && !flushPending) return { action: 'send', waitMs: 0 };
+  return { action: 'defer', waitMs };
+}
+
 // Large-image key precedence (returns the TEMPLATE string; the caller fills it):
 //   1. statusAssets[status]          per-status art ("working" gif, etc.)
 //   2. modelAssets[fable|opus|sonnet|haiku|default]   per-model art, never stale

package/src/scanner.js

@@ -439,8 +439,15 @@ function parseChunkInto(text, summary, pstate) {
 // null) falls back to a from-scratch parse.
 export function parseTranscript(filePath, prev = null) {
   const st = statSync(filePath);
+  // Append only if this is the SAME file that grew: the current size must be
+  // >= the size at the last parse (mirrors readSessionTokens). The old check,
+  // `st.size >= prev._offset`, was too weak — a rewrite to a size between the
+  // consumed offset and the prior file size would wrongly append onto stale
+  // counts (the leading bytes are now different content), silently corrupting
+  // lifetime stats. A cache entry predating _size has no size to compare, so it
+  // falls back to a full re-parse (which then stamps _size going forward).
   const canAppend = !!(prev && prev._parse && typeof prev._offset === 'number'
-    && st.size >= prev._offset);
+    && typeof prev._size === 'number' && st.size >= prev._size);
   const summary = canAppend ? structuredClone(prev) : blankTranscriptSummary();
   const pstate = canAppend
     ? { recentIds: (prev._parse.recentIds || []).slice(), lastRec: prev._parse.lastRec || null }
@@ -481,6 +488,7 @@ export function parseTranscript(filePath, prev = null) {
     // else: a partial line mid-write — leave it for the next (append) read.
   }
   summary._offset = offset;
+  summary._size = st.size; // file size at this parse — guards the append fast-path above
   summary._parse = { recentIds: pstate.recentIds, lastRec: pstate.lastRec };
   return summary;
 }
@@ -721,10 +729,11 @@ export function readAggregate() {
 
 export { dayKey, weekKey, hourKey };
 
-function aggregateFrom(cache) {
+export function aggregateFrom(cache) {
   const agg = {
     sessions: 0,
     subagentRuns: 0,
+    subagentActiveMs: 0,
     inputTokens: 0,
     outputTokens: 0,
     cacheReadTokens: 0,
@@ -814,6 +823,15 @@ function aggregateFrom(cache) {
     }
     if (isSub) {
       agg.subagentRuns += 1;
+      // Subagent active time is tracked separately and deliberately NOT folded
+      // into agg.activeMs. A subagent's wall-time overlaps its parent session
+      // (and parallel subagents overlap each other), and gaps >=5min are already
+      // excluded from the parent's activeMs (see ACTIVE_GAP_CAP_MS) — so summing
+      // the scalar would double-count short subagents. agg.activeMs stays an
+      // interactive-session measure; subagentActiveMs exposes delegated work as
+      // its own honest number. A single unified figure would need interval-union
+      // across parent+subagents, not scalar sums.
+      agg.subagentActiveMs += summary.activeMs || 0;
       // Subagents still contribute tokens/tools/lines/cost to per-day/week/hour buckets.
       const mergeSubBuckets = (srcMap, destMap) => {
         for (const [k, src] of Object.entries(srcMap || {})) {

package/src/version.js

@@ -11,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT } from './paths.js';
 
-const BAKED = '0.19.1';
+const BAKED = '0.20.2';
 
 function readPkgVersion() {
   try {