zopkit-bug-resolution-mcp 1.7.0 → 1.8.0

package/README.md

@@ -189,3 +189,81 @@ Four more, independent of the fetch/resolve flow above:
   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(() => {});

package/bin/zopkit-task-marker.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Per-task token attribution — the PostToolUse hook.
+//
+// The two bug-resolution MCP tools already bracket a task precisely:
+//
+//   fetch_bug_context      "calling this IS starting work on it"
+//                          (open / failed_testing -> in_progress)
+//   submit_bug_resolution  ends it (-> needs_testing)
+//
+// So a PostToolUse hook matched on those two names knows exactly when a
+// task starts and stops, with the session id, the bug id (in tool_input)
+// and the transcript path all handed to it on stdin. It reads the session's
+// cumulative token totals at each boundary and posts them; the SERVER
+// subtracts. The delta is what the bug actually cost, per model.
+//
+// Why the server does the subtraction rather than this hook: a locally
+// cached baseline is lost on reboot (the end marker would then have nothing
+// to diff against), and keeping it server-side makes an in-flight window
+// reportable — "being worked right now, 120k tokens in" — which a local
+// diff cannot express until the task closes.
+//
+// Install:  npx zopkit-bug-resolution-mcp --init-usage-reporting
+//
+// Wire-up (settings.json):
+//   "PostToolUse": [{
+//     "matcher": "mcp__bug-resolution__(fetch_bug_context|submit_bug_resolution)",
+//     "hooks": [{ "type": "command", "command": "<this script>" }]
+//   }]
+
+import { loadConfig, post, readStdinJson } from '../lib/zopkit-config.js';
+import { scanSessionCumulative, EMPTY_CUMULATIVE } from '../lib/session-scan.js';
+
+const START_TOOL = 'fetch_bug_context';
+const END_TOOL = 'submit_bug_resolution';
+
+/** Which end of a window this tool call represents, or null if the hook
+ *  fired for something else (a broader matcher than the documented one). */
+function phaseFor(toolName) {
+  if (!toolName) return null;
+  if (toolName.endsWith(START_TOOL)) return 'start';
+  if (toolName.endsWith(END_TOOL)) return 'end';
+  return null;
+}
+
+async function main() {
+  const payload = await readStdinJson();
+  if (!payload) return;
+
+  const cfg = loadConfig();
+  if (!cfg) return;
+
+  const phase = phaseFor(payload.tool_name);
+  if (!phase) return;
+
+  const bugReportId = payload.tool_input?.bugReportId;
+  // fetch_assigned_bugs and create_bug_report carry no bugReportId; if a
+  // broader matcher routed one here there is simply no task to bracket.
+  if (!bugReportId || !payload.session_id) return;
+
+  // PostToolUse fires AFTER the tool succeeded, so by now the transcript
+  // already contains this turn — the reading includes the work up to and
+  // including the marker itself, consistently at both ends, which is what
+  // makes the subtraction clean.
+  const cumulative = payload.transcript_path
+    ? await scanSessionCumulative(payload.transcript_path).catch(() => EMPTY_CUMULATIVE)
+    : EMPTY_CUMULATIVE;
+
+  await post('/api/admin/bug-reports/task-marker', {
+    bugReportId,
+    sessionId: payload.session_id,
+    phase,
+    // The client's clock, not the server's: a hook can be retried or
+    // queued, and a window's boundaries must match the transcript they
+    // were read from.
+    observedAt: new Date().toISOString(),
+    byModel: cumulative.byModel,
+    turns: cumulative.turns,
+    subagentTurns: cumulative.subagentTurns,
+    activeMs: cumulative.activeMs,
+  });
+}
+
+// A hook that throws surfaces an error to the developer about telemetry
+// they did not ask to think about. Never that.
+main().catch(() => {});

package/index.js

@@ -44,6 +44,45 @@ import { createInterface } from 'node:readline';
 import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
 
+// ── CLI subcommands ───────────────────────────────────────────────────────
+// Handled BEFORE the server is constructed (and before the API-key guard
+// below), since --init-usage-reporting exists precisely to configure a
+// machine that has no key yet. Without a subcommand this falls straight
+// through to the stdio MCP server, which is the normal path.
+const argv = process.argv.slice(2);
+function flag(name) {
+  const i = argv.indexOf(`--${name}`);
+  return i === -1 ? undefined : (argv[i + 1]?.startsWith('--') ? true : argv[i + 1] ?? true);
+}
+
+if (argv.includes('--init-usage-reporting')) {
+  const { initUsageReporting } = await import('./lib/init-usage-reporting.js');
+  process.exit(
+    initUsageReporting({
+      apiKey: typeof flag('api-key') === 'string' ? flag('api-key') : undefined,
+      baseUrl: typeof flag('base-url') === 'string' ? flag('base-url') : undefined,
+      shareSessionName: argv.includes('--share-session-name'),
+    })
+  );
+}
+
+if (argv.includes('--check-statusline')) {
+  const { checkStatusline } = await import('./lib/init-usage-reporting.js');
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  process.exit(await checkStatusline(Buffer.concat(chunks).toString('utf8')));
+}
+
+if (argv.includes('--backfill-tasks')) {
+  const { runBackfill } = await import('./bin/zopkit-backfill-tasks.js');
+  const days = Number(flag('days'));
+  await runBackfill({
+    days: Number.isFinite(days) && days > 0 ? days : 90,
+    dryRun: argv.includes('--dry-run'),
+  });
+  process.exit(process.exitCode ?? 0);
+}
+
 const API_KEY = process.env.BUG_REPORT_API_KEY;
 const BASE_URL = (process.env.BUG_REPORT_API_BASE_URL || 'https://api.zopkit.com').replace(/\/$/, '');
 
@@ -52,7 +91,7 @@ if (!API_KEY) {
     'Generate one from the company-admin panel (Bug Reports → API Keys) and set it when registering this server.');
 }
 
-const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.7.0' });
+const server = new McpServer({ name: 'zopkit-bug-resolution', version: '1.8.0' });
 
 const BUG_SEVERITIES = ['low', 'medium', 'high', 'critical'];
 // Keep in sync with BUG_STATUSES in backend/src/db/schema/platform/bug-reports.ts.

package/lib/init-usage-reporting.js

@@ -0,0 +1,197 @@
+// `--init-usage-reporting` — wire the status line and the two hooks into
+// Claude Code, and write the credentials they need.
+//
+// Done as an explicit opt-in command rather than silently on install: this
+// edits the developer's own ~/.claude/settings.json and turns on reporting
+// to a shared team panel. Both deserve a deliberate action.
+//
+// It is conservative about what it touches:
+//  - never overwrites an existing statusLine (prints what to do instead),
+//  - appends its hooks rather than replacing the arrays,
+//  - is idempotent: running it twice changes nothing the second time,
+//  - backs the file up before writing.
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_PATH } from './zopkit-config.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const BIN = join(HERE, '..', 'bin');
+
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json');
+
+const STATUSLINE_CMD = `node ${join(BIN, 'zopkit-statusline.js')}`;
+const MARKER_CMD = `node ${join(BIN, 'zopkit-task-marker.js')}`;
+const SESSION_END_CMD = `node ${join(BIN, 'zopkit-session-end.js')}`;
+
+// The matcher the task marker relies on. Narrow on purpose — a broader one
+// would spawn a node process on every tool call in the session.
+const MARKER_MATCHER = 'mcp__bug-resolution__(fetch_bug_context|submit_bug_resolution)';
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/** Already present? Compare on the command string, so re-running after an
+ *  upgrade (same path) is a no-op rather than a duplicate. */
+function hasHook(entries, command) {
+  return (entries ?? []).some((e) => (e.hooks ?? []).some((h) => h.command === command));
+}
+
+export function initUsageReporting({ apiKey, baseUrl, shareSessionName = false } = {}) {
+  const log = (...a) => console.error(...a);
+
+  // ── 1. credentials ──────────────────────────────────────────────────
+  const key = apiKey || process.env.BUG_REPORT_API_KEY;
+  if (!key) {
+    log('No API key.');
+    log('  Generate one in the company-admin panel (Bug Reports → API Keys), then:');
+    log('    npx zopkit-bug-resolution-mcp --init-usage-reporting --api-key bugres_…');
+    log('  …or export BUG_REPORT_API_KEY and re-run.');
+    return 1;
+  }
+
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  const existingCfg = readJson(CONFIG_PATH, {});
+  writeFileSync(
+    CONFIG_PATH,
+    JSON.stringify(
+      {
+        ...existingCfg,
+        apiKey: key,
+        baseUrl: baseUrl || existingCfg.baseUrl || 'https://api.zopkit.com',
+        // Opt-in: the session title describes what you are working on, and
+        // it lands on a panel the whole staff can read.
+        shareSessionName: shareSessionName || existingCfg.shareSessionName || false,
+      },
+      null,
+      2
+    ) + '\n',
+    // The key is a credential; keep it off other accounts on the machine.
+    { mode: 0o600 }
+  );
+  log(`✓ credentials → ${CONFIG_PATH}`);
+
+  for (const f of ['zopkit-statusline.js', 'zopkit-task-marker.js', 'zopkit-session-end.js']) {
+    try {
+      chmodSync(join(BIN, f), 0o755);
+    } catch {
+      // bundled read-only (npx cache) — `node <path>` still works, and that
+      // is the form written into settings.json anyway.
+    }
+  }
+
+  // ── 2. settings.json ────────────────────────────────────────────────
+  const settings = readJson(SETTINGS_PATH, {});
+  if (existsSync(SETTINGS_PATH)) {
+    copyFileSync(SETTINGS_PATH, `${SETTINGS_PATH}.zopkit-backup`);
+    log(`✓ backed up → ${SETTINGS_PATH}.zopkit-backup`);
+  }
+
+  let changed = false;
+
+  if (!settings.statusLine) {
+    settings.statusLine = { type: 'command', command: STATUSLINE_CMD };
+    changed = true;
+    log('✓ statusLine configured');
+  } else if (settings.statusLine.command === STATUSLINE_CMD) {
+    log('· statusLine already configured');
+  } else {
+    // Never clobber: a custom status line is work the developer did, and
+    // theirs is probably nicer than ours.
+    log('! statusLine already set to something else — left alone.');
+    log('  To keep yours AND report usage, call ours from inside it (it reads stdin and');
+    log('  writes one line), or pipe the payload through:');
+    log(`    ${STATUSLINE_CMD}`);
+  }
+
+  settings.hooks ??= {};
+
+  settings.hooks.PostToolUse ??= [];
+  if (!hasHook(settings.hooks.PostToolUse, MARKER_CMD)) {
+    settings.hooks.PostToolUse.push({
+      matcher: MARKER_MATCHER,
+      hooks: [{ type: 'command', command: MARKER_CMD }],
+    });
+    changed = true;
+    log('✓ PostToolUse task-marker hook added');
+  } else {
+    log('· task-marker hook already present');
+  }
+
+  settings.hooks.SessionEnd ??= [];
+  if (!hasHook(settings.hooks.SessionEnd, SESSION_END_CMD)) {
+    settings.hooks.SessionEnd.push({ hooks: [{ type: 'command', command: SESSION_END_CMD }] });
+    changed = true;
+    log('✓ SessionEnd hook added');
+  } else {
+    log('· SessionEnd hook already present');
+  }
+
+  if (changed) {
+    writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n');
+    log(`✓ wrote ${SETTINGS_PATH}`);
+  }
+
+  log('');
+  log('Restart Claude Code for the status line and hooks to take effect.');
+  log('');
+  log('Then, to attribute bugs you already fixed on this machine:');
+  log('  npx zopkit-bug-resolution-mcp --backfill-tasks --dry-run');
+  log('');
+  log('Note: the account-level percentages come from rate_limits in the status-line');
+  log('payload. If your Claude Code predates that field the panel still shows context');
+  log('and per-session cost; it just leaves the 5h/7d bars empty. Check with:');
+  log('  npx zopkit-bug-resolution-mcp --check-statusline');
+  return 0;
+}
+
+/**
+ * `--check-statusline` — print exactly which of the fields this feature
+ * depends on the local Claude Code actually emits.
+ *
+ * Worth having as a command rather than a docs note: the fields arrived in
+ * different releases, so "is my client new enough" has a different answer
+ * per field, and guessing wrong looks identical to a broken install.
+ */
+export async function checkStatusline(payloadText) {
+  let p;
+  try {
+    p = JSON.parse(payloadText);
+  } catch {
+    console.error('Pipe a status-line payload in. Easiest way to capture one:');
+    console.error('');
+    console.error('  cd /tmp && claude --settings \'{"statusLine":{"type":"command",' +
+      '"command":"tee /tmp/zopkit-sl.json"}}\'');
+    console.error('  # let it render once, exit, then:');
+    console.error('  npx zopkit-bug-resolution-mcp --check-statusline < /tmp/zopkit-sl.json');
+    return 1;
+  }
+
+  const checks = [
+    ['session_id', p.session_id, 'required — identifies the session'],
+    ['context_window.used_percentage', p.context_window?.used_percentage, 'the per-session context bar'],
+    ['context_window.context_window_size', p.context_window?.context_window_size, 'the bar\'s denominator'],
+    ['cost.total_cost_usd', p.cost?.total_cost_usd, 'per-session cost'],
+    ['rate_limits.five_hour.used_percentage', p.rate_limits?.five_hour?.used_percentage, 'the 5-hour bar'],
+    ['rate_limits.seven_day.used_percentage', p.rate_limits?.seven_day?.used_percentage, 'the weekly % — replaces self-reporting'],
+    ['rate_limits.spend_limit.used_usd', p.rate_limits?.spend_limit?.used_usd, 'gateway spend (needs CC >= 2.1.284)'],
+  ];
+
+  console.error(`Claude Code ${p.version ?? '(version not reported)'}\n`);
+  let missing = 0;
+  for (const [field, value, why] of checks) {
+    const present = value !== undefined && value !== null;
+    if (!present) missing += 1;
+    console.error(`  ${present ? '✓' : '✗'} ${field.padEnd(40)} ${present ? '' : `— absent; ${why} will be empty`}`);
+  }
+  console.error('');
+  console.error(missing === 0 ? 'Everything this feature uses is available.' : `${missing} field(s) absent — upgrade Claude Code to fill them in.`);
+  return 0;
+}

package/lib/session-scan.js

@@ -0,0 +1,150 @@
+// Cumulative token accounting for ONE Claude Code session.
+//
+// index.js's computeWeeklyTokenBreakdown answers "how much did this
+// developer spend this week", scanning every transcript in a time window.
+// This answers a different question — "how much has THIS session spent so
+// far, in total" — which is what task attribution is built on: the marker
+// hook reads this at each boundary and the server subtracts, so the delta
+// between fetch_bug_context and submit_bug_resolution is the bug's real cost.
+//
+// Deliberately NOT time-windowed. A window boundary inside a session would
+// make the two readings incomparable, and the subtraction is what makes the
+// time filter unnecessary anyway.
+
+import { createReadStream, readdirSync, statSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { join, dirname, basename } from 'node:path';
+
+/** Models Claude Code logs for its own synthetic messages (rate-limit
+ *  notices, interrupts). They carry a zero usage block and no real spend. */
+const SYNTHETIC_MODEL = '<synthetic>';
+
+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;
+}
+
+/**
+ * Subagent transcripts for a session live in a nested directory a flat
+ * listing never finds: …/<projectDir>/<sessionId>/subagents/*.jsonl. Their
+ * spend is real and belongs to whatever task was running at the time, so a
+ * task window that ignored them would undercount — sometimes by a third.
+ */
+function subagentFiles(transcriptPath) {
+  const dir = join(dirname(transcriptPath), basename(transcriptPath, '.jsonl'), 'subagents');
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith('.jsonl'))
+      .map((e) => join(dir, e.name));
+  } catch {
+    return []; // no subagents for this session — the common case
+  }
+}
+
+/**
+ * Stream one transcript, folding its assistant turns into `acc`.
+ *
+ * Streams line-by-line rather than readFileSync+split: a long session's
+ * transcript runs to hundreds of MB, and this is called from a hook on the
+ * critical path of a tool call.
+ */
+async function foldTranscript(filePath, acc, { isSubagent }) {
+  let stream;
+  try {
+    stream = createReadStream(filePath, { encoding: 'utf8' });
+  } catch {
+    return;
+  }
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      if (!line.trim()) continue;
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue; // a partially-flushed last line, not a reason to abandon the file
+      }
+
+      // Claude Code's own measure of time actually spent on a turn. Summed
+      // instead of using wall-clock, which measures when the developer went
+      // to lunch: one historical window read as 738 minutes of "work" that
+      // was really 36. Main thread only — a subagent's duration overlaps
+      // its parent's and would double-count.
+      if (!isSubagent && entry.type === 'system' && entry.subtype === 'turn_duration') {
+        acc.activeMs = (acc.activeMs ?? 0) + (entry.durationMs || 0);
+        continue;
+      }
+
+      if (entry.type !== 'assistant' || !entry.message) continue;
+
+      // Streaming writes the same final usage numbers 2-3x per real
+      // response (once per content-block flush), so totals would be
+      // inflated 2-3x without this.
+      const messageId = entry.message.id;
+      if (messageId) {
+        if (acc._seen.has(messageId)) continue;
+        acc._seen.add(messageId);
+      }
+
+      const usage = entry.message.usage;
+      if (!usage) continue;
+      const model = entry.message.model || 'unknown';
+      if (model === SYNTHETIC_MODEL) continue;
+
+      addUsage(acc.byModel, model, usage);
+      if (isSubagent) acc.subagentTurns += 1;
+      else acc.turns += 1;
+    }
+  } finally {
+    rl.close();
+    stream.destroy();
+  }
+}
+
+/**
+ * Everything this session has spent so far.
+ *
+ * Subagent spend is folded INTO byModel (so the totals are complete) and
+ * also counted separately as subagentTurns, matching the convention the
+ * weekly breakdown already uses.
+ *
+ * activeMs stays null when the transcript has no turn_duration records at
+ * all — older Claude Code versions don't write them, and "unknown" must not
+ * collapse into "zero minutes of work".
+ */
+export async function scanSessionCumulative(transcriptPath) {
+  const acc = {
+    byModel: {},
+    turns: 0,
+    subagentTurns: 0,
+    activeMs: null,
+    _seen: new Set(),
+  };
+  try {
+    statSync(transcriptPath);
+  } catch {
+    return { byModel: {}, turns: 0, subagentTurns: 0, activeMs: null };
+  }
+  await foldTranscript(transcriptPath, acc, { isSubagent: false });
+  for (const sub of subagentFiles(transcriptPath)) {
+    await foldTranscript(sub, acc, { isSubagent: true });
+  }
+  return {
+    byModel: acc.byModel,
+    turns: acc.turns,
+    subagentTurns: acc.subagentTurns,
+    activeMs: acc.activeMs,
+  };
+}
+
+/** Round-trip-safe empty reading, for a session whose transcript cannot be
+ *  read at all (the marker still records a window; it just measures zero). */
+export const EMPTY_CUMULATIVE = { byModel: {}, turns: 0, subagentTurns: 0, activeMs: null };

package/lib/zopkit-config.js

@@ -0,0 +1,93 @@
+// Shared config for the hook/status-line binaries (bin/*.js).
+//
+// The MCP server itself gets BUG_REPORT_API_KEY from the `env` block of the
+// mcpServers entry in ~/.claude.json. Hooks and the status line do NOT —
+// they are plain commands Claude Code spawns, inheriting only the ordinary
+// shell environment, which does not have that key.
+//
+// So they read a small config file instead, and fall back to the env var for
+// anyone who does export it globally. The file lives outside the repo on
+// purpose: an API key in settings.json is one `git add` away from being
+// committed.
+//
+//   ~/.claude/.zopkit-usage.json
+//   { "apiKey": "bugres_…", "baseUrl": "https://api.zopkit.com" }
+//
+// Create it with:  npx zopkit-bug-resolution-mcp --init-usage-reporting
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const CONFIG_PATH = join(homedir(), '.claude', '.zopkit-usage.json');
+
+let cached;
+
+export function loadConfig() {
+  if (cached !== undefined) return cached;
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    // Missing or unreadable is the normal case before setup — not an error
+    // worth printing, since these binaries run on every status-line render
+    // and must never write noise into a developer's terminal.
+  }
+  const apiKey = file.apiKey || process.env.BUG_REPORT_API_KEY || null;
+  const baseUrl = (file.baseUrl || process.env.BUG_REPORT_API_BASE_URL || 'https://api.zopkit.com').replace(/\/$/, '');
+  // Opt-in, default off. The session title describes what a developer is
+  // working on, which is a step beyond the cwd this feature already
+  // collects, and it lands on a panel every staff member with the
+  // 'claude-usage' section can read.
+  const shareSessionName = file.shareSessionName === true;
+  cached = apiKey ? { apiKey, baseUrl, shareSessionName } : null;
+  return cached;
+}
+
+/**
+ * POST, with a hard timeout and every failure swallowed.
+ *
+ * Nothing these binaries report is worth degrading the editor over: a status
+ * line that hangs on a network call blanks the bar, and a hook that throws
+ * surfaces an error to the developer about telemetry they did not ask to
+ * think about. The next heartbeat is seconds away, so there is nothing to
+ * retry either.
+ */
+export async function post(path, body, { timeoutMs = 5000 } = {}) {
+  const cfg = loadConfig();
+  if (!cfg) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${cfg.baseUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': cfg.apiKey },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) return null;
+    return await res.json().catch(() => null);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Read all of stdin as text. Claude Code hands hooks and the status line
+ *  their JSON payload this way. */
+export async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/** Parse the stdin payload, returning null rather than throwing — a
+ *  malformed payload must not take the status line down with it. */
+export async function readStdinJson() {
+  try {
+    return JSON.parse(await readStdin());
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "zopkit-bug-resolution-mcp",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
-  "description": "MCP server for Zopkit wrapper bug reports: fetch full bug context (with screenshots), submit how a bug was fixed, list bugs assigned to you, file new bug reports, report your Claude Code usage status, and report a real token/model/context-window breakdown (including subagent spend) from your local transcripts. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) — see README.md.",
+  "description": "MCP server + status-line/hook reporters for Zopkit wrapper bug reports: fetch full bug context (with screenshots), submit how a bug was fixed, list bugs assigned to you, file new bug reports, and report REAL Claude Code usage \u2014 live per-session context and account rate limits via the status line, plus per-bug token attribution via PostToolUse hooks. Requires a BUG_REPORT_API_KEY (generated in the company-admin panel) \u2014 see README.md.",
   "license": "UNLICENSED",
   "engines": {
     "node": ">=18"
@@ -13,7 +13,9 @@
   },
   "files": [
     "index.js",
-    "README.md"
+    "README.md",
+    "bin/",
+    "lib/"
   ],
   "scripts": {
     "start": "node index.js"