ai-lens 0.8.51 → 0.8.52

package/.commithash

@@ -1 +1 @@
-7c4d056
+8553371

package/README.md

@@ -1,6 +1,8 @@
 # AI Lens
 
-Analytics for AI coding sessions. Captures hook events from Claude Code and Cursor, and near-real-time session events from Codex, normalizes them to a unified format, queues locally, and ships to a centralized server with a web dashboard.
+Analytics for AI coding sessions. Captures hook events from Claude Code, Cursor,
+and Codex, normalizes them to a unified format, queues locally, and ships to a
+centralized server with a web dashboard and MCP integration.
 
 ```
 Hook fires → capture.js → normalize → queue.jsonl → sender.js → POST /api/events → server → dashboard
@@ -19,6 +21,7 @@ This will:
 2. Copy client files to `~/.ai-lens/client/`
 3. Configure hooks in `~/.claude/settings.json` and/or `~/.cursor/hooks.json`
 4. Start the Codex watcher for user-level and project-local Codex sessions
+5. Register the MCP server for in-editor analytics (optional)
 
 Re-running is safe — it updates outdated hooks and skips current ones.
 
@@ -27,19 +30,38 @@ Re-running is safe — it updates outdated hooks and skips current ones.
 To write hooks into the project directory (`.cursor/hooks.json` and `.claude/settings.json`) instead of global `~/.cursor/` and `~/.claude/`, run from the project root:
 
 ```bash
-npx git+ssh://git@rantsports.gitlab.yandexcloud.net:ai-first-workspace/internal/analytics/ai-lens.git init --server https://ai-lens.rantsports.com --no-mcp --project-hooks
+npx -y ai-lens init --server https://ai-lens.rantsports.com --no-mcp --project-hooks
 ```
 
 Add `--use-repo-path` to run `capture.js` directly from the package (repo or npx cache) instead of copying to `~/.ai-lens/client/`. Useful when the repo is next to the workspace.
 
-Hooks use the path `~/.ai-lens/client/capture.js` by default (or the package path with `--use-repo-path`); the config can be committed to the repo.
+### CLI commands
 
-Configure the server URL and optionally filter projects:
+```bash
+npx ai-lens init       # Setup wizard — detect tools, install hooks, configure MCP
+npx ai-lens status     # Run health checks and generate a diagnostic report
+npx ai-lens remove     # Remove hooks, client files, and MCP config
+npx ai-lens version    # Show installed version
+```
+
+### CLI options
+
+| Flag | Description |
+|------|-------------|
+| `--server URL` | Server URL (default: `http://localhost:3000`) |
+| `--yes`, `-y` | Non-interactive mode, accept all defaults |
+| `--no-mcp` | Skip MCP server registration |
+| `--mcp-scope SCOPE` | MCP scope: `user` (default), `local`, or `project` |
+| `--projects LIST` | Comma-separated project paths to monitor (default: all) |
+| `--project-hooks` | Write hooks into project directory instead of global config |
+| `--use-repo-path` | Run capture.js from package path instead of copying to `~/.ai-lens/client/` |
+
+### Environment variables (client)
 
 ```bash
 # In your shell profile (~/.zshrc, ~/.bashrc)
-export AI_LENS_SERVER_URL=http://your-server:13300
-export AI_LENS_PROJECTS="~/work/, ~/projects/"   # optional, default: all; nested repos under these roots are included
+export AI_LENS_SERVER_URL=https://ai-lens.rantsports.com
+export AI_LENS_PROJECTS="~/meta/, ~/meta-cursor/"   # optional, default: all
 ```
 
 <details>
@@ -96,47 +118,94 @@ docker compose up -d
 ```
 
 Starts three containers:
-- **nginx** — reverse proxy with basic auth, port `13300`
-- **app** — Node.js Express server with dashboard
-- **postgres** — PostgreSQL 16 database
 
-Dashboard: `http://your-server:13300`
+| Container | Image | Purpose |
+|-----------|-------|---------|
+| **app** | `ai-lens/app` | API server + web dashboard (port 3000) |
+| **postgres** | `postgres:16-alpine` | PostgreSQL 16 database |
+| **analyzer** | `ai-lens/analyzer` | Background session analyzer (needs `claude login`) |
+
+Dashboard: https://ai-lens.rantsports.com
 
-Default credentials:
+Images are stored in ECR (`267996409571.dkr.ecr.eu-north-1.amazonaws.com/ai-lens/`) and mirrored to GHCR (`ghcr.io/r-ms/ai-lens/`) on every push to `main`.
 
-| User | Password | Purpose |
-|------|----------|---------|
-| `collector` | `secret-collector-token-2026-ai-lens` | Client sender (automatic via `AI_LENS_AUTH_TOKEN`) |
-| `meta` | `meta` | Browser / dashboard access |
+### Environment variables (server)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `DATABASE_URL` | _(required)_ | PostgreSQL connection string |
+| `POSTGRES_PASSWORD` | `ailens` | PostgreSQL password (docker compose) |
+| `ANALYSIS_INTERVAL` | `3600` | Seconds between analysis runs |
+| `AI_LENS_ADMIN_SECRET` | _(none)_ | Admin secret for auth token management |
+| `OPENAI_API_KEY` | _(none)_ | OpenAI API key for FAISS vector search; text search works without it |
+| `TEAMS_CONFIG` | _(none)_ | JSON config for team definitions |
+| `CORS_ALLOWED_ORIGINS` | _(none)_ | Allowed CORS origins |
+
+#### Auth0 SSO
+
+| Variable | Description |
+|----------|-------------|
+| `AUTH0_DOMAIN` | Auth0 tenant domain |
+| `AUTH0_CLIENT_ID` | Auth0 SPA client ID |
+| `AUTH0_AUDIENCE` | Auth0 API audience identifier |
+| `AUTH0_ALLOWED_DOMAIN` | Restrict login to a specific email domain |
+| `AUTH0_CLI_CLIENT_ID` | Auth0 Native app client ID for device code flow |
+| `MCP_SERVER_URL` | Public server URL for MCP OAuth callbacks |
+
+Without Auth0, the server uses git email headers for identity (personal mode).
 
 ### Local development
 
 ```bash
 docker compose up postgres -d
-npm install --prefix server   # Install server deps (auto-runs via prestart)
+npm install
 DATABASE_URL=postgresql://ailens:ailens@localhost:5432/ailens npm start
 ```
 
-The server now requires PostgreSQL via `DATABASE_URL`. The old SQLite fallback is no longer supported.
-
 ## Dashboard
 
-React + TypeScript SPA with session timelines, tool breakdowns, adoption trends, and per-developer analytics.
+React + TypeScript SPA with:
+- Organization-wide KPIs and adoption trends
+- Team and developer breakdowns
+- Session timelines with tool usage
+- AI-generated session and team analyses
+- Token usage by model
+- MCP server and skill distribution
+- Knowledge base and recurring problems
 
 ```bash
 cd dashboard
 npm install
 npm run dev          # Vite dev server with HMR (proxies API to localhost:3000)
-```
-
-Production build (served by Express as static files):
-
-```bash
-npm run build:dashboard
+npm run build        # Production build (served by Express as static files)
 ```
 
 Tech: Vite, Tailwind CSS, Nivo charts, TanStack Query, react-router-dom.
 
+## MCP Tools
+
+When MCP is enabled during `npx ai-lens init`, these tools become available inside Claude Code and Cursor:
+
+| Tool | Description |
+|------|-------------|
+| `who_am_i` | Identify yourself by git email — returns your developer profile and team(s) |
+| `get_overview` | Organization-wide KPIs: active developers, adoption rate, AI hours, MCP and skill distribution |
+| `list_teams` | List all teams with member counts, adoption rate, and AI hours |
+| `get_team` | Team detail: KPIs, members, tasks, activity trend, MCP and skill distribution |
+| `get_team_analysis` | AI-generated team analysis: achievements, recurring problems, recommendations |
+| `get_developer` | Developer profile: sessions, AI hours, tasks, MCP and skill usage, team comparison |
+| `get_mcp_distribution` | MCP server usage across the organization |
+| `get_chain` | Session chain with compact event timeline, plan mode segments, and timing |
+| `get_events` | Full event data for specific event IDs |
+| `get_chain_analysis` | AI-generated chain analysis: tasks, problems, tool errors, unanswered questions |
+| `request_analysis` | Manually trigger analysis for a specific session chain |
+| `get_token_usage` | Token usage statistics grouped by model (input/output/cache tokens) |
+| `knowhow_search` | Search the team knowledge base built from session analyses |
+| `knowhow_update` | Add or update a knowledge base entry |
+| `export_developer_tips` | Export personalized tips as a Markdown document |
+| `search` | Natural language search across sessions, tasks, and projects |
+
 ## API
 
 ### `POST /api/events`
@@ -144,7 +213,7 @@ Tech: Vite, Tailwind CSS, Nivo charts, TanStack Query, react-router-dom.
 Batch insert events. Deduplicates by `event_id` (ON CONFLICT DO NOTHING) — safe to re-send.
 
 ```
-Headers: X-Developer-Git-Email, X-Developer-Name, Authorization: Basic <base64>
+Headers: X-Developer-Git-Email, X-Developer-Name, X-Auth-Token
 Body: [{ source, session_id, type, project_path, timestamp, data, raw, event_id }]
 Response: { received, skipped, deduplicated }
 ```
@@ -163,38 +232,36 @@ List all developers.
 
 ### `GET /api/dashboard/*`
 
-Aggregate endpoints for dashboard charts (stats, trends, tool usage, etc.).
+Aggregate endpoints for dashboard charts: overview, teams, developers, tokens, MCP distribution, developer activity, knowledge base, problems, company/team/developer analyses.
 
 ## Event Types
 
 | Type | Source | Description |
 |------|--------|-------------|
-| `SessionStart` | Both | Session opened |
-| `SessionEnd` | Both | Session closed |
-| `UserPromptSubmit` | Both | User sent a prompt |
-| `PostToolUse` | Both | Tool execution completed |
-| `PostToolUseFailure` | Both | Tool execution failed |
-| `Stop` | Both | Agent stopped |
-| `PreCompact` | Both | Context compaction triggered |
+| `SessionStart` | All | Session opened |
+| `SessionEnd` | All | Session closed |
+| `UserPromptSubmit` | All | User sent a prompt |
+| `PostToolUse` | All | Tool execution completed |
+| `PostToolUseFailure` | All | Tool execution failed |
+| `Stop` | All | Agent stopped |
+| `PreCompact` | All | Context compaction triggered |
 | `PlanModeStart` | Claude Code | Entered plan mode |
 | `PlanModeEnd` | Claude Code | Exited plan mode (plan content in raw payload) |
-| `SubagentStart` | Both | Subagent spawned |
-| `SubagentStop` | Both | Subagent finished |
+| `SubagentStart` | All | Subagent spawned |
+| `SubagentStop` | All | Subagent finished |
 | `FileEdit` | Cursor | File edited |
 | `ShellExecution` | Cursor | Shell command executed |
 | `MCPExecution` | Cursor | MCP tool executed |
-| `AgentResponse` | Cursor | Agent response |
+| `AgentResponse` | Cursor | Agent response (includes token usage in raw payload) |
 | `AgentThought` | Cursor | Agent reasoning |
 
-## Environment Variables
+## Supported Tools
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `3000` (local), `13300` (Docker) | Server port |
-| `DATABASE_URL` | _(required)_ | PostgreSQL connection string |
-| `AI_LENS_SERVER_URL` | `http://localhost:3000` | Client → server endpoint |
-| `AI_LENS_AUTH_TOKEN` | `collector:secret-collector-token-2026-ai-lens` | Client auth (`user:password`) |
-| `AI_LENS_PROJECTS` | _(all)_ | Comma-separated project paths to monitor (`~` supported) |
+| Tool | Hook mechanism |
+|------|---------------|
+| **Claude Code** | Hooks via `~/.claude/settings.json` |
+| **Cursor** | Hooks via `~/.cursor/hooks.json` |
+| **Codex** | File watcher on `~/.codex` and project-local `.codex` directories |
 
 ## Client Data
 
@@ -203,41 +270,35 @@ Stored in `~/.ai-lens/`:
 | File | Purpose |
 |------|---------|
 | `client/` | Installed client files (capture.js, sender.js, config.js) |
+| `config.json` | Server URL, auth token, project list |
 | `queue.jsonl` | Pending events |
 | `queue.sending.jsonl` | Events being sent (atomic rename as mutex) |
 | `sender.log` | Sender activity log |
+| `capture.log` | Capture drop log (normalization failures, write errors) |
 | `session-paths.json` | Session-to-project path cache |
 
 ## Development
 
 ```bash
-npm test               # Run all tests (vitest, 204 tests)
+npm test               # Run all tests (vitest, 683 tests)
 npm run test:watch     # Watch mode
 npm run dev:dashboard  # Dashboard dev server
 ```
 
-Tests use in-memory SQLite via `initTestDb()`.
+Tests require PostgreSQL — set `DATABASE_URL` or use `docker compose up postgres -d` (test DB `ailens_test` is created automatically).
 
 ## Deployment
 
 GitLab CI (`.gitlab-ci.yml`) on push to `main`:
 
-1. `rsync` to deploy host
-2. `docker compose down && docker compose up -d --build`
-3. Health check
-
-## Data Migration
-
-Sync local SQLite data to a remote PostgreSQL server:
-
-```bash
-node scripts/sync-to-remote.js                       # Default remote
-node scripts/sync-to-remote.js http://custom:13300   # Custom URL
-```
+1. **build-app** — builds `ai-lens/app` Docker image, pushes to ECR + GHCR
+2. **build-analyzer** — builds `ai-lens/analyzer` Docker image, pushes to ECR + GHCR
+3. **deploy** — zero-downtime rolling deploy to production (scale up new container, health check, remove old)
 
-Safe to re-run — deduplicates by `event_id`.
+Build jobs trigger only when relevant files change (Dockerfile, server/**, dashboard/**, etc.).
 
 ## Requirements
 
 - Node.js 20+
 - Docker + Docker Compose (for production deployment)
+- PostgreSQL 16 (for local development without Docker)

package/cli/hooks.js

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync, unlinkSync, chmodSync } from 'node:fs';
+import { existsSync, lstatSync, readFileSync, writeFileSync, copyFileSync, renameSync, mkdirSync, rmSync, unlinkSync, chmodSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -145,7 +145,16 @@ export function cursorCaptureCommand(useTilde = false, customPath = null) {
 // Client file installation
 // ---------------------------------------------------------------------------
 
-const CLIENT_FILES = ['capture.js', 'sender.js', 'config.js', 'redact.js', 'codex.js', 'codex-watcher.js'];
+/**
+ * Enumerate every .js file that ships with the package's client/ directory.
+ * Dynamic discovery (rather than a hardcoded CLIENT_FILES list) guarantees
+ * that any new client/*.js file added to the repo is automatically installed,
+ * so a forgotten list entry can never produce a broken install that crashes
+ * every hook with ERR_MODULE_NOT_FOUND on a missing sibling import.
+ */
+export function listClientFiles(sourceDir = join(__dirname, '..', 'client')) {
+  return readdirSync(sourceDir).filter(f => f.endsWith('.js')).sort();
+}
 
 /**
  * Copy client/ files from the package source to ~/.ai-lens/client/.
@@ -155,7 +164,7 @@ export function installClientFiles() {
   const sourceDir = join(__dirname, '..', 'client');
   mkdirSync(CLIENT_INSTALL_DIR, { recursive: true });
 
-  for (const file of CLIENT_FILES) {
+  for (const file of listClientFiles(sourceDir)) {
     copyFileSync(join(sourceDir, file), join(CLIENT_INSTALL_DIR, file));
   }
 

package/cli/init.js

@@ -67,7 +67,7 @@ function getJson(url) {
   });
 }
 
-function postJson(url, body) {
+function postJson(url, body, timeoutMs = 15_000) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
     const isHttps = parsed.protocol === 'https:';
@@ -82,7 +82,7 @@ function postJson(url, body) {
         'Content-Type': 'application/json',
         'Content-Length': Buffer.byteLength(data),
       },
-      timeout: 15_000,
+      timeout: timeoutMs,
     };
     const req = requestFn(options, (res) => {
       let buf = '';
@@ -107,7 +107,7 @@ function postJson(url, body) {
   });
 }
 
-function postForm(url, params) {
+function postForm(url, params, timeoutMs = 15_000) {
   return new Promise((resolve, reject) => {
     const parsed = new URL(url);
     const isHttps = parsed.protocol === 'https:';
@@ -122,7 +122,7 @@ function postForm(url, params) {
         'Content-Type': 'application/x-www-form-urlencoded',
         'Content-Length': Buffer.byteLength(data),
       },
-      timeout: 15_000,
+      timeout: timeoutMs,
     };
     const req = requestFn(options, (res) => {
       let buf = '';
@@ -146,6 +146,26 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+function isTransientNetError(err) {
+  const msg = `${err && err.code ? err.code : ''} ${err && err.message ? err.message : err}`;
+  return /ECONNRESET|EPIPE|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ECONNREFUSED|socket hang up/i.test(String(msg));
+}
+
+/** Retry fn on flaky TLS/proxy resets (common during long Auth0 device polls). */
+async function withRetries(fn, { attempts = 5, baseDelayMs = 2000 } = {}) {
+  let lastErr;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransientNetError(err) || i === attempts) throw err;
+      await sleep(baseDelayMs * i);
+    }
+  }
+  throw lastErr;
+}
+
 function startCodexWatcher(watcherPath) {
   if (!existsSync(watcherPath)) return false;
   if (process.env.AI_LENS_TEST_NO_DETACHED_SPAWN === '1') return true;
@@ -219,17 +239,24 @@ async function deviceCodeAuth(serverUrl) {
   while (Date.now() < deadline) {
     await sleep(interval * 1000);
 
-    const tokenResp = await postForm(`https://${domain}/oauth/token`, {
-      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-      client_id: cliClientId,
-      device_code,
-    });
+    // Auth0 may keep this request open longer than a typical HTTP call; 15s caused false "Request timed out".
+    const tokenResp = await withRetries(
+      () => postForm(`https://${domain}/oauth/token`, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+        client_id: cliClientId,
+        device_code,
+      }, 120_000),
+      { attempts: 6, baseDelayMs: 2000 },
+    );
 
     if (tokenResp.status === 200 && tokenResp.data.id_token) {
       // 5. Exchange JWT for personal token
-      const result = await postJson(`${serverUrl}/api/auth/device-token`, {
-        jwt: tokenResp.data.id_token,
-      });
+      const result = await withRetries(
+        () => postJson(`${serverUrl}/api/auth/device-token`, {
+          jwt: tokenResp.data.id_token,
+        }, 120_000),
+        { attempts: 5, baseDelayMs: 2000 },
+      );
       if (!result?.token) throw new Error('Server returned no token — contact your admin');
       return result;
     }
@@ -510,10 +537,11 @@ export default async function init() {
     try {
       authResult = await deviceCodeAuth(serverUrl);
     } catch (err) {
-      if (err.message.includes('not configured')) {
+      const msg = (err && err.message) ? err.message : String(err);
+      if (msg.includes('not configured')) {
         warn(`  Auth not configured on server — personal mode (events sent via git identity)`);
       } else {
-        warn(`  Authentication failed: ${err.message}`);
+        warn(`  Authentication failed: ${msg}`);
         warn(`  Run "npx -y ai-lens init" again later to authenticate`);
       }
     }

package/client/capture.js

@@ -7,7 +7,7 @@
  * normalizes to unified event format, appends to queue, spawns sender if needed.
  */
 
-import { readFileSync, writeFileSync, appendFileSync, existsSync, unlinkSync, renameSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, appendFileSync, existsSync, unlinkSync, renameSync, realpathSync, statSync, openSync, readSync, closeSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -19,6 +19,7 @@ import {
   SENDING_DIR,
   DEDUP_DIR,
   SESSION_PATHS_DIR,
+  TRANSCRIPT_OFFSETS_DIR,
   CAPTURE_LOG_PATH,
   LOG_MAX_AGE_DAYS,
   SENDER_BACKOFF_PATH,
@@ -31,6 +32,7 @@ import {
   isCodexEnabled,
 } from './config.js';
 import { isLockStale, isSenderBackoffActive } from './sender.js';
+import { toNumberOrNull, buildTokenUsageRaw } from './token-usage.js';
 // Soft import — redact.js may not exist on older client installs
 let redactObject = (o) => o;
 try {
@@ -154,6 +156,287 @@ function truncateToolResult(result, toolName) {
   return result;
 }
 
+/**
+ * Read the persisted byte offset + size + mtime for a transcript file.
+ * Returns null on any error (caller treats as "start from 0").
+ */
+function readTranscriptOffsetState(offsetFile) {
+  try {
+    const parsed = JSON.parse(readFileSync(offsetFile, 'utf-8'));
+    if (
+      parsed &&
+      typeof parsed.offset === 'number' &&
+      typeof parsed.size === 'number' &&
+      typeof parsed.mtime_ms === 'number'
+    ) {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomically persist the byte offset + size + mtime for a transcript file.
+ * Mirrors the tmp+rename pattern used by cacheSessionPath.
+ */
+function writeTranscriptOffsetState(offsetFile, state) {
+  ensureDataDir();
+  const tmp = offsetFile + '.tmp.' + process.pid;
+  try {
+    writeFileSync(tmp, JSON.stringify(state));
+    try {
+      renameSync(tmp, offsetFile);
+    } catch {
+      try { unlinkSync(tmp); } catch {}
+    }
+  } catch { /* best-effort: a missed offset write means we re-read one Stop worth */ }
+}
+
+// Run stale-offset cleanup at most once per 24h per machine. Each unique
+// transcript path produces a persistent offset file; without this pass the
+// directory grows unbounded over months. We rate-limit via the mtime of a
+// marker file so the common path of every Stop hook is a single statSync.
+const TRANSCRIPT_OFFSETS_CLEANUP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+function maybeCleanStaleTranscriptOffsets() {
+  const marker = join(TRANSCRIPT_OFFSETS_DIR, '.last_cleanup');
+  let shouldRun = true;
+  try {
+    const st = statSync(marker);
+    if (Date.now() - st.mtimeMs < TRANSCRIPT_OFFSETS_CLEANUP_INTERVAL_MS) {
+      shouldRun = false;
+    }
+  } catch {
+    // Marker missing — first run on this machine, proceed.
+  }
+  if (!shouldRun) return;
+
+  // Touch the marker FIRST so concurrent Stop hooks within the same second
+  // don't both kick off the readdir scan. ensureDataDir() in case the dir
+  // doesn't exist yet on a fresh install.
+  ensureDataDir();
+  try {
+    writeFileSync(marker, '');
+  } catch {
+    // If we can't write the marker we still try the scan, but the rate limit
+    // won't take effect — which is acceptable best-effort behavior.
+  }
+
+  let entries = [];
+  try {
+    entries = readdirSync(TRANSCRIPT_OFFSETS_DIR);
+  } catch {
+    return;
+  }
+
+  for (const name of entries) {
+    if (name.startsWith('.')) continue; // skip .last_cleanup and other dotfiles
+    let originalPath;
+    try {
+      originalPath = decodeURIComponent(name);
+    } catch {
+      continue;
+    }
+    try {
+      if (!existsSync(originalPath)) {
+        unlinkSync(join(TRANSCRIPT_OFFSETS_DIR, name));
+      }
+    } catch {
+      // Ignore per-entry errors so one stuck file doesn't block the pass.
+    }
+  }
+}
+
+/**
+ * Incrementally read only the NEW bytes appended to a Claude Code transcript
+ * since the last time this function was called for that transcript, and
+ * return ONE entry per real (non-synthetic) assistant API call in the delta.
+ *
+ * Each entry corresponds to a single Anthropic API call: a single assistant
+ * line in the JSONL with its own usage record. A single user->agent turn can
+ * produce many of these (tool-use loops), and the caller is expected to emit
+ * one unified TokenUsage event per entry — symmetric with Cursor's per-call
+ * AgentResponse rows and Codex's per-call TokenUsage rows.
+ *
+ * Returns { calls, commitOffset }:
+ *   - `calls` is Array<{usage, model, timestamp, uuid}>:
+ *     • `usage` has Anthropic-named keys (input_tokens, output_tokens,
+ *       cache_read_input_tokens, cache_creation_input_tokens) for
+ *       buildTokenUsageRaw.
+ *     • `model` is the model from that specific assistant line.
+ *     • `timestamp` is the assistant line's own ISO timestamp if present, else
+ *       null (caller falls back to the Stop event's timestamp).
+ *     • `uuid` is the assistant line's `uuid` field (Claude Code transcripts
+ *       always include one). Used by the caller to derive a stable event_id
+ *       so concurrent Stop hook invocations can't double-emit a single API call.
+ *   - `commitOffset` is a no-arg function the caller MUST invoke ONLY after
+ *     successfully writing every TokenUsage event derived from `calls` into
+ *     the spool. If spool writes fail (or the caller never calls it), the
+ *     transcript cursor stays put and the next Stop re-reads the same delta —
+ *     the server-side ON CONFLICT on the deterministic event_id then dedups
+ *     whichever rows did land. This is what makes the pipeline crash-safe:
+ *     we never mark transcript bytes "consumed" until we know the rows they
+ *     produced are durably queued.
+ *
+ * Returns an empty `calls` array (and a no-op `commitOffset`) if nothing new
+ * in the delta or no real assistant lines are found.
+ *
+ * Partial-line handling: a Stop hook can fire while Claude Code is mid-write,
+ * so the delta may end before a trailing '\n'. We detect this, ignore the
+ * partial tail, and persist the offset at the byte right after the LAST
+ * complete '\n' so the next Stop re-reads the partial line once it's finished.
+ */
+function extractNewClaudeApiCallsFromTranscript(transcriptPath) {
+  // Run the rate-limited stale-offset cleanup at most once per 24h. Wrapped in
+  // try/catch so a cleanup failure never prevents the token read.
+  try { maybeCleanStaleTranscriptOffsets(); } catch { /* best-effort */ }
+
+  // Default: no-op commit. Callers always receive a function so they never
+  // have to null-check before invoking.
+  const noopCommit = () => {};
+
+  if (!transcriptPath || typeof transcriptPath !== 'string') {
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  const offsetFile = join(TRANSCRIPT_OFFSETS_DIR, encodeURIComponent(transcriptPath));
+
+  let currentSize = 0;
+  let currentMtime = 0;
+  try {
+    const st = statSync(transcriptPath);
+    currentSize = st.size;
+    currentMtime = st.mtimeMs;
+  } catch (err) {
+    captureLog({ msg: 'transcript-offset-error', stage: 'stat', path: transcriptPath, error: err?.message });
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  const savedState = readTranscriptOffsetState(offsetFile);
+  let startOffset = 0;
+  if (savedState) {
+    // Detect rotation/truncation: file shrank below our saved cursor, or file
+    // didn't grow but the mtime changed (content rewrite in place).
+    if (currentSize < savedState.offset) {
+      startOffset = 0;
+    } else if (currentSize === savedState.offset && currentMtime !== savedState.mtime_ms) {
+      startOffset = 0;
+    } else {
+      startOffset = savedState.offset;
+    }
+  }
+
+  // Nothing new — just a stat, super cheap.
+  if (currentSize === startOffset) {
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  let buffer = null;
+  try {
+    const length = currentSize - startOffset;
+    const fd = openSync(transcriptPath, 'r');
+    try {
+      buffer = Buffer.alloc(length);
+      readSync(fd, buffer, 0, length, startOffset);
+    } finally {
+      closeSync(fd);
+    }
+  } catch (err) {
+    captureLog({ msg: 'transcript-offset-error', stage: 'read', path: transcriptPath, error: err?.message });
+    // Read failed before we got any bytes — leave the cursor unchanged so the
+    // next Stop retries. (Old behavior advanced past the unread bytes; that
+    // silently dropped data on transient I/O errors.)
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  if (!buffer || buffer.length === 0) {
+    // Defensive: shouldn't happen because of the currentSize === startOffset
+    // early return above. Don't advance the cursor.
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  // Find the LAST complete newline. CRITICAL: search the BYTE buffer, not a
+  // decoded string — string indices use UTF-16 code units, but file offsets
+  // are byte-based. Mixing the two corrupts startOffset on non-ASCII content
+  // (Russian transcripts, emoji, etc.) and causes lines to be replayed on the
+  // next Stop, double-counting tokens.
+  //
+  // 0x0A is the byte value of '\n' (always single-byte in UTF-8 — '\n' is
+  // ASCII, so this byte never appears inside a multi-byte sequence).
+  const lastNewlineIndex = buffer.lastIndexOf(0x0A);
+  if (lastNewlineIndex === -1) {
+    // The entire chunk is a partial trailing line — leave the cursor unchanged
+    // so the next Stop re-reads the line once it's finished.
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  // Process only the bytes up to (and including) the last '\n'. The new
+  // persisted offset points at the byte AFTER that newline so any partial
+  // trailing line is replayed on the next Stop. Decode just the processable
+  // slice as UTF-8 once for line iteration.
+  const processable = buffer.slice(0, lastNewlineIndex).toString('utf-8');
+  const newOffset = startOffset + lastNewlineIndex + 1;
+  const nextState = { offset: newOffset, size: currentSize, mtime_ms: currentMtime };
+  const commitOffset = () => writeTranscriptOffsetState(offsetFile, nextState);
+
+  // Iterate lines in the processable region. Defensive parse-tolerance is
+  // still useful for the rare case where a single line in the middle is
+  // malformed (we skip it rather than dropping the whole delta).
+  const calls = [];
+  try {
+    const lines = processable.split('\n');
+    for (const rawLine of lines) {
+      const line = rawLine && rawLine.trim();
+      if (!line) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (parsed?.type !== 'assistant') continue;
+      const message = parsed?.message;
+      if (!message || typeof message !== 'object') continue;
+      const model = message.model;
+      // Skip <synthetic> internal placeholder entries — they carry all-zero
+      // usage and would not show up on billing.
+      if (!model || model === '<synthetic>') continue;
+      const usage = message.usage;
+      if (!usage || typeof usage !== 'object') continue;
+      // Capture each call as its own entry — the caller emits one unified
+      // TokenUsage event per entry, matching Cursor/Codex per-call granularity.
+      calls.push({
+        usage: {
+          input_tokens: toNumberOrNull(usage.input_tokens) ?? 0,
+          output_tokens: toNumberOrNull(usage.output_tokens) ?? 0,
+          cache_read_input_tokens: toNumberOrNull(usage.cache_read_input_tokens) ?? 0,
+          cache_creation_input_tokens: toNumberOrNull(usage.cache_creation_input_tokens) ?? 0,
+        },
+        model,
+        timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : null,
+        uuid: typeof parsed.uuid === 'string' ? parsed.uuid : null,
+      });
+    }
+  } catch (err) {
+    captureLog({ msg: 'transcript-offset-error', stage: 'parse', path: transcriptPath, error: err?.message });
+    // On a parse-loop exception, advance the cursor to the last complete
+    // newline so we don't spin re-reading the same bytes. There are no calls
+    // to spool in this path, so it's safe to commit immediately (no risk of
+    // losing events).
+    commitOffset();
+    return { calls: [], commitOffset: noopCommit };
+  }
+
+  // IMPORTANT: do NOT persist the offset here. The caller is responsible for
+  // invoking `commitOffset` only AFTER it has successfully written every
+  // TokenUsage event derived from `calls` to the spool. Advancing the cursor
+  // eagerly (the previous behavior) would silently drop rows whenever a
+  // writeToSpool() failed after we'd already "consumed" the transcript bytes.
+  return { calls, commitOffset };
+}
+
 // =============================================================================
 // Source Detection
 // =============================================================================
@@ -315,6 +598,19 @@ const PLAN_MODE_TOOLS = {
   ExitPlanMode: 'PlanModeEnd',
 };
 
+/**
+ * Normalize a Claude Code hook event into one or more unified events.
+ *
+ * Returns an array — almost every hook produces a single primary event, but
+ * Stop and SubagentStop additionally read NEW assistant API calls from the
+ * transcript and emit one TokenUsage event per call (one assistant line in
+ * the transcript = one API call = one row in the events table). This keeps
+ * row granularity symmetric with Cursor (one AgentResponse per API call) and
+ * Codex (one TokenUsage per token_count record).
+ *
+ * Returns an empty array for hooks that should be silently dropped (e.g. a
+ * non-plan-mode PreToolUse).
+ */
 function normalizeClaudeCode(event) {
   const sessionId = event.session_id;
   const hookType = event.hook_event_name || event.hook;
@@ -342,7 +638,7 @@ function normalizeClaudeCode(event) {
       const preToolName = event.tool_name || event.tool || 'unknown';
       // Only capture PreToolUse for plan mode tools; skip others to avoid duplicating PostToolUse
       if (!PLAN_MODE_TOOLS[preToolName]) {
-        return null;
+        return [];
       }
       type = PLAN_MODE_TOOLS[preToolName];
       data = { tool: preToolName };
@@ -417,7 +713,7 @@ function normalizeClaudeCode(event) {
     data.permission_mode = event.permission_mode;
   }
 
-  return {
+  const primary = {
     event_id: null,
     source: 'claude_code',
     session_id: sessionId,
@@ -427,6 +723,46 @@ function normalizeClaudeCode(event) {
     data,
     raw: event,
   };
+
+  // For Stop and SubagentStop, also read the transcript delta and emit one
+  // TokenUsage event per real assistant API call. This is what makes Claude
+  // Code's row-per-call granularity match Cursor and Codex.
+  //
+  // Claude Code's Stop hook passes the path as `transcript_path`, but
+  // SubagentStop uses `agent_transcript_path` (see Claude Code hook docs and
+  // test/fixtures/claude-code-events/subagent-stop.json). Check both so
+  // subagent token usage is not silently dropped in production.
+  if (hookType === 'Stop' || hookType === 'SubagentStop') {
+    const transcriptPath = event.transcript_path || event.agent_transcript_path;
+    const { calls, commitOffset } = extractNewClaudeApiCallsFromTranscript(transcriptPath);
+    const tokenEvents = calls.map(call => ({
+      event_id: null, // assigned in main() from a stable hash of call.uuid
+      source: 'claude_code',
+      session_id: sessionId,
+      type: 'TokenUsage',
+      project_path: projectPath,
+      timestamp: call.timestamp || timestamp,
+      data: {
+        model: call.model,
+        input_tokens: call.usage.input_tokens,
+        output_tokens: call.usage.output_tokens,
+      },
+      raw: buildTokenUsageRaw({ source_uuid: call.uuid }, call.usage, call.model),
+    }));
+    const result = [primary, ...tokenEvents];
+    // Attach the commit callback as a non-enumerable property on the returned
+    // array so it survives through normalizeEvent() without leaking into
+    // iteration (for...of, .map, writeToSpool's {...spread}) or into tests
+    // that assert on events.length / events[0].
+    Object.defineProperty(result, 'commitTranscriptOffset', {
+      value: commitOffset,
+      enumerable: false,
+      writable: false,
+    });
+    return result;
+  }
+
+  return [primary];
 }
 
 // =============================================================================
@@ -498,6 +834,7 @@ function normalizeCursor(event) {
   }
 
   let data = {};
+  let raw = event;
   switch (hookName) {
     case 'sessionStart':
       data = { workspace_roots: event.workspace_roots };
@@ -565,6 +902,7 @@ function normalizeCursor(event) {
       break;
     case 'afterAgentResponse':
       data = { text: truncate(event.text || '', TRUNCATION_LIMITS.agentResponse) };
+      raw = buildTokenUsageRaw(event, event.usage || null, event.model || null);
       break;
     case 'afterAgentThought':
       data = {
@@ -595,7 +933,7 @@ function normalizeCursor(event) {
     data.permission_mode = event.permission_mode;
   }
 
-  return {
+  return [{
     event_id: null,
     source: 'cursor',
     session_id: sessionId,
@@ -603,20 +941,27 @@ function normalizeCursor(event) {
     project_path: projectPath,
     timestamp,
     data,
-    raw: event,
-  };
+    raw,
+  }];
 }
 
 // =============================================================================
 // Normalize (dispatcher)
 // =============================================================================
 
+/**
+ * Normalize a raw hook event into an array of unified events. Almost every
+ * hook produces a single primary event, but Claude Code Stop/SubagentStop
+ * additionally emit one TokenUsage event per API call read from the
+ * transcript delta. Returns an empty array for hooks that should be silently
+ * dropped (e.g. non-plan-mode PreToolUse) or an unrecognized source.
+ */
 export function normalizeEvent(event) {
   const source = detectSource(event);
   switch (source) {
     case 'claude_code': return normalizeClaudeCode(event);
     case 'cursor': return normalizeCursor(event);
-    default: return null;
+    default: return [];
   }
 }
 
@@ -740,69 +1085,135 @@ async function main() {
     process.exit(0);
   }
 
-  const unified = normalizeEvent(event);
-  if (!unified || !unified.session_id) {
+  const events = normalizeEvent(event);
+  if (!events || events.length === 0 || !events[0].session_id) {
     logDrop('normalize_failed', { hook: event.hook_event_name });
     process.exit(0);
   }
 
-  // Deterministic event_id from raw stdin — both hooks receive identical bytes,
-  // so they produce the same ID and ON CONFLICT(event_id) catches the duplicate.
-  unified.event_id = deterministicEventId(input);
+  // The primary event (always at index 0) carries the canonical session/type
+  // for project-filter, identity, and dedup decisions. Additional events
+  // (Claude Code per-call TokenUsage rows) inherit the same project, identity,
+  // and git metadata from the primary, since they all originate from the same
+  // hook invocation on the same machine.
+  const primary = events[0];
 
-  // Filter by monitored projects (if configured)
+  // Filter by monitored projects (if configured) — based on the primary event.
+  // If the primary is filtered out, drop the entire batch (the per-call events
+  // share the same project_path).
   const monitored = getMonitoredProjects();
-  let projectPath = unified.project_path;
+  let projectPath = primary.project_path;
   try { projectPath = realpathSync(projectPath); } catch {}
   if (monitored && projectPath && !monitored.some(p => pathContains(p, projectPath))) {
     // Fallback: for Cursor multi-root workspaces, check if any raw workspace_roots entry matches
     const roots = Array.isArray(event.workspace_roots) ? event.workspace_roots : [];
     const resolvedRoots = roots.map(r => { try { return realpathSync(r); } catch { return r; } });
     if (!resolvedRoots.some(root => monitored.some(p => pathContains(p, root)))) {
-      logDrop('project_filter', { type: unified.type, source: unified.source, session_id: unified.session_id, project_path: unified.project_path, monitored });
+      logDrop('project_filter', { type: primary.type, source: primary.source, session_id: primary.session_id, project_path: primary.project_path, monitored });
       process.exit(0);
     }
   }
 
   // Resolve identity: git first, then fall back to event payload (e.g. Cursor's user_email)
   // When auth token is present, server resolves developer from token — email is optional
-  const identity = getGitIdentity(unified.project_path);
+  const identity = getGitIdentity(primary.project_path);
   const token = getAuthToken();
   const hasAuthToken = typeof token === 'string' && token.startsWith('ailens_dev_');
   const resolved = resolveIdentity(identity, event, hasAuthToken);
   if (!resolved.proceed) {
-    logDrop('no_email', { type: unified.type, session_id: unified.session_id });
+    logDrop('no_email', { type: primary.type, session_id: primary.session_id });
     process.exit(0);
   }
 
   // Deduplicate consecutive identical event types (e.g. repeated Stop from idle sessions).
+  // Only the PRIMARY event participates in this check; per-call TokenUsage events
+  // have their own stable event_id (derived from the assistant line uuid), so
+  // server-side ON CONFLICT(event_id) handles their dedup naturally.
   // Placed after project_filter and no_email checks so dropped events don't poison the cache.
-  // checkDuplicate is a pure read — does NOT commit. commitDedup is called only AFTER a
-  // successful queue write, preventing cache poisoning: if appendToQueue throws, the event
-  // is lost but checkDuplicate will still return false on the next attempt (allowing retry).
-  if (checkDuplicate(unified.session_id, unified.source, unified.type)) {
-    logDrop('duplicate', { type: unified.type, session_id: unified.session_id });
+  if (checkDuplicate(primary.session_id, primary.source, primary.type)) {
+    logDrop('duplicate', { type: primary.type, session_id: primary.session_id });
     process.exit(0);
   }
-  unified.developer_email = resolved.email;
-  unified.developer_name = resolved.name;
 
-  // Attach git metadata (remote, branch, commit)
-  const gitMeta = getGitMetadata(unified.project_path);
-  unified.git_remote = gitMeta.git_remote;
-  unified.git_branch = gitMeta.git_branch;
-  unified.git_commit = gitMeta.git_commit;
+  // Attach git metadata once — every event in the batch shares it.
+  const gitMeta = getGitMetadata(primary.project_path);
+
+  // Assign event_ids:
+  //   - Primary: deterministic from stdin hash (so Cursor + Claude Code firing
+  //     the same hook compute the same id and dedup at ON CONFLICT).
+  //   - Per-call TokenUsage: stable hash of the assistant line's uuid (so two
+  //     concurrent Stop hooks reading the same lines compute the same id and
+  //     dedup at the same UNIQUE constraint).
+  primary.event_id = deterministicEventId(input);
+  for (let i = 1; i < events.length; i++) {
+    const ev = events[i];
+    const sourceUuid = ev.raw && ev.raw.source_uuid;
+    if (sourceUuid) {
+      ev.event_id = deterministicEventId(`claude_code:tokenusage:${sourceUuid}`);
+    } else {
+      // Fallback: stdin hash + per-event index. Should never be needed because
+      // Claude Code transcripts always include uuid per record.
+      ev.event_id = deterministicEventId(`${input}:tokenusage:${i}`);
+    }
+  }
 
-  // Write to spool (pending/ dir)
-  try {
-    writeToSpool(unified);
-  } catch (err) {
-    captureLog({ msg: 'queue-write-failed', error: err.message, type: unified.type, session_id: unified.session_id });
-    process.exit(1);
+  // Write every event in the batch to the spool, attaching shared metadata.
+  let primaryWritten = false;
+  let allTokenUsageWritten = true;
+  for (const ev of events) {
+    ev.developer_email = resolved.email;
+    ev.developer_name = resolved.name;
+    ev.git_remote = gitMeta.git_remote;
+    ev.git_branch = gitMeta.git_branch;
+    ev.git_commit = gitMeta.git_commit;
+    try {
+      writeToSpool(ev);
+      if (ev === primary) primaryWritten = true;
+    } catch (err) {
+      captureLog({ msg: 'queue-write-failed', error: err.message, type: ev.type, session_id: ev.session_id });
+      // If the primary failed, propagate the failure so the hook exits non-zero
+      // (and dedup is NOT committed). If a per-call event failed, log and keep
+      // going — losing one TokenUsage row is better than dropping the whole
+      // turn, but we'll also refuse to commit the transcript offset below so
+      // the next Stop re-reads the same delta (server-side dedup on event_id
+      // handles the already-succeeded rows).
+      if (ev === primary) process.exit(1);
+      if (ev.type === 'TokenUsage') allTokenUsageWritten = false;
+    }
   }
 
-  // Commit dedup only after successful queue write — prevents cache poisoning on write failure.
-  commitDedup(unified.session_id, unified.source, unified.type);
+  // Commit dedup AND the transcript offset together, only if every event in
+  // the batch (primary + every per-call TokenUsage) made it into the spool.
+  //
+  // Why gate dedup on allTokenUsageWritten too:
+  //   If primary spooled but a per-call TokenUsage write failed, committing
+  //   dedup would cause the next back-to-back idle Stop to be dropped as a
+  //   duplicate — and since that drop happens BEFORE the transcript re-read,
+  //   the missing TokenUsage row would stay lost until some other event type
+  //   resets the dedup cache. By deferring dedup until every per-call write
+  //   succeeds, we guarantee the next Stop (even another idle Stop in the
+  //   same session) will re-read the delta and retry the failed rows. The
+  //   primary Stop gets spooled twice in that scenario, but its deterministic
+  //   event_id hits server-side ON CONFLICT — idempotent.
+  //
+  // Why gate the transcript offset on the same condition:
+  //   Advancing the cursor marks those transcript bytes "consumed". If any
+  //   TokenUsage row derived from them is missing from the spool, we must
+  //   re-read those bytes on the next Stop. Server-side ON CONFLICT on the
+  //   deterministic event_id (hashed from the assistant line's uuid) dedups
+  //   whichever rows did land, and the missing row(s) finally get through.
+  const batchFullySpooled = primaryWritten && allTokenUsageWritten;
+  if (batchFullySpooled) {
+    commitDedup(primary.session_id, primary.source, primary.type);
+    if (typeof events.commitTranscriptOffset === 'function') {
+      try {
+        events.commitTranscriptOffset();
+      } catch (err) {
+        captureLog({ msg: 'transcript-offset-commit-failed', error: err?.message });
+        // Not fatal: on the next Stop we'll just re-read the same delta.
+      }
+    }
+  }
 
   // Always try to spawn sender — atomic rename in sender handles dedup
   try {

package/client/codex.js

@@ -1,6 +1,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
+import { toNumberOrNull } from './token-usage.js';
 
 const TRUNCATION_LIMITS = {
   toolInput: { command: 500, old_string: 200, new_string: 200, default: 200 },
@@ -179,6 +180,7 @@ function streamStateFor(state, streamKey) {
       projectPath: null,
       pendingCalls: new Map(),
       hasActivity: false,
+      model: null,
     });
   }
   return state.streams.get(streamKey);
@@ -188,6 +190,20 @@ function sessionTimestamp(record) {
   return record?.timestamp || new Date().toISOString();
 }
 
+function buildCodexTokenUsageRaw(record, last, model) {
+  const inputTokens = toNumberOrNull(last?.input_tokens);
+  const outputTokens = toNumberOrNull(last?.output_tokens);
+  const cachedInputTokens = toNumberOrNull(last?.cached_input_tokens);
+
+  return {
+    ...record,
+    ...(model ? { model } : {}),
+    ...(inputTokens != null ? { input_tokens: inputTokens } : {}),
+    ...(outputTokens != null ? { output_tokens: outputTokens } : {}),
+    ...(cachedInputTokens != null ? { cache_read_tokens: cachedInputTokens } : {}),
+  };
+}
+
 function buildUnifiedEvent(stream, type, timestamp, data, raw) {
   if (!stream.sessionId || !stream.projectPath) return null;
   return {
@@ -313,6 +329,7 @@ export function normalizeCodexSessionEntries(record, state, streamKey = 'default
     stream.rawSessionId = sessionId;
     stream.projectPath = cwd;
     stream.hasActivity = false;
+    stream.model = null;
     events.push(buildUnifiedEvent(
       stream,
       'SessionStart',
@@ -338,8 +355,38 @@ export function normalizeCodexSessionEntries(record, state, streamKey = 'default
     return events.filter(Boolean);
   }
 
+  if (record?.type === 'turn_context') {
+    const nextModel = record?.payload?.model;
+    if (nextModel) stream.model = nextModel;
+    return [];
+  }
+
   if (!stream.sessionId || !stream.projectPath) return [];
 
+  if (record?.type === 'event_msg' && record?.payload?.type === 'token_count') {
+    const info = record?.payload?.info;
+    if (!info) return [];
+    const last = info.last_token_usage;
+    if (!last) return [];
+    const inputTokens = toNumberOrNull(last.input_tokens);
+    const outputTokens = toNumberOrNull(last.output_tokens);
+    if (inputTokens == null && outputTokens == null) return [];
+    stream.hasActivity = true;
+    return [buildUnifiedEvent(
+      stream,
+      'TokenUsage',
+      sessionTimestamp(record),
+      {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        cached_input_tokens: toNumberOrNull(last.cached_input_tokens),
+        reasoning_output_tokens: toNumberOrNull(last.reasoning_output_tokens),
+        model: stream.model || null,
+      },
+      buildCodexTokenUsageRaw(record, last, stream.model),
+    )].filter(Boolean);
+  }
+
   if (record?.type === 'response_item') {
     const payload = record.payload || {};
 

package/client/config.js

@@ -17,13 +17,25 @@ export const CURRENT_STORAGE_VERSION = 1;
 export const QUEUE_PATH   = join(DATA_DIR, 'queue.jsonl');
 export const SENDING_PATH = join(DATA_DIR, 'queue.sending.jsonl');
 export const SESSION_PATHS_DIR  = join(DATA_DIR, 'session-paths');
+export const TRANSCRIPT_OFFSETS_DIR = join(DATA_DIR, 'transcript-offsets');
 export const GIT_REMOTES_DIR    = join(DATA_DIR, 'git-remotes');
 export const LOG_PATH = join(DATA_DIR, 'sender.log');
 export const CAPTURE_LOG_PATH = join(DATA_DIR, 'capture.log');
 export const SENDER_BACKOFF_PATH = join(DATA_DIR, 'sender-backoff.json');
 export const LOG_MAX_AGE_DAYS = 30;
 const GIT_ROOT_CACHE = new Map();
-let _gitRunner = (args, options) => childProcess.execFileSync('git', args, options);
+// Pipe stderr (instead of inheriting it) so that "fatal: not a git repository"
+// and similar messages from git invocations in non-repo paths don't leak to
+// the parent terminal. Every caller wraps the runner in try/catch and discards
+// errors; otherwise stderr bytes would print to the user's terminal regardless.
+//
+// The stdio override is applied AFTER spreading caller options so a caller
+// cannot accidentally re-enable stderr inheritance by passing { stdio: 'inherit' }.
+// Tests that need a custom runner should use _setGitRunner, not options.stdio.
+function _runGit(args, options) {
+  return childProcess.execFileSync('git', args, { ...options, stdio: ['ignore', 'pipe', 'pipe'] });
+}
+let _gitRunner = _runGit;
 
 export function log(fields) {
   const entry = { ts: new Date().toISOString(), ...fields };
@@ -64,7 +76,7 @@ export function _clearGitCache() { GIT_ROOT_CACHE.clear(); }
 /** @internal Test helper: override the git runner. */
 export function _setGitRunner(fn) { _gitRunner = fn; }
 /** @internal Test helper: restore the default git runner. */
-export function _resetGitRunner() { _gitRunner = (args, options) => childProcess.execFileSync('git', args, options); }
+export function _resetGitRunner() { _gitRunner = _runGit; }
 
 export const DEFAULT_SERVER_URL = 'http://localhost:3000';
 
@@ -74,6 +86,7 @@ export function ensureDataDir() {
   mkdirSync(SENDING_DIR,        { recursive: true });
   mkdirSync(DEDUP_DIR,          { recursive: true });
   mkdirSync(SESSION_PATHS_DIR,  { recursive: true });
+  mkdirSync(TRANSCRIPT_OFFSETS_DIR, { recursive: true });
   mkdirSync(GIT_REMOTES_DIR,    { recursive: true });
 }
 

package/client/token-usage.js

@@ -0,0 +1,47 @@
+/**
+ * Shared token-usage helpers used by both Claude Code (capture.js) and
+ * Codex (codex.js) normalization paths. Extracted to keep the two in sync
+ * and avoid silent divergence between the two tracking pipelines.
+ */
+
+/**
+ * Return `value` if it is a finite number, otherwise `null`.
+ * Used to guard JSON fields before copying them into raw payloads —
+ * protects against `NaN`, `undefined`, strings, etc. sneaking through.
+ */
+export function toNumberOrNull(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Lift Anthropic-style usage fields from `usage` onto a shallow clone of
+ * `event`, renaming cache keys to the short form used by the dashboard SQL:
+ *
+ *   cache_read_input_tokens     -> cache_read_tokens
+ *   cache_creation_input_tokens -> cache_write_tokens
+ *
+ * Returns `event` unchanged if both `usage` and `model` are falsy, so callers
+ * can pass this through blindly without checking for presence first.
+ *
+ * Used by Cursor afterAgentResponse (where usage comes directly from the hook
+ * payload) and by Claude Code's per-call TokenUsage emission (where each call
+ * is one assistant line in the transcript). Codex has its own OpenAI-shaped
+ * helper because the field names differ.
+ *
+ * @param {object} event       Base object to clone (the hook event for Cursor,
+ *                             a synthetic minimal carrier for Claude Code's
+ *                             per-call events).
+ * @param {object|null} usage  Usage object with Anthropic-named keys.
+ * @param {string|null} model  Model name from the assistant line.
+ */
+export function buildTokenUsageRaw(event, usage, model) {
+  if (!usage && !model) return event;
+  return {
+    ...event,
+    ...(model ? { model } : {}),
+    ...(toNumberOrNull(usage?.input_tokens) != null ? { input_tokens: usage.input_tokens } : {}),
+    ...(toNumberOrNull(usage?.output_tokens) != null ? { output_tokens: usage.output_tokens } : {}),
+    ...(toNumberOrNull(usage?.cache_read_input_tokens) != null ? { cache_read_tokens: usage.cache_read_input_tokens } : {}),
+    ...(toNumberOrNull(usage?.cache_creation_input_tokens) != null ? { cache_write_tokens: usage.cache_creation_input_tokens } : {}),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lens",
-  "version": "0.8.51",
+  "version": "0.8.52",
   "type": "module",
   "description": "Centralized session analytics for AI coding tools",
   "bin": {