claude-rpc 0.3.11 → 0.6.0

package/src/install.js

@@ -8,7 +8,7 @@ import {
   readdirSync, unlinkSync,
 } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import {
   CLAUDE_SETTINGS, CONFIG_PATH, USER_CONFIG_DIR, ROOT,
   HOOK_SCRIPT, IS_PACKAGED, IS_NPM_INSTALL,
@@ -135,10 +135,10 @@ function sweepStaleCanonicalBackups() {
     const prefix = CANONICAL_EXE_NAME + '.old-';
     for (const name of readdirSync(CANONICAL_INSTALL_DIR)) {
       if (name.startsWith(prefix)) {
-        try { unlinkSync(join(CANONICAL_INSTALL_DIR, name)); } catch {}
+        try { unlinkSync(join(CANONICAL_INSTALL_DIR, name)); } catch { /* file locked or vanished — sweep is best-effort */ }
       }
     }
-  } catch {}
+  } catch { /* install dir unreadable — nothing to sweep */ }
 }
 
 // Copy the running binary into CANONICAL_EXE if it's not already there.
@@ -160,7 +160,7 @@ export function ensureCanonicalExe(currentExe) {
         console.log(`  exe already installed → ${CANONICAL_EXE}`);
         return CANONICAL_EXE;
       }
-    } catch {}
+    } catch { /* stat failed — fall through to copy attempt */ }
   }
 
   try {
@@ -170,7 +170,7 @@ export function ensureCanonicalExe(currentExe) {
     // renamed copy when the process exits.
     if (process.platform === 'win32' && existsSync(CANONICAL_EXE)) {
       try { renameSync(CANONICAL_EXE, CANONICAL_EXE + '.old-' + Date.now()); }
-      catch {}
+      catch { /* not running, no rename needed — copyFileSync below will just overwrite */ }
     }
     copyFileSync(currentExe, CANONICAL_EXE);
     if (process.platform !== 'win32') chmodSync(CANONICAL_EXE, 0o755);
@@ -270,6 +270,39 @@ export function migrateConfig() {
   return true;
 }
 
+// Round-trip a synthetic SessionStart event through the same launcher
+// shape that Claude Code itself will use. Proves the hook command actually
+// resolves and runs — without this, `setup` could happily wire a broken
+// 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'];
+  let result;
+  try {
+    result = spawnSync(cmd, args, {
+      input: '',
+      encoding: 'utf8',
+      timeout: 3000,
+      windowsHide: true,
+    });
+  } catch (e) {
+    return { ok: false, detail: `spawn failed: ${e.message}` };
+  }
+  if (result.error) return { ok: false, detail: `spawn error: ${result.error.message}` };
+  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)}` };
+  }
+  return { ok: true, detail: 'SessionStart round-trip succeeded' };
+}
+
 export async function install({ exePath, withStartup = true } = {}) {
   if (process.platform !== 'win32' && withStartup) {
     console.warn('Note: startup registration only works on Windows; other steps still run.');
@@ -288,6 +321,18 @@ export async function install({ exePath, withStartup = true } = {}) {
     try { await addStartupEntry(target); }
     catch (e) { console.warn(`  startup entry failed: ${e.message}`); }
   }
+
+  // Proof the hook pipe actually fires. A setup that returns success
+  // without verification is a lie — we caught broken-hook-path bugs
+  // twice during v0.3.x because no one ran a real event after install.
+  const probe = verifyHookPipe(target);
+  if (probe.ok) {
+    console.log(`  hook pipe   ✓ ${probe.detail}`);
+  } else {
+    console.warn(`  hook pipe   ✗ ${probe.detail}`);
+    console.warn(`              ↳ run \`claude-rpc doctor\` for a full diagnostic`);
+  }
+
   console.log('\nDone.');
   console.log(`Edit ${CONFIG_PATH} to set your Discord clientId, then run:`);
   // Per-mode "start" instructions — packaged exe takes a daemon subcommand,
@@ -301,6 +346,7 @@ export async function install({ exePath, withStartup = true } = {}) {
     console.log(`  node "${join(ROOT, 'src', 'daemon.js').replace(/\\/g, '/')}"`);
     console.log(`  # or: claude-rpc start  (if you've run \`npm link\`)`);
   }
+  console.log(`\nThen: \`claude-rpc doctor\` to verify everything is wired.`);
 }
 
 export async function uninstall() {

package/src/pricing.js

@@ -29,16 +29,39 @@ const PRICING = {
 
 const DEFAULT = PRICING.sonnet;
 
+const TIERS = new Set(['opus', 'sonnet', 'haiku']);
+
 // Map a model id like "claude-opus-4-7-20251101" to a pricing key.
+//
+// The old implementation did `s.includes(key)` against the PRICING keys
+// sorted by descending length, which silently mis-routed any future model
+// id whose name contained one of those substrings out of order
+// (e.g. `claude-sonneteer-x` matching `sonnet`). Now: split the id on `-`,
+// find the first explicit tier token, then read the version digits that
+// follow. Falls back from `tier-major-minor` → `tier-major` → tier generic
+// → sonnet, in that order.
 export function pricingKeyFor(modelId) {
   if (!modelId) return 'sonnet';
-  const s = String(modelId).toLowerCase();
-  // Most specific match wins.
-  const candidates = Object.keys(PRICING).sort((a, b) => b.length - a.length);
-  for (const key of candidates) {
-    if (s.includes(key)) return key;
+  const parts = String(modelId).toLowerCase().split('-');
+
+  let tier = null;
+  let tierIdx = -1;
+  for (let i = 0; i < parts.length; i++) {
+    if (TIERS.has(parts[i])) { tier = parts[i]; tierIdx = i; break; }
+  }
+  if (!tier) return 'sonnet'; // unknown family — sonnet-class fallback
+
+  const major = parts[tierIdx + 1];
+  const minor = parts[tierIdx + 2];
+  if (major && /^\d+$/.test(major)) {
+    if (minor && /^\d+$/.test(minor)) {
+      const k = `${tier}-${major}-${minor}`;
+      if (PRICING[k]) return k;
+    }
+    const km = `${tier}-${major}`;
+    if (PRICING[km]) return km;
   }
-  return 'sonnet';
+  return tier; // generic tier rates
 }
 
 export function ratesFor(modelId) {

package/src/privacy.js

@@ -0,0 +1,231 @@
+// Privacy mode — controls what the Discord card shows about a given cwd.
+// Three layers, highest-priority first:
+//
+//   1. Per-project ./.claude-rpc.json file in the project root.
+//      { "visibility": "hidden|name-only|public", "projectName": "alias" }
+//      Shortcut: { "private": true } == { "visibility": "hidden" }
+//   2. Runtime list at ~/.claude-rpc/private-list.json, toggled by
+//      `claude-rpc private` / `claude-rpc public`.
+//   3. Auto-detection of GitHub private repos via the `gh` CLI when
+//      installed. Best-effort, silently skips when gh isn't available
+//      or auth isn't set up. Cached per-cwd with 5min TTL.
+//
+// "Visibility" levels:
+//   public      everything as-is (default)
+//   name-only   project name kept, but currentFile / currentTool / files
+//               arrays cleared so the card doesn't leak paths
+//   hidden      cwd cleared entirely; daemon then short-circuits to
+//               clearActivity (same effect as hideWhenStale)
+//
+// Aggregates (scanner) and the local TUI/web dashboards are NEVER affected
+// by these flags. Privacy is a one-way valve from local state → Discord.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, basename, dirname, resolve as resolvePath } from 'node:path';
+import { DATA_DIR } from './paths.js';
+
+const PRIVATE_LIST_PATH = join(DATA_DIR, 'private-list.json');
+const TTL_MS = 5 * 60 * 1000;
+
+const projectFileCache = new Map();   // cwd → { ts, value | null }
+const ghPrivateCache  = new Map();    // cwd → { ts, value: bool | null }
+
+// ── Per-project .claude-rpc.json ────────────────────────────────────────
+
+// Walk up from `cwd` looking for a .claude-rpc.json. Stops at the first
+// match or at a .git directory (the project root). Lets a subdirectory
+// inherit the parent's privacy config.
+function findProjectFile(cwd) {
+  if (!cwd) return null;
+  let dir = cwd;
+  while (true) {
+    const candidate = join(dir, '.claude-rpc.json');
+    if (existsSync(candidate)) return candidate;
+    if (existsSync(join(dir, '.git'))) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readProjectConfig(cwd) {
+  if (!cwd) return null;
+  const cached = projectFileCache.get(cwd);
+  if (cached && Date.now() - cached.ts < TTL_MS) return cached.value;
+  let value = null;
+  const path = findProjectFile(cwd);
+  if (path) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8'));
+      if (parsed && typeof parsed === 'object') value = parsed;
+    } catch { /* broken JSON ≡ no override */ }
+  }
+  projectFileCache.set(cwd, { ts: Date.now(), value });
+  return value;
+}
+
+function normalizeProjectConfig(cfg) {
+  if (!cfg) return null;
+  let visibility = cfg.visibility;
+  if (cfg.private === true && !visibility) visibility = 'hidden';
+  if (!['public', 'name-only', 'hidden'].includes(visibility)) visibility = null;
+  return {
+    visibility,
+    projectName: typeof cfg.projectName === 'string' ? cfg.projectName : null,
+  };
+}
+
+// ── Runtime private-list ────────────────────────────────────────────────
+
+function readPrivateList() {
+  if (!existsSync(PRIVATE_LIST_PATH)) return { paths: [] };
+  try {
+    const v = JSON.parse(readFileSync(PRIVATE_LIST_PATH, 'utf8'));
+    if (Array.isArray(v?.paths)) return v;
+  } catch { /* broken JSON ≡ no list (treat as empty rather than crash) */ }
+  return { paths: [] };
+}
+
+function writePrivateList(list) {
+  if (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });
+  writeFileSync(PRIVATE_LIST_PATH, JSON.stringify(list, null, 2));
+}
+
+export function addPrivateCwd(cwd) {
+  const list = readPrivateList();
+  const abs = resolvePath(cwd);
+  if (!list.paths.includes(abs)) {
+    list.paths.push(abs);
+    writePrivateList(list);
+  }
+  return list.paths;
+}
+
+export function removePrivateCwd(cwd) {
+  const list = readPrivateList();
+  const abs = resolvePath(cwd);
+  list.paths = list.paths.filter((p) => p !== abs);
+  writePrivateList(list);
+  return list.paths;
+}
+
+export function listPrivateCwds() {
+  return readPrivateList().paths;
+}
+
+function isInPrivateList(cwd) {
+  if (!cwd) return false;
+  const abs = resolvePath(cwd);
+  return readPrivateList().paths.some(
+    (p) => abs === p || abs.startsWith(p + '/') || abs.startsWith(p + '\\')
+  );
+}
+
+// ── GitHub-private detection (best-effort, gh CLI) ──────────────────────
+
+function detectGithubPrivate(cwd) {
+  if (!cwd) return null;
+  const cached = ghPrivateCache.get(cwd);
+  if (cached && Date.now() - cached.ts < TTL_MS) return cached.value;
+  let value = null;
+  try {
+    const out = execFileSync(
+      'gh',
+      ['repo', 'view', '--json', 'isPrivate', '-q', '.isPrivate'],
+      { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 }
+    ).toString().trim();
+    if (out === 'true') value = true;
+    else if (out === 'false') value = false;
+  } catch { /* gh missing, not auth'd, not a repo, timeout — unknown */ }
+  ghPrivateCache.set(cwd, { ts: Date.now(), value });
+  return value;
+}
+
+// ── Resolution + application ────────────────────────────────────────────
+
+// Resolve effective visibility for a cwd.
+// Returns: { visibility, projectName, reason }
+export function resolveVisibility(cwd, config = {}) {
+  const proj = normalizeProjectConfig(readProjectConfig(cwd));
+  if (proj?.visibility) {
+    return { visibility: proj.visibility, projectName: proj.projectName, reason: '.claude-rpc.json' };
+  }
+  if (isInPrivateList(cwd)) {
+    return { visibility: 'hidden', projectName: proj?.projectName ?? null, reason: 'private-list' };
+  }
+  const patterns = config?.privacy?.patterns || [];
+  if (patterns.length && cwd) {
+    const leaf = basename(cwd);
+    for (const p of patterns) {
+      if (matchesPattern(leaf, p)) {
+        const mode = config?.privacy?.mode || 'hidden';
+        return { visibility: mode, projectName: proj?.projectName ?? null, reason: `config pattern '${p}'` };
+      }
+    }
+  }
+  if (config?.privacy?.autoDetectGithubPrivate !== false) {
+    const isPrivate = detectGithubPrivate(cwd);
+    if (isPrivate === true) {
+      const mode = config?.privacy?.githubPrivateMode || 'hidden';
+      return { visibility: mode, projectName: proj?.projectName ?? null, reason: 'github private repo' };
+    }
+  }
+  return { visibility: 'public', projectName: proj?.projectName ?? null, reason: 'default' };
+}
+
+// Glob-lite. '*' matches any run; otherwise plain text. Case-insensitive.
+function matchesPattern(name, pattern) {
+  if (pattern === name) return true;
+  if (!pattern.includes('*')) return false;
+  const re = new RegExp('^' + pattern.split('*').map(escapeRe).join('.*') + '$', 'i');
+  return re.test(name);
+}
+function escapeRe(s) { return s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'); }
+
+// Apply privacy to a post-applyIdle state. Pure function — no IO.
+export function applyPrivacy(state, config = {}) {
+  if (!state || state.status === 'stale') return state;
+  const { visibility, projectName } = resolveVisibility(state.cwd || '', config);
+
+  if (visibility === 'public') {
+    if (projectName) {
+      return { ...state, cwd: joinCwdAlias(state.cwd, projectName), _privacy: { visibility, alias: true } };
+    }
+    return state;
+  }
+
+  if (visibility === 'name-only') {
+    return {
+      ...state,
+      cwd: projectName ? joinCwdAlias(state.cwd, projectName) : state.cwd,
+      currentTool: null,
+      currentFile: null,
+      filesEdited: [],
+      filesRead: [],
+      filesOpened: [],
+      _privacy: { visibility, alias: !!projectName },
+    };
+  }
+
+  // hidden
+  return {
+    ...state,
+    cwd: '',
+    currentTool: null,
+    currentFile: null,
+    filesEdited: [],
+    filesRead: [],
+    filesOpened: [],
+    _privacy: { visibility, alias: false },
+  };
+}
+
+function joinCwdAlias(cwd, alias) {
+  if (!cwd) return alias;
+  const sep = cwd.includes('\\') ? '\\' : '/';
+  const parts = cwd.split(/[\\/]/).filter(Boolean);
+  if (!parts.length) return alias;
+  parts[parts.length - 1] = alias;
+  return (cwd.startsWith('/') ? '/' : '') + parts.join(sep);
+}

package/src/scanner.js

@@ -1,5 +1,6 @@
 import { readdirSync, readFileSync, statSync, existsSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
+import { homedir } from 'node:os';
 import { CLAUDE_PROJECTS, SCAN_CACHE_PATH, AGGREGATE_PATH, DATA_DIR, EVENTS_LOG_PATH } from './paths.js';
 import { languageOf } from './languages.js';
 import { costFor, pricingKeyFor } from './pricing.js';
@@ -327,6 +328,18 @@ function listTranscripts(projectsDir) {
   return results;
 }
 
+// Walk multiple project roots in one pass. Used by scan() to support
+// `additionalProjectsDirs` config + the `claude-rpc backfill <path>` command
+// for ad-hoc imports. Deduplicates by absolute path so overlapping roots
+// don't double-count.
+function listAllTranscripts(dirs) {
+  const all = new Set();
+  for (const d of dirs) {
+    for (const fp of listTranscripts(d)) all.add(fp);
+  }
+  return Array.from(all);
+}
+
 function isSubagentPath(p) {
   return /[\\/]subagents[\\/]/.test(p);
 }
@@ -345,7 +358,7 @@ function readTranscriptCwd(path, mtimeMs) {
       const r = safeJson(line);
       if (r?.cwd) { cwd = r.cwd; break; }
     }
-  } catch {}
+  } catch { /* transcript head unreadable — cwd stays null, project name falls back to slug */ }
   cwdCache.set(path, { mtime: mtimeMs, cwd });
   return cwd;
 }
@@ -451,7 +464,7 @@ function readNotificationsByDay() {
       const k = dayKey(e.ts);
       out[k] = (out[k] || 0) + 1;
     }
-  } catch {}
+  } catch { /* events log unreadable/truncated — return whatever we got, the aggregate will just under-count notifications */ }
   return out;
 }
 
@@ -722,12 +735,45 @@ function aggregateFrom(cache) {
   return agg;
 }
 
+// Known alternate locations Claude Code transcripts could live in besides
+// ~/.claude/projects. Returned filtered to those that actually exist. Most
+// installs only use the default; this is for older Claude Code versions,
+// XDG-strict setups, or restored backups.
+export function discoverAltProjectDirs() {
+  const home = homedir();
+  const candidates = [
+    join(home, '.config', 'claude', 'projects'),
+    join(home, '.local', 'share', 'claude', 'projects'),
+    join(home, 'AppData', 'Roaming', 'claude', 'projects'),
+    join(home, 'AppData', 'Local', 'claude', 'projects'),
+    join(home, 'Library', 'Application Support', 'claude', 'projects'),
+  ];
+  return candidates.filter((p) => existsSync(p) && p !== CLAUDE_PROJECTS);
+}
+
 // Incremental scan: re-parse only changed files. Returns {aggregate, scanned, skipped, removed}.
-export function scan({ projectsDir = CLAUDE_PROJECTS, onProgress, force = false } = {}) {
+//
+// Accepts either:
+//   { projectsDir: '/path' }       — single root (legacy)
+//   { projectsDirs: ['a', 'b'] }   — multi-root (backfill/import)
+// When neither is set, defaults to [CLAUDE_PROJECTS, ...discoverAltProjectDirs()].
+// Auto-discovery is cheap (existsSync per known location) so it runs every
+// scan — a freshly-restored backup at one of the alt paths gets picked up
+// without any user action.
+export function scan({ projectsDir, projectsDirs, onProgress, force = false, extraDirs = [] } = {}) {
+  const dirs = [];
+  if (projectsDirs && projectsDirs.length) dirs.push(...projectsDirs);
+  else if (projectsDir) dirs.push(projectsDir);
+  else {
+    dirs.push(CLAUDE_PROJECTS);
+    dirs.push(...discoverAltProjectDirs());
+  }
+  for (const d of extraDirs) if (!dirs.includes(d)) dirs.push(d);
+
   const cache = readCache();
   cache.files = cache.files || {};
   const seen = new Set();
-  const transcripts = listTranscripts(projectsDir);
+  const transcripts = listAllTranscripts(dirs);
   let scanned = 0;
   let skipped = 0;
   for (const fp of transcripts) {
@@ -750,13 +796,22 @@ export function scan({ projectsDir = CLAUDE_PROJECTS, onProgress, force = false
       // skip corrupt file but keep prior cache entry
     }
   }
-  // Remove cache entries for deleted transcripts
+  // Remove cache entries for transcripts that disappeared from disk. Only
+  // wipe entries whose root is one of the dirs we just scanned — otherwise
+  // a one-off backfill against a subset of dirs would nuke cache for
+  // unrelated paths.
   let removed = 0;
+  const sep = process.platform === 'win32' ? '\\' : '/';
+  const dirPrefixes = dirs.map((d) => d.replace(/[/\\]+$/, '') + sep);
   for (const key of Object.keys(cache.files)) {
-    if (!seen.has(key)) { delete cache.files[key]; removed += 1; }
+    if (seen.has(key)) continue;
+    if (dirPrefixes.some((p) => key.startsWith(p))) {
+      delete cache.files[key];
+      removed += 1;
+    }
   }
   writeCache(cache);
   const aggregate = aggregateFrom(cache);
   writeAggregate(aggregate);
-  return { aggregate, scanned, skipped, removed, total: transcripts.length };
+  return { aggregate, scanned, skipped, removed, total: transcripts.length, dirs };
 }

package/src/server/api.js

@@ -0,0 +1,175 @@
+// Data-shape helpers used by the dashboard's /api routes. Pure functions
+// over the aggregate + state files; no HTTP concerns. Tested separately
+// from the routing layer.
+
+import { basename } from 'node:path';
+import { readState } from '../state.js';
+import { buildVars, fillTemplate, applyIdle, framePasses } from '../format.js';
+import { readAggregate, findLiveSessions, dayKey } from '../scanner.js';
+import { loadConfig as loadSharedConfig } from '../config.js';
+
+// Re-export under the historical name so any external callers (e.g. tests
+// that did `import { loadConfig } from '../api.js'`) still resolve.
+// Internally everything uses the shared loader so a bad config doesn't
+// blank out the dashboard with `{}` — it falls back to defaults.
+export function loadConfig() {
+  return loadSharedConfig();
+}
+
+export function rangeToDays(range) {
+  if (range === 'all') return Infinity;
+  if (range === '1y') return 365;
+  const n = parseInt(range, 10);
+  return Number.isFinite(n) && n > 0 ? n : 90;
+}
+
+// Filter byDay to a windowed slice; also recompute roll-ups (top files etc.)
+// scoped to that window. Returns a shape similar to the aggregate but trimmed.
+export function windowedAggregate(agg, range) {
+  if (!agg) return null;
+  const days = rangeToDays(range);
+  if (!Number.isFinite(days)) return agg; // 'all' → pass through
+
+  const today = new Date(); today.setHours(0, 0, 0, 0);
+  const keepKeys = new Set();
+  for (let i = 0; i < days; i++) {
+    const d = new Date(today); d.setDate(d.getDate() - i);
+    keepKeys.add(dayKey(d.getTime()));
+  }
+
+  const byDay = {};
+  let activeMs = 0, prompts = 0, toolCalls = 0, lines = 0, linesRem = 0, cost = 0, sessions = 0;
+  let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheWriteTokens = 0;
+  for (const [k, day] of Object.entries(agg.byDay || {})) {
+    if (!keepKeys.has(k)) continue;
+    byDay[k] = day;
+    activeMs += day.activeMs || 0;
+    prompts += day.userMessages || 0;
+    toolCalls += day.toolCalls || 0;
+    lines += day.linesAdded || 0;
+    linesRem += day.linesRemoved || 0;
+    cost += day.cost || 0;
+    sessions += day.sessions || 0;
+    inputTokens += day.inputTokens || 0;
+    outputTokens += day.outputTokens || 0;
+    cacheReadTokens += day.cacheReadTokens || 0;
+    cacheWriteTokens += day.cacheWriteTokens || 0;
+  }
+
+  return {
+    range,
+    byDay,
+    activeMs,
+    userMessages: prompts,
+    toolCalls,
+    linesAdded: lines,
+    linesRemoved: linesRem,
+    linesNet: lines - linesRem,
+    estimatedCost: cost,
+    sessions,
+    inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens,
+    grandTokens: inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens,
+    // Pass-through global keys for context.
+    streak: agg.streak,
+    longestStreak: agg.longestStreak,
+    daysSinceFirst: agg.daysSinceFirst,
+    peakHour: agg.peakHour,
+    bestDay: agg.bestDay,
+    projects: agg.projects || {},
+    toolBreakdown: agg.toolBreakdown || {},
+    topEditedFiles: agg.topEditedFiles || [],
+    languages: agg.languages || {},
+    bashCommands: agg.bashCommands || {},
+    webDomains: agg.webDomains || {},
+    subagents: agg.subagents || {},
+    costByModel: agg.costByModel || {},
+    modelsUsed: agg.modelsUsed || {},
+    mcpToolCalls: agg.mcpToolCalls || 0,
+    builtinToolCalls: agg.builtinToolCalls || 0,
+    byHour: agg.byHour || {},
+    byWeekday: agg.byWeekday || {},
+    notifications: agg.notifications || 0,
+  };
+}
+
+// Live snapshot: current state + lifetime aggregate + rendered rotation frames.
+// Used by GET /api/state — the SSE 'state' event tells the client to refetch.
+export function snapshot() {
+  const config = loadConfig();
+  const live = findLiveSessions({ thresholdMs: 90_000 });
+  let state = readState();
+  state.liveSessions = live;
+  state = applyIdle(state, config);
+  const aggregate = readAggregate() || {};
+  const vars = buildVars(state, config, aggregate);
+  const p = config.presence || {};
+  const frames = (p.rotation || []).map((f) => ({
+    details: fillTemplate(f.details || '', vars),
+    state: fillTemplate(f.state || '', vars),
+    passes: framePasses(f, vars),
+    requires: f.requires || null,
+  }));
+  return {
+    now: Date.now(),
+    state,
+    aggregate: {
+      sessions: aggregate.sessions,
+      subagentRuns: aggregate.subagentRuns,
+      userMessages: aggregate.userMessages,
+      toolCalls: aggregate.toolCalls,
+      uniqueFiles: aggregate.uniqueFiles,
+      activeMs: aggregate.activeMs,
+      wallMs: aggregate.wallMs,
+      inputTokens: aggregate.inputTokens,
+      outputTokens: aggregate.outputTokens,
+      cacheReadTokens: aggregate.cacheReadTokens,
+      cacheWriteTokens: aggregate.cacheWriteTokens,
+      byDay: aggregate.byDay || {},
+      byHour: aggregate.byHour || {},
+      byWeekday: aggregate.byWeekday || {},
+      projects: aggregate.projects || {},
+      toolBreakdown: aggregate.toolBreakdown || {},
+      topEditedFiles: (aggregate.topEditedFiles || []).slice(0, 12).map((e) => ({ file: basename(e.path), path: e.path, count: e.count })),
+      streak: aggregate.streak,
+      longestStreak: aggregate.longestStreak,
+      daysSinceFirst: aggregate.daysSinceFirst,
+      bestDay: aggregate.bestDay,
+      peakHour: aggregate.peakHour,
+      linesAdded: aggregate.linesAdded || 0,
+      linesRemoved: aggregate.linesRemoved || 0,
+      linesNet: aggregate.linesNet || 0,
+      languages: aggregate.languages || {},
+      bashCommands: aggregate.bashCommands || {},
+      webDomains: aggregate.webDomains || {},
+      subagents: aggregate.subagents || {},
+      mcpToolCalls: aggregate.mcpToolCalls || 0,
+      builtinToolCalls: aggregate.builtinToolCalls || 0,
+      estimatedCost: aggregate.estimatedCost || 0,
+      costByModel: aggregate.costByModel || {},
+      modelsUsed: aggregate.modelsUsed || {},
+      notifications: aggregate.notifications || 0,
+    },
+    vars,
+    frames,
+  };
+}
+
+export function projectDrilldown(name) {
+  const agg = readAggregate() || {};
+  const projects = agg.projects || {};
+  const project = projects[name];
+  if (!project) return null;
+  return {
+    name,
+    ...project,
+    files: (agg.topEditedFiles || []).slice(0, 25),
+    tools: agg.toolBreakdown || {},
+  };
+}
+
+export function dayDetail(dayKeyStr) {
+  const agg = readAggregate() || {};
+  const day = (agg.byDay || {})[dayKeyStr];
+  if (!day) return null;
+  return { day: dayKeyStr, ...day };
+}