great-cto 3.52.0 → 3.53.0

package/board/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "great-cto",
   "description": "You already have the agent. This is everything around it. great_cto runs Claude Code as a pipeline of 72 specialist agents \u2014 an independent model checks each stage before the next builds on it, spending caps refuse rather than warn, and three decisions stay yours: what gets built, how, and whether it ships.",
-  "version": "3.52.0",
+  "version": "3.53.0",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"

package/board/packages/board/lib/routes.mjs

@@ -13,6 +13,7 @@ import { sseClients, notifHistory } from './state.mjs';
 import { autoRegisterProject, listProjects, resolveProjectCwd, resolveProjectInfo, getChangeTier, readProjectsRegistry, getRegistryDegradation } from './projects.mjs';
 import { readVerdictsWithHealth } from './verdicts.mjs';
 import { agentUsage, usageSnapshot } from '../../../scripts/lib/agent-usage.mjs';
+import { usageIndexSnapshot, summarizeUsage, readCodexTitles } from '../../../scripts/lib/session-usage.mjs';
 import { reviewerStatus } from '../../../scripts/lib/required-reviewers.mjs';
 import { readSessionStatus } from '../../../scripts/lib/session-status.mjs';
 import { readScores, summarizeScores } from '../../../scripts/lib/scores.mjs';
@@ -1492,6 +1493,31 @@ async function dispatch(req, res, url, cwd) {
     return true;
   }
 
+  // What Claude Code and Codex consumed on this machine — tokens, models, the
+  // heaviest conversations, tools, skills, agents, cache, Codex's plan window —
+  // read from the hosts' own session logs (scripts/lib/session-usage.mjs).
+  // Machine-wide like /api/agent-usage: the logs are one history. Served on the
+  // board's own host only; nothing here is sent anywhere.
+  if (pathname === '/api/usage') {
+    const rawDays = parseInt(url.searchParams.get('days') || '30', 10);
+    const days = Number.isFinite(rawDays) && rawDays > 0 ? Math.min(rawDays, 365) : 30;
+    const snap = boardSessionUsage().get();
+    let body;
+    if (snap.state !== 'ready') {
+      body = { state: snap.state, why: snap.why };
+    } else {
+      const sum = summarizeUsage(snap.index, { days, codexTitles: readCodexTitles() });
+      const ours = new Set(boardAgentNames());
+      for (const host of Object.keys(sum.lists)) {
+        sum.lists[host].agents = sum.lists[host].agents.map((a) => ({ ...a, ours: ours.has(a.name) }));
+      }
+      body = { ...sum, seen: snap.seen, files: snap.files };
+    }
+    res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+    return true;
+  }
+
   // Domain reviewers this project's PROJECT.md requires (archetype, packs,
   // compliance), each with whether a verdict exists — the list gate:ship refuses on.
   // Sessions in this project that wait for a person — written by the
@@ -2141,14 +2167,24 @@ async function dispatch(req, res, url, cwd) {
 
 
 let _usageSnap = null;
+function boardAgentNames() {
+  const agentsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'agents');
+  try { return fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)); } catch { return []; }
+}
+
 function boardUsage() {
   if (!_usageSnap) {
-    const agentsDir = path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'agents');
-    let agents = [];
-    try { agents = fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)); } catch { /* none: every count is unavailable-by-omission */ }
+    // No agents dir: every count is unavailable-by-omission.
+    const agents = boardAgentNames();
     _usageSnap = usageSnapshot({ compute: () => agentUsage({ agents }) });
   }
   return _usageSnap;
 }
 
+let _sessionUsageSnap = null;
+function boardSessionUsage() {
+  if (!_sessionUsageSnap) _sessionUsageSnap = usageIndexSnapshot();
+  return _sessionUsageSnap;
+}
+
 export { dispatch, secondOpinionForTree };

package/board/packages/board/lib/view-counter.mjs

@@ -21,12 +21,14 @@
 import fs from 'fs';
 import path from 'path';
 
-// The only view names the redesigned IA renders (BRD-R8): Decisions, Ledger,
-// Fleet, Harness, Settings, plus the demoted-to-deep-link `kanban`. Anything
-// else is rejected outright, before any filesystem write — an unknown view
-// name written to this file would silently corrupt the K2/K3 counts it
-// exists to protect.
-const VALID_VIEWS = ['decisions', 'ledger', 'fleet', 'harness', 'settings', 'kanban'];
+// The view names the board routes to (index.html `ROUTES`): Work, History,
+// Decisions, Ledger, Fleet, Harness, Usage, Settings, plus the demoted-to-deep-link
+// `kanban`. Anything else is rejected outright, before any filesystem write — an
+// unknown view name written to this file would silently corrupt the K2/K3 counts
+// it exists to protect. Work and History were routed and missing from this list,
+// so opening either answered 400 into the console; the test now pins the two
+// lists to each other.
+const VALID_VIEWS = ['work', 'history', 'decisions', 'ledger', 'fleet', 'harness', 'usage', 'settings', 'kanban'];
 
 function logFilePath(root) {
   return path.join(root, '.great_cto', 'view-counter.log');

package/board/packages/board/public/index.html

@@ -2369,6 +2369,63 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
 
 /* ── Metrics page ─────────────────────────────────────────────────────────── */
 .metrics-page { padding: 24px 32px; }
+
+/* Usage (great_cto-egkw) — two hosts side by side, every block in two columns
+   that fold into one at phone width. */
+.usage-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; flex-wrap: wrap; }
+.usage-chips {
+  display: inline-flex; gap: 4px; padding: 3px;
+  background: var(--bg-muted); border: 1px solid var(--border);
+}
+.usage-chip {
+  background: transparent; border: none; color: var(--text2);
+  padding: 5px 12px; min-height: 32px; cursor: pointer;
+  font-family: var(--mono); font-size: var(--fs-caption); font-weight: 500; letter-spacing: 0.05em;
+}
+.usage-chip:hover { color: var(--text); }
+.usage-chip.active { background: var(--accent); color: var(--on-accent); }
+.usage-chip:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }
+.usage-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 380px), 1fr)); gap: 12px; margin-bottom: 20px; }
+.usage-card { background: var(--bg-card); border: 1px solid var(--border); padding: 16px 18px; min-width: 0; }
+.usage-card h3 { font-size: var(--fs-title-s); font-weight: 600; margin: 0 0 10px; color: var(--text); display: flex; justify-content: space-between; gap: 8px; }
+.usage-card h3 .muted { font-weight: 400; font-size: var(--fs-caption); }
+.usage-big { font-family: var(--display); font-size: var(--fs-num-m); font-variant-numeric: tabular-nums; color: var(--text); line-height: 1.1; }
+.usage-stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(110px, 1fr)); gap: 10px; margin-top: 12px; }
+.usage-stat { min-width: 0; }
+.usage-stat b { display: block; font-family: var(--mono); font-size: var(--fs-title-s); font-weight: 500; font-variant-numeric: tabular-nums; color: var(--text); }
+.usage-stat span { font-size: var(--fs-caption); color: var(--text3); }
+.usage-limit { margin-top: 14px; padding-top: 12px; border-top: 1px solid var(--border); }
+.usage-limit-head { display: flex; justify-content: space-between; gap: 8px; font-size: var(--fs-small); color: var(--text2); }
+.usage-limit-head b { font-family: var(--mono); font-variant-numeric: tabular-nums; color: var(--text); font-weight: 500; }
+.usage-meter { height: 8px; background: var(--bg-muted); border: 1px solid var(--border); margin: 6px 0; }
+.usage-meter > span { display: block; height: 100%; background: var(--accent); }
+.usage-meter.warn > span { background: var(--status-progress); }
+.usage-meter.full > span { background: var(--status-blocked); }
+.usage-sub { font-size: var(--fs-caption); color: var(--text3); line-height: 1.5; }
+.usage-note { font-size: var(--fs-small); color: var(--text2); line-height: 1.55; }
+.usage-chart svg { display: block; width: 100%; height: 120px; }
+.usage-axis { display: flex; justify-content: space-between; font-family: var(--mono); font-size: var(--fs-caption); color: var(--text3); margin-top: 4px; }
+.usage-legend { display: flex; flex-wrap: wrap; gap: 4px 14px; font-size: var(--fs-caption); color: var(--text2); margin-top: 8px; }
+.usage-legend i { display: inline-block; width: 10px; height: 10px; margin-right: 5px; vertical-align: -1px; }
+.usage-table-wrap { overflow-x: auto; }
+.usage-table { width: 100%; border-collapse: collapse; font-size: var(--fs-small); }
+.usage-table th { text-align: left; font-weight: 500; color: var(--text3); font-size: var(--fs-caption); padding: 4px 6px; border-bottom: 1px solid var(--border); white-space: nowrap; }
+.usage-table td { padding: 6px; border-bottom: 1px solid var(--border); color: var(--text); vertical-align: top; }
+.usage-table td.num, .usage-table th.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabular-nums; white-space: nowrap; }
+.usage-title { max-width: 260px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.usage-tag { display: inline-block; font-family: var(--mono); font-size: var(--fs-eyebrow); letter-spacing: 0.04em; padding: 1px 5px; margin-left: 6px; border: 1px solid var(--border-strong); color: var(--text2); }
+.usage-share { display: inline-block; width: 48px; height: 6px; background: var(--bg-muted); margin-right: 6px; vertical-align: 1px; }
+.usage-share > span { display: block; height: 100%; background: var(--accent); }
+.usage-sec-head { display: flex; justify-content: space-between; align-items: center; gap: 12px; flex-wrap: wrap; margin-bottom: 12px; }
+.usage-sec-head .mp-section-label { margin: 0; }
+.usage-lists { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 12px; margin-bottom: 20px; }
+.usage-list { list-style: none; margin: 0; padding: 0; }
+.usage-list li { display: grid; grid-template-columns: minmax(0, 1fr) auto; gap: 8px; font-size: var(--fs-small); padding: 4px 0; position: relative; }
+.usage-list li .nm { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--text); }
+.usage-list li .n { font-family: var(--mono); font-variant-numeric: tabular-nums; color: var(--text2); }
+.usage-list li .bar { grid-column: 1 / -1; height: 3px; background: var(--bg-muted); }
+.usage-list li .bar > span { display: block; height: 100%; background: var(--accent); opacity: 0.7; }
+@media (max-width: 767px) { .usage-title { max-width: 160px; } .usage-chip { min-height: 44px; } }
 .mp-section-label {
   font-family: var(--mono); font-size: var(--fs-caption);
   letter-spacing: 0.1em; text-transform: uppercase;
@@ -3355,6 +3412,10 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
         <span>Harness</span>
         <span class="count" id="nav-harness-count"></span>
       </div>
+      <div class="nav-item" data-tab="usage" role="tab" tabindex="0" aria-label="Usage" title="Usage" onkeydown="navTabKeydown(event, this)" onclick="switchTab('usage', this)">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M4 20V10 M10 20V4 M16 20v-7 M22 20H2"/></svg>
+        <span>Usage</span>
+      </div>
     </nav>
     </details>
     <div class="nav-divider"></div>
@@ -3603,6 +3664,23 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
       </div>
     </div>
 
+    <!-- Usage (great_cto-egkw). What Claude Code and Codex consumed on this
+         machine, read from the hosts' own session logs by
+         scripts/lib/session-usage.mjs. Machine-wide, not per project. -->
+    <div class="panel" id="panel-usage" role="tabpanel">
+      <div class="metrics-page">
+        <div class="usage-head">
+          <h1 class="page-title">Usage <span class="muted" style="font-weight:400;font-size:var(--fs-small)">what Claude Code and Codex consumed on this machine</span></h1>
+          <div class="usage-chips" role="group" aria-label="Period">
+            <button type="button" class="usage-chip" data-days="7" onclick="loadUsage(7)">7D</button>
+            <button type="button" class="usage-chip active" data-days="30" onclick="loadUsage(30)">30D</button>
+            <button type="button" class="usage-chip" data-days="90" onclick="loadUsage(90)">90D</button>
+          </div>
+        </div>
+        <div id="usage-body" class="usage-note" role="status">Reading the session logs of Claude Code and Codex on this machine.</div>
+      </div>
+    </div>
+
     <div class="panel" id="panel-kanban">
       <h1 class="page-title">Tasks</h1>
       <div id="filter-bar" class="filter-bar"></div>
@@ -5877,6 +5955,216 @@ function renderAgentActivity(snap) {
 // The Harnesses card. Four states for the second opinion, and the fourth is
 // the reason the card exists: `unavailable` — declared codex, no codex here —
 // must never look like `none` or like a switch someone turned off.
+// ── Usage (great_cto-egkw) ─────────────────────────────────────────────────
+// Both hosts, side by side, from /api/usage. Three honesty rules carried from
+// the reader: an unpriced model is n/a, never $0; Claude Code's plan use is not
+// written anywhere, so it is not drawn — only the refusals are; and a host with
+// no logs on this machine says so instead of showing zeros.
+let usageDays = 30;
+let usageHost = 'claude';
+let usageData = null;
+let _usageTimer = null;
+const USAGE_HOSTS = { claude: 'Claude Code', codex: 'Codex' };
+const USAGE_LOGS = { claude: '~/.claude/projects', codex: '~/.codex/sessions' };
+const USAGE_FN = { chat: 'Conversations', subagent: 'Subagents', automation: 'Automations', headless: 'Headless runs' };
+const USAGE_FN_COLOR = { chat: 'var(--accent)', subagent: 'var(--status-progress)', automation: 'var(--status-gate)', headless: 'var(--text3)' };
+
+function fmtTok(n) {
+  n = Number(n) || 0;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+function fmtUsdEq(n) {
+  if (n == null) return null;
+  return n >= 100 ? `$${Math.round(n).toLocaleString('en-US')}` : `$${n.toFixed(2)}`;
+}
+const fmtPct = (x) => (x == null ? null : `${Math.round(x * 100)}%`);
+
+async function loadUsage(days) {
+  if (days) usageDays = days;
+  document.querySelectorAll('.usage-chip[data-days]').forEach((c) => c.classList.toggle('active', Number(c.dataset.days) === usageDays));
+  clearTimeout(_usageTimer);
+  const d = await api(`/api/usage?days=${usageDays}`);
+  const body = document.getElementById('usage-body');
+  if (!body) return;
+  if (!d || d.error) {
+    body.className = 'usage-note';
+    body.textContent = `Usage could not be read: ${(d && d.error) || 'the board is not reachable — is the server still running?'}`;
+    return;
+  }
+  if (d.state === 'computing') {
+    body.className = 'usage-note';
+    body.textContent = `Counting — ${d.why}`;
+    _usageTimer = setTimeout(() => { if (currentTab === 'usage') loadUsage(); }, 2000);
+    return;
+  }
+  if (d.state !== 'counted') {
+    body.className = 'usage-note';
+    body.textContent = `Usage is not available: ${d.why || d.state}`;
+    return;
+  }
+  usageData = d;
+  renderUsage(d);
+}
+
+function setUsageHost(host) {
+  usageHost = host;
+  if (usageData) renderUsage(usageData);
+}
+
+function usageLimitWindow(minutes) {
+  if (minutes === 10080) return 'Weekly limit';
+  if (minutes === 300) return '5-hour limit';
+  return minutes ? `${minutes}-minute limit` : 'Limit';
+}
+
+function usageHostCard(d, host) {
+  const name = USAGE_HOSTS[host];
+  if (!d.seen || !d.seen[host]) {
+    return `<section class="usage-card" data-host="${host}"><h3>${name}</h3><p class="usage-note">No ${name} session logs on this machine (${USAGE_LOGS[host]}) — nothing to count, which is not the same as nothing used.</p></section>`;
+  }
+  const h = d.hosts[host];
+  const unpricedHere = (d.models || []).filter((m) => m.host === host && m.usd == null).map((m) => m.model);
+  const usd = h.usd == null
+    ? absent('uncomputable', `no price is set for ${unpricedHere.join(', ') || 'these models'} — add one to ~/.great_cto/model-prices.json`)
+    : esc(fmtUsdEq(h.usd)) + (h.unpricedResponses ? ` <span class="usage-tag" title="${esc(`${h.unpricedResponses} responses from unpriced models are not in this figure`)}">partial</span>` : '');
+  const stat = (v, label) => `<div class="usage-stat"><b>${v}</b><span>${label}</span></div>`;
+  let limit;
+  if (host === 'codex') {
+    const L = d.limits && d.limits.codex;
+    const win = (w) => {
+      if (!w) return '';
+      const used = Math.max(0, Math.min(100, Number(w.used) || 0));
+      const cls = used >= 90 ? 'full' : used >= 70 ? 'warn' : '';
+      const resets = w.resets ? fmtDT(new Date(w.resets * 1000).toISOString()) : '—';
+      return `<div class="usage-limit-head"><span>${usageLimitWindow(w.minutes)}</span><b>${used}% used</b></div>
+        <div class="usage-meter ${cls}" role="meter" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${used}" aria-label="${esc(usageLimitWindow(w.minutes))}"><span style="width:${used}%"></span></div>
+        <div class="usage-sub">resets ${esc(resets)}</div>`;
+    };
+    limit = L && (L.primary || L.secondary)
+      ? `<div class="usage-limit">${win(L.primary)}${win(L.secondary)}<div class="usage-sub">plan ${esc(L.plan || '—')} · as Codex last reported it, ${esc(relTime(L.at))} ago</div></div>`
+      : `<div class="usage-limit"><div class="usage-limit-head"><span>Plan limit</span>${absent('unloaded', 'no Codex session has reported its rate-limit window yet')}</div></div>`;
+  } else {
+    const hits = h.limitHits || { plan: 0, server: 0 };
+    limit = `<div class="usage-limit"><div class="usage-limit-head"><span>Plan limit</span>${absent('uncomputable', 'Claude Code does not write how much of the plan is used — only when a request is refused')}</div>
+      <div class="usage-sub">${hits.plan} refused at the plan limit · ${hits.server} server-side throttles (not your limit) in ${d.window.days} days</div></div>`;
+  }
+  return `<section class="usage-card" data-host="${host}">
+    <h3><span>${name}</span><span class="muted">${esc(d.window.from)} → ${esc(d.window.to)}</span></h3>
+    <div class="usage-big" title="${esc(`${(h.tokens || 0).toLocaleString('en-US')} tokens, cache reads included`)}">${fmtTok(h.tokens)} <span class="muted" style="font-size:var(--fs-small)">tokens</span></div>
+    <div class="usage-stats">
+      ${stat(usd, 'at API list price')}
+      ${stat(esc((h.sessions || 0).toLocaleString('en-US')), 'conversations')}
+      ${stat(esc((h.responses || 0).toLocaleString('en-US')), 'model responses')}
+      ${stat(h.hitRate == null ? absent('none', 'no input in this window') : esc(fmtPct(h.hitRate)), 'input from cache')}
+      ${stat(esc(fmtTok(h.output)), 'output tokens')}
+    </div>
+    ${limit}
+  </section>`;
+}
+
+function usageDayChart(d, host) {
+  const name = USAGE_HOSTS[host];
+  const head = `<h3><span>${name} by day</span><span class="muted">tokens</span></h3>`;
+  if (!d.seen || !d.seen[host]) return `<section class="usage-card usage-chart">${head}<p class="usage-note">No logs to draw.</p></section>`;
+  const days = d.daily || [];
+  const max = Math.max(0, ...days.map((x) => x[host].tokens));
+  if (!max) return `<section class="usage-card usage-chart">${head}<p class="usage-note">Nothing in this window.</p></section>`;
+  const fns = Object.keys(USAGE_FN).filter((f) => days.some((x) => x[host].byFn[f]));
+  const W = 10;
+  let bars = '';
+  days.forEach((x, i) => {
+    let y = 100;
+    const parts = fns.map((f) => `${USAGE_FN[f]} ${fmtTok(x[host].byFn[f] || 0)}`).join(' · ');
+    const tip = `${x.date}: ${fmtTok(x[host].tokens)} tokens${x[host].usd ? ` · ${fmtUsdEq(x[host].usd)}` : ''}${parts ? ` (${parts})` : ''}`;
+    bars += `<g><title>${esc(tip)}</title>`;
+    for (const f of fns) {
+      const v = x[host].byFn[f] || 0;
+      if (!v) continue;
+      const hgt = (v / max) * 96;
+      y -= hgt;
+      bars += `<rect x="${i * W + 1}" y="${y.toFixed(2)}" width="${W - 2}" height="${hgt.toFixed(2)}" fill="${USAGE_FN_COLOR[f]}"></rect>`;
+    }
+    bars += `<rect x="${i * W}" y="0" width="${W}" height="100" fill="transparent"></rect></g>`;
+  });
+  const legend = fns.map((f) => `<span><i style="background:${USAGE_FN_COLOR[f]}"></i>${USAGE_FN[f]} ${fmtTok(d.hosts[host].byFn[f] || 0)}</span>`).join('');
+  return `<section class="usage-card usage-chart">${head}
+    <svg viewBox="0 0 ${days.length * W} 100" preserveAspectRatio="none" role="img" aria-label="${esc(`${name} tokens per day, peak ${fmtTok(max)}`)}">${bars}</svg>
+    <div class="usage-axis"><span>${esc(days[0].date)}</span><span>peak ${fmtTok(max)}</span><span>${esc(days[days.length - 1].date)}</span></div>
+    <div class="usage-legend">${legend}</div>
+  </section>`;
+}
+
+function usageTopTable(d, host) {
+  const name = USAGE_HOSTS[host];
+  const rows = (d.top && d.top[host]) || [];
+  const head = `<h3><span>${name}: heaviest conversations</span><span class="muted">share of ${name} tokens</span></h3>`;
+  if (!rows.length) return `<section class="usage-card">${head}<p class="usage-note">${d.seen && d.seen[host] ? 'Nothing in this window.' : 'No logs on this machine.'}</p></section>`;
+  const money = host === 'claude';
+  const body = rows.map((r) => {
+    const tag = r.fn && r.fn !== 'chat' ? `<span class="usage-tag">${esc(USAGE_FN[r.fn] || r.fn)}</span>` : '';
+    const sub = r.subagentTokens ? `<div class="usage-sub">${fmtPct(r.subagentTokens / r.tokens)} in subagents</div>` : '';
+    const share = Math.max(1, Math.round(r.share * 100));
+    return `<tr>
+      <td><div class="usage-title" title="${esc(r.title)}">${esc(r.title)}</div>${sub}</td>
+      <td>${esc(r.project || '—')}${tag}</td>
+      <td class="num"><span class="usage-share" aria-hidden="true"><span style="width:${share}%"></span></span>${fmtPct(r.share)}</td>
+      <td class="num">${fmtTok(r.tokens)}</td>
+      ${money ? `<td class="num">${r.usd == null ? absent('uncomputable', 'a model in this conversation has no price') : esc(fmtUsdEq(r.usd))}</td>` : ''}
+    </tr>`;
+  }).join('');
+  return `<section class="usage-card">${head}<div class="usage-table-wrap"><table class="usage-table">
+    <thead><tr><th>Conversation</th><th>Project</th><th class="num">Share</th><th class="num">Tokens</th>${money ? '<th class="num">$ list</th>' : ''}</tr></thead>
+    <tbody>${body}</tbody></table></div></section>`;
+}
+
+function usageModels(d) {
+  const rows = d.models || [];
+  if (!rows.length) return '<p class="usage-note">No model responses in this window.</p>';
+  const body = rows.map((m) => {
+    const fast = m.model.endsWith('@fast');
+    const label = fast ? `${m.model.slice(0, -5)} (fast)` : m.model;
+    return `<tr><td>${esc(USAGE_HOSTS[m.host])}</td><td>${esc(label)}</td><td class="num">${m.responses.toLocaleString('en-US')}</td><td class="num">${fmtTok(m.tokens)}</td><td class="num">${fmtTok(m.output)}</td>
+      <td class="num">${m.usd == null ? absent('uncomputable', `no price is set for ${m.model} — add one to ~/.great_cto/model-prices.json`) : esc(fmtUsdEq(m.usd))}</td></tr>`;
+  }).join('');
+  return `<section class="usage-card" style="margin-bottom:20px"><div class="usage-table-wrap"><table class="usage-table">
+    <thead><tr><th>Host</th><th>Model</th><th class="num">Responses</th><th class="num">Tokens</th><th class="num">Output</th><th class="num">$ list</th></tr></thead>
+    <tbody>${body}</tbody></table></div></section>`;
+}
+
+function usageList(title, rows, empty) {
+  if (!rows || !rows.length) return `<section class="usage-card"><h3><span>${title}</span></h3><p class="usage-note">${empty}</p></section>`;
+  const max = Math.max(...rows.map((r) => r.n));
+  const items = rows.map((r) => `<li><span class="nm" title="${esc(r.name)}">${esc(r.name)}${r.ours ? '<span class="usage-tag">great_cto</span>' : ''}</span><span class="n">${r.n.toLocaleString('en-US')}</span><span class="bar" aria-hidden="true"><span style="width:${Math.max(2, Math.round((r.n / max) * 100))}%"></span></span></li>`).join('');
+  return `<section class="usage-card"><h3><span>${title}</span></h3><ul class="usage-list">${items}</ul></section>`;
+}
+
+function renderUsage(d) {
+  const body = document.getElementById('usage-body');
+  if (!body) return;
+  body.className = '';
+  const l = (d.lists && d.lists[usageHost]) || {};
+  const hostBtn = (h) => `<button type="button" class="usage-chip${usageHost === h ? ' active' : ''}" aria-pressed="${usageHost === h}" onclick="setUsageHost('${h}')">${USAGE_HOSTS[h]}</button>`;
+  body.innerHTML = `
+    <div class="usage-grid">${usageHostCard(d, 'claude')}${usageHostCard(d, 'codex')}</div>
+    <h2 class="mp-section-label">By day, by kind of work</h2>
+    <div class="usage-grid">${usageDayChart(d, 'claude')}${usageDayChart(d, 'codex')}</div>
+    <h2 class="mp-section-label">Heaviest conversations</h2>
+    <div class="usage-grid">${usageTopTable(d, 'claude')}${usageTopTable(d, 'codex')}</div>
+    <h2 class="mp-section-label">Models</h2>
+    ${usageModels(d)}
+    <div class="usage-sec-head"><h2 class="mp-section-label">What was called</h2><div class="usage-chips" role="group" aria-label="Host">${hostBtn('claude')}${hostBtn('codex')}</div></div>
+    <div class="usage-lists">
+      ${usageList('Tools', l.tools, 'No tool calls in this window.')}
+      ${usageList('Skills', l.skills, 'No skills were loaded in this window.')}
+      ${usageList('Agents', l.agents, 'No subagents were dispatched in this window.')}
+      ${usageList('MCP servers', l.mcp, 'No MCP tools were called in this window.')}
+    </div>
+    <p class="usage-note">Read on this machine from ${USAGE_LOGS.claude} and ${USAGE_LOGS.codex}; nothing is sent anywhere. Tokens include cache reads. <b>$ list</b> is the API list-price equivalent from great_cto's price table, not a subscription bill — Claude Code's own estimate can differ for some models. A model without a price shows n/a, never $0.</p>`;
+}
+
 async function renderHarnesses() {
   const body = document.getElementById('harnesses-body');
   const status = document.getElementById('harnesses-status');
@@ -8340,6 +8628,7 @@ function cmdkActions() {
     { group: 'Go', label: 'Ledger — what it cost, what is running', run: () => switchTab('ledger') },
     { group: 'Go', label: 'Fleet — the agents and what they may do', run: () => switchTab('fleet') },
     { group: 'Go', label: 'Harness — host and second opinion', run: () => switchTab('harness') },
+    { group: 'Go', label: 'Usage — what Claude Code and Codex consumed', run: () => switchTab('usage') },
     { group: 'Go', label: 'Settings', run: () => switchTab('settings') },
     { group: 'Go', label: 'Tasks board (#/kanban, deep link)', run: () => switchTab('kanban') },
     { group: 'Do', label: 'New issue', run: () => openNewIssueModal() },
@@ -8532,7 +8821,7 @@ try {
 // panels, not keys.
 const DEST = { decisions: 'inbox', ledger: 'budgets', fleet: 'agents', dashboard: 'budgets', share: 'settings', notifications: 'settings' };
 const NAV = { inbox: 'decisions', budgets: 'ledger', agents: 'fleet', dashboard: 'ledger', share: 'settings', notifications: 'settings' };
-const ROUTES = { work: 1, history: 1, decisions: 1, ledger: 1, fleet: 1, harness: 1, settings: 1, kanban: 1 };
+const ROUTES = { work: 1, history: 1, decisions: 1, ledger: 1, fleet: 1, harness: 1, usage: 1, settings: 1, kanban: 1 };
 function switchTab(id, el) {
   const lid = DEST[id] || id;          // the panel's own name
   const navKey = NAV[id] || id;        // the destination to highlight
@@ -8541,7 +8830,7 @@ function switchTab(id, el) {
   currentTab = lid;
   document.getElementById('nav-views-label').hidden = lid !== 'agents';
   document.querySelector('.nav-views').hidden = lid !== 'agents';
-  if (['agents', 'budgets', 'harness'].includes(lid)) document.getElementById('tools-nav').open = true;
+  if (['agents', 'budgets', 'harness', 'usage'].includes(lid)) document.getElementById('tools-nav').open = true;
   if (lid === 'work' || lid === 'history') window.GctoWork.refresh();
   if (ROUTES[id]) {
     if (location.hash !== `#/${id}`) history.replaceState(null, '', `#/${id}`);
@@ -8562,7 +8851,7 @@ function switchTab(id, el) {
   // crumb — `labels` used to be referenced here but is only ever a function-local in
   // this file, so this threw ReferenceError on every tab switch and skipped the per-tab
   // loaders below (e.g. logs stuck on "Loading…"). Use a local label map.
-  const TAB_LABELS = { work: 'Work', history: 'History', decisions: 'Decisions', ledger: 'Ledger', fleet: 'Fleet', harness: 'Harness', settings: 'Settings', budgets: 'Budgets', docs: 'Docs', dashboard: 'Board', inbox: 'Inbox', tasks: 'Tasks', agents: 'Agents', logs: 'Activity', notifications: 'Notifications', metrics: 'Metrics', share: 'Share' };
+  const TAB_LABELS = { work: 'Work', history: 'History', decisions: 'Decisions', ledger: 'Ledger', fleet: 'Fleet', harness: 'Harness', usage: 'Usage', settings: 'Settings', budgets: 'Budgets', docs: 'Docs', dashboard: 'Board', inbox: 'Inbox', tasks: 'Tasks', agents: 'Agents', logs: 'Activity', notifications: 'Notifications', metrics: 'Metrics', share: 'Share' };
   const crumb = document.getElementById('crumb-here'); if (crumb) crumb.textContent = TAB_LABELS[id] || TAB_LABELS[lid] || 'Board';
   // Budgets render on Metrics, so the heartbeat that feeds them has to be
   // fetched when Metrics opens — not only from the agents drill-in it used to
@@ -8595,6 +8884,7 @@ function switchTab(id, el) {
   if (lid === 'notifications' || lid === 'settings') loadNotifications();
   if (lid === 'settings') loadSettingsPage();
   if (lid === 'harness') renderHarnesses();
+  if (lid === 'usage') loadUsage();
 }
 
 // Sidebar tabs: Enter/Space activate, arrows move (WAI-ARIA tablist).

package/board/scripts/lib/session-usage.mjs

@@ -0,0 +1,629 @@
+/**
+ * session-usage — what Claude Code and Codex actually consumed on this machine,
+ * read from their own session logs.
+ *
+ *   Claude Code  ~/.claude/projects/<slug>/<session>.jsonl
+ *                ~/.claude/projects/<slug>/<session>/subagents/agent-*.jsonl
+ *   Codex        ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
+ *                ~/.codex/archived_sessions/rollout-*.jsonl
+ *
+ * Both hosts already write per-response token usage, the model, every tool call
+ * and — Codex only — the plan's rate-limit window. Nothing on the board read it:
+ * the Ledger priced verdicts, which is what great_cto's agents reported, not
+ * what the hosts spent. This module is the missing reader.
+ *
+ * Rules, each from a way this goes wrong:
+ *
+ *  - One assistant response is written as SEVERAL Claude Code lines, one per
+ *    content block, and every one of them repeats the same `usage`. Summing lines
+ *    counts a response two to three times (58 lines, 26 responses in the session
+ *    this was found in). Usage is taken once per `message.id`; tool calls are
+ *    taken per line, because each line carries a different block.
+ *  - Codex reports `input_tokens` INCLUDING the cached part. It is split here
+ *    into fresh input and cache reads so both hosts share one shape.
+ *  - Dollars are not stored. Tokens are stored per day per model and priced when
+ *    read, so a price override applies to history, and a model nobody priced is
+ *    reported as unpriced, never as free.
+ *  - A 429 is not a plan limit. Claude Code writes "not your usage limit" on a
+ *    server-side throttle; the two are counted apart.
+ *  - Read-only on the logs. The index lives in ~/.great_cto. A file that
+ *    disappears (Claude Code prunes old transcripts) keeps its counted days: the
+ *    history is ours once read, and losing it would read as a quiet month.
+ *  - Append-only files are read from the last complete line, so a refresh costs
+ *    the new bytes, not the gigabytes.
+ *  - Nothing here leaves the machine. Titles and project names are private; the
+ *    board serves them on its own host only.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { priceUsage, effectivePrices } from './cost-meter.mjs';
+
+const INDEX_VERSION = 1;
+const RING = 256;                 // recent response ids remembered across reads
+const KEEP_GONE_DAYS = 400;       // how long a vanished file's days are kept
+const CHUNK = 1 << 20;
+
+const home = () => os.homedir();
+export const DEFAULT_CLAUDE_DIR = () => path.join(home(), '.claude', 'projects');
+export const DEFAULT_CODEX_DIRS = () => [path.join(home(), '.codex', 'sessions'), path.join(home(), '.codex', 'archived_sessions')];
+export const DEFAULT_CODEX_TITLES = () => path.join(home(), '.codex', 'session_index.jsonl');
+export const DEFAULT_CACHE_FILE = () => path.join(home(), '.great_cto', 'session-usage-index.json');
+
+const short = (s) => createHash('sha1').update(String(s)).digest('hex').slice(0, 16);
+
+/** Local calendar day of an ISO timestamp — the operator's day, not UTC's. */
+export function dayOf(ts) {
+  const d = new Date(ts);
+  if (Number.isNaN(d.getTime())) return null;
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/**
+ * A working directory → the project a person would name.
+ * Agent worktrees are folded into the repository they belong to: forty
+ * `wt-1788…` rows would hide which project the work was for.
+ */
+export function projectName(cwd, homeDir = home()) {
+  if (!cwd || typeof cwd !== 'string') return null;
+  const cw = cwd.match(/^(.*)\/\.claude\/worktrees\/[^/]+/);
+  if (cw) return path.basename(cw[1]);
+  const cx = cwd.match(/\/\.codex\/worktrees\/[^/]+\/([^/]+)/);
+  if (cx) return cx[1];
+  if (path.resolve(cwd) === path.resolve(homeDir)) return '~';
+  return path.basename(cwd) || null;
+}
+
+// ── file discovery ────────────────────────────────────────────────────────────
+
+function walk(dir, maxDepth, out) {
+  const go = (d, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) { if (depth < maxDepth) go(p, depth + 1); }
+      else if (e.isFile() && e.name.endsWith('.jsonl')) out.push(p);
+    }
+  };
+  go(dir, 0);
+  return out;
+}
+
+export function listLogFiles({ claudeDir = DEFAULT_CLAUDE_DIR(), codexDirs = DEFAULT_CODEX_DIRS() } = {}) {
+  const files = [];
+  const seen = { claude: false, codex: false };
+  if (isDir(claudeDir)) { seen.claude = true; for (const f of walk(claudeDir, 4, [])) files.push({ host: 'claude', file: f }); }
+  for (const d of codexDirs) {
+    if (isDir(d)) { seen.codex = true; for (const f of walk(d, 4, [])) files.push({ host: 'codex', file: f }); }
+  }
+  return { files, seen };
+}
+
+function isDir(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+// ── shared accumulation ───────────────────────────────────────────────────────
+
+function emptyDay() {
+  return { in: 0, out: 0, cr: 0, cw: 0, cwh: 0, rs: 0, msgs: 0, models: {}, tools: {}, skills: {}, agents: {}, mcp: {}, lim: { plan: 0, server: 0 } };
+}
+
+function dayBucket(entry, ts) {
+  const day = dayOf(ts);
+  if (!day) return null;
+  return entry.days[day] || (entry.days[day] = emptyDay());
+}
+
+const bump = (map, key, n = 1) => { if (key) map[key] = (map[key] || 0) + n; };
+
+function addTokens(b, model, t) {
+  b.in += t.in; b.out += t.out; b.cr += t.cr; b.cw += t.cw; b.cwh += t.cwh; b.rs += t.rs; b.msgs += 1;
+  const m = b.models[model] || (b.models[model] = { in: 0, out: 0, cr: 0, cw: 0, cwh: 0, msgs: 0 });
+  m.in += t.in; m.out += t.out; m.cr += t.cr; m.cw += t.cw; m.cwh += t.cwh; m.msgs += 1;
+}
+
+function countTool(b, name) {
+  if (!name) return;
+  if (name.startsWith('mcp__')) {
+    const server = name.split('__')[1] || name;
+    bump(b.mcp, server);
+  }
+  bump(b.tools, name);
+}
+
+function remember(ring, id) {
+  ring.push(id);
+  if (ring.length > RING) ring.splice(0, ring.length - RING);
+}
+
+function touchSpan(meta, ts) {
+  if (!ts) return;
+  if (!meta.first || ts < meta.first) meta.first = ts;
+  if (!meta.last || ts > meta.last) meta.last = ts;
+}
+
+// ── Claude Code ───────────────────────────────────────────────────────────────
+
+/** Session id, parent and function of a Claude Code transcript, from its path. */
+function claudeFileMeta(file) {
+  const base = path.basename(file, '.jsonl');
+  const dir = path.dirname(file);
+  if (path.basename(dir) === 'subagents') {
+    const parent = path.basename(path.dirname(dir));
+    let agentType = null;
+    try { agentType = JSON.parse(fs.readFileSync(path.join(dir, `${base}.meta.json`), 'utf8')).agentType || null; } catch { /* older layout: no meta */ }
+    return { session: base, parent, fn: 'subagent', agentType };
+  }
+  return { session: base, parent: null, fn: null, agentType: null };
+}
+
+const PLAN_LIMIT_TEXT = /not your usage limit/i;
+
+/** `great-cto:senior-dev` and `senior-dev` are one agent; `feature-dev:code-reviewer` is not ours. */
+export function agentName(raw) {
+  if (typeof raw !== 'string' || !raw) return 'general-purpose';
+  return raw.replace(/^great[-_]cto:/, '');
+}
+
+export function claudeLine(entry, line) {
+  // Most bytes in a transcript are tool RESULTS in user lines. They carry no
+  // usage, so they are not parsed — except to name a session that has no title.
+  const isAssistant = line.includes('"type":"assistant"');
+  const isTitle = line.includes('"custom-title"');
+  const wantsPrompt = !entry.meta.prompt && !entry.meta.title && line.includes('"type":"user"');
+  if (!isAssistant && !isTitle && !wantsPrompt) return;
+  let r;
+  try { r = JSON.parse(line); } catch { return; }
+  const meta = entry.meta;
+
+  if (r.type === 'custom-title' && r.customTitle) { meta.title = String(r.customTitle).slice(0, 160); return; }
+  if (r.type === 'user') {
+    if (r.isCompactSummary || r.isMeta) return;
+    const c = r.message?.content;
+    const text = typeof c === 'string' ? c : Array.isArray(c) ? c.filter((b) => b?.type === 'text').map((b) => b.text || '').join(' ') : '';
+    const clean = text.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    if (clean && !clean.startsWith('Caveat:')) meta.prompt = clean.slice(0, 120);
+    return;
+  }
+  if (r.type !== 'assistant') return;
+
+  const ts = typeof r.timestamp === 'string' ? r.timestamp : null;
+  if (!ts) return;
+  touchSpan(meta, ts);
+  if (!meta.cwd && r.cwd) meta.cwd = r.cwd;
+  if (!meta.entry && r.entrypoint) meta.entry = r.entrypoint;
+  if (!meta.fn && !r.isSidechain) meta.fn = /^sdk/.test(r.entrypoint || '') ? 'headless' : 'chat';
+  const b = dayBucket(entry, ts);
+  if (!b) return;
+
+  if (r.isApiErrorMessage && r.error === 'rate_limit') {
+    const c = r.message?.content;
+    const text = Array.isArray(c) ? c.map((x) => x?.text || '').join(' ') : String(c || '');
+    if (PLAN_LIMIT_TEXT.test(text)) b.lim.server += 1; else b.lim.plan += 1;
+    return;
+  }
+
+  const msg = r.message || {};
+  for (const block of Array.isArray(msg.content) ? msg.content : []) {
+    if (block?.type !== 'tool_use') continue;
+    countTool(b, block.name);
+    if (block.name === 'Skill') bump(b.skills, typeof block.input?.skill === 'string' ? block.input.skill : null);
+    if (block.name === 'Agent' || block.name === 'Task') bump(b.agents, agentName(block.input?.subagent_type));
+  }
+
+  const u = msg.usage;
+  const model = msg.model;
+  if (!u || !model || model === '<synthetic>') return;
+  const id = msg.id || r.requestId || r.uuid;
+  if (id && entry.state.ids.includes(id)) return;
+  if (id) remember(entry.state.ids, id);
+  const cwh = u.cache_creation?.ephemeral_1h_input_tokens || 0;
+  const t = {
+    in: u.input_tokens || 0,
+    out: u.output_tokens || 0,
+    cr: u.cache_read_input_tokens || 0,
+    cw: Math.max(0, (u.cache_creation_input_tokens || 0) - cwh),
+    cwh,
+    rs: u.output_tokens_details?.thinking_tokens || 0,
+  };
+  addTokens(b, u.speed === 'fast' ? `${model}@fast` : model, t);
+  // Older Claude Code wrote subagent turns into the parent's own file.
+  if (r.isSidechain && meta.fn !== 'subagent') b.side = (b.side || 0) + t.in + t.out + t.cr + t.cw + t.cwh;
+}
+
+// ── Codex ─────────────────────────────────────────────────────────────────────
+
+const SKILL_PATH = /skills\/(?:\.system\/)?([A-Za-z0-9_.-]+)\/SKILL\.md/g;
+const TOOL_CALL = /\btools\.([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+
+function codexUsage(u) {
+  const input = u.input_tokens || 0;
+  const cached = Math.min(u.cached_input_tokens || 0, input);
+  return { in: input - cached, out: u.output_tokens || 0, cr: cached, cw: u.cache_write_input_tokens || 0, cwh: 0, rs: u.reasoning_output_tokens || 0 };
+}
+
+export function codexLine(entry, line) {
+  const hit = line.includes('"token_usage_record"') || line.includes('"token_count"')
+    || line.includes('"turn_context"') || line.includes('"session_meta"')
+    || line.includes('"custom_tool_call"') || line.includes('"function_call"');
+  if (!hit) return;
+  let r;
+  try { r = JSON.parse(line); } catch { return; }
+  const p = r.payload || {};
+  const ts = typeof r.timestamp === 'string' ? r.timestamp : null;
+  const meta = entry.meta;
+  const st = entry.state;
+
+  if (r.type === 'session_meta') {
+    meta.session = p.id || p.session_id || meta.session;
+    if (p.cwd) meta.cwd = p.cwd;
+    meta.entry = p.originator || null;
+    const sub = p.source && typeof p.source === 'object' ? p.source.subagent?.thread_spawn : null;
+    if (sub) {
+      meta.fn = 'subagent';
+      meta.parent = sub.parent_thread_id || null;
+      meta.agentType = sub.agent_role || p.agent_role || null;
+      const b = ts && dayBucket(entry, ts);
+      if (b) bump(b.agents, meta.agentType || 'subagent');
+    } else if (p.thread_source === 'automation') meta.fn = 'automation';
+    else if (p.originator === 'codex_exec' || p.source === 'exec') meta.fn = 'headless';
+    else meta.fn = 'chat';
+    return;
+  }
+  if (r.type === 'turn_context') { if (p.model) st.model = p.model; return; }
+  if (!ts) return;
+
+  if (r.type === 'response_item' && (p.type === 'custom_tool_call' || p.type === 'function_call')) {
+    const b = dayBucket(entry, ts);
+    if (!b) return;
+    touchSpan(meta, ts);
+    const input = String(p.input ?? p.arguments ?? '');
+    // `exec` is Codex's code-mode wrapper: the tools are called inside it.
+    const inner = p.name === 'exec' ? [...input.matchAll(TOOL_CALL)].map((m) => m[1]) : [];
+    if (inner.length) for (const n of inner) countTool(b, n); else countTool(b, p.name);
+    for (const m of input.matchAll(SKILL_PATH)) bump(b.skills, m[1]);
+    return;
+  }
+
+  if (r.type === 'token_usage_record' && p.usage) {
+    const id = p.response_id;
+    if (id && st.ids.includes(id)) return;
+    if (id) remember(st.ids, id);
+    st.records = true;
+    const b = dayBucket(entry, ts);
+    if (!b) return;
+    touchSpan(meta, ts);
+    addTokens(b, st.model || 'unknown', codexUsage(p.usage));
+    return;
+  }
+
+  if (r.type === 'event_msg' && p.type === 'token_count') {
+    const rl = p.rate_limits;
+    if (rl && (rl.primary || rl.secondary)) {
+      meta.limits = {
+        at: ts, plan: rl.plan_type || meta.limits?.plan || null, reached: rl.rate_limit_reached_type || null,
+        primary: rl.primary ? { used: rl.primary.used_percent, minutes: rl.primary.window_minutes, resets: rl.primary.resets_at } : null,
+        secondary: rl.secondary ? { used: rl.secondary.used_percent, minutes: rl.secondary.window_minutes, resets: rl.secondary.resets_at } : null,
+        credits: rl.credits ? { has: !!rl.credits.has_credits, unlimited: !!rl.credits.unlimited, balance: rl.credits.balance ?? null } : null,
+      };
+    }
+    // Older sessions have no token_usage_record. Their usage is the growth of
+    // the cumulative total — token_count is emitted more than once per response,
+    // so `last_token_usage` would count a response twice.
+    const tot = p.info?.total_token_usage;
+    if (!st.records && tot && typeof tot.total_tokens === 'number') {
+      const prev = st.prev;
+      st.prev = tot;
+      if (prev && tot.total_tokens <= prev.total_tokens) return;
+      const delta = {};
+      for (const k of ['input_tokens', 'cached_input_tokens', 'cache_write_input_tokens', 'output_tokens', 'reasoning_output_tokens']) {
+        delta[k] = Math.max(0, (tot[k] || 0) - ((prev && prev[k]) || 0));
+      }
+      // A thread forked from another opens with a total and no breakdown — the
+      // context it inherited, not a response. It is the base, never usage.
+      if (!delta.input_tokens && !delta.output_tokens && !delta.cached_input_tokens) return;
+      const b = dayBucket(entry, ts);
+      if (!b) return;
+      touchSpan(meta, ts);
+      addTokens(b, st.model || 'unknown', codexUsage(delta));
+    }
+  }
+}
+
+// ── incremental reading ───────────────────────────────────────────────────────
+
+/** Feed every COMPLETE line in [start, size) to onLine; return where the next read starts. */
+async function readFrom(file, start, onLine) {
+  const fh = await fs.promises.open(file, 'r');
+  try {
+    const buf = Buffer.allocUnsafe(CHUNK);
+    let pos = start;
+    let carry = null;
+    let committed = start;
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, 0, CHUNK, pos);
+      if (bytesRead === 0) break;
+      pos += bytesRead;
+      let data = buf.subarray(0, bytesRead);
+      if (carry) { data = Buffer.concat([carry, data]); carry = null; }
+      let from = 0;
+      for (;;) {
+        const nl = data.indexOf(10, from);
+        if (nl === -1) break;
+        if (nl > from) onLine(data.toString('utf8', from, nl));
+        committed += nl + 1 - from;
+        from = nl + 1;
+      }
+      // A line still being written stays unread until it has its newline.
+      if (from < data.length) carry = Buffer.from(data.subarray(from));
+    }
+    return committed;
+  } finally {
+    await fh.close();
+  }
+}
+
+function freshEntry(host, file) {
+  const meta = host === 'claude' ? claudeFileMeta(file) : { session: null, parent: null, fn: null, agentType: null };
+  return { host, size: 0, mtimeMs: 0, offset: 0, meta: { ...meta, title: null, prompt: null, cwd: null, entry: null, first: null, last: null }, state: { ids: [], model: null, prev: null, records: false }, days: {} };
+}
+
+function loadIndex(cacheFile) {
+  try {
+    const x = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+    if (x && x.version === INDEX_VERSION && x.files && typeof x.files === 'object') return x;
+  } catch { /* missing or corrupt: rebuilt, never trusted */ }
+  return { version: INDEX_VERSION, files: {} };
+}
+
+function saveIndex(cacheFile, index) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const tmp = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(index));
+    fs.renameSync(tmp, cacheFile);
+  } catch { /* unsaved: the next pass re-reads, nothing else is lost */ }
+}
+
+/**
+ * Bring the index up to date with the logs on disk.
+ * @returns {Promise<{index:object, seen:{claude:boolean,codex:boolean}, read:number, files:number}>}
+ */
+export async function scanUsage({ claudeDir = DEFAULT_CLAUDE_DIR(), codexDirs = DEFAULT_CODEX_DIRS(), cacheFile = DEFAULT_CACHE_FILE(), now = Date.now() } = {}) {
+  const index = loadIndex(cacheFile);
+  const { files, seen } = listLogFiles({ claudeDir, codexDirs });
+  const live = new Set();
+  let read = 0;
+  for (const { host, file } of files) {
+    const key = short(file);
+    live.add(key);
+    let st;
+    try { st = fs.statSync(file); } catch { continue; }
+    let e = index.files[key];
+    if (e && e.size === st.size && e.mtimeMs === st.mtimeMs) continue;
+    // Smaller than what was read means rewritten, not appended: start over.
+    if (!e || e.host !== host || st.size < e.offset) e = freshEntry(host, file);
+    try {
+      const onLine = host === 'claude' ? (l) => claudeLine(e, l) : (l) => codexLine(e, l);
+      e.offset = await readFrom(file, e.offset, onLine);
+      e.size = st.size;
+      e.mtimeMs = st.mtimeMs;
+      index.files[key] = e;
+      read++;
+    } catch { /* unreadable now: tried again next pass, never counted as empty */ }
+  }
+  // A file that is gone keeps its days until they are too old to matter.
+  const cutoff = dayOf(now - KEEP_GONE_DAYS * 86400000);
+  for (const [key, e] of Object.entries(index.files)) {
+    if (live.has(key)) continue;
+    e.gone = true;
+    if (!e.meta?.last || dayOf(e.meta.last) < cutoff) delete index.files[key];
+  }
+  saveIndex(cacheFile, index);
+  return { index, seen, read, files: files.length };
+}
+
+// ── the summary the board draws ───────────────────────────────────────────────
+
+/** Codex thread names, last write wins. */
+export function readCodexTitles(file = DEFAULT_CODEX_TITLES()) {
+  const out = {};
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { const r = JSON.parse(line); if (r.id && r.thread_name) out[r.id] = String(r.thread_name).slice(0, 160); } catch { /* partial */ }
+  }
+  return out;
+}
+
+const FAST = '@fast';
+
+/** Dollars for one model bucket, or null when nobody priced the model. */
+function priceBucket(model, m, prices) {
+  const fast = model.endsWith(FAST);
+  const base = fast ? model.slice(0, -FAST.length) : model;
+  const p = priceUsage({
+    model: base,
+    prices,
+    usage: {
+      input_tokens: m.in, output_tokens: m.out, cache_read_input_tokens: m.cr,
+      cache_creation_input_tokens: m.cw + m.cwh,
+      cache_creation: { ephemeral_1h_input_tokens: m.cwh, ephemeral_5m_input_tokens: m.cw },
+    },
+  });
+  if (!p.priced) return { usd: null, assumed: false };
+  // Fast mode bills at twice the standard rate (Opus 5: $10/$50 against $5/$25).
+  return { usd: fast ? p.usd * 2 : p.usd, assumed: p.assumed };
+}
+
+const tokensOf = (t) => t.in + t.out + t.cr + t.cw + t.cwh;
+
+function rank(map, limit, label = (n) => n) {
+  return Object.entries(map).sort((a, b) => b[1] - a[1]).slice(0, limit).map(([name, n]) => ({ name: label(name), n }));
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** claude.ai connectors reach the transcript as a bare UUID; say what it is rather than print it. */
+export function mcpLabel(server) {
+  return UUID.test(server) ? `claude.ai connector ${server.slice(0, 8)}` : server;
+}
+
+/**
+ * The window the board shows.
+ * @param {object} index  from scanUsage
+ * @param {{days?:number, now?:number, codexTitles?:Record<string,string>, prices?:object, top?:number}} opts
+ */
+export function summarizeUsage(index, { days = 30, now = Date.now(), codexTitles = {}, prices = effectivePrices(), top = 10 } = {}) {
+  const span = Math.max(1, Math.min(365, Math.floor(days) || 30));
+  const dates = [];
+  for (let i = span - 1; i >= 0; i--) dates.push(dayOf(now - i * 86400000));
+  const inWindow = new Set(dates);
+  const from = dates[0];
+
+  const blank = () => ({ in: 0, out: 0, cr: 0, cw: 0, cwh: 0, rs: 0, msgs: 0, usd: 0, unpricedMsgs: 0, sessions: 0, byFn: {}, lim: { plan: 0, server: 0 } });
+  const hosts = { claude: blank(), codex: blank() };
+  const daily = Object.fromEntries(dates.map((d) => [d, { claude: { tokens: 0, usd: 0, byFn: {} }, codex: { tokens: 0, usd: 0, byFn: {} } }]));
+  const models = {};
+  const lists = { claude: { tools: {}, skills: {}, agents: {}, mcp: {} }, codex: { tools: {}, skills: {}, agents: {}, mcp: {} } };
+  const sessions = {};
+  const unpriced = new Set();
+  let codexLimits = null;
+  let codexPlan = null;
+
+  for (const e of Object.values(index.files || {})) {
+    const host = e.host;
+    if (!hosts[host]) continue;
+    const lim = host === 'codex' ? e.meta?.limits : null;
+    if (lim && (!codexLimits || lim.at > codexLimits.at)) codexLimits = lim;
+    if (lim?.plan && (!codexPlan || lim.at > codexPlan.at)) codexPlan = { at: lim.at, plan: lim.plan };
+    const fn = e.meta?.fn || 'chat';
+    let touched = false;
+    for (const [day, b] of Object.entries(e.days || {})) {
+      if (!inWindow.has(day)) continue;
+      touched = true;
+      const h = hosts[host];
+      h.lim.plan += b.lim?.plan || 0;
+      h.lim.server += b.lim?.server || 0;
+      for (const kind of ['tools', 'skills', 'agents', 'mcp']) for (const [k, n] of Object.entries(b[kind] || {})) bump(lists[host][kind], k, n);
+      let dayUsd = 0;
+      let dayUnpriced = false;
+      for (const [model, m] of Object.entries(b.models || {})) {
+        const { usd } = priceBucket(model, m, prices);
+        if (usd == null) dayUnpriced = true;
+        const mk = `${host}|${model}`;
+        const row = models[mk] || (models[mk] = { host, model, in: 0, out: 0, cr: 0, cw: 0, cwh: 0, msgs: 0, usd: 0, priced: usd != null });
+        row.in += m.in; row.out += m.out; row.cr += m.cr; row.cw += m.cw; row.cwh += m.cwh; row.msgs += m.msgs;
+        if (usd != null) { row.usd += usd; dayUsd += usd; } else { row.priced = false; h.unpricedMsgs += m.msgs; unpriced.add(model); }
+      }
+      const tk = tokensOf(b);
+      const side = Math.min(b.side || 0, tk);
+      h.in += b.in; h.out += b.out; h.cr += b.cr; h.cw += b.cw; h.cwh += b.cwh; h.rs += b.rs; h.msgs += b.msgs; h.usd += dayUsd;
+      const dd = daily[day][host];
+      dd.tokens += tk; dd.usd += dayUsd;
+      for (const [f, n] of [[fn, tk - side], ['subagent', side]]) {
+        if (!n) continue;
+        h.byFn[f] = (h.byFn[f] || 0) + n;
+        dd.byFn[f] = (dd.byFn[f] || 0) + n;
+      }
+      // A subagent's spend belongs to the conversation that dispatched it.
+      const sid = `${host}|${e.meta?.parent || e.meta?.session || 'unknown'}`;
+      const s = sessions[sid] || (sessions[sid] = { host, id: e.meta?.parent || e.meta?.session || null, tokens: 0, usd: 0, priced: true, msgs: 0, subagentTokens: 0, last: null, title: null, project: null, fn: null });
+      s.tokens += tk; s.usd += dayUsd; s.msgs += b.msgs;
+      s.subagentTokens += fn === 'subagent' ? tk : side;
+      if (dayUnpriced) s.priced = false;
+    }
+    if (!touched) continue;
+    const sid = `${host}|${e.meta?.parent || e.meta?.session || 'unknown'}`;
+    const s = sessions[sid];
+    if (e.meta?.last && (!s.last || e.meta.last > s.last)) s.last = e.meta.last;
+    // The conversation's own file names it; a subagent's file only fills a gap.
+    const own = !e.meta?.parent;
+    if (own || !s.title) s.title = (host === 'codex' ? codexTitles[e.meta?.session] : null) || e.meta?.title || e.meta?.prompt || s.title;
+    if (own || !s.project) s.project = projectName(e.meta?.cwd) || s.project;
+    if (own || !s.fn) s.fn = fn;
+  }
+
+  const sess = Object.values(sessions);
+  for (const host of ['claude', 'codex']) hosts[host].sessions = sess.filter((s) => s.host === host).length;
+  const topFor = (host) => {
+    const all = sess.filter((s) => s.host === host);
+    const total = all.reduce((a, s) => a + s.tokens, 0) || 1;
+    return all.sort((a, b) => b.tokens - a.tokens).slice(0, top).map((s) => ({
+      title: s.title || '(untitled)', project: s.project, fn: s.fn, tokens: s.tokens,
+      usd: s.priced ? s.usd : null, share: s.tokens / total, subagentTokens: s.subagentTokens, last: s.last,
+    }));
+  };
+
+  const cache = (h) => {
+    const read = h.cr; const all = h.in + h.cr + h.cw + h.cwh;
+    return { hitRate: all ? read / all : null };
+  };
+
+  return {
+    state: 'counted',
+    window: { from, to: dates[dates.length - 1], days: span },
+    hosts: Object.fromEntries(Object.entries(hosts).map(([k, h]) => [k, {
+      tokens: tokensOf(h), input: h.in, output: h.out, cacheRead: h.cr, cacheWrite: h.cw + h.cwh, reasoning: h.rs,
+      responses: h.msgs, sessions: h.sessions, usd: h.unpricedMsgs === h.msgs && h.msgs > 0 ? null : h.usd,
+      unpricedResponses: h.unpricedMsgs, byFn: h.byFn, limitHits: h.lim, ...cache(h),
+    }])),
+    daily: dates.map((d) => ({ date: d, ...daily[d] })),
+    models: Object.values(models).sort((a, b) => tokensOf(b) - tokensOf(a)).map((m) => ({
+      host: m.host, model: m.model, responses: m.msgs, tokens: tokensOf(m), output: m.out, usd: m.priced ? m.usd : null,
+    })),
+    top: { claude: topFor('claude'), codex: topFor('codex') },
+    lists: Object.fromEntries(Object.entries(lists).map(([host, l]) => [host, {
+      tools: rank(l.tools, 15), skills: rank(l.skills, 15), agents: rank(l.agents, 15), mcp: rank(l.mcp, 15, mcpLabel),
+    }])),
+    limits: { codex: codexLimits ? { ...codexLimits, plan: codexLimits.plan || codexPlan?.plan || null } : null },
+    unpricedModels: [...unpriced].sort(),
+  };
+}
+
+/**
+ * A request-safe view: `get()` answers at once and refreshes in the background.
+ * The first pass over a real history reads gigabytes; a board request cannot
+ * wait for it, and a second request must not start a second pass.
+ */
+export function usageIndexSnapshot({ scan = () => scanUsage(), ttlMs = 60 * 1000, now = () => Date.now() } = {}) {
+  let last = null;
+  let at = 0;
+  let running = null;
+  const start = () => {
+    if (running) return;
+    let pass;
+    try { pass = Promise.resolve(scan()); } catch (e) { pass = Promise.reject(e); }
+    running = pass
+      .then((r) => { last = { state: 'ready', ...r }; }, (e) => { last = last?.state === 'ready' ? last : { state: 'unavailable', why: `session logs could not be read: ${e?.message || e}` }; })
+      .finally(() => { at = now(); running = null; });
+  };
+  return {
+    get() {
+      if (!last) { start(); return { state: 'computing', why: 'reading the Claude Code and Codex session logs — the first pass over a large history takes a minute or two' }; }
+      if (now() - at > ttlMs) start();
+      return last;
+    },
+    /** For tests and the CLI: wait for the pass in flight. */
+    async settle() { start(); while (running) await running; return last; },
+  };
+}
+
+// CLI: node scripts/lib/session-usage.mjs [--days N] [--json]
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain) {
+  const i = process.argv.indexOf('--days');
+  const days = i > -1 ? Number(process.argv[i + 1]) : 30;
+  const t0 = Date.now();
+  const r = await scanUsage();
+  const s = summarizeUsage(r.index, { days, codexTitles: readCodexTitles() });
+  if (process.argv.includes('--json')) { console.log(JSON.stringify(s, null, 2)); process.exit(0); }
+  const fmt = (n) => (n >= 1e9 ? `${(n / 1e9).toFixed(2)}B` : n >= 1e6 ? `${(n / 1e6).toFixed(1)}M` : n >= 1e3 ? `${(n / 1e3).toFixed(1)}k` : String(n));
+  console.log(`session-usage: ${r.files} log files, ${r.read} read in ${((Date.now() - t0) / 1000).toFixed(1)}s · window ${s.window.from} → ${s.window.to}`);
+  for (const [h, v] of Object.entries(s.hosts)) {
+    console.log(`  ${h.padEnd(7)} ${fmt(v.tokens).padStart(8)} tokens · ${v.responses} responses · ${v.sessions} sessions · cache ${v.hitRate == null ? '—' : `${Math.round(v.hitRate * 100)}%`} · ${v.usd == null ? 'unpriced' : `$${v.usd.toFixed(2)} at list price`}`);
+  }
+  if (s.limits.codex?.primary) console.log(`  codex limit: ${s.limits.codex.primary.used}% of ${s.limits.codex.primary.minutes} min window (plan ${s.limits.codex.plan})`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.52.0",
+  "version": "3.53.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",