great-cto 2.76.0 → 2.77.1

package/board/packages/board/lib/fleet.mjs

@@ -0,0 +1,363 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { GREAT_CTO_DIR } from './config.mjs';
+import { readFileSafe } from './util.mjs';
+import { readVerdicts } from './verdicts.mjs';
+
+// ── Agent fleet view (DESIGN-agents-fleet-view §3) ─────────────────────────
+//
+// Single source of truth for the /agents tab. Composes:
+//   • canonical agent files at ~/.claude/agents/great_cto-*.md
+//   • verdict log at ~/.great_cto/verdicts/<agent>.log
+//   • retire sidecar at ~/.claude/agents/great_cto-<slug>.md.retired
+//
+// Domain taxonomy is slug-keyword based (founder Q#3 — picked: derived, not
+// frontmatter, to avoid pipeline-wide migration). Founder may flip to
+// frontmatter-driven later — encapsulated in this function only.
+
+const AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+
+function deriveDomain(slug) {
+  const s = slug.toLowerCase();
+  if (/architect|adr|design|prompt/.test(s)) return 'arch';
+  if (/security|sec-|threat|pci|gdpr|hipaa/.test(s)) return 'security';
+  if (/qa|test|eval|review/.test(s)) return 'qa';
+  if (/devops|deploy|infra|l3|support|oncall/.test(s)) return 'ops';
+  if (/reviewer$/.test(s)) return 'domain';
+  if (/pm|plan|product/.test(s)) return 'pm';
+  if (/learn|memory|continuous/.test(s)) return 'memory';
+  return 'other';
+}
+
+// Founder Q#5 — picked: baked-in regex set (start small, expand later).
+const FAILURE_PATTERNS = [
+  { key: 'rate-limit',          re: /rate[ -]?limit|HTTP 429|too many requests/i },
+  { key: 'precondition',        re: /BLOCKED:.*no\s+(ARCH|PLAN|PROJECT)/i },
+  { key: 'timeout',             re: /timeout|timed out|exceeded.*window/i },
+  { key: 'parse-fail',          re: /JSON\.parse|invalid_json|parse.*fail/i },
+  { key: 'spawn-fail',          re: /spawn(Sync)?\b.*ENOENT|command not found/i },
+];
+
+function clusterFailureModes(verdicts) {
+  const counts = new Map();
+  for (const v of verdicts) {
+    const text = v.raw || '';
+    for (const p of FAILURE_PATTERNS) {
+      if (p.re.test(text)) {
+        const entry = counts.get(p.key) || { key: p.key, count: 0, last_seen: null };
+        entry.count += 1;
+        if (!entry.last_seen || v.ts > entry.last_seen) entry.last_seen = v.ts;
+        counts.set(p.key, entry);
+        break;
+      }
+    }
+  }
+  return [...counts.values()].sort((a, b) => b.count - a.count);
+}
+
+function isRetired(slug) {
+  return fs.existsSync(path.join(AGENTS_DIR, `great_cto-${slug}.md.retired`));
+}
+
+// Verdict status mapping — agents emit a mix of vocabularies:
+//   APPROVED / OK / DONE / PASS → success
+//   BLOCKED / FAIL / FAILED / REJECTED → failure
+//   anything else → neutral
+function isSuccess(verdict) {
+  return /^(APPROVED|OK|DONE|PASS|PASSED)$/i.test(verdict || '');
+}
+function isFailure(verdict) {
+  return /^(BLOCKED|FAIL|FAILED|REJECTED)$/i.test(verdict || '');
+}
+
+function getAgentsFleet(projectCwd) {
+  const agents = [];
+  let files = [];
+  try {
+    files = fs.readdirSync(AGENTS_DIR)
+      .filter(f => f.startsWith('great_cto-') && f.endsWith('.md'))
+      .sort();
+  } catch { /* dir missing → empty fleet */ }
+
+  const verdicts = readVerdicts(projectCwd);
+  const now = Date.now();
+  const day30Ms = 30 * 86400_000;
+  const day7Ms = 7 * 86400_000;
+
+  // Group verdicts by agent for one pass.
+  const byAgent = new Map();
+  for (const v of verdicts) {
+    if (!v.agent) continue;
+    if (!byAgent.has(v.agent)) byAgent.set(v.agent, []);
+    byAgent.get(v.agent).push(v);
+  }
+
+  // Fleet metrics from getMetrics agents_cost (estimate-based).
+  // Currently project-scoped; for fleet view we want global, so recompute
+  // a quick aggregate. Time-based estimate using same rates as getMetrics.
+  const HUMAN_RATE_PER_HR = parseFloat(process.env.GREATCTO_HUMAN_RATE_PER_HR || '150');
+  const LLM_RATE_PER_HR   = parseFloat(process.env.GREATCTO_LLM_RATE_PER_HR || '0.30');
+  const DEFAULT_TASK_MIN  = 30;
+
+  for (const f of files) {
+    const slug = f.replace(/^great_cto-/, '').replace(/\.md$/, '');
+    const fp = path.join(AGENTS_DIR, f);
+    const raw = readFileSafe(fp) || '';
+    const descM = raw.match(/^description:\s*"?([^"\n]+)"?/m);
+    const modelM = raw.match(/^model:\s*(\S+)/m);
+    const colorM = raw.match(/^color:\s*(\S+)/m);
+
+    const vs = byAgent.get(slug) || [];
+    const vs30d = vs.filter(v => v.ts && (now - new Date(v.ts).getTime()) < day30Ms);
+    const vs7d  = vs.filter(v => v.ts && (now - new Date(v.ts).getTime()) < day7Ms);
+
+    const okCount30d   = vs30d.filter(v => isSuccess(v.verdict)).length;
+    const failCount30d = vs30d.filter(v => isFailure(v.verdict)).length;
+    const failCount7d  = vs7d.filter(v => isFailure(v.verdict)).length;
+    const decided = okCount30d + failCount30d;
+    const successRate = decided > 0 ? Math.round((okCount30d / decided) * 100) : null;
+
+    const lastRun = vs[0]?.ts || null;  // verdicts already sorted by readVerdicts caller? if not, scan:
+    let lastRunActual = null;
+    for (const v of vs) {
+      if (v.ts && (!lastRunActual || v.ts > lastRunActual)) lastRunActual = v.ts;
+    }
+
+    // Estimated cost — DEFAULT_TASK_MIN per verdict (no real timing data here).
+    const estLlmUsd   = (vs30d.length * DEFAULT_TASK_MIN / 60) * LLM_RATE_PER_HR;
+    const estHumanUsd = (vs30d.length * DEFAULT_TASK_MIN / 60) * HUMAN_RATE_PER_HR;
+    const savingsX = estLlmUsd > 0 ? Math.round(estHumanUsd / estLlmUsd) : null;
+    const realLlmUsd = vs30d.reduce((s, v) => s + (v.cost_usd || 0), 0);
+
+    // Health classification.
+    let health = 'ok';
+    if (vs.length === 0) health = 'unused';
+    else if (!lastRunActual || (now - new Date(lastRunActual).getTime()) > day30Ms) health = 'idle';
+    if (failCount7d >= 3) health = 'failing';
+
+    agents.push({
+      slug,
+      description: descM?.[1]?.trim() || '',
+      model: modelM?.[1]?.trim() || 'sonnet',
+      color: colorM?.[1]?.trim() || null,
+      domain: deriveDomain(slug),
+      runs_total: vs.length,
+      runs_30d: vs30d.length,
+      runs_7d: vs7d.length,
+      fail_30d: failCount30d,
+      fail_7d: failCount7d,
+      ok_30d: okCount30d,
+      success_rate: successRate,
+      last_run: lastRunActual,
+      llm_usd_30d_est: Math.round(estLlmUsd * 100) / 100,
+      human_usd_30d_est: Math.round(estHumanUsd),
+      llm_usd_30d_real: realLlmUsd > 0 ? Math.round(realLlmUsd * 100) / 100 : null,
+      savings_x: savingsX,
+      health,
+      retired: isRetired(slug),
+    });
+  }
+
+  // Summary tiles.
+  const total = agents.length;
+  const active30d = agents.filter(a => a.runs_30d > 0 && !a.retired).length;
+  const retireCandidates = agents.filter(a => a.runs_30d === 0 && !a.retired).length;
+  const failing = agents.filter(a => a.health === 'failing' && !a.retired).length;
+  const totalLlm30d = agents.reduce((s, a) => s + (a.llm_usd_30d_est || 0), 0);
+
+  return {
+    agents,
+    total,
+    summary: {
+      installed: total,
+      active_30d: active30d,
+      retire_candidates: retireCandidates,
+      failing_7d: failing,
+      llm_usd_30d: Math.round(totalLlm30d * 100) / 100,
+    },
+  };
+}
+
+function getAgentProfile(slug) {
+  const fp = path.join(AGENTS_DIR, `great_cto-${slug}.md`);
+  if (!fs.existsSync(fp)) return null;
+
+  const raw = readFileSafe(fp) || '';
+  const descM = raw.match(/^description:\s*"?([^"\n]+)"?/m);
+  const modelM = raw.match(/^model:\s*(\S+)/m);
+  const colorM = raw.match(/^color:\s*(\S+)/m);
+  const appliesM = raw.match(/^applies_to:\s*\[([^\]]+)\]/m);
+  const applies_to = appliesM
+    ? appliesM[1].split(',').map(s => s.trim().replace(/['"]/g, '')).filter(Boolean)
+    : [];
+  // tools: either an inline CSV (`tools: Read, Bash, Grep`) or a YAML list.
+  const toolsM = raw.match(/^tools:\s*(.+)$/m);
+  let tools = [];
+  if (toolsM && toolsM[1].trim() && !toolsM[1].trim().startsWith('#')) {
+    tools = toolsM[1].split(',').map(s => s.trim()).filter(Boolean)
+      .map(t => /^Bash\(/.test(t) ? 'Bash' : t);   // collapse Bash(...) allowlist to one chip
+    tools = [...new Set(tools)];
+  } else {
+    const listM = raw.match(/^tools:\s*\n((?:\s*-\s*.+\n?)+)/m);
+    if (listM) tools = listM[1].split('\n').map(l => (l.match(/^\s*-\s*(.+)$/) || [])[1]).filter(Boolean).map(s => s.trim());
+  }
+  // skills: a YAML list under `skills:`. Stop before the closing `---` frontmatter delimiter
+  // (otherwise `---` parses as a bogus `--` entry).
+  const skills = [];
+  const skillsM = raw.match(/^skills:\s*\n((?:[ \t]*-[ \t]*.+\n?)+)/m);
+  if (skillsM) for (const line of skillsM[1].split('\n')) { const v = (line.match(/^[ \t]*-[ \t]*(.+)$/) || [])[1]; const t = v && v.trim(); if (t && !/^-+$/.test(t)) skills.push(t); }
+
+  const verdicts = readVerdicts();
+  const all = verdicts.filter(v => v.agent === slug);
+  const now = Date.now();
+  const day30Ms = 30 * 86400_000;
+  const day7Ms = 7 * 86400_000;
+  const vs30d = all.filter(v => v.ts && (now - new Date(v.ts).getTime()) < day30Ms);
+
+  const okCount30d   = vs30d.filter(v => isSuccess(v.verdict)).length;
+  const failCount30d = vs30d.filter(v => isFailure(v.verdict)).length;
+  const failCount7d  = all.filter(v => v.ts
+    && (now - new Date(v.ts).getTime()) < day7Ms
+    && isFailure(v.verdict)).length;
+  const decided = okCount30d + failCount30d;
+
+  let lastRun = null;
+  for (const v of all) {
+    if (v.ts && (!lastRun || v.ts > lastRun)) lastRun = v.ts;
+  }
+
+  const HUMAN_RATE_PER_HR = parseFloat(process.env.GREATCTO_HUMAN_RATE_PER_HR || '150');
+  const LLM_RATE_PER_HR   = parseFloat(process.env.GREATCTO_LLM_RATE_PER_HR || '0.30');
+  const DEFAULT_TASK_MIN  = 30;
+  const estLlmUsd   = (vs30d.length * DEFAULT_TASK_MIN / 60) * LLM_RATE_PER_HR;
+  const estHumanUsd = (vs30d.length * DEFAULT_TASK_MIN / 60) * HUMAN_RATE_PER_HR;
+  const realLlmUsd = vs30d.reduce((s, v) => s + (v.cost_usd || 0), 0);
+
+  // Recent runs — last 20, newest first.
+  const recent = [...all]
+    .sort((a, b) => (b.ts || '').localeCompare(a.ts || ''))
+    .slice(0, 20)
+    .map(v => ({
+      ts: v.ts,
+      verdict: v.verdict,
+      cost_usd: v.cost_usd,
+      raw: (v.raw || '').slice(0, 200),
+    }));
+
+  // Failure modes — regex-cluster verdicts that look like failures.
+  const failures = all.filter(v => isFailure(v.verdict));
+  const failure_modes = clusterFailureModes(failures);
+
+  let health = 'ok';
+  if (all.length === 0) health = 'unused';
+  else if (!lastRun || (now - new Date(lastRun).getTime()) > day30Ms) health = 'idle';
+  if (failCount7d >= 3) health = 'failing';
+
+  return {
+    slug,
+    description: descM?.[1]?.trim() || '',
+    model: modelM?.[1]?.trim() || 'sonnet',
+    color: colorM?.[1]?.trim() || null,
+    applies_to,
+    tools,
+    skills,
+    domain: deriveDomain(slug),
+    health,
+    retired: isRetired(slug),
+    runs_total: all.length,
+    runs_30d: vs30d.length,
+    ok_30d: okCount30d,
+    fail_30d: failCount30d,
+    success_rate: decided > 0 ? Math.round((okCount30d / decided) * 100) : null,
+    last_run: lastRun,
+    llm_usd_30d_est: Math.round(estLlmUsd * 100) / 100,
+    human_usd_30d_est: Math.round(estHumanUsd),
+    llm_usd_30d_real: realLlmUsd > 0 ? Math.round(realLlmUsd * 100) / 100 : null,
+    savings_x: estLlmUsd > 0 ? Math.round(estHumanUsd / estLlmUsd) : null,
+    recent_runs: recent,
+    failure_modes,
+    file_path: fp,
+  };
+}
+
+function retireAgent(slug) {
+  const fp = path.join(AGENTS_DIR, `great_cto-${slug}.md`);
+  if (!fs.existsSync(fp)) return { ok: false, error: 'agent_not_found' };
+  const marker = `${fp}.retired`;
+  fs.writeFileSync(marker, new Date().toISOString() + '\n');
+  return { ok: true, slug, retired_at: new Date().toISOString() };
+}
+
+function restoreAgent(slug) {
+  const fp = path.join(AGENTS_DIR, `great_cto-${slug}.md`);
+  if (!fs.existsSync(fp)) return { ok: false, error: 'agent_not_found' };
+  const marker = `${fp}.retired`;
+  if (fs.existsSync(marker)) fs.unlinkSync(marker);
+  return { ok: true, slug, restored_at: new Date().toISOString() };
+}
+
+// ── decisions.md (global ADR log) ──────────────────────────────────────────
+// Append-only architectural decisions log. Triggered on gate approve/reject.
+// One line per decision; pure markdown so users can `cat` / `grep` / view in
+// their editor without tooling.
+function decisionsLogPath() {
+  return path.join(GREAT_CTO_DIR, 'decisions.md');
+}
+
+function appendDecisionLog({ ts, project, action, id, title, reason }) {
+  const file = decisionsLogPath();
+  try { fs.mkdirSync(GREAT_CTO_DIR, { recursive: true }); } catch {}
+  // Initialize header if file doesn't exist
+  if (!fs.existsSync(file)) {
+    const header =
+`# great_cto — decisions log
+
+Append-only architectural decisions across all projects. One line per
+gate approve/reject. Agents and humans can grep this for "have we decided
+this before?" lookups.
+
+Format: \`- [TIMESTAMP] [PROJECT] [APPROVED|REJECTED] gate-id — title — reason\`
+
+`;
+    fs.writeFileSync(file, header);
+  }
+  const verdict = action === 'approve' ? 'APPROVED' : 'REJECTED';
+  const safeTitle = (title || '').replace(/\n/g, ' ').slice(0, 120);
+  const safeReason = (reason || '').replace(/\n/g, ' ').slice(0, 200);
+  const line = `- [${ts}] [${project}] [${verdict}] ${id} — ${safeTitle}${safeReason ? ` — ${safeReason}` : ''}\n`;
+  fs.appendFileSync(file, line);
+}
+
+function readDecisionsLog(limit = 20) {
+  const file = decisionsLogPath();
+  if (!fs.existsSync(file)) return [];
+  try {
+    const text = fs.readFileSync(file, 'utf-8');
+    const lines = text.split('\n').filter(l => l.startsWith('- ['));
+    // Newest last → reverse and take last `limit`
+    return lines.slice(-limit).reverse().map(line => {
+      // Parse: - [TS] [PROJECT] [VERDICT] id — title — reason
+      const m = line.match(/^- \[([^\]]+)\] \[([^\]]+)\] \[([^\]]+)\] ([^\s]+)\s+—\s+(.+?)(?:\s+—\s+(.+))?$/);
+      if (!m) return null;
+      return { ts: m[1], project: m[2], verdict: m[3], id: m[4], title: m[5], reason: m[6] || '' };
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export {
+  deriveDomain,
+  clusterFailureModes,
+  isRetired,
+  isSuccess,
+  isFailure,
+  getAgentsFleet,
+  getAgentProfile,
+  retireAgent,
+  restoreAgent,
+  decisionsLogPath,
+  appendDecisionLog,
+  readDecisionsLog,
+};

package/board/packages/board/lib/metrics.mjs

@@ -0,0 +1,282 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { sseClients, bdCache } from './state.mjs';
+import { getTasks } from './beads.mjs';
+import { readVerdicts, readPlanCosts, readQAStats, readSecStats } from './verdicts.mjs';
+
+// ── Metrics ────────────────────────────────────────────────────────────────────
+function getMetrics(cwd = process.cwd(), days = 30) {
+  // `days` controls the window for cost/agents_cost and for "shipped in window".
+  // Tasks shipped within the window are returned in `tasks.done_in_window`.
+  // Full lifetime `tasks.done` is still returned for backwards compatibility.
+  const tasks = getTasks(cwd);
+  // BH-28: resolved gates (approve→closed, reject→blocked) get mapped to
+  // status='done' by mapStatus(). Those are governance decisions, not shipped
+  // features — counting them inflates velocity / tasks-shipped on the report.
+  const done = tasks.filter(t => t.status === 'done' && !t.is_gate);
+  const inProgress = tasks.filter(t => t.status === 'in_progress');
+  const backlog = tasks.filter(t => t.status === 'backlog');
+
+  // Velocity: features closed per week
+  const now = Date.now();
+  const week = 7 * 24 * 60 * 60 * 1000;
+  const doneThisWeek = done.filter(t => t.closed_at && (now - new Date(t.closed_at).getTime()) < week);
+  const doneThisMonth = done.filter(t => t.closed_at && (now - new Date(t.closed_at).getTime()) < 30 * 24 * 60 * 60 * 1000);
+
+  // Cycle time (median, last 30 days, cap individual cycles at 30 days).
+  // Previously: arithmetic mean over ALL tasks ever, no cap — stuck tasks
+  // (created months earlier, finally closed) pulled the average into the
+  // tens of thousands of minutes. Median + 30d cap matches how the cost
+  // tile bounds cycles ([server.mjs:816](server.mjs:816)).
+  const cycleCap = 30 * 86400_000;
+  const completionTimes = done
+    .filter(t => t.created_at && t.closed_at && (now - new Date(t.closed_at).getTime()) < cycleCap)
+    .map(t => new Date(t.closed_at).getTime() - new Date(t.created_at).getTime())
+    .filter(ms => ms > 0 && ms < cycleCap)
+    .sort((a, b) => a - b);
+  const medianCompletionMs = completionTimes.length
+    ? completionTimes[Math.floor(completionTimes.length / 2)]
+    : 0;
+
+  // Verdicts (global verdicts log lives in ~/.great_cto/verdicts/)
+  const verdicts = readVerdicts(cwd);
+
+  // Cost from plans (per-project) — filter to the same window as task/verdict
+  // loops below so /api/metrics and /api/cost agree on the headline AI spend.
+  const costData = readPlanCosts(cwd, days * 86400_000);
+
+  // QA/Security (per-project)
+  const qaStats = readQAStats(cwd);
+  const secStats = readSecStats(cwd);
+
+  // Agent utilization from verdicts.
+  // Filter against canonical list of installed agents (~/.claude/agents/great_cto-*.md)
+  // so a typo in a verdict line does not produce a phantom agent in the dashboard.
+  //
+  // Previously: non-canonical agents bucketed into `unknown` — which became
+  // the TOP agent in production dashboards because legacy verdict log files
+  // (backend.log, frontend.log, docs.log, ops.log, qa.log, security.log,
+  // test-agent.log) from older great_cto versions were all aggregated there.
+  // That hid real agent activity under a misleading label.
+  //
+  // Now: non-canonical agents are tracked separately (legacy_agent_runs)
+  // and surfaced as a single summary count, NOT individually polluting the
+  // agent-runs map. Users see honest specialist metrics + a cleanup hint.
+  const canonicalAgents = getCanonicalAgents();
+  const agentRuns = {};
+  const legacyAgentRuns = {};
+  for (const v of verdicts) {
+    if (!v.agent) continue;
+    if (canonicalAgents.has(v.agent)) {
+      agentRuns[v.agent] = (agentRuns[v.agent] || 0) + 1;
+    } else {
+      legacyAgentRuns[v.agent] = (legacyAgentRuns[v.agent] || 0) + 1;
+    }
+  }
+  const legacyAgentCount = Object.values(legacyAgentRuns).reduce((a, b) => a + b, 0);
+
+  // Agent cost + time breakdown.
+  //
+  // Cost model derivation (LLM_RATE_PER_HR):
+  //   Sonnet 4.6:  input $3/1M, output $15/1M.
+  //     Typical agent task: ~30K in + 5K out → ~$0.165 per task.
+  //     At 30 min/task → ~$0.33/hour.
+  //   Haiku 4.5:   input $1/1M, output $5/1M.
+  //     Same task shape → ~$0.055 → ~$0.11/hour.
+  //   Mixed pipeline (architect Sonnet, qa Haiku, ...): ~$0.30/hour avg.
+  //
+  // Previous default of $0.02/hour produced an unbelievable 7500× ratio in
+  // the UI. v2.5.9: realistic default $0.30/hour gives ~500× — still a
+  // huge advantage, but defensible.
+  //
+  // Override via env var:
+  //   GREATCTO_LLM_RATE_PER_HR=0.50   (e.g. all-Sonnet pipeline)
+  //   GREATCTO_HUMAN_RATE_PER_HR=200  (e.g. SF senior engineer fully-loaded)
+  //
+  // When verdict logs contain real `cost=$X` tags, those override the
+  // time-based estimate per agent (see "real cost overlay" loop below).
+  const HUMAN_RATE_PER_HR = parseFloat(process.env.GREATCTO_HUMAN_RATE_PER_HR || '150');
+  const LLM_RATE_PER_HR   = parseFloat(process.env.GREATCTO_LLM_RATE_PER_HR || '0.30');
+  const DEFAULT_TASK_MIN  = 30;  // fallback when no timing data
+  // Window: count only tasks closed in the last `days` (or still in progress).
+  // Previously: lifetime — produced LLM-spend tile ($1749) wildly out of step
+  // with the "Last 30 days" panel ($6.42) shown directly below it. Now both
+  // sit on the same N-day window so the dashboard numbers reconcile.
+  const costWindowMs = days * 86400_000;
+  // AI active time per task: use estimated_minutes if set, else DEFAULT_TASK_MIN (30m).
+  // We deliberately DO NOT use wall-clock (closed_at - created_at) because that
+  // includes idle time — tasks that sit in backlog for days before being closed
+  // in a single commit would inflate "AI time" to weeks/months. This is the only
+  // honest model without per-agent-run timing data from verdicts.
+  const agentCostMap = {};
+  for (const t of tasks) {
+    if (!t.agent) continue;
+    // Only count completed tasks — in-progress tasks have no closed_at and
+    // should not inflate the LLM cost estimate (they match the old
+    //   `if (t.closed_at && outside_window) continue`  guard which
+    // inadvertently passed through !closed_at tasks). Mirrors getCostHistory.
+    if (!t.closed_at) continue;
+    if ((now - new Date(t.closed_at).getTime()) > costWindowMs) continue;
+    const mins = t.estimated_minutes || DEFAULT_TASK_MIN;
+    const llmCost   = mins / 60 * LLM_RATE_PER_HR;
+    const humanCost = mins / 60 * HUMAN_RATE_PER_HR;
+    if (!agentCostMap[t.agent]) agentCostMap[t.agent] = { agent: t.agent, llm_usd: 0, human_usd: 0, time_min: 0, tasks_total: 0, tasks_done: 0, real_llm_usd: 0 };
+    agentCostMap[t.agent].llm_usd   += llmCost;
+    agentCostMap[t.agent].human_usd += humanCost;
+    agentCostMap[t.agent].time_min  += mins;
+    agentCostMap[t.agent].tasks_total += 1;
+    if (t.status === 'done') agentCostMap[t.agent].tasks_done += 1;
+  }
+  // Real cost overlay — sum verdict cost=$X tags per agent. We expose this
+  // as a separate field (`real_llm_usd`) for transparency, but DON'T
+  // overwrite the time-based estimate. Reason: verdict data is often
+  // synthetic test fixtures or partial (only some agents log cost), which
+  // would distort the savings ratio with implausibly low numbers.
+  //
+  // Heuristic for trusted production verdicts (future): require >= 50%
+  // of agent runs to have cost_usd, AND sum/time hourly rate >= $0.05/hr.
+  // Until that's implemented, time-based estimate is the canonical number.
+  // Window verdicts by timestamp — same window as agents_cost / tasks.
+  // Without this, "AI spend" stayed at lifetime $93 even when period=7D
+  // showed only 12 tasks worth ~$0.30 — making savings ratios nonsensical.
+  for (const v of verdicts) {
+    if (v.cost_usd == null) continue;
+    if (!agentCostMap[v.agent]) continue;
+    if (v.ts && (now - new Date(v.ts).getTime()) > costWindowMs) continue;
+    agentCostMap[v.agent].real_llm_usd += v.cost_usd;
+  }
+  for (const a of Object.values(agentCostMap)) {
+    a.cost_source = 'estimate';   // time-based is canonical
+    if (a.real_llm_usd > 0) {
+      a.real_llm_usd = Math.round(a.real_llm_usd * 10000) / 10000;
+    } else {
+      delete a.real_llm_usd;
+    }
+  }
+  const agentsCost = Object.values(agentCostMap)
+    .map(a => ({
+      ...a,
+      llm_usd:   Math.round(a.llm_usd   * 100) / 100,
+      human_usd: Math.round(a.human_usd * 100) / 100,
+      time_min:  Math.round(a.time_min),
+    }))
+    .sort((a, b) => b.time_min - a.time_min);
+
+  // Cost source priority (v2.5.9 — flipped to put time-based estimate
+  // before verdict-totals; verdict cost data is often synthetic test
+  // fixtures or partial coverage, which produced unbelievable 25,000×
+  // ratios in earlier versions):
+  //
+  //   1) PLAN-*.md files (real planned cost figures) — costData
+  //   2) Task-based estimation (canonical — uses realistic $0.30/$150 rates)
+  //   3) Verdict totals expose as `real_llm_usd` for transparency, NOT
+  //      used as the headline number unless plans / tasks are absent
+  const taskLlmTotal   = agentsCost.reduce((s, a) => s + a.llm_usd, 0);
+  const taskHumanTotal = agentsCost.reduce((s, a) => s + a.human_usd, 0);
+  // Filter verdicts to the same window for consistent total
+  const verdictLlmTotal = verdicts.reduce((s, v) => {
+    if (v.cost_usd == null) return s;
+    if (v.ts && (now - new Date(v.ts).getTime()) > costWindowMs) return s;
+    return s + v.cost_usd;
+  }, 0);
+
+  let cost;
+  if (costData.llm_usd > 0 || costData.human_usd > 0) {
+    cost = { ...costData, real_llm_usd: verdictLlmTotal > 0 ? Math.round(verdictLlmTotal * 10000) / 10000 : null };
+  } else if (taskLlmTotal > 0) {
+    // savings_x intentionally NULL for source='tasks': it would always equal
+    // HUMAN_RATE_PER_HR / LLM_RATE_PER_HR (e.g. 500) because both legs share
+    // the same task-minute base. That's the rate ratio, not measured savings —
+    // putting it on a dashboard tile misleads. Only plans/verdicts have an
+    // independent human number worth comparing.
+    cost = {
+      llm_usd:   Math.round(taskLlmTotal   * 100) / 100,
+      human_usd: Math.round(taskHumanTotal),
+      savings_x: null,
+      rate_ratio: Math.round(HUMAN_RATE_PER_HR / LLM_RATE_PER_HR),
+      window_days: 30,
+      count:     0,
+      source:    'tasks',
+      real_llm_usd: verdictLlmTotal > 0 ? Math.round(verdictLlmTotal * 10000) / 10000 : null,
+    };
+  } else if (verdictLlmTotal > 0) {
+    // Last-resort: no tasks, only verdict data. Pair with a token human
+    // baseline (verdict count × DEFAULT_TASK_MIN × $150/hr) so the ratio
+    // stays meaningful.
+    const verdictHuman = verdicts.length * (30 / 60) * HUMAN_RATE_PER_HR;
+    cost = {
+      llm_usd:   Math.round(verdictLlmTotal * 100) / 100,
+      human_usd: Math.round(verdictHuman),
+      savings_x: Math.round(verdictHuman / verdictLlmTotal),
+      count:     verdicts.filter(v => v.cost_usd != null).length,
+      source:    'verdicts',
+      real_llm_usd: Math.round(verdictLlmTotal * 10000) / 10000,
+    };
+  } else {
+    cost = { llm_usd: 0, human_usd: 0, savings_x: 0, count: 0, source: 'none', real_llm_usd: null };
+  }
+
+  // Count tasks completed in selected window (for period-scoped reports)
+  const doneInWindow = done.filter(t => t.closed_at && (now - new Date(t.closed_at).getTime()) <= costWindowMs);
+
+  return {
+    window_days: days,
+    tasks: {
+      total: tasks.length,
+      done: done.length,
+      done_in_window: doneInWindow.length,
+      in_progress: inProgress.length,
+      backlog: backlog.length,
+    },
+    // BH-22 fix: these are ROLLING windows (last 7 days, last 30 days from
+    // 'now') — not calendar week/month. Old keys this_week/this_month are
+    // kept for backward compat but the canonical names are last_7d/last_30d.
+    velocity: {
+      last_7d: doneThisWeek.length,
+      last_30d: doneThisMonth.length,
+      this_week: doneThisWeek.length,    // alias, deprecated — remove in v3.0
+      this_month: doneThisMonth.length,  // alias, deprecated — remove in v3.0
+    },
+    avg_completion_min: Math.round(medianCompletionMs / 60000),
+    cycle_time_stat: 'median_30d',
+    cost,
+    qa: qaStats,
+    security: secStats,
+    agents: agentRuns,
+    agents_cost: agentsCost,
+    legacy_agent_runs: legacyAgentRuns,
+    legacy_agent_count: legacyAgentCount,
+    verdicts: verdicts.slice(-20),
+    recent_done: done.slice(-10).reverse(),
+    // Observability counters (BH-13, 2026-05-15): surface internal queues
+    // so users + monitoring can spot leaks / runaway state.
+    server: {
+      sse_clients: sseClients.size,
+      bd_cache_entries: bdCache.size,
+    },
+  };
+}
+
+// Canonical list of installed agents from ~/.claude/agents/great_cto-*.md.
+// Cached with a 30s TTL to avoid stat'ing on every metrics request.
+let _canonicalAgentsCache = { agents: null, ts: 0 };
+function getCanonicalAgents() {
+  const now = Date.now();
+  if (_canonicalAgentsCache.agents && now - _canonicalAgentsCache.ts < 30_000) {
+    return _canonicalAgentsCache.agents;
+  }
+  const agentsDir = path.join(os.homedir(), '.claude', 'agents');
+  const set = new Set();
+  try {
+    for (const f of fs.readdirSync(agentsDir)) {
+      if (f.startsWith('great_cto-') && f.endsWith('.md')) {
+        set.add(f.replace(/^great_cto-/, '').replace(/\.md$/, ''));
+      }
+    }
+  } catch { /* dir missing — empty set is fine */ }
+  _canonicalAgentsCache = { agents: set, ts: now };
+  return set;
+}
+
+export { getMetrics, getCanonicalAgents };