great-cto 3.0.0 → 3.2.0

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

@@ -2,7 +2,7 @@
   "name": "great_cto",
   "id": "great_cto",
   "description": "Engineering process for solo founders and teams up to 50 engineers. Agents do architecture, code review, QA, and security. You make two decisions per feature.",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/board/packages/board/lib/beads.mjs

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { spawnSync } from 'child_process';
+import { spawnSync, spawn } from 'child_process';
 import { readSafe } from './util.mjs';
 import { bdCache } from './state.mjs';
 import { log } from './log.mjs';
@@ -38,11 +38,35 @@ import { log } from './log.mjs';
 // because each request arrived just after the entry expired.
 const BD_CACHE_TTL_MS = Number(process.env.GREAT_CTO_BD_CACHE_TTL_MS || 300000);
 
+/**
+ * Drop a directory's entry so the next read is guaranteed fresh.
+ *
+ * For a WRITE the board just performed. The operator clicked approve and is
+ * waiting for the result; paying for the read is correct there, and serving the
+ * pre-approval state would be a lie about what they just did.
+ */
 function bdCacheInvalidate(cwd) {
   clearSelfTouch(cwd);
   bdCache.delete(cwd);
 }
 
+/**
+ * Mark a directory's entry stale WITHOUT dropping it.
+ *
+ * For a change that arrived from outside — a file event under a project someone
+ * is watching. Deleting made the next reader, who asked for something unrelated,
+ * pay 623 ms warm and 6.8 s cold for a write they did not make. An entry marked
+ * stale is still served, and the refresh happens off the event loop.
+ *
+ * The difference is intent, not mechanism: a write we performed must be visible
+ * to whoever asked for it; a change we merely noticed must not stop the board.
+ */
+function bdCacheStale(cwd) {
+  clearSelfTouch(cwd);
+  const cached = bdCache.get(cwd);
+  if (cached) bdCache.set(cwd, { ...cached, ts: 0 });
+}
+
 // ── bd binary resolution (BH-32) ────────────────────────────────────────────
 // A board launched from a GUI / launchd / a login shell that didn't source the
 // usual profile often has a minimal PATH (`/usr/bin:/bin`) that omits where
@@ -251,6 +275,60 @@ function clearSelfTouch(cwd) { lastBdRunAt.delete(cwd); }
  */
 const EMPTY_TTL_MS = Number(process.env.GREAT_CTO_BD_EMPTY_TTL_MS || 5000);
 
+/**
+ * Directories with a background refresh already in flight.
+ *
+ * Without this, ten requests arriving while one refresh runs start ten more.
+ */
+const refreshing = new Set();
+
+/**
+ * Refresh a directory's entry WITHOUT holding the event loop.
+ *
+ * `spawnSync` is what made this board unanswerable: `bd list` costs seconds and
+ * blocks everything for the whole of it — /api/version, one readdirSync,
+ * measured at 1-10 s because it was queued behind a task read. Warming at boot
+ * moved the first stall out of sight; this removes the rest.
+ *
+ * Nothing awaits it. It exists to make the NEXT read fast, and a caller that
+ * needed the new data would have had to block for it anyway.
+ */
+function bdRefreshAsync(cwd) {
+  if (refreshing.has(cwd)) return;
+  refreshing.add(cwd);
+  lastBdRunAt.set(cwd, Date.now());
+  let out = '';
+  try {
+    const child = spawn(BD_BIN, ['list', '--json', '--all', '--include-gates'], { cwd, env: bdEnv() });
+    child.stdout?.on('data', (d) => { out += d; });
+    child.on('error', (e) => {
+      refreshing.delete(cwd);
+      bdFailures.set(cwd, `bd could not be run: ${e?.message || e}`.slice(0, 300));
+    });
+    child.on('close', (code) => {
+      refreshing.delete(cwd);
+      lastBdRunAt.set(cwd, Date.now());
+      if (code !== 0) { bdFailures.set(cwd, `bd exited ${code}`); return; }
+      try {
+        const parsed = JSON.parse(out || '[]');
+        // Same guard as the sync path: bd 0.6x can answer 0 with a JSON object,
+        // and a non-array rendered as no tasks is the silent zero again.
+        if (!Array.isArray(parsed)) {
+          bdFailures.set(cwd, String(parsed?.error || 'bd returned something that is not a task list').slice(0, 300));
+          return;
+        }
+        bdFailures.delete(cwd);
+        bdCache.set(cwd, { ts: Date.now(), data: parsed });
+      } catch (e) {
+        bdFailures.set(cwd, `bd output could not be parsed: ${e?.message || e}`.slice(0, 300));
+      }
+    });
+  } catch (e) {
+    refreshing.delete(cwd);
+    bdFailures.set(cwd, `bd could not be spawned: ${e?.message || e}`.slice(0, 300));
+  }
+}
+
 function bdList(cwd = process.cwd(), runner = bd, opts = {}) {
   const maxAge = Number.isFinite(opts.maxAgeMs) ? opts.maxAgeMs : BD_CACHE_TTL_MS;
   const cached = bdCache.get(cwd);
@@ -258,6 +336,24 @@ function bdList(cwd = process.cwd(), runner = bd, opts = {}) {
     ? Math.min(maxAge, EMPTY_TTL_MS)
     : maxAge;
   if (cached && Date.now() - cached.ts < ttl) return cached.data;
+
+  // Stale-while-revalidate. An entry that exists is served immediately, however
+  // old, and refreshed off the event loop. Only a directory with NO entry at all
+  // blocks — which after the boot warm-up means a project nobody has opened yet,
+  // once.
+  //
+  // The alternative was making this async and every caller with it: getTasks,
+  // getInbox, getPipeline, the metrics readers, the SSE broadcast, the alert
+  // sweeps. That refactor is the correct end state and is not what a board
+  // hanging today needs.
+  //
+  // The injected `runner` is how the tests drive this. When one is supplied the
+  // sync path is kept, so a test that stubs `bd` still observes the call it
+  // stubbed rather than a background spawn it cannot see.
+  if (cached && runner === bd) {
+    bdRefreshAsync(cwd);
+    return cached.data;
+  }
   try {
     lastBdRunAt.set(cwd, Date.now());
     const result = runner(['list', '--json', '--all', '--include-gates'], { cwd });
@@ -635,6 +731,7 @@ function detectAgent(task) {
 
 export {
   bdCacheInvalidate,
+  bdCacheStale,
   BD_CACHE_TTL_MS,
   SWEEP_MAX_AGE_MS,
   EMPTY_TTL_MS,

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

@@ -203,7 +203,19 @@ function getAgentsFleet(projectCwd) {
   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);
+  // MEASURED spend, or none. This tile reported the estimate — verdict count
+  // times a hardcoded rate — under the label "LLM SPEND 30D", while the metrics
+  // page reported its own estimate, derived from TASKS, under the same words.
+  // The two disagreed by more than twofold ($3.90 against $1.65) and neither
+  // said it was estimating, so the board contradicted itself and sounded certain
+  // doing it.
+  //
+  // The estimate stays available per agent as `llm_usd_30d_est`, named as an
+  // estimate. The fleet total claims only what verdicts actually recorded, and
+  // is null when they recorded nothing — the same rule the metrics tile, the
+  // portfolio and the budgets all follow now.
+  const totalReal30d = agents.reduce((s, a) => s + (a.llm_usd_30d_real || 0), 0);
+  const measuredFor = agents.filter((a) => a.llm_usd_30d_real != null).length;
 
   return {
     agents,
@@ -213,7 +225,9 @@ function getAgentsFleet(projectCwd) {
       active_30d: active30d,
       retire_candidates: retireCandidates,
       failing_7d: failing,
-      llm_usd_30d: Math.round(totalLlm30d * 100) / 100,
+      llm_usd_30d: measuredFor ? Math.round(totalReal30d * 100) / 100 : null,
+      llm_usd_30d_measured_for: measuredFor,
+      llm_usd_30d_agents_with_runs: agents.filter((a) => a.runs_30d > 0).length,
     },
   };
 }

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

@@ -160,7 +160,12 @@ function getMetrics(cwd = process.cwd(), days = 30) {
   // 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;
+    // A RECORDED zero is not a measurement. `log-verdict.sh` wrote `cost_usd: 0`
+    // whenever no cost was passed, for this repository's whole history, so
+    // `!= null` counted every one of them as a measured run costing nothing —
+    // and the board reported "$0.00 AI spend" over projects with dozens of
+    // agent runs. Same defect as the fleet's, on a second screen.
+    if (v.cost_usd == null || v.cost_usd === 0) 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;
@@ -195,7 +200,7 @@ function getMetrics(cwd = process.cwd(), days = 30) {
   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.cost_usd == null || v.cost_usd === 0) return s;
     if (v.ts && (now - new Date(v.ts).getTime()) > costWindowMs) return s;
     return s + v.cost_usd;
   }, 0);
@@ -206,7 +211,7 @@ function getMetrics(cwd = process.cwd(), days = 30) {
   // Bar: enough windowed done-tasks carry a real verdict cost (coverage ≥ 50%,
   // min 3), and the measured total is a real spend (≥ 1¢, not a synthetic $0).
   const doneInWindowCount = done.filter(t => t.closed_at && (now - new Date(t.closed_at).getTime()) <= costWindowMs).length;
-  const verdictsWithCost = verdicts.filter(v => v.cost_usd != null && (!v.ts || (now - new Date(v.ts).getTime()) <= costWindowMs)).length;
+  const verdictsWithCost = verdicts.filter(v => v.cost_usd != null && v.cost_usd !== 0 && (!v.ts || (now - new Date(v.ts).getTime()) <= costWindowMs)).length;
   const measuredTrustworthy = verdictLlmTotal >= 0.01
     && verdictsWithCost >= Math.max(3, Math.ceil(0.5 * doneInWindowCount));
 

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

@@ -1468,6 +1468,56 @@ async function dispatch(req, res, url, cwd) {
     return true;
   }
 
+  // Search INSIDE documents, not only their titles.
+  //
+  // The docs list has always matched on filename and heading. A hundred and
+  // eighty-seven documents whose contents cannot be searched are a directory
+  // listing, and the thing an operator actually wants — "where did we write down
+  // the reason for X" — was answerable only by leaving the board.
+  //
+  // GET /api/docs/search?q=...  ->  { q, matched, scanned, results[] }
+  if (pathname === '/api/docs/search' && req.method === 'GET') {
+    const c = url.searchParams.get('project') ? resolveProjectCwd(url.searchParams.get('project')) : cwd;
+    const q = (url.searchParams.get('q') || '').trim();
+    if (q.length < 2) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'query must be at least 2 characters' }));
+      return true;
+    }
+    try {
+      const { listDocs } = await import('./docs.mjs');
+      const all = listDocs(c);
+      const needle = q.toLowerCase();
+      const results = [];
+      let scanned = 0, unreadable = 0;
+      for (const g of (all.groups || [])) {
+        for (const d of (g.docs || [])) {
+          if (results.length >= 60) break;
+          let text;
+          try { text = fs.readFileSync(path.join(c, d.path), 'utf8'); scanned++; }
+          catch { unreadable++; continue; }   // counted, never silently skipped
+          const lines = text.split('\n');
+          const hits = [];
+          for (let i = 0; i < lines.length && hits.length < 3; i++) {
+            if (lines[i].toLowerCase().includes(needle)) {
+              hits.push({ line: i + 1, text: lines[i].trim().slice(0, 160) });
+            }
+          }
+          if (hits.length) results.push({ path: d.path, title: d.title || d.name, group: g.label, hits });
+        }
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+      // `scanned` and `unreadable` travel with the answer: "no results" over
+      // 187 files and "no results" over 3 that could be opened are different
+      // facts, and only one of them means the phrase is not there.
+      res.end(JSON.stringify({ q, matched: results.length, scanned, unreadable, results }));
+    } catch (e) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: String(e.message || e) }));
+    }
+    return true;
+  }
+
   // API requests get a JSON 404 so frontends can JSON.parse() the response
   // without crashing. Static-file 404s stay plain text.
   if (pathname.startsWith('/api/')) {

package/board/packages/board/lib/watchers.mjs

@@ -3,7 +3,7 @@ import path from 'path';
 import { GREAT_CTO_DIR } from './config.mjs';
 import { sseClients } from './state.mjs';
 import { listProjects } from './projects.mjs';
-import { bdCacheInvalidate, getTasks, isSelfInflictedTouch } from './beads.mjs';
+import { bdCacheStale, getTasks, isSelfInflictedTouch } from './beads.mjs';
 import { getPipeline, getInbox } from './data-readers.mjs';
 
 // ── File watcher ───────────────────────────────────────────────────────────────
@@ -48,7 +48,10 @@ function watchBeads() {
     // broadcastTasks itself; a write from outside is not a self-touch and lands
     // in the branch below.
     if (isSelfInflictedTouch(dir)) return;
-    bdCacheInvalidate(dir);
+    // Stale, not deleted. A change we NOTICED must not make the next reader pay
+    // for it — they asked for something else. The broadcast below still reads
+    // fresh, because a stale entry refreshes on read.
+    bdCacheStale(dir);
     for (const res of sseClients) {
       if (res._gctoCwd === dir) {
         try {

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

@@ -1640,6 +1640,56 @@ button { font-family: inherit; cursor: pointer; }
   display: flex; gap: 4px; align-items: center;
 }
 .inbox-row .actions .gate-btn { height: 26px; padding: 0 10px; font-size: 11px; }
+.budgets-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.budgets-table th {
+  text-align: left; font-family: var(--mono); font-size: 10px;
+  letter-spacing: 0.08em; text-transform: uppercase; color: var(--text2);
+  padding: 0 12px 8px 0; border-bottom: 1px solid var(--border);
+}
+.budgets-table td { padding: 10px 12px 10px 0; border-bottom: 1px solid var(--border); vertical-align: middle; }
+/* A row has to answer three questions: what is this agent, what does it cost,
+   over what period. The slug alone answered none of them. */
+.budgets-table .bt-slug { font-family: var(--mono); font-size: 12.5px; }
+.budgets-table .bt-desc {
+  font-size: 12px; color: var(--text2); margin-top: 2px;
+  max-width: 52ch; text-wrap: pretty;
+}
+.budgets-table .bt-runs,
+.budgets-table .bt-cap { font-family: var(--mono); font-variant-numeric: tabular-nums; text-align: right; }
+.budgets-table .bt-spend { font-family: var(--mono); font-size: 12px; white-space: nowrap; }
+.budgets-table .bt-usd { font-variant-numeric: tabular-nums; color: var(--text); }
+.budgets-table th[title] { cursor: help; }
+.budgets-idle summary { cursor: pointer; font-size: 13px; color: var(--text2); }
+.budgets-idle summary:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 2px; }
+.budgets-table .bt-actions { text-align: right; white-space: nowrap; }
+.budgets-table .bt-actions .ab-btn + .ab-btn { margin-left: 6px; }
+.budgets-empty {
+  padding: 16px; border: 1px dashed var(--border-strong); border-radius: 8px;
+  color: var(--text2); font-size: 13px;
+}
+.budgets-uncapped { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 8px; }
+.docs-search { display: flex; align-items: center; gap: 8px; margin: 10px 0 16px; }
+.docs-search input {
+  flex: 1 1 auto; min-width: 0; max-width: 460px;
+  height: 32px; padding: 0 10px;
+  border: 1px solid var(--border); border-radius: 8px;
+  background: var(--bg-card); color: var(--text); font: inherit; font-size: 13px;
+}
+.docs-search input:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }
+.docs-search-hint { font-family: var(--mono); font-size: 10px; color: var(--text3); }
+.docs-search-meta { font-size: 12px; color: var(--text2); margin-bottom: 12px; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.docs-hit { padding: 10px 0; border-top: 1px solid var(--border); }
+.docs-hit-line { display: flex; gap: 10px; font-family: var(--mono); font-size: 11px; color: var(--text2); margin-top: 4px; }
+.docs-hit-no { color: var(--text3); min-width: 34px; text-align: right; }
+.col-more {
+  display: block; width: 100%;
+  margin-top: 6px; padding: 8px;
+  font-family: var(--mono); font-size: 11px;
+  border: 1px dashed var(--border-strong); border-radius: 8px;
+  background: transparent; color: var(--text2);
+}
+.col-more:hover { border-style: solid; color: var(--text); }
+.col-more:focus-visible { outline: 2px solid var(--focus-ring); outline-offset: 1px; }
 .inbox-empty {
   padding: 14px 16px;
   background: var(--bg-muted);
@@ -2532,6 +2582,11 @@ button { font-family: inherit; cursor: pointer; }
         <span>Activity</span>
         <span class="count" id="nav-logs-count">0</span>
       </div>
+      <div class="nav-item" data-tab="budgets" role="tab" tabindex="0" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();this.click();}" onclick="switchTab('budgets', this)">
+        <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M12 1v22 M17 5H9.5a3.5 3.5 0 0 0 0 7h5a3.5 3.5 0 0 1 0 7H6"/></svg>
+        <span>Budgets</span>
+        <span class="count" id="nav-budget-count"></span>
+      </div>
       <div class="nav-item" data-tab="notifications" role="tab" tabindex="0" onkeydown="if(event.key==='Enter'||event.key===' '){event.preventDefault();this.click();}" onclick="switchTab('notifications', this); loadNotifHistory()">
         <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5"><path d="M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9 M10.3 21a1.94 1.94 0 0 0 3.4 0"/></svg>
         <span>Notifications</span>
@@ -2712,6 +2767,14 @@ button { font-family: inherit; cursor: pointer; }
         <div class="mp-hero" id="mp-hero"></div>
         <div class="mp-secondary" id="mp-secondary"></div>
 
+        <!-- Budgets live HERE, on Metrics, not two clicks deep in the Agents
+             drill-in. A control the operator could not find is a control they do
+             not have — and it was invisible on top of that, hidden whenever a
+             project had declared no caps, which is exactly the project that
+             needs the button to declare one. -->
+        <div class="mp-section-label" style="margin-top:24px">Agent budgets</div>
+        <div id="agent-budgets" class="mp-card" style="padding:12px 16px;font-size:12px;margin-bottom:4px;"></div>
+
         <div class="mp-section-label" id="mp-cost-label" style="margin-top:24px">Cost · last 30 days</div>
         <div class="mp-card cost-panel" id="cost-panel">
           <div class="cost-empty">Loading…</div>
@@ -2754,11 +2817,6 @@ button { font-family: inherit; cursor: pointer; }
 
         <!-- §3.1 Fleet controls -->
         <section aria-label="Fleet controls" style="margin-top:20px">
-          <!-- Agent budgets (Paperclip cascading budget pattern) -->
-          <div id="agent-budgets" style="display:none;background:var(--bg-muted);border:1px solid var(--border);border-radius:8px;padding:10px 14px;margin-bottom:12px;font-size:12px;">
-            <!-- populated by renderAgentBudgets() from /api/heartbeat -->
-          </div>
-
           <div class="mp-card fleet-controls">
             <div class="fleet-search">
               <input type="search" id="fleet-search" placeholder="Filter agents (press / to focus)" aria-label="Filter agents by slug" />
@@ -2838,8 +2896,29 @@ button { font-family: inherit; cursor: pointer; }
       <div id="sessions-body" class="muted">Loading…</div>
     </div>
 
+    <div class="panel" id="panel-budgets" role="tabpanel">
+      <div class="metrics-page">
+        <h1>Agent budgets</h1>
+        <p class="muted" style="max-width:70ch;margin:6px 0 20px">
+          A cap on what one agent may spend. When measured spend passes it, the pipeline
+          refuses to dispatch that agent and says so — it does not fail quietly.
+          Spend is measured from verdicts that carry a cost; while none does, the cap
+          cannot fire and says that too. An estimate never refuses.
+        </p>
+        <div id="budgets-page-body">loading…</div>
+      </div>
+    </div>
+
     <div class="panel" id="panel-docs">
       <h1>Docs</h1>
+      <div class="docs-search">
+        <input type="search" id="docs-q" placeholder="Search inside documents…"
+               aria-label="Search inside documents"
+               onkeydown="if(event.key==='Enter'){event.preventDefault();searchDocs();}else if(event.key==='Escape'){this.value='';clearDocsSearch();}" />
+        <button type="button" class="ab-btn" onclick="searchDocs()">Search</button>
+        <span class="docs-search-hint"><kbd>Enter</kbd> search · <kbd>Esc</kbd> clear</span>
+      </div>
+      <div id="docs-results" style="display:none"></div>
       <div id="docs-body" class="muted">loading…</div>
     </div>
 
@@ -3410,9 +3489,18 @@ function renderAgentBudgets(budgets, meta = {}) {
   if (!el) return;
   const entries = Object.entries(budgets || {});
   const malformed = meta.budgets_malformed || [];
-  if (entries.length === 0 && !malformed.length) { el.style.display = 'none'; return; }
   el.style.display = 'block';
 
+  // Shown even with nothing declared. Hiding it meant the only project that
+  // needed the "add a budget" button — one with no budgets — was the only
+  // project that never saw it.
+  if (entries.length === 0 && !malformed.length) {
+    el.innerHTML = '<div class="ab-title">Agent budgets · <code>PROJECT.md</code></div>'
+      + '<div class="ab-spent">No caps declared — every agent dispatches regardless of what it has spent.</div>'
+      + '<button type="button" class="ab-btn ab-add" onclick="addAgentBudget()">+ Add a budget</button>';
+    return;
+  }
+
   // Judgements the fleet already computed, keyed by slug. Absent while the
   // fleet is still loading — the row then shows the cap and says the state is
   // not known yet, rather than guessing one.
@@ -3450,6 +3538,149 @@ function renderAgentBudgets(budgets, meta = {}) {
     + `<button type="button" class="ab-btn ab-add" onclick="addAgentBudget()">+ Add a budget</button>`;
 }
 
+/* The Budgets screen.
+ *
+ * The panel on the agents tab was only reachable two clicks in, and hidden
+ * entirely on a project with no caps declared — so on the project the operator
+ * actually opened, the feature did not exist. A limit you can only see after
+ * hand-editing the config it reads is documentation, not a feature.
+ *
+ * This screen shows the same judgements the dispatcher refuses with, plus every
+ * agent that has NO cap, because "which agents are uncapped" is the question you
+ * arrive with when you come here at all.
+ */
+async function loadBudgetsPage() {
+  const body = document.getElementById('budgets-page-body');
+  if (!body) return;
+  body.innerHTML = '<div class="muted">loading…</div>';
+
+  const [h] = await Promise.all([
+    api(`/api/heartbeat${pqs()}`),
+    (typeof refreshAgentsInstalled === 'function' && !(fleetState?.agents || []).length)
+      ? refreshAgentsInstalled() : Promise.resolve(),
+  ]);
+  const caps = h?.budgets || {};
+  const agents = (fleetState?.agents || []).filter((a) => !a.retired);
+
+  // 69 identical chips in one blob answered none of the three questions a person
+  // arrives with: what does this agent do, what does it usually cost, and over
+  // what period. Worse, 62 of the 69 had not run in thirty days — a cap on an
+  // agent that never runs is a cap on nothing, and they were the bulk of the
+  // wall.
+  //
+  // Ordered by what it costs to leave uncapped: agents that ran, most spend
+  // first. The ones that never ran are still reachable, behind a count.
+  const spendOf = (a) => (a.llm_usd_30d_real ?? a.llm_usd_30d_est ?? 0);
+  const ran = agents.filter((a) => (a.runs_30d || 0) > 0)
+    .sort((x, y) => spendOf(y) - spendOf(x) || (y.runs_30d || 0) - (x.runs_30d || 0));
+  const idle = agents.filter((a) => !(a.runs_30d > 0));
+
+  const firstSentence = (t) => {
+    const s1 = String(t || '').split(/(?<=[.!?])\s/)[0] || '';
+    return s1.length > 150 ? s1.slice(0, 147) + '…' : s1;
+  };
+
+  // Spend is stated with its window and its provenance. `est` is a time-based
+  // guess and says so; a real figure only exists where a verdict carried a cost.
+  const spendCell = (a) => {
+    if (a.llm_usd_30d_real != null && a.llm_usd_30d_real > 0) {
+      return `<span class="bt-usd">$${a.llm_usd_30d_real.toFixed(2)}</span> <span class="muted">measured</span>`;
+    }
+    if (a.llm_usd_30d_est != null && a.llm_usd_30d_est > 0) {
+      return `<span class="bt-usd">$${a.llm_usd_30d_est.toFixed(2)}</span> <span class="muted">estimated</span>`;
+    }
+    return '<span class="muted">not measured</span>';
+  };
+
+  const stateCell = (slug) => {
+    const b = (fleetState?.agents || []).find((a) => a.slug === slug)?.budget;
+    if (!b || b.state === 'no-limit') return '';
+    const spent = (b.state === 'within' || b.state === 'exceeded')
+      ? `$${(b.measuredUsd ?? 0).toFixed(2)} measured` : (b.state === 'unmeasured' ? 'nothing measured yet' : '');
+    return `${budgetChip(b)} <span class="ab-spent">${esc(spent)}</span>`;
+  };
+
+  const row = (a, cap) => `
+    <tr>
+      <td class="bt-agent">
+        <div class="bt-slug">${esc(a.slug)}</div>
+        <div class="bt-desc">${esc(firstSentence(a.description))}</div>
+      </td>
+      <td class="bt-runs">${a.runs_30d || 0}</td>
+      <td class="bt-spend">${spendCell(a)}</td>
+      <td class="bt-cap">${cap != null ? `$${esc(String(cap))}` : '<span class="muted">—</span>'}</td>
+      <td class="bt-state">${cap != null ? stateCell(a.slug) : ''}</td>
+      <td class="bt-actions">${cap != null
+        ? `<button type="button" class="ab-btn" onclick="editAgentBudget('${esc(a.slug)}', ${Number(cap)})">Change</button>`
+          + `<button type="button" class="ab-btn ab-rm" onclick="clearAgentBudget('${esc(a.slug)}', ${Number(cap)})">Remove</button>`
+        : `<button type="button" class="ab-btn" onclick="addBudgetFor('${esc(a.slug)}')">Set a cap</button>`}</td>
+    </tr>`;
+
+  const table = (rows) => `
+    <table class="budgets-table">
+      <thead><tr>
+        <th scope="col">Agent</th>
+        <th scope="col" title="Dispatches in the last 30 days">Runs 30d</th>
+        <th scope="col" title="LLM spend over the same 30 days">Spend 30d</th>
+        <th scope="col">Cap</th><th scope="col">State</th><th scope="col"></th>
+      </tr></thead>
+      <tbody>${rows}</tbody>
+    </table>`;
+
+  // A cap declared for an agent the fleet does not list still has to appear —
+  // otherwise a limit that is holding a stage would be invisible here.
+  const known = new Set(agents.map((a) => a.slug));
+  const orphanCaps = Object.entries(caps).filter(([slug]) => !known.has(slug));
+
+  const capped = ran.filter((a) => a.slug in caps);
+  const uncappedRan = ran.filter((a) => !(a.slug in caps));
+
+  const notes = [
+    h?.budgets_deprecated_key
+      ? `<div class="ab-note">Read from the deprecated <code>${esc(h.budgets_deprecated_key)}:</code> key — rename it to <code>agent-budgets:</code>.</div>` : '',
+    (h?.budgets_malformed || []).length
+      ? `<div class="ab-note ab-bad">${h.budgets_malformed.length} line(s) in PROJECT.md were not read: `
+        + h.budgets_malformed.map((m) => `<code>${esc(m.line)}</code> — ${esc(m.why)}`).join('; ') + '</div>' : '',
+  ].join('');
+
+  const capsBlock = (capped.length || orphanCaps.length) ? `
+    <div class="mp-section-label">Capped (${capped.length + orphanCaps.length})</div>
+    ${table(capped.map((a) => row(a, caps[a.slug])).join('')
+      + orphanCaps.map(([slug, cap]) => row({ slug, description: 'not among the installed agents', runs_30d: 0 }, cap)).join(''))}`
+    : `<div class="budgets-empty">No agent has a spending cap in this project. Nothing is being held, and nothing will be.</div>`;
+
+  const activeBlock = uncappedRan.length ? `
+    <div class="mp-section-label" style="margin-top:28px">Ran in the last 30 days, no cap (${uncappedRan.length})</div>
+    <p class="muted" style="margin:4px 0 10px">These are the ones a cap would actually apply to.</p>
+    ${table(uncappedRan.map((a) => row(a, null)).join(''))}` : '';
+
+  // Capping an agent that has not run is capping nothing. Reachable, not shown.
+  const idleBlock = idle.length ? `
+    <details class="budgets-idle" style="margin-top:28px">
+      <summary>${idle.length} installed agents have not run in 30 days</summary>
+      <div class="budgets-uncapped">${idle.slice(0, 80).map((a) => `
+        <button type="button" class="ab-btn" onclick="addBudgetFor('${esc(a.slug)}')"
+                title="${esc(firstSentence(a.description))}">${esc(a.slug)} +</button>`).join('')}
+        ${idle.length > 80 ? `<span class="muted">and ${idle.length - 80} more</span>` : ''}
+      </div>
+    </details>` : '';
+
+  body.innerHTML = `${notes}${capsBlock}${activeBlock}${idleBlock}
+    <button type="button" class="ab-btn ab-add" onclick="addAgentBudget()">+ Add a budget for any agent</button>`;
+
+  const badge = document.getElementById('nav-budget-count');
+  if (badge) badge.textContent = Object.keys(caps).length ? String(Object.keys(caps).length) : '';
+}
+
+/** Set a cap for a named agent, skipping the "which agent?" question. */
+function addBudgetFor(slug) {
+  const usd = budgetPrompt(slug, null);
+  if (usd == null) return;
+  writeAgentBudget({ agent: slug, limit_usd: usd },
+    `Set ${slug} to $${usd}?\n\n`
+    + `Written to .great_cto/PROJECT.md. Measured spend past $${usd} stops the pipeline dispatching ${slug}.`);
+}
+
 /* Writing a cap writes PROJECT.md — a file the operator owns and git tracks.
  *
  * The confirm states what the number DOES rather than asking whether you are
@@ -3467,6 +3698,7 @@ async function writeAgentBudget(body, consequence) {
   showToast(`Budget for <strong>${esc(r.agent)}</strong> ${r.removed ? 'removed' : 'saved'}`, 'success', 2500);
   refreshHeartbeat();
   if (typeof loadFleet === 'function') loadFleet();
+  if (currentTab === 'budgets') loadBudgetsPage();
 }
 
 function budgetPrompt(agent, current) {
@@ -4223,6 +4455,54 @@ async function loadDocs() {
  * of them live in ~/.great_cto and are shared by every project, which is why
  * they never appeared in a per-project walk at all.
  */
+/* Search inside documents, not only their names.
+ *
+ * 187 documents whose contents cannot be searched are a directory listing, and
+ * the question actually asked of them — "where did we write down the reason for
+ * X" — was answerable only by leaving the board.
+ *
+ * `scanned` and `unreadable` come back with the answer and are shown: "nothing
+ * found across 187 files" and "nothing found across the 3 that could be opened"
+ * are different facts, and only one of them means the phrase is not there.
+ */
+async function searchDocs() {
+  const q = (document.getElementById('docs-q')?.value || '').trim();
+  const out = document.getElementById('docs-results');
+  const body = document.getElementById('docs-body');
+  if (!out) return;
+  if (q.length < 2) { clearDocsSearch(); return; }
+
+  out.style.display = 'block';
+  out.innerHTML = '<div class="muted" style="padding:12px 0">searching…</div>';
+  if (body) body.style.display = 'none';
+
+  const d = await api(`/api/docs/search?q=${encodeURIComponent(q)}${pqs().replace(/^\?/, '&')}`);
+  if (!d || d.error) {
+    out.innerHTML = `<div class="muted" style="padding:12px 0">search failed — ${esc(d?.error || 'no response')}</div>`;
+    return;
+  }
+  const head = `<div class="docs-search-meta">${d.matched} document(s) contain “${esc(d.q)}” · `
+    + `${d.scanned} searched${d.unreadable ? ` · ${d.unreadable} could not be opened` : ''} · `
+    + `<button type="button" class="ab-btn" onclick="clearDocsSearch()">back to all docs</button></div>`;
+  if (!d.matched) {
+    out.innerHTML = head + '<div class="muted" style="padding:12px 0">No document contains that phrase.</div>';
+    return;
+  }
+  out.innerHTML = head + d.results.map((r) => `
+    <div class="docs-hit">
+      <a href="#" onclick="event.preventDefault();openDoc('${esc(r.path)}')"><b>${esc(r.title)}</b></a>
+      <span class="muted"> · ${esc(r.group)} · <code>${esc(r.path)}</code></span>
+      ${r.hits.map((h) => `<div class="docs-hit-line"><span class="docs-hit-no">${h.line}</span>${esc(h.text)}</div>`).join('')}
+    </div>`).join('');
+}
+
+function clearDocsSearch() {
+  const out = document.getElementById('docs-results');
+  const body = document.getElementById('docs-body');
+  if (out) { out.style.display = 'none'; out.innerHTML = ''; }
+  if (body) body.style.display = '';
+}
+
 async function loadContextLayers() {
   let m;
   try { m = await api(`/api/memory${pqs()}`); } catch { m = null; }
@@ -5094,6 +5374,15 @@ function clearFilters() {
 }
 
 /* ── Kanban ─────────────────────────────────────────────────────────────── */
+/** Columns the operator has asked to see in full, for this page load. */
+const expandedColumns = new Set();
+const COLUMN_CAP = 25;
+
+function expandColumn(id) {
+  expandedColumns.add(id);
+  renderKanban(allTasks);
+}
+
 function renderKanban(tasks) {
   renderFilterBar();
   const board = document.getElementById('kanban-board');
@@ -5109,6 +5398,11 @@ function renderKanban(tasks) {
   board.innerHTML = '';
   for (const col of COLUMNS) {
     const items = byCol[col.id];
+    // Capped per column, not globally: a Backlog of 5 and a Done of 227 are
+    // different problems and only one of them needs a lid.
+    const cap = expandedColumns.has(col.id) ? Infinity : COLUMN_CAP;
+    const shown = items.slice(0, cap);
+    const hidden = items.length - shown.length;
     const dotClass = col.dot === 'filled' ? 'filled' : col.dot === 'half' ? 'half' : '';
     const el = document.createElement('div');
     el.className = `column col-${col.id}`;
@@ -5118,10 +5412,20 @@ function renderKanban(tasks) {
         <span class="col-title">${col.label}</span>
         <span class="col-count">${items.length}</span>
       </div>
-      <div class="col-body">${items.length ? items.map(cardHTML).join('') : '<div class="empty">No tasks</div>'}</div>`;
+      <div class="col-body">${
+        items.length
+          ? shown.map(cardHTML).join('') + (hidden > 0
+              // 227 done cards in one column is not a list anybody reads; it is
+              // a scroll. The count in the header is the fact worth having, and
+              // the rest is available by asking rather than by default.
+              ? `<button type="button" class="col-more" onclick="expandColumn('${col.id}')">`
+                + `Show ${hidden} more · ${items.length} total</button>`
+              : '')
+          : '<div class="empty">No tasks</div>'
+      }</div>`;
     board.appendChild(el);
     el.querySelectorAll('.card').forEach((cardEl, i) => {
-      cardEl.addEventListener('click', () => openSide(items[i]));
+      cardEl.addEventListener('click', () => openSide(shown[i]));
     });
   }
 }
@@ -5411,9 +5715,15 @@ function renderDashboard(m) {
       delta: deltaBadge(done, m.previous?.done, m.previous?.comparable),
     },
     {
-      // $0.00 with nothing spent yet is a measurement; "—" would claim we never
-      // looked. The trend line underneath already says which of the two it is.
-      v: costKnown ? `$${aiSpend < 10 ? aiSpend.toFixed(2) : fmtMoney(aiSpend)}` : absent('unloaded', 'the metrics payload carried no cost section'),
+      // Three states, and $0.00 is only one of them. A measured zero is worth
+      // showing; a zero that is the TIME-BASED ESTIMATE with no plans or tasks
+      // to estimate from is not a figure at all, and rendering it as $0.00 told
+      // a project with dozens of agent runs that it had spent nothing.
+      v: !costKnown
+        ? absent('unloaded', 'the metrics payload carried no cost section')
+        : (realLlmUsd === 0 && llmUsd === 0
+            ? absent('uncomputable', 'no verdict carries a cost and there is nothing to estimate from')
+            : `$${aiSpend < 10 ? aiSpend.toFixed(2) : fmtMoney(aiSpend)}`),
       sub: '',
       label: 'AI spend',
       delta: deltaBadge(aiSpend, m.previous?.llm_usd, m.previous?.comparable, { invert: true }),
@@ -6066,8 +6376,19 @@ 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 = { docs: 'Docs', dashboard: 'Board', inbox: 'Inbox', tasks: 'Tasks', agents: 'Agents', logs: 'Activity', notifications: 'Notifications', metrics: 'Metrics', share: 'Share' };
+  const TAB_LABELS = { 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] || '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
+  // live in.
+  if (id === 'dashboard') refreshHeartbeat();
+  // The Notifications panel has carried an inline history list all along, and
+  // `renderNotifHistoryInline()` to fill it — but the only caller was
+  // `openNotifDrawer()`. Opening the tab itself never loaded it, so the sidebar
+  // promised 50 unread and the screen showed settings. Declared and not
+  // consumed, in the UI this time.
+  if (id === 'notifications') loadNotifHistory();
+  if (id === 'budgets') loadBudgetsPage();
   if (id === 'dashboard' || id === 'agents') {
     // pqsd(), not pqs(): this call omitted `days` entirely, so the server applied
     // its 30-day default and overwrote whatever window the period chips had
@@ -6255,11 +6576,32 @@ function renderFleetSummary() {
       trend: s.retire_candidates > 0 ? 'click to filter' : 'fleet is lean',
       onClick: 'setFleetFilter("activity", "never")',
     },
-    { v: '$' + (s.llm_usd_30d ?? 0).toFixed(2), label: 'LLM spend 30d', cls: '', trend: s.failing_7d ? `${s.failing_7d} failing` : '' },
+    {
+      // `?? 0` turned "nothing was measured" into "$0.00 spent", and before that
+      // the number here was an ESTIMATE from verdict counts while the metrics
+      // page estimated from tasks — two screens, one label, $3.90 against $1.65.
+      v: s.llm_usd_30d != null
+        ? '$' + s.llm_usd_30d.toFixed(2)
+        : absent('uncomputable', `no verdict carries a cost — ${s.llm_usd_30d_agents_with_runs ?? 0} agent(s) ran in this window`),
+      vHtml: s.llm_usd_30d == null,
+      label: 'LLM spend 30d',
+      cls: '',
+      trend: s.llm_usd_30d != null
+        ? `measured for ${s.llm_usd_30d_measured_for} agent(s)`
+        : (s.failing_7d ? `${s.failing_7d} failing` : 'measured from verdicts'),
+    },
   ];
+  // `t.v` is HTML when it is an absence marker — a span carrying the reason on
+  // hover and in the accessible name — and a plain string otherwise. Escaping it
+  // unconditionally printed the markup as text on the fleet tile. `vHtml` is the
+  // deliberate opt-in; every value without it is still escaped.
+  //
+  // This comment lives out here because it names `t.v` in backticks, and a
+  // backtick inside the template literal below terminates it — which is how the
+  // board shipped a syntax error for about ninety seconds.
   el.innerHTML = tiles.map(t => `
     <div class="metric-card ${t.cls}" ${t.onClick ? `role="button" tabindex="0" onclick='${t.onClick}' onkeydown='if(event.key==="Enter"||event.key===" "){event.preventDefault();${t.onClick}}'` : ''}>
-      <div class="metric-num">${esc(String(t.v))}</div>
+      <div class="metric-num">${t.vHtml ? t.v : esc(String(t.v))}</div>
       <div class="metric-label">${esc(t.label)}</div>
       ${t.trend ? `<div class="metric-trend">${esc(t.trend)}</div>` : ''}
     </div>`).join('');

package/board/packages/board/server.mjs

@@ -13,6 +13,7 @@ import fs from 'fs';
 import path from 'path';
 import { spawnSync } from 'child_process';
 import { PORT, PUBLIC, HOST } from './lib/config.mjs';
+import { getTasks } from './lib/beads.mjs';
 import { originAllowed, isInsideDir } from './lib/util.mjs';
 import { discoverProjects, resolveProjectInfo } from './lib/projects.mjs';
 import { startAlertCron } from './lib/alerts.mjs';
@@ -114,6 +115,29 @@ server.listen(PORT, HOST, () => {
     log.info(`  ⚠ bound to ${HOST} — reachable beyond this machine. Operators authenticate via invite`);
     log.info(`    links; put your reverse-proxy auth in front for anything admin-grade.`);
   }
+  // Warm the task cache for THIS project before a browser asks.
+  //
+  // `bd list` costs seconds and runs through `spawnSync`, which holds the event
+  // loop for the whole of it. On a cold board the first request pays that, and
+  // every other request queues behind it: opening the board showed "loading…"
+  // on Docs for 27 seconds, measured, while the endpoint itself takes 0.4 s
+  // warm. Nothing was broken — everything was waiting.
+  //
+  // Doing it here moves the stall to before anyone is looking, where a stall
+  // costs nothing. `setImmediate` so the listening callback returns first and
+  // the port is genuinely open while this runs.
+  setImmediate(() => {
+    const t0 = Date.now();
+    try {
+      getTasks(process.cwd());
+      log.info(`  → task cache warmed in ${Date.now() - t0}ms`);
+    } catch (e) {
+      // A warm-up that failed changes nothing a request would not have hit
+      // anyway; it must never stop the board from serving.
+      log.warn(`  → could not warm the task cache: ${e?.message || e}`);
+    }
+  });
+
   // Discover all great_cto projects on disk asynchronously — don't block
   // the listening event so /api/tasks is available immediately.
   discoverProjects().then(n => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "3.0.0",
+  "version": "3.2.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",