great-cto 2.99.0 → 3.1.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": "2.99.0",
+  "version": "3.1.0",
   "author": {
     "name": "Great CTO",
     "url": "https://github.com/avelikiy/great_cto"

package/board/packages/board/lib/alerts.mjs

@@ -12,7 +12,14 @@ import { listProjects, readProjectMd } from './projects.mjs';
 import { addNotification } from './notifications.mjs';
 import { getMetrics } from './metrics.mjs';
 import { getCostHistory, getInbox } from './data-readers.mjs';
-import { getTasks } from './beads.mjs';
+// Every sweep below runs over EVERY registered project, and `bd list` is
+// spawnSync — the event loop is held for the whole of it. At 16 projects and
+// 2-6 s each that is ~60 s per sweep, and three of these fire every five
+// minutes. Sweeps therefore read at sweep freshness, not interactive freshness:
+// see SWEEP_MAX_AGE_MS in beads.mjs for the arithmetic that made the board
+// unanswerable while reporting "live · synced just now".
+import { getTasks, SWEEP_MAX_AGE_MS } from './beads.mjs';
+const SWEEP = { maxAgeMs: SWEEP_MAX_AGE_MS };
 import { readVerdicts } from './verdicts.mjs';
 import { isFailure } from './fleet.mjs';
 import { getShareState, toggleShare } from './share.mjs';
@@ -146,7 +153,7 @@ function startAlertCron() {
       const projects = listProjects();
       const now = Date.now();
       for (const proj of projects) {
-        const tasks = getTasks(proj.path);
+        const tasks = getTasks(proj.path, SWEEP);
         const p0 = tasks.filter(t => {
           if (t.priority !== 0) return false;
           if (t.raw_status === 'closed' || t.raw_status === 'done') return false;
@@ -220,7 +227,7 @@ function startAlertCron() {
     try {
       const projects = listProjects();
       for (const proj of projects) {
-        const tasks = getTasks(proj.path);
+        const tasks = getTasks(proj.path, SWEEP);
         const gates = tasks.filter(t => t.is_gate && t.raw_status !== 'closed' && t.raw_status !== 'blocked');
         for (const g of gates) {
           const created = new Date(g.created_at || g.updated_at || 0).getTime();
@@ -348,7 +355,7 @@ function startAlertCron() {
         const blocked = inbox.summary?.blocked ?? 0;
         const gates = inbox.summary?.gates ?? 0;
         // Tasks closed yesterday
-        const tasks = (() => { try { return getTasks(proj.path); } catch { return []; } })();
+        const tasks = (() => { try { return getTasks(proj.path, SWEEP); } catch { return []; } })();
         const doneYesterday = tasks.filter(t => {
           if (!t.closed_at) return false;
           return t.closed_at.slice(0, 10) === yesterday;

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';
@@ -22,9 +22,50 @@ import { log } from './log.mjs';
 // `bdCacheInvalidate` fires on every write through the board, and the file
 // watchers fire when anything changes the store underneath us. The TTL is only
 // the backstop for a change that arrived through neither.
-const BD_CACHE_TTL_MS = Number(process.env.GREAT_CTO_BD_CACHE_TTL_MS || 30000);
+// 5 minutes, and the number is a backstop rather than a freshness promise.
+//
+// Staleness is bounded by INVALIDATION, not by this clock. Every write through
+// the board drops the entry (four call sites in routes.mjs), and the file
+// watchers drop it for the project a client is actually watching on any change
+// underneath it. What the TTL covers is the residue: a change that arrived
+// through neither path, in a project nobody has open.
+//
+// 30 s was worse than it looks. `bd list` costs 6.8 s on this repository, so a
+// person who clicks, reads for half a minute, and clicks again pays the full
+// cost every single time — the cache only ever helped a burst. Measured after
+// the sweep fix, with no `bd` child present in twenty seconds of sampling: the
+// board was no longer saturated and still answered /api/inbox in 8-11 s,
+// 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);
+}
 
-function bdCacheInvalidate(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
@@ -143,11 +184,183 @@ function bdReason(result) {
   return (line || 'bd exited non-zero without a message').slice(0, 300);
 }
 
-function bdList(cwd = process.cwd(), runner = bd) {
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.maxAgeMs] How stale an entry may be before it is
+ *   refreshed. Defaults to BD_CACHE_TTL_MS — the interactive freshness a person
+ *   looking at one project expects.
+ *
+ *   Background sweeps pass a much larger value, and the reason is arithmetic
+ *   rather than taste. `bd list` costs 2-6 s per project; this machine has 16
+ *   registered. One sweep is therefore ~60 s of SYNCHRONOUS work — `spawnSync`
+ *   holds the event loop for the whole of it — while the TTL was 30 s. The first
+ *   entries expired before the sweep that filled them had finished, so the next
+ *   sweep re-ran all sixteen. Three of the alert crons do this every five
+ *   minutes: ~190 s of blocking per 300 s.
+ *
+ *   Measured while it was happening: a `bd` child present in 9 of 10 samples
+ *   over 20 s, and `/api/version` — a single readdirSync — answering in 1-10 s
+ *   because it was queued behind the sweep. The board rendered empty, said
+ *   "live · synced just now", and was telling the truth: SSE was connected and
+ *   every data request had timed out.
+ *
+ *   A cache whose TTL is shorter than the sweep that fills it never hits. Same
+ *   defect as the 2 s TTL fixed yesterday, one level up: that one was measured
+ *   against a single call, this one has to be measured against the whole sweep.
+ */
+/**
+ * When we last ran `bd` ourselves in a directory.
+ *
+ * `bd list` is a READ, and dolt still writes: it touches
+ * `.dolt/noms/manifest` and `.dolt/noms/journal.idx` on every invocation. The
+ * file watcher watches exactly those files — deliberately, because `bd create`
+ * writes only to dolt and never to interactions.jsonl, so they are the only
+ * signal for a new issue.
+ *
+ * The two together form a loop: a request runs `bd list`, dolt touches the
+ * journal, the watcher fires, the cache entry is invalidated, and the next
+ * request runs `bd list` again. The read destroyed the cache that existed to
+ * make the read unnecessary. This is why raising the TTL never worked — not at
+ * 2 s, not at 30 s, not at 5 minutes. The entry was never expiring; it was being
+ * deleted.
+ *
+ * A touch within `SELF_TOUCH_WINDOW_MS` of our own run is ours. A real external
+ * write inside that window is missed by the watcher and picked up by the next
+ * event or by the TTL — the alternative is the loop, which costs every read.
+ */
+const lastBdRunAt = new Map();
+const SELF_TOUCH_WINDOW_MS = 3000;
+
+/** True when a file event under `cwd` is the echo of a `bd` we just ran. */
+function isSelfInflictedTouch(cwd) {
+  const at = lastBdRunAt.get(cwd);
+  return at != null && Date.now() - at < SELF_TOUCH_WINDOW_MS;
+}
+
+/**
+ * A DELIBERATE invalidation means something really changed, so the file event it
+ * is about to produce is not ours to ignore.
+ *
+ * Without this the self-touch window swallowed real writes. Approving a gate
+ * goes: read the inbox (our `bd list`, stamped), approve (a `bd update`), dolt
+ * touches the journal, watcher fires — and the touch lands inside the 3 s window
+ * opened by our own read, so it was skipped and the SSE broadcast never went out.
+ * Live updates stopped, and the comment above said the write would be "picked up
+ * by the next event", which for a broadcast means never.
+ *
+ * Every write path already calls `bdCacheInvalidate`. Clearing the mark there
+ * costs nothing and makes the window mean what it says: it suppresses the echo
+ * of a READ, never the consequence of a write.
+ */
+function clearSelfTouch(cwd) { lastBdRunAt.delete(cwd); }
+
+/**
+ * An EMPTY answer is cached briefly, whatever the TTL says.
+ *
+ * Empty is the one result most likely to be premature: a board that starts while
+ * a project is still being written reads no tasks, and that answer is
+ * indistinguishable from a project that genuinely has none. At a 2 s TTL the
+ * mistake healed before anyone noticed. At 5 minutes it does not — the board
+ * served `{"gates":0,"blocked":0,"p0":0,"stale":0}` for longer than any test
+ * runs, and longer than a person will wait before deciding the board is broken.
+ *
+ * That is exactly what raising the TTL did to this suite: the gate tests create
+ * a task, start a board, and poll. The poll used to recover. It stopped
+ * recovering, and the failures moved around enough between runs to read as the
+ * flakiness that had been there all day — which is why I spent three runs
+ * blaming the machine.
+ *
+ * A short window for empty costs one `bd list` on a project that really is
+ * empty, and nothing at all on one that is not.
+ */
+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);
-  if (cached && Date.now() - cached.ts < BD_CACHE_TTL_MS) return cached.data;
+  const ttl = cached && Array.isArray(cached.data) && cached.data.length === 0
+    ? 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 });
+    // Stamped again on return: the touch happens DURING the call, and the call
+    // takes seconds. Stamping only before it leaves a window where our own echo
+    // arrives after the mark has already aged out.
+    lastBdRunAt.set(cwd, Date.now());
     if (result.status !== 0) {
       bdFailures.set(cwd, bdReason(result));
       if (cached) return cached.data; // last-good data, cache untouched
@@ -449,8 +662,15 @@ function parseTasksMd(cwd) {
   }
 }
 
-function getTasks(cwd = process.cwd()) {
-  const all = bdList(cwd);
+/**
+ * Sweeps that touch every registered project pass `{ maxAgeMs: SWEEP_MAX_AGE_MS }`.
+ * A gate that has been stale for hours is not less stale for having been read
+ * ten minutes ago, and no alert is worth making the board unanswerable.
+ */
+const SWEEP_MAX_AGE_MS = Number(process.env.GREAT_CTO_BD_SWEEP_MAX_AGE_MS || 15 * 60 * 1000);
+
+function getTasks(cwd = process.cwd(), opts = {}) {
+  const all = bdList(cwd, bd, opts);
   // Fallback to tasks.md when no Beads tasks (project not initialized with bd)
   if (all.length === 0) {
     const mdTasks = parseTasksMd(cwd);
@@ -511,7 +731,11 @@ function detectAgent(task) {
 
 export {
   bdCacheInvalidate,
+  bdCacheStale,
   BD_CACHE_TTL_MS,
+  SWEEP_MAX_AGE_MS,
+  EMPTY_TTL_MS,
+  isSelfInflictedTouch,
   BD_BIN,
   bdEnv,
   bd,

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

@@ -5,6 +5,10 @@ import { GREAT_CTO_DIR } from './config.mjs';
 import { readFileSafe } from './util.mjs';
 import { log } from './log.mjs';
 import { readVerdicts } from './verdicts.mjs';
+// Per-agent spending limits. The judge lives in scripts/lib because the pipeline
+// dispatcher enforces the same verdict — one definition, so the board cannot
+// show `within` while the dispatcher holds the stage.
+import { parseAgentBudgets, judgeAgentBudget } from '../../../scripts/lib/agent-budget.mjs';
 
 // ── Agent fleet view (DESIGN-agents-fleet-view §3) ─────────────────────────
 //
@@ -86,6 +90,16 @@ function isFailure(verdict) {
 }
 
 function getAgentsFleet(projectCwd) {
+  // Read once per call, not per agent: sixty agents would otherwise re-read and
+  // re-parse the same PROJECT.md sixty times on every board refresh.
+  let agentBudgets = new Map();
+  try {
+    if (projectCwd) {
+      agentBudgets = parseAgentBudgets(
+        fs.readFileSync(path.join(projectCwd, '.great_cto', 'PROJECT.md'), 'utf8')).budgets;
+    }
+  } catch { /* no PROJECT.md, or unreadable — every agent reads as no-limit */ }
+
   const agents = [];
   let files = [];
   try {
@@ -170,6 +184,17 @@ function getAgentsFleet(projectCwd) {
       savings_x: savingsX,
       health,
       retired: isRetired(slug),
+      // Four states, and only `exceeded` can hold a dispatch — see
+      // scripts/lib/agent-budget.mjs. `llm_usd_30d_real` is null when nothing was
+      // measured, which is exactly what makes the difference between "under the
+      // cap" and "no idea" visible here instead of guessed.
+      budget: judgeAgentBudget({
+        agent: slug,
+        budgets: agentBudgets,
+        spend: realLlmUsd > 0
+          ? { real_llm_usd: Math.round(realLlmUsd * 100) / 100, llm_usd: Math.round(estLlmUsd * 100) / 100 }
+          : { llm_usd: Math.round(estLlmUsd * 100) / 100 },
+      }),
     });
   }
 
@@ -178,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,
@@ -188,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));
 
@@ -269,9 +274,33 @@ function getMetrics(cwd = process.cwd(), days = 30) {
   const verdictsInWindow = verdicts.filter(v => v.ts && (now - new Date(v.ts).getTime()) <= costWindowMs);
   const acceptance = acceptanceMetrics(verdictsInWindow, cost.llm_usd);
 
+  // The window immediately before this one, same length — so a tile can say
+  // "12% fewer than the previous 30 days" instead of only "+3 this week".
+  //
+  // Three states, not two. `comparable: false` when the project has no history
+  // reaching back two full windows: a project that is three weeks old has no
+  // previous 30 days, and rendering that absence as 0% or as a fall from zero
+  // would be inventing a comparison. The tile shows nothing in that case.
+  const prevStart = now - 2 * costWindowMs;
+  const prevEnd = now - costWindowMs;
+  const inPrev = (ms) => ms > prevStart && ms <= prevEnd;
+  const oldestSignal = Math.min(
+    ...[...done.map(t => t.closed_at), ...verdicts.map(v => v.ts)]
+      .filter(Boolean).map(x => new Date(x).getTime()).filter(Number.isFinite),
+    Infinity,
+  );
+  const previous = {
+    comparable: Number.isFinite(oldestSignal) && oldestSignal <= prevEnd,
+    done: done.filter(t => t.closed_at && inPrev(new Date(t.closed_at).getTime())).length,
+    llm_usd: Math.round(verdicts
+      .filter(v => v.ts && v.cost_usd != null && inPrev(new Date(v.ts).getTime()))
+      .reduce((a, v) => a + v.cost_usd, 0) * 10000) / 10000,
+  };
+
   return {
     window_days: days,
     acceptance,
+    previous,
     tasks: {
       total: tasks.length,
       done: done.length,

package/board/packages/board/lib/portfolio.mjs

@@ -31,7 +31,8 @@ import path from 'node:path';
 import { readVerdicts } from './verdicts.mjs';
 
 /** A project's state, or an honest account of why it is unknown. */
-export function projectRow(entry, { now = Date.now() } = {}) {
+export function projectRow(entry, opts = {}) {
+  const { now = Date.now() } = opts;
   const base = { slug: entry.slug, path: entry.path, archetype: entry.archetype || null, description: entry.description || '' };
 
   if (!entry.path || !fs.existsSync(entry.path)) {
@@ -60,7 +61,20 @@ export function projectRow(entry, { now = Date.now() } = {}) {
   // Spend is only claimed over verdicts that carry a cost. A verdict without one
   // is not zero spend — it is spend nobody recorded, and adding it as zero is how
   // a dashboard reports a number smaller than the invoice.
-  const priced = verdicts.filter((v) => typeof v.cost_usd === 'number');
+  //
+  // The rule was right and the test for it was `typeof === 'number'`, which a
+  // RECORDED zero passes. `log-verdict.sh` wrote `cost_usd: 0` whenever no cost
+  // was passed to it, for the whole history of this repository, so the fleet read
+  // eight projects as "$0.00 spent" over 2 to 27 records each — the confident
+  // zero this file's own header exists to prevent, assembled out of
+  // non-measurements.
+  //
+  // A zero is not evidence of spend. It is counted separately and shown, never
+  // dropped and never summed: `booking` and `subs` prove the mixture is real, so
+  // silently discarding the zeros would hide how little of each figure is
+  // actually measured.
+  const priced = verdicts.filter((v) => typeof v.cost_usd === 'number' && v.cost_usd > 0);
+  const recordedZero = verdicts.filter((v) => v.cost_usd === 0).length;
   const spend = priced.reduce((a, v) => a + v.cost_usd, 0);
 
   const last = verdicts.length
@@ -76,8 +90,9 @@ export function projectRow(entry, { now = Date.now() } = {}) {
     idleMs: newest ? now - newest : null,
     spend: priced.length ? Number(spend.toFixed(4)) : null,
     spendKnownFor: priced.length,
-    spendUnknownFor: verdicts.length - priced.length,
-    needsYou: needsAttention(last),
+    spendZeroFor: recordedZero,
+    spendUnknownFor: verdicts.length - priced.length - recordedZero,
+    needsYou: needsAttention(last, { transitions: opts.transitions || null }),
   };
 }
 
@@ -89,12 +104,45 @@ export function projectRow(entry, { now = Date.now() } = {}) {
  * says "security-officer returned REJECTED", not a red dot the reader has to
  * interpret.
  */
-export function needsAttention(last) {
+/**
+ * What is waiting on the CTO in this project, or null.
+ *
+ * This only looked at whether the LAST verdict was a failure, so across
+ * seventeen projects it returned null seventeen times — including for one with a
+ * blocked task and an open P0 visible on its own inbox. The column that exists
+ * to answer "what needs me" answered nothing, everywhere, and looked like calm.
+ *
+ * A stage that ended in a terminal APPROVED/DONE and has a gate declared after
+ * it is waiting on a person. That is what the module header promised: position
+ * from verdicts alone, erring toward "this may need you", which is the right
+ * direction to be wrong in for a decisions queue.
+ *
+ * Derived from verdicts and the pipeline map only. This module deliberately does
+ * not run `bd` — the header above says why, and a sweep of seventeen projects at
+ * 2-6 s each is the saturation this board was fixed for today.
+ *
+ * @param {object|null} last     the newest verdict
+ * @param {object} [opts]
+ * @param {object} [opts.transitions]  the pipeline map, for the gate question
+ */
+export function needsAttention(last, { transitions = null } = {}) {
   if (!last) return null;
   const v = String(last.verdict || '').toUpperCase();
   if (['BLOCKED', 'FAIL', 'FAILED', 'REJECTED'].includes(v)) {
     return `${last.agent || 'a stage'} returned ${v}`;
   }
+
+  // A stage that finished successfully behind a declared gate is waiting on a
+  // person. Reported conservatively — the map says a gate is declared there, not
+  // that this particular gate is currently open — because for a decisions queue
+  // "this may need you" is the right direction to be wrong in.
+  if (transitions && ['APPROVED', 'DONE', 'PASS', 'PLAN_READY', 'BRIEF_READY'].includes(v)) {
+    const rule = transitions[last.agent];
+    const gates = rule?.gate ? (Array.isArray(rule.gate) ? rule.gate : [rule.gate]) : [];
+    if (gates.length) {
+      return `${last.agent} finished — ${gates.join(', ')} declared next`;
+    }
+  }
   return null;
 }
 
@@ -105,12 +153,15 @@ export function needsAttention(last) {
  * unreadable registry used to render as a board with no projects, which is the
  * same lie one level further out.
  */
-export function portfolio(registry, { now = Date.now(), maxProjects = 100 } = {}) {
+export function portfolio(registry, { now = Date.now(), maxProjects = 100, transitions = null } = {}) {
   if (!registry || registry.unread) {
     return { registryUnread: registry?.unread || 'the project registry could not be read', projects: [] };
   }
+  // The map is read ONCE for the sweep, not once per project. It is the same map
+  // for every project now that it lives in the plugin, and seventeen reads of a
+  // file to answer one question each is how a glanceable screen stops being one.
   const entries = (registry.projects || []).slice(0, maxProjects);
-  const projects = entries.map((e) => projectRow(e, { now }));
+  const projects = entries.map((e) => projectRow(e, { now, transitions }));
 
   const readable = projects.filter((p) => !p.unread);
   return {