claude-code-session-manager 0.14.0 → 0.16.0

package/src/main/index.cjs

@@ -1,4 +1,4 @@
-const { app, BrowserWindow, ipcMain, dialog, Menu, session, systemPreferences, globalShortcut, shell, clipboard } = require('electron');
+const { app, BrowserWindow, ipcMain, dialog, Menu, session, systemPreferences, globalShortcut, shell, clipboard, powerSaveBlocker, protocol } = require('electron');
 const { spawn, execFile, execFileSync } = require('node:child_process');
 const path = require('node:path');
 const fs = require('node:fs');
@@ -9,6 +9,7 @@ const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
 const { manager: ptyManager, registerPtyHandlers } = require('./pty.cjs');
 const configMgr = require('./config.cjs');
 const transcripts = require('./transcripts.cjs');
+const usageMatrix = require('./usageMatrix.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 const billing = require('./usage.cjs');
 const logs = require('./logs.cjs');
@@ -34,11 +35,14 @@ const searchIpc = require('./search.cjs');
 const repoAnalyzer = require('./repoAnalyzer.cjs');
 const hivesIpc = require('./hives.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
-const { checkInsideHome } = require('./lib/insideHome.cjs');
+const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');
 const { openInEditor, openFileInEditor, openInFinder, openInTerminal } = require('./lib/openExternalApp.cjs');
 
 let mainWindow = null;
 let rebooting = false;
+// powerSaveBlocker handle — keeps the system from suspending while the app runs
+// so the scheduler's polling and jobs aren't frozen. -1 = not held.
+let powerBlockerId = -1;
 
 // Boot diagnostics — populated at app.whenReady so the renderer can poll their
 // state via IPC and surface toasts on the failure paths. The first-paint
@@ -187,6 +191,7 @@ async function rebootApp() {
     ptyManager.attachWindow(mainWindow);
     configMgr.attachWindow(mainWindow);
     transcripts.attachWindow(mainWindow);
+    usageMatrix.attachWindow(mainWindow);
     voiceHotkey.init(mainWindow).catch((e) => {
       logs.writeLine({ scope: 'voice-hotkey', level: 'error', message: 'reinit failed', meta: { error: e?.message } });
     });
@@ -546,6 +551,7 @@ ipcMain.handle('app:archive-project', validated(schemas.archiveProject, async ({
 registerPtyHandlers();
 configMgr.registerConfigHandlers();
 transcripts.registerTranscriptHandlers();
+usageMatrix.registerHandlers();
 sessionsStore.registerSessionsHandlers();
 billing.registerBillingHandlers();
 logs.registerLogHandlers();
@@ -591,6 +597,29 @@ if (process.env.SM_E2E === '1') {
   try { app.disableHardwareAcceleration(); } catch { /* */ }
 }
 
+// smfile:// — privileged scheme that serves home-scoped files to the in-app
+// Editor's HTML preview iframe. Loading the user's HTML via a custom scheme
+// (rather than srcdoc) gives the iframe document its OWN origin + empty CSP, so
+// the page's own visualization scripts run — while the iframe is still
+// sandboxed without allow-same-origin (opaque origin), keeping it walled off
+// from the host app, its IPC bridge, and the user's filesystem. Must be
+// registered before app.whenReady() (Electron rejects late scheme privileges).
+protocol.registerSchemesAsPrivileged([
+  { scheme: 'smfile', privileges: { standard: true, secure: true, supportFetchAPI: true, stream: true } },
+]);
+
+// Common content types for previewed assets. Anything unknown is served as
+// octet-stream so the browser sniffs / downloads rather than mis-rendering.
+const SMFILE_MIME = {
+  '.html': 'text/html', '.htm': 'text/html',
+  '.css': 'text/css', '.js': 'text/javascript', '.mjs': 'text/javascript',
+  '.json': 'application/json', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf',
+  '.txt': 'text/plain', '.csv': 'text/csv', '.xml': 'application/xml',
+};
+
 // Single-instance lock (PRD F1 v2 §requestSingleInstanceLock).
 // In dev mode we skip the lock so two-dev-instance workflows still work.
 // E2E tests also skip so playwright.electron.launch can run multiple specs
@@ -682,7 +711,7 @@ app.whenReady().then(async () => {
     // — adds ~3 packages and ~2MB to the renderer build; the network fetch
     // happens once per cold launch and is cached by Electron's HTTP cache.
     "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com",
-    "img-src 'self' data: blob:",
+    "img-src 'self' data: blob: smfile:",
     "font-src 'self' data: https://fonts.gstatic.com",
     // schemastore.org is used by Monaco for JSON schema validation
     // (settings.json, keybindings.json — see App.tsx::installMonacoSchemas).
@@ -691,10 +720,18 @@ app.whenReady().then(async () => {
     "connect-src 'self' https://api.anthropic.com https://registry.npmjs.org https://json.schemastore.org https://www.schemastore.org",
     "media-src 'self' blob:",
     "worker-src 'self' blob:",
-    "frame-src 'none'",
+    // smfile: powers the Editor's sandboxed HTML preview iframe. The iframe is
+    // sandboxed WITHOUT allow-same-origin, so its document has an opaque origin
+    // and cannot reach the host even though it may run its own scripts.
+    "frame-src smfile:",
     "frame-ancestors 'none'",
   ].join('; ') + ';';
   session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
+    // smfile:// serves the Editor's HTML-preview documents. They must NOT
+    // inherit the app CSP — `frame-ancestors 'none'` would forbid framing them,
+    // and `script-src 'self'` would block the page's own visualization scripts.
+    // Isolation comes from the iframe sandbox (opaque origin), not from CSP.
+    if (details.url.startsWith('smfile:')) { cb({}); return; }
     cb({
       responseHeaders: {
         ...details.responseHeaders,
@@ -703,6 +740,29 @@ app.whenReady().then(async () => {
     });
   });
 
+  // smfile:// handler — serves a single home-scoped file for the Editor's HTML
+  // preview iframe (and its relative assets: ./chart.js, ./data.json, images).
+  // URL shape: smfile://local/<absolute-path>. The pathname IS the absolute
+  // path; assertInsideHome enforces containment + rejects symlink escapes. The
+  // sandboxed iframe's relative requests resolve against this same scheme, so
+  // co-located assets load while everything stays inside home.
+  protocol.handle('smfile', async (request) => {
+    try {
+      const url = new URL(request.url);
+      const abs = decodeURIComponent(url.pathname);
+      const { realPath } = assertInsideHome(abs); // throws if outside home
+      const st = await fs.promises.stat(realPath);
+      if (st.isDirectory()) return new Response('Not a file', { status: 404 });
+      if (st.size > 25 * 1024 * 1024) return new Response('Too large', { status: 413 });
+      const buf = await fs.promises.readFile(realPath);
+      const ext = path.extname(realPath).toLowerCase();
+      const type = SMFILE_MIME[ext] || 'application/octet-stream';
+      return new Response(buf, { headers: { 'content-type': type } });
+    } catch (err) {
+      return new Response(`smfile error: ${err && err.message}`, { status: 404 });
+    }
+  });
+
   // Grant microphone / media permissions only for trusted origins.
   const MEDIA_PERMS = new Set(['media', 'audioCapture', 'microphone']);
   const isTrustedOrigin = (url) =>
@@ -777,6 +837,7 @@ app.whenReady().then(async () => {
   ptyManager.attachWindow(mainWindow);
   configMgr.attachWindow(mainWindow);
   transcripts.attachWindow(mainWindow);
+  usageMatrix.attachWindow(mainWindow);
   voiceHotkey.init(mainWindow).catch((e) => {
     logs.writeLine({ scope: 'voice-hotkey', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
@@ -788,6 +849,19 @@ app.whenReady().then(async () => {
     logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
 
+  // Keep the machine awake while the app is open. The scheduler polls billing
+  // usage every 2 min and runs `claude -p` jobs that must survive an idle
+  // laptop — a system suspend (GNOME/Pop!_OS idle or lid timeout) would freeze
+  // both. `prevent-app-suspension` stops suspend but still lets the display
+  // dim/sleep, so battery impact is limited to keeping the CPU resumable.
+  // On Linux this routes through the org.freedesktop.login1 inhibitor.
+  try {
+    powerBlockerId = powerSaveBlocker.start('prevent-app-suspension');
+    logs.writeLine({ scope: 'main', level: 'info', message: 'powerSaveBlocker started', meta: { id: powerBlockerId } });
+  } catch (e) {
+    logs.writeLine({ scope: 'main', level: 'warn', message: 'powerSaveBlocker failed', meta: { error: e?.message } });
+  }
+
   // OTEL: load persisted config and start the exporter only if `enabled`.
   // Failures are non-fatal — the app must keep working without telemetry.
   otelSettings.load()
@@ -806,6 +880,10 @@ app.on('will-quit', () => {
   // PRD F1 v2 §IPC plumbing: must unregisterAll on will-quit.
   try { globalShortcut.unregisterAll(); } catch { /* */ }
   voiceHotkey.disposeOnQuit();
+  if (powerBlockerId !== -1) {
+    try { powerSaveBlocker.stop(powerBlockerId); } catch { /* */ }
+    powerBlockerId = -1;
+  }
 });
 
 app.on('window-all-closed', () => {

package/src/main/transcripts.cjs

@@ -25,6 +25,7 @@ const os = require('node:os');
 const chokidar = require('chokidar');
 const otel = require('./otel.cjs');
 const logs = require('./logs.cjs');
+const usageMatrix = require('./usageMatrix.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 
 let window = null;
@@ -142,6 +143,14 @@ async function flush(sub, { emit = true } = {}) {
     // Ring buffer (cap at 500 entries to bound memory).
     sub.buffer.push(ev);
     if (sub.buffer.length > 500) sub.buffer.shift();
+    // Feed the AgOps aggregator on every event — both replay and live, so
+    // freshly-attached tabs land with full history reflected in the matrix.
+    usageMatrix.recordEvent({
+      tabId: sub.tabId,
+      cwd: sub.cwd,
+      sessionUuid: sub.sessionUuid,
+      ev,
+    });
     if (emit) sendIfAlive(window, `transcript:event:${sub.tabId}`, ev);
     // Mirror to OTEL — no-op when disabled. We emit on the initial drain too
     // so backfilled transcripts show up in the trace store.
@@ -206,6 +215,8 @@ function unsubscribe(tabId) {
   if (!sub) return;
   sub.watcher?.close().catch(() => {});
   subs.delete(tabId);
+  // Drop the tab from the AgOps matrix — "active sessions" only.
+  usageMatrix.removeTab(tabId);
 }
 
 function getBuffer(tabId) {
@@ -216,6 +227,7 @@ function getBuffer(tabId) {
 function closeAll() {
   for (const sub of subs.values()) sub.watcher?.close().catch(() => {});
   subs.clear();
+  usageMatrix.closeAll();
 }
 
 function registerTranscriptHandlers() {

package/src/main/usageMatrix.cjs

@@ -0,0 +1,336 @@
+/**
+ * usageMatrix.cjs — per-tab agentic-ops aggregator.
+ *
+ * Watches the same classified transcript events that transcripts.cjs streams
+ * to the renderer and maintains a small rolling state per tab: turn count,
+ * token velocity (5-min window), cache age, subagent fan-out, and behavioral
+ * flags (geometric context growth, cache cold-start risk, long session).
+ *
+ * Lives in main rather than the renderer so a renderer reload does not lose
+ * the rolling counters — multi-hour sessions are the primary use case and
+ * losing the velocity series at a reload would make the dashboard useless
+ * exactly when it matters most.
+ *
+ * Broadcasts `usage:matrix:tick` on a 5-second cadence (and once on demand
+ * via the `usage:matrix:snapshot` handler at mount).
+ */
+
+'use strict';
+
+const path = require('node:path');
+const { ipcMain } = require('electron');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
+
+const TICK_MS = 5_000;
+const TOKEN_WINDOW_MS = 5 * 60_000; // 5 min rolling window for tokens/min
+const TURN_RING = 20;               // per-turn input-token series cap
+const TOOL_RING = 100;              // recent tool-name series cap
+const CACHE_TTL_MS = 60 * 60_000;   // Anthropic prefix cache ~60 min
+const CACHE_WARN_MS = 50 * 60_000;  // start warning at 50 min
+
+const BURN_LOW = 5_000;       // tokens/min
+const BURN_CRITICAL = 30_000; // tokens/min
+const LONG_SESSION_TURNS = 70;
+const GEOMETRIC_MIN_TOKENS = 50_000; // don't flag tiny series
+
+/** Map<tabId, TabState> */
+const tabs = new Map();
+let window = null;
+let tickTimer = null;
+let dirty = false;
+
+function attachWindow(w) {
+  window = w;
+  if (!tickTimer) {
+    tickTimer = setInterval(broadcastIfChanged, TICK_MS);
+  }
+}
+
+function workspaceName(cwd) {
+  if (!cwd) return '(unknown)';
+  return path.basename(cwd) || cwd;
+}
+
+function blankTab(tabId, cwd, sessionUuid) {
+  return {
+    tabId,
+    cwd,
+    sessionUuid,
+    workspace: workspaceName(cwd),
+    startedAt: Date.now(),
+    lastEventAt: 0,
+    lastAssistantAt: 0,
+    lastUserAt: 0,
+    lastPlanAt: 0,
+    turns: 0,
+    cumulativeUsage: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 },
+    perTurnInputTokens: [],
+    tokenWindow: [], // [{ts, tokens}]
+    toolSeries: [],  // [{ts, name}]
+    agentSpawns: 0,
+    agentsActive: new Map(), // toolUseId -> {at}
+  };
+}
+
+function ensureTab(tabId, cwd, sessionUuid) {
+  let t = tabs.get(tabId);
+  if (!t) {
+    t = blankTab(tabId, cwd, sessionUuid);
+    tabs.set(tabId, t);
+  }
+  return t;
+}
+
+/**
+ * Feed one classified transcript event into the per-tab aggregator. Called
+ * from transcripts.cjs for every event, both during replay and live.
+ */
+function recordEvent({ tabId, cwd, sessionUuid, ev }) {
+  if (!tabId || !ev) return;
+  const t = ensureTab(tabId, cwd, sessionUuid);
+  const now = Date.now();
+  t.lastEventAt = now;
+
+  switch (ev.kind) {
+    case 'usage': {
+      // Each usage rollup = one assistant turn in Claude Code's transcript.
+      const u = ev.data || {};
+      const inTok = (u.input_tokens || 0)
+        + (u.cache_creation_input_tokens || 0)
+        + (u.cache_read_input_tokens || 0);
+      const outTok = u.output_tokens || 0;
+      t.cumulativeUsage.input += u.input_tokens || 0;
+      t.cumulativeUsage.output += outTok;
+      t.cumulativeUsage.cacheRead += u.cache_read_input_tokens || 0;
+      t.cumulativeUsage.cacheCreate += u.cache_creation_input_tokens || 0;
+      t.turns += 1;
+      t.lastAssistantAt = now;
+
+      t.perTurnInputTokens.push(inTok);
+      if (t.perTurnInputTokens.length > TURN_RING) t.perTurnInputTokens.shift();
+
+      t.tokenWindow.push({ ts: now, tokens: inTok + outTok });
+      pruneWindow(t.tokenWindow, now);
+      dirty = true;
+      break;
+    }
+    case 'tool_use': {
+      const name = ev.data?.name;
+      if (name) {
+        t.toolSeries.push({ ts: now, name });
+        if (t.toolSeries.length > TOOL_RING) t.toolSeries.shift();
+      }
+      dirty = true;
+      break;
+    }
+    case 'agent_spawn': {
+      t.agentSpawns += 1;
+      const id = ev.data?.toolUseId;
+      if (id) t.agentsActive.set(id, { at: now });
+      dirty = true;
+      break;
+    }
+    case 'tool_result': {
+      const id = ev.data?.toolUseId;
+      if (id && t.agentsActive.has(id)) {
+        t.agentsActive.delete(id);
+        dirty = true;
+      }
+      break;
+    }
+    case 'plan': {
+      t.lastPlanAt = now;
+      dirty = true;
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+function pruneWindow(arr, now) {
+  const cutoff = now - TOKEN_WINDOW_MS;
+  while (arr.length && arr[0].ts < cutoff) arr.shift();
+}
+
+function removeTab(tabId) {
+  if (tabs.delete(tabId)) dirty = true;
+}
+
+/**
+ * Build a derived snapshot. Heavy work happens here, not on the hot
+ * recordEvent path — recordEvent only appends to ring buffers and flips a
+ * dirty bit.
+ */
+function buildSnapshot() {
+  const now = Date.now();
+  const out = [];
+
+  let totalSubagentsActive = 0;
+  let totalSubagentsSpawned = 0;
+  let totalTokensToday = 0;
+  let combinedTokensPerMin = 0;
+
+  for (const t of tabs.values()) {
+    pruneWindow(t.tokenWindow, now);
+    const windowTokens = t.tokenWindow.reduce((s, e) => s + e.tokens, 0);
+    const windowMin = Math.min(TOKEN_WINDOW_MS, now - (t.tokenWindow[0]?.ts ?? now)) / 60_000;
+    const tokensPerMin = windowMin > 0.1 ? Math.round(windowTokens / windowMin) : 0;
+    combinedTokensPerMin += tokensPerMin;
+
+    const intensity = tokensPerMin >= BURN_CRITICAL
+      ? 'critical'
+      : tokensPerMin >= BURN_LOW
+      ? 'medium'
+      : tokensPerMin > 0
+      ? 'low'
+      : 'idle';
+
+    const cacheAgeMs = t.lastAssistantAt ? now - t.lastAssistantAt : null;
+    const cacheState = cacheAgeMs == null
+      ? 'cold'
+      : cacheAgeMs > CACHE_TTL_MS
+      ? 'cold'
+      : cacheAgeMs > CACHE_WARN_MS
+      ? 'expiring'
+      : 'warm';
+
+    const avgPerTurn = t.perTurnInputTokens.length > 0
+      ? Math.round(t.perTurnInputTokens.reduce((s, n) => s + n, 0) / t.perTurnInputTokens.length)
+      : 0;
+
+    const geometricGrowth = detectGeometricGrowth(t.perTurnInputTokens);
+
+    // State derivation. Order matters — earlier branches win.
+    let state;
+    if (t.lastPlanAt > 0 && (now - t.lastPlanAt) < 60_000 && t.lastPlanAt >= t.lastAssistantAt) {
+      state = 'plan';
+    } else if (t.agentsActive.size > 0 && (now - t.lastAssistantAt) > 10_000) {
+      state = 'background';
+    } else if (t.lastEventAt > 0 && (now - t.lastEventAt) < 30_000) {
+      state = 'executing';
+    } else {
+      state = 'idle';
+    }
+
+    const subagentsActive = t.agentsActive.size;
+    totalSubagentsActive += subagentsActive;
+    totalSubagentsSpawned += t.agentSpawns;
+    totalTokensToday += t.cumulativeUsage.input + t.cumulativeUsage.output;
+
+    const alerts = [];
+    if (geometricGrowth) {
+      alerts.push({
+        level: 'warn',
+        code: 'geometric-growth',
+        message: `Per-turn input grew geometrically (avg ${(avgPerTurn / 1000).toFixed(0)}k). Run /compact.`,
+      });
+    }
+    if (t.turns >= LONG_SESSION_TURNS) {
+      alerts.push({
+        level: 'warn',
+        code: 'long-session',
+        message: `Session is at turn ${t.turns}. Context resubmissions cost ${(avgPerTurn / 1000).toFixed(0)}k tokens each.`,
+      });
+    }
+    if (cacheState === 'expiring' && state === 'idle') {
+      const minLeft = Math.max(0, Math.round((CACHE_TTL_MS - (cacheAgeMs ?? 0)) / 60_000));
+      alerts.push({
+        level: 'info',
+        code: 'cache-cold-start',
+        message: `Cache cold-start in ${minLeft}m. Next command will incur full cache_creation cost.`,
+      });
+    }
+    if (cacheState === 'cold' && t.lastAssistantAt > 0) {
+      alerts.push({
+        level: 'info',
+        code: 'cache-cold',
+        message: 'Cache expired. Next command pays full cache_creation pricing.',
+      });
+    }
+    if (subagentsActive >= 4) {
+      alerts.push({
+        level: 'info',
+        code: 'subagent-fanout',
+        message: `${subagentsActive} subagents in flight. Consider waiting before fanning out more.`,
+      });
+    }
+
+    out.push({
+      tabId: t.tabId,
+      workspace: t.workspace,
+      cwd: t.cwd,
+      state,
+      turns: t.turns,
+      lastEventAt: t.lastEventAt,
+      lastAssistantAt: t.lastAssistantAt,
+      cacheAgeMs,
+      cacheState,
+      tokensPerMin,
+      intensity,
+      avgTokensPerTurn: avgPerTurn,
+      cumulativeUsage: { ...t.cumulativeUsage },
+      subagentsActive,
+      subagentsSpawned: t.agentSpawns,
+      geometricGrowth,
+      alerts,
+    });
+  }
+
+  // Most active first.
+  out.sort((a, b) => b.tokensPerMin - a.tokensPerMin || b.lastEventAt - a.lastEventAt);
+
+  return {
+    generatedAt: now,
+    tabs: out,
+    totals: {
+      activeSessions: out.length,
+      subagentsActive: totalSubagentsActive,
+      subagentsSpawned: totalSubagentsSpawned,
+      tokensTotal: totalTokensToday,
+      combinedTokensPerMin,
+    },
+  };
+}
+
+/**
+ * Geometric growth: avg of last 3 turns > 1.8 × avg of prior 3 turns,
+ * and last-3 avg above GEOMETRIC_MIN_TOKENS so trivial sessions don't flag.
+ */
+function detectGeometricGrowth(series) {
+  if (series.length < 6) return false;
+  const tail = series.slice(-3);
+  const prev = series.slice(-6, -3);
+  const tailAvg = tail.reduce((s, n) => s + n, 0) / 3;
+  const prevAvg = prev.reduce((s, n) => s + n, 0) / 3;
+  if (tailAvg < GEOMETRIC_MIN_TOKENS) return false;
+  if (prevAvg <= 0) return false;
+  return tailAvg / prevAvg >= 1.8;
+}
+
+function broadcastIfChanged() {
+  if (!dirty) return;
+  dirty = false;
+  if (!window) return;
+  sendIfAlive(window, 'usage:matrix:tick', buildSnapshot());
+}
+
+function registerHandlers() {
+  ipcMain.handle('usage:matrix:snapshot', () => buildSnapshot());
+}
+
+function closeAll() {
+  if (tickTimer) {
+    clearInterval(tickTimer);
+    tickTimer = null;
+  }
+  tabs.clear();
+}
+
+module.exports = {
+  attachWindow,
+  recordEvent,
+  removeTab,
+  registerHandlers,
+  closeAll,
+};

package/src/preload/api.d.ts

@@ -130,6 +130,54 @@ export type BillingFetchResult =
   | { kind: 'transient'; message: string; httpStatus: number | null }
   | { kind: 'config'; message: string };
 
+// ── Usage matrix (AgOps dashboard, main-side aggregator)
+export type UsageMatrixState = 'idle' | 'executing' | 'plan' | 'background';
+export type UsageMatrixIntensity = 'idle' | 'low' | 'medium' | 'critical';
+export type UsageMatrixCacheState = 'warm' | 'expiring' | 'cold';
+
+export interface UsageMatrixAlert {
+  level: 'info' | 'warn';
+  code:
+    | 'geometric-growth'
+    | 'long-session'
+    | 'cache-cold-start'
+    | 'cache-cold'
+    | 'subagent-fanout';
+  message: string;
+}
+
+export interface UsageMatrixTab {
+  tabId: string;
+  workspace: string;
+  cwd: string;
+  state: UsageMatrixState;
+  turns: number;
+  lastEventAt: number;
+  lastAssistantAt: number;
+  cacheAgeMs: number | null;
+  cacheState: UsageMatrixCacheState;
+  tokensPerMin: number;
+  intensity: UsageMatrixIntensity;
+  avgTokensPerTurn: number;
+  cumulativeUsage: { input: number; output: number; cacheRead: number; cacheCreate: number };
+  subagentsActive: number;
+  subagentsSpawned: number;
+  geometricGrowth: boolean;
+  alerts: UsageMatrixAlert[];
+}
+
+export interface UsageMatrixSnapshot {
+  generatedAt: number;
+  tabs: UsageMatrixTab[];
+  totals: {
+    activeSessions: number;
+    subagentsActive: number;
+    subagentsSpawned: number;
+    tokensTotal: number;
+    combinedTokensPerMin: number;
+  };
+}
+
 export interface VoiceHotkeyConfig {
   accelerator: string;
   mode: 'hold' | 'toggle';
@@ -787,6 +835,10 @@ export interface SessionManagerAPI {
   billing: {
     fetch: () => Promise<BillingFetchResult>;
   };
+  usageMatrix: {
+    snapshot: () => Promise<UsageMatrixSnapshot>;
+    onTick: (handler: (snap: UsageMatrixSnapshot) => void) => () => void;
+  };
   logs: {
     write: (scope: string, level: 'debug' | 'info' | 'warn' | 'error', message: string, meta?: unknown) => void;
     dir: () => Promise<string>;

package/src/preload/index.cjs

@@ -76,6 +76,14 @@ contextBridge.exposeInMainWorld('api', {
   billing: {
     fetch: () => ipcRenderer.invoke('billing:fetch'),
   },
+  usageMatrix: {
+    snapshot: () => ipcRenderer.invoke('usage:matrix:snapshot'),
+    onTick: (handler) => {
+      const listener = (_e, payload) => handler(payload);
+      ipcRenderer.on('usage:matrix:tick', listener);
+      return () => ipcRenderer.removeListener('usage:matrix:tick', listener);
+    },
+  },
   logs: {
     write: (scope, level, message, meta) =>
       ipcRenderer.send('log:write', { scope, level, message, meta }),