zopkit-bug-resolution-mcp 1.6.0 → 1.8.0

package/README.md

@@ -27,18 +27,24 @@ usage status — instead of hand-rolling curl commands:
   company-admin panel's "Claude Usage" tab, via `POST /api/admin/claude-usage`.
 - **`report_claude_token_usage`** — unlike the one above, this one is NOT
   self-attested: it scans this developer's own local Claude Code transcripts
-  (`~/.claude/projects/**/*.jsonl`, same machine the MCP server runs on — no
-  `/usage`, no status line, no asking a human) for the last 7 days, dedupes
-  streamed duplicates by `message.id`, and reports real input/output/
-  cache-creation/cache-read token totals, session count, and whether any
-  sessions used web search or spawned subagents, via
+  (`~/.claude/projects/**/*.jsonl` AND their nested `.../subagents/*.jsonl` —
+  same machine the MCP server runs on, no `/usage`, no status line, no
+  asking a human) for a configurable window (`days`, default 7), streamed
+  line-by-line and cached per-file so repeat calls in one session are
+  near-instant. Dedupes streamed duplicates by `message.id` and reports real
+  input/output/cache-creation/cache-read token totals (subagent spend folded
+  in, not just detected), a per-model split, how full the most recently
+  active session's context window currently is, session count, and whether
+  any sessions used web search or spawned subagents — via
   `POST /api/admin/claude-usage/token-breakdown`. Also runs automatically,
-  fire-and-forget, as a side effect of the four bug-report tools above
-  (`submit_bug_resolution`, `fetch_bug_context`, `fetch_assigned_bugs`,
-  `create_bug_report`) on success — so a developer who never touches this
-  tool directly still gets a token breakdown reported just by doing normal
-  bug-report work. Failures from the auto-report path are swallowed
-  entirely; they never surface as a tool error.
+  genuinely non-blocking (never awaited), as a side effect of the four
+  bug-report tools above (`submit_bug_resolution`, `fetch_bug_context`,
+  `fetch_assigned_bugs`, `create_bug_report`) on success — so a developer
+  who never touches this tool directly still gets a token breakdown
+  reported just by doing normal bug-report work, with zero added latency on
+  those calls. Failures from the auto-report path are swallowed entirely;
+  they never surface as a tool error, and (since it isn't awaited) never
+  delay the real response either.
 
 All six are thin wrappers — see `backend/src/features/bug-reports/README.md`
 and `backend/src/features/claude-usage/README.md` for what each endpoint
@@ -150,16 +156,21 @@ Four more, independent of the fetch/resolve flow above:
   `/usage`, the status line, or the account's billing page — there's no way
   for the tool to look this up itself) to update the "Claude Usage" tab in
   the company-admin panel. Pass an optional `note` for context (e.g. "Team
-  plan, resets Monday").
-- Ask it to call `report_claude_token_usage` (no input needed) to push a
-  real token/session breakdown for the last 7 days up to the same "Claude
-  Usage" tab — distinct from and independent of `report_claude_usage`
-  above. You usually don't need to call this directly: it already fires
-  automatically after every successful `fetch_bug_context`,
-  `submit_bug_resolution`, `fetch_assigned_bugs`, or `create_bug_report`
-  call, and a short note gets appended to that tool's own response telling
-  you it happened (e.g. "Also updated your Claude token usage: 2.1M new
-  tokens across 3 session(s) this week.").
+  plan, resets Monday"), and an optional `resetsAt` (ISO timestamp) whenever
+  you can see a concrete reset time (e.g. in the status line's rate-limit
+  JSON) — this is what lets the panel show real staleness instead of a
+  human having to parse a reset time out of free-text `note`.
+- Ask it to call `report_claude_token_usage` (optionally with `days: N` to
+  scan a window other than the default 7) to push a real token/model/context
+  breakdown up to the same "Claude Usage" tab — distinct from and
+  independent of `report_claude_usage` above. You usually don't need to call
+  this directly: it already fires automatically after every successful
+  `fetch_bug_context`, `submit_bug_resolution`, `fetch_assigned_bugs`, or
+  `create_bug_report` call, genuinely in the background (it's never awaited,
+  so it adds no latency and its own response text never shows up in that
+  tool's reply) — this standalone call is for an explicit, on-demand check
+  with a full summary (tokens by model, current context occupancy, subagent
+  share) in the response.
 
 ## Notes
 
@@ -173,3 +184,86 @@ Four more, independent of the fetch/resolve flow above:
 - `fetch_bug_context` and `submit_bug_resolution` still need a report id —
   this server doesn't search or browse. `fetch_assigned_bugs` is the one tool
   that doesn't require knowing an id up front.
+- `report_claude_token_usage`'s breakdown only ever sends the BASENAME of a
+  session's working directory (e.g. `isocode`, not `/Users/you/Downloads/
+  isocode`) to the company-admin panel — real project names, no full
+  filesystem paths or usernames, even though the local scan reads the full
+  path off the transcript.
+
+---
+
+## Usage reporting (v1.8.0)
+
+Three reporters ship alongside the MCP server. They are plain commands
+Claude Code spawns — a status line and two hooks — not MCP tools, because
+what they report has to be captured at moments no tool call happens at.
+
+```bash
+npx zopkit-bug-resolution-mcp --init-usage-reporting --api-key bugres_…
+# then restart Claude Code
+```
+
+That writes `~/.claude/.zopkit-usage.json` (mode 0600 — it holds your API
+key) and adds a `statusLine` plus two hooks to `~/.claude/settings.json`.
+It backs the file up first, never overwrites an existing `statusLine`, and
+is idempotent.
+
+### What each one does
+
+| | fires | reports |
+|---|---|---|
+| `bin/zopkit-statusline.js` | every assistant message (300ms debounce), `/compact`, session start/resume, rate-limit reset | per-session context occupancy, the account's 5h/7d limit percentages, session cost |
+| `bin/zopkit-task-marker.js` | `PostToolUse` on `fetch_bug_context` / `submit_bug_resolution` | the session's cumulative tokens at each end of a task window |
+| `bin/zopkit-session-end.js` | `SessionEnd` | that the session is over |
+
+The status line is the interesting one. Claude Code hands it a JSON payload
+containing `rate_limits.seven_day.used_percentage` — the number `/usage`
+shows, which nothing server-side can fetch on your behalf. A status-line
+script isn't a third party; it runs inside your own session. So that figure
+no longer has to be typed in by a human (`report_claude_usage`, now legacy).
+
+Two rules the status-line script follows, both load-bearing:
+
+1. **It renders before it touches the network.** Claude Code cancels an
+   in-flight status-line script when the next update arrives, so a slow
+   fetch ahead of the first write would blank the bar.
+2. **It whitelists fields, never forwards the payload.** The payload
+   carries more than this feature needs. `session_name` — your session's
+   AI-generated title, i.e. a description of what you're working on — is
+   sent **only** with `--share-session-name`, because it lands on a panel
+   every staff member with the `claude-usage` section can read.
+
+### Checking your Claude Code is new enough
+
+These fields arrived across several releases, so "is my client new enough"
+has a different answer per field:
+
+```bash
+# capture one payload
+cd /tmp && claude --settings '{"statusLine":{"type":"command","command":"tee /tmp/sl.json"}}'
+# …let it render once, exit, then:
+npx zopkit-bug-resolution-mcp --check-statusline < /tmp/sl.json
+```
+
+It prints which fields are present and what goes empty without each.
+
+### Backfilling past bugs
+
+The task markers are already in every transcript you've ever written, so
+bugs you fixed before installing the hook can be attributed retroactively:
+
+```bash
+npx zopkit-bug-resolution-mcp --backfill-tasks --dry-run
+npx zopkit-bug-resolution-mcp --backfill-tasks
+```
+
+Reconstruction is weaker than live markers and tags every window it writes
+`backfill`, which the panel renders differently. Known imprecisions: a
+window includes anything else you did inside it; an un-submitted window is
+closed at the first 30-minute gap (without that, one ran 738 minutes and
+swallowed its whole session); and only transcripts on this machine exist.
+
+### Turning it off
+
+Delete `~/.claude/.zopkit-usage.json` — every reporter no-ops without it —
+or remove the `statusLine` / `hooks` entries from `~/.claude/settings.json`.

package/bin/zopkit-backfill-tasks.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// One-shot historical backfill of per-task token attribution.
+//
+// The PostToolUse marker hook only knows about tasks worked AFTER it is
+// installed. But the markers it relies on — fetch_bug_context and
+// submit_bug_resolution tool calls — are already sitting in every
+// transcript ever written, so the same windows can be reconstructed
+// retroactively.
+//
+// Reconstruction is strictly weaker than live markers, and says so: every
+// window it writes is tagged attributionSource 'backfill', which the panel
+// renders differently from a measured one. Three known imprecisions:
+//
+//  - A window includes everything the developer did inside it. If they
+//    wandered off to an unrelated file, it is still charged to the bug.
+//  - An un-submitted window has no natural end, so it is closed at the
+//    first gap longer than IDLE_GAP_MS. Without that, one historical
+//    window ran 738 minutes and swallowed the rest of the session.
+//  - Only transcripts on THIS machine are visible. Work done elsewhere, or
+//    through the panel rather than the MCP tool, is simply absent — which
+//    is why coverage is reported at the end rather than left to assume.
+//
+// Usage:
+//   npx zopkit-bug-resolution-mcp --backfill-tasks [--days 90] [--dry-run]
+
+import { createReadStream, readdirSync, statSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { loadConfig, post } from '../lib/zopkit-config.js';
+
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+const START_TOOL = 'mcp__bug-resolution__fetch_bug_context';
+const END_TOOL = 'mcp__bug-resolution__submit_bug_resolution';
+const SYNTHETIC_MODEL = '<synthetic>';
+
+// An un-submitted window ends at the first gap longer than this. Picked to
+// sit above a long single turn (a big refactor, a slow test run) and below
+// a meal.
+const IDLE_GAP_MS = 30 * 60 * 1000;
+
+function emptyTotals() {
+  return { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+}
+
+function addUsage(byModel, model, usage) {
+  const t = (byModel[model] ??= emptyTotals());
+  t.inputTokens += usage.input_tokens || 0;
+  t.outputTokens += usage.output_tokens || 0;
+  t.cacheCreationTokens += usage.cache_creation_input_tokens || 0;
+  t.cacheReadTokens += usage.cache_read_input_tokens || 0;
+}
+
+async function readEntries(filePath) {
+  const out = [];
+  let stream;
+  try {
+    stream = createReadStream(filePath, { encoding: 'utf8' });
+  } catch {
+    return out;
+  }
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      try {
+        out.push(JSON.parse(line));
+      } catch {
+        // partial final line
+      }
+    }
+  } finally {
+    rl.close();
+    stream.destroy();
+  }
+  return out;
+}
+
+function toolUses(entry) {
+  const c = entry?.message?.content;
+  return Array.isArray(c) ? c.filter((b) => b?.type === 'tool_use') : [];
+}
+
+/** Reconstruct every task window in one session transcript. */
+async function windowsForSession(filePath, sinceMs) {
+  const entries = await readEntries(filePath);
+  if (entries.length === 0) return [];
+
+  const sessionId = basename(filePath, '.jsonl');
+  const windows = [];
+  let current = null;
+  let seen = new Set();
+  let lastTs = null;
+
+  const close = () => {
+    if (current && current.turns > 0) windows.push(current);
+    current = null;
+    seen = new Set();
+  };
+
+  const sorted = entries
+    .filter((e) => e.timestamp)
+    .sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : 0));
+
+  for (const entry of sorted) {
+    const ts = entry.timestamp;
+
+    if (entry.type === 'system' && entry.subtype === 'turn_duration' && current) {
+      current.activeMs = (current.activeMs ?? 0) + (entry.durationMs || 0);
+      continue;
+    }
+    if (entry.type !== 'assistant' || !entry.message) continue;
+
+    // An un-submitted window stops at the first long gap, rather than
+    // running to the end of the session.
+    if (current && !current.closed && lastTs && Date.parse(ts) - Date.parse(lastTs) > IDLE_GAP_MS) {
+      close();
+    }
+    lastTs = ts;
+
+    // Marker detection runs on every line, duplicates included — setting a
+    // boundary twice is harmless, unlike double-counting tokens.
+    for (const block of toolUses(entry)) {
+      if (block.name === START_TOOL && block.input?.bugReportId) {
+        close();
+        current = {
+          bugReportId: block.input.bugReportId,
+          sessionId,
+          startedAt: ts,
+          endedAt: ts,
+          byModel: {},
+          turns: 0,
+          subagentTurns: 0,
+          activeMs: null,
+          closed: false,
+        };
+      } else if (block.name === END_TOOL && current && block.input?.bugReportId === current.bugReportId) {
+        current.closed = true;
+      }
+    }
+
+    if (!current) continue;
+
+    const messageId = entry.message.id;
+    if (messageId) {
+      if (seen.has(messageId)) continue;
+      seen.add(messageId);
+    }
+    const usage = entry.message.usage;
+    if (!usage) continue;
+    const model = entry.message.model || 'unknown';
+    if (model === SYNTHETIC_MODEL) continue;
+
+    addUsage(current.byModel, model, usage);
+    current.turns += 1;
+    current.endedAt = ts;
+
+    if (current.closed) close();
+  }
+  close();
+
+  // Fold in subagent spend that falls inside a window. Subagent transcripts
+  // carry the parent sessionId, so a timestamp range is enough to attribute
+  // them — and omitting them undercounts a window that fanned out.
+  const subDir = join(filePath.replace(/\.jsonl$/, ''), 'subagents');
+  let subFiles = [];
+  try {
+    subFiles = readdirSync(subDir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.jsonl'))
+      .map((e) => join(subDir, e.name));
+  } catch {
+    // none
+  }
+  for (const sub of subFiles) {
+    const subEntries = await readEntries(sub);
+    for (const w of windows) {
+      const subSeen = new Set();
+      for (const entry of subEntries) {
+        if (entry.type !== 'assistant' || !entry.message || !entry.timestamp) continue;
+        if (entry.timestamp < w.startedAt || entry.timestamp > w.endedAt) continue;
+        const id = entry.message.id;
+        if (id) {
+          if (subSeen.has(id)) continue;
+          subSeen.add(id);
+        }
+        const usage = entry.message.usage;
+        if (!usage) continue;
+        const model = entry.message.model || 'unknown';
+        if (model === SYNTHETIC_MODEL) continue;
+        addUsage(w.byModel, model, usage);
+        w.subagentTurns += 1;
+      }
+    }
+  }
+
+  return windows.filter((w) => Date.parse(w.endedAt) >= sinceMs);
+}
+
+function listSessionTranscripts() {
+  const files = [];
+  let dirs;
+  try {
+    dirs = readdirSync(PROJECTS_DIR, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue;
+    const dirPath = join(PROJECTS_DIR, d.name);
+    let entries;
+    try {
+      entries = readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (e.isFile() && e.name.endsWith('.jsonl')) files.push(join(dirPath, e.name));
+    }
+  }
+  return files;
+}
+
+function fmt(n) {
+  if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+  return String(n);
+}
+
+export async function runBackfill({ days = 90, dryRun = false } = {}) {
+  const cfg = loadConfig();
+  if (!cfg && !dryRun) {
+    console.error('No API key — run `npx zopkit-bug-resolution-mcp --init-usage-reporting` first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const sinceMs = Date.now() - days * 24 * 60 * 60 * 1000;
+  const transcripts = listSessionTranscripts();
+  console.error(`Scanning ${transcripts.length} transcripts for task markers (last ${days} days)…`);
+
+  const all = [];
+  for (const file of transcripts) {
+    try {
+      // Cheap pre-filter: most transcripts never touched a bug tool.
+      if (statSync(file).size === 0) continue;
+      const found = await windowsForSession(file, sinceMs);
+      all.push(...found);
+    } catch {
+      // unreadable transcript — skip, don't abort the run
+    }
+  }
+
+  if (all.length === 0) {
+    console.error('No task windows found. Nothing to backfill.');
+    return;
+  }
+
+  const bugs = new Set(all.map((w) => w.bugReportId));
+  console.error(`\n${all.length} windows across ${bugs.size} bugs:\n`);
+  for (const w of all.sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1)).slice(0, 20)) {
+    const newTokens = Object.values(w.byModel).reduce(
+      (s, t) => s + t.inputTokens + t.outputTokens + t.cacheCreationTokens,
+      0
+    );
+    const cacheRead = Object.values(w.byModel).reduce((s, t) => s + t.cacheReadTokens, 0);
+    console.error(
+      `  ${w.bugReportId.slice(0, 8)}  ${fmt(newTokens).padStart(8)} new  ${fmt(cacheRead).padStart(8)} cr  ` +
+        `${String(w.turns).padStart(3)} turns  ${w.closed ? 'closed' : 'open  '}  ` +
+        `${w.activeMs === null ? ' —' : `${Math.round(w.activeMs / 60000)}m`}`
+    );
+  }
+  if (all.length > 20) console.error(`  … and ${all.length - 20} more`);
+
+  if (dryRun) {
+    console.error('\n--dry-run: nothing posted.');
+    return;
+  }
+
+  let ok = 0;
+  let failed = 0;
+  for (const w of all) {
+    const res = await post('/api/admin/bug-reports/task-window', {
+      bugReportId: w.bugReportId,
+      sessionId: w.sessionId,
+      startedAt: w.startedAt,
+      // An un-submitted window has no real end; recording the last turn as
+      // one would claim the task finished there. It did not.
+      endedAt: w.closed ? w.endedAt : null,
+      activeMs: w.activeMs,
+      turns: w.turns,
+      subagentTurns: w.subagentTurns,
+      byModel: w.byModel,
+      attributionSource: 'backfill',
+    });
+    if (res?.success) ok += 1;
+    else failed += 1;
+  }
+
+  console.error(`\nPosted ${ok} windows${failed ? `, ${failed} failed` : ''}.`);
+  // Coverage, stated rather than assumed: a roll-up that silently omits
+  // most bugs reads as "those fixes were cheap".
+  console.error(
+    `Coverage: ${bugs.size} bugs have attribution from this machine. Bugs worked through the ` +
+      'panel, on another machine, or without fetch_bug_context remain unattributed by design.'
+  );
+}

package/bin/zopkit-session-end.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// SessionEnd hook — drop a finished session off the Claude Usage panel at
+// once, instead of letting it age out of the live window.
+//
+// Best-effort by nature: a crashed terminal, a killed tmux pane or a closed
+// laptop never fire SessionEnd. That is exactly why the server derives
+// "live" from lastSeenAt rather than storing a flag — this hook makes the
+// common case immediate, it is not what makes it correct.
+//
+// Wire-up (settings.json):
+//   "SessionEnd": [{ "hooks": [{ "type": "command", "command": "<this script>" }] }]
+
+import { loadConfig, post, readStdinJson } from '../lib/zopkit-config.js';
+
+async function main() {
+  const payload = await readStdinJson();
+  if (!payload?.session_id) return;
+  if (!loadConfig()) return;
+
+  await post(
+    '/api/admin/claude-usage/session-end',
+    { sessionId: payload.session_id, reason: payload.reason },
+    // SessionEnd hooks share a 1.5s budget by default, so this gets a
+    // tighter timeout than the rest: better to leave the row to age out
+    // than to hold up the editor's shutdown.
+    { timeoutMs: 1200 }
+  );
+}
+
+main().catch(() => {});

package/bin/zopkit-statusline.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Status line + real-time usage heartbeat.
+//
+// Claude Code hands a statusLine command a JSON payload on stdin that
+// already contains everything the Claude Usage panel was guessing at:
+//
+//   context_window.{total_input_tokens,context_window_size,used_percentage}
+//   rate_limits.five_hour.used_percentage     <- the /usage number
+//   rate_limits.seven_day.used_percentage     <- ditto, the weekly one
+//   rate_limits.spend_limit.{used_usd,limit_usd}
+//   cost.total_cost_usd, model, session_id, workspace.repo, version, …
+//
+// That is the figure report_claude_usage was asking a human to read off
+// `/usage` and type in. It is not retrievable by a third party — but a
+// status-line script runs INSIDE the developer's own session, so it is not
+// a third party. Nothing reported here is self-attested.
+//
+// It re-runs on every new assistant message, on /compact, on session
+// start/resume, when a rate-limit window reaches its resets_at, and on an
+// optional refreshInterval timer, debounced at 300ms. One clock per
+// session, ticking independently — which is what makes concurrent sessions
+// work, where the old single-row-per-developer design could not.
+//
+// Install:  npx zopkit-bug-resolution-mcp --init-usage-reporting
+//
+// TWO RULES govern everything below:
+//
+//  1. RENDER BEFORE THE NETWORK. Claude Code cancels an in-flight status
+//     line script when the next update arrives. A slow fetch before the
+//     first write would blank the bar.
+//  2. WHITELIST, NEVER FORWARD. The payload carries more than this feature
+//     needs (session titles, prompt-cache miss causes). Only the named
+//     fields below are sent, and the session title only on explicit opt-in.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { loadConfig, post, readStdinJson } from '../lib/zopkit-config.js';
+
+// Per-session throttle. The status line fires on every assistant message; a
+// 40-turn session would otherwise be 40 POSTs. 15s keeps the panel's 10s
+// poll meaningfully fresh without that.
+const THROTTLE_MS = 15_000;
+
+const STATE_DIR = join(tmpdir(), 'zopkit-usage');
+
+function statePath(sessionId) {
+  return join(STATE_DIR, `${String(sessionId).replace(/[^\w.-]/g, '_')}.json`);
+}
+
+function readState(sessionId) {
+  try {
+    return JSON.parse(readFileSync(statePath(sessionId), 'utf8'));
+  } catch {
+    return { lastSentAt: 0, lastContextTokens: null };
+  }
+}
+
+function writeState(sessionId, state) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(statePath(sessionId), JSON.stringify(state));
+  } catch {
+    // A read-only tmpdir just means no throttling — still correct, only
+    // chattier. Never a reason to fail the status line.
+  }
+}
+
+function pct(n) {
+  return typeof n === 'number' && Number.isFinite(n) ? Math.floor(n) : null;
+}
+
+/** The line the developer actually sees. Kept deliberately plain — anyone
+ *  who wants branch/git decoration can wrap this script. */
+function render(p) {
+  const parts = [];
+  if (p.model?.display_name) parts.push(p.model.display_name);
+  const ctx = pct(p.context_window?.used_percentage);
+  if (ctx !== null) parts.push(`${ctx}% ctx`);
+  const week = pct(p.rate_limits?.seven_day?.used_percentage);
+  if (week !== null) parts.push(`${week}% wk`);
+  const fiveHour = pct(p.rate_limits?.five_hour?.used_percentage);
+  // Only worth the space once it is the binding constraint — the 5-hour
+  // window is what actually blocks you mid-afternoon.
+  if (fiveHour !== null && fiveHour >= 50) parts.push(`${fiveHour}% 5h`);
+  if (p.workspace?.git_worktree) parts.push(p.workspace.git_worktree);
+  return parts.join(' · ');
+}
+
+/** Only the named fields, never the raw payload. */
+function buildHeartbeat(p, cfg, fresh) {
+  return {
+    sessionId: p.session_id,
+    sessionName: cfg.shareSessionName ? (p.session_name ?? null) : null,
+    model: p.model?.id ?? null,
+    version: p.version ?? null,
+
+    contextTokens: p.context_window?.total_input_tokens ?? null,
+    contextLimit: p.context_window?.context_window_size ?? null,
+    contextPercent: p.context_window?.used_percentage ?? null,
+    exceeds200k: p.exceeds_200k_tokens ?? null,
+
+    cwd: p.workspace?.current_dir ?? p.cwd ?? null,
+    repo: p.workspace?.repo?.name ?? null,
+    gitBranch: p.workspace?.git_worktree ?? null,
+
+    costUsd: p.cost?.total_cost_usd ?? null,
+    linesAdded: p.cost?.total_lines_added ?? null,
+    linesRemoved: p.cost?.total_lines_removed ?? null,
+    effort: p.effort?.level ?? null,
+    fastMode: p.fast_mode ?? null,
+
+    rateLimits: p.rate_limits ?? null,
+
+    // Whether a NEW API response landed since the last heartbeat for this
+    // session, detected by the context token count moving. Only a fresh
+    // reading may advance the account-level percentages: an idle session's
+    // status line still re-renders on a timer carrying `rate_limits` from
+    // its last API response, possibly an hour stale, and would otherwise
+    // walk a live session's number backwards.
+    fresh,
+  };
+}
+
+async function main() {
+  const payload = await readStdinJson();
+  if (!payload) return;
+
+  // RULE 1: the bar is written before anything can block.
+  process.stdout.write(render(payload));
+
+  const cfg = loadConfig();
+  if (!cfg || !payload.session_id) return;
+
+  const state = readState(payload.session_id);
+  const now = Date.now();
+  const contextTokens = payload.context_window?.total_input_tokens ?? null;
+  const fresh = contextTokens !== null && contextTokens !== state.lastContextTokens;
+
+  // Throttle, but never let a fresh reading wait: a developer watching
+  // their weekly percentage climb should see it move on the panel, not 15
+  // seconds later.
+  if (!fresh && now - (state.lastSentAt || 0) < THROTTLE_MS) return;
+
+  writeState(payload.session_id, { lastSentAt: now, lastContextTokens: contextTokens });
+  await post('/api/admin/claude-usage/heartbeat', buildHeartbeat(payload, cfg, fresh));
+}
+
+// Any unexpected throw must still leave the bar rendered and the editor
+// unbothered.
+main().catch(() => {});