great-cto 2.99.0 → 3.0.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.0.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

@@ -22,9 +22,26 @@ 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);
 
-function bdCacheInvalidate(cwd) { bdCache.delete(cwd); }
+function bdCacheInvalidate(cwd) {
+  clearSelfTouch(cwd);
+  bdCache.delete(cwd);
+}
 
 // ── bd binary resolution (BH-32) ────────────────────────────────────────────
 // A board launched from a GUI / launchd / a login shell that didn't source the
@@ -143,11 +160,111 @@ 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);
+
+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;
   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 +566,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);
@@ -512,6 +636,9 @@ function detectAgent(task) {
 export {
   bdCacheInvalidate,
   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 },
+      }),
     });
   }
 

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

@@ -269,9 +269,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 {

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

@@ -18,6 +18,7 @@ import { log } from './log.mjs';
 import { bdCacheInvalidate, checkBeadsAvailable, bdWriteSerialised, bd, bdErr, getTasks, setTaskStatusInTasksMd, getReadDegradation } from './beads.mjs';
 import { getMetrics } from './metrics.mjs';
 import { readVerdicts } from './verdicts.mjs';
+import { parseAgentBudgets, upsertAgentBudget, removeAgentBudget } from '../../../scripts/lib/agent-budget.mjs';
 import { getAgentsFleet, getAgentProfile, retireAgent, restoreAgent, appendDecisionLog, readDecisionsLog } from './fleet.mjs';
 import { getResume, getShareState, toggleShare } from './share.mjs';
 import { listSessions, readSession, editedFiles, searchSessions } from './transcripts.mjs';
@@ -363,7 +364,18 @@ async function dispatch(req, res, url, cwd) {
       const degraded = getRegistryDegradation();
       // A registry that could not be read used to render as a board with no
       // projects — the same silence this screen exists to remove, one level out.
-      const out = portfolio(degraded ? { unread: degraded } : reg);
+      // The pipeline map, so the fleet can say which projects are waiting on a
+      // decision rather than only which ones failed. Read once for the sweep;
+      // unreadable means the gate question is simply not answered, never
+      // answered as "nothing is waiting".
+      let transitions = null;
+      try {
+        const { pipelineMapFor } = await import('../../../scripts/lib/pipeline-health.mjs');
+        const { parsePipelineToml } = await import('../../../scripts/hooks/pipeline-dispatcher.mjs');
+        const map = pipelineMapFor(cwd);
+        if (map.path) transitions = parsePipelineToml(fs.readFileSync(map.path, 'utf8'));
+      } catch { transitions = null; }
+      const out = portfolio(degraded ? { unread: degraded } : reg, { transitions });
       res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
       res.end(JSON.stringify(out));
     } catch (e) {
@@ -1343,16 +1355,20 @@ async function dispatch(req, res, url, cwd) {
     // Per-agent budgets from PROJECT.md
     const projectMdPath = path.join(cwd, '.great_cto', 'PROJECT.md');
     let budgets = {};
+    let budgetsDeprecatedKey = null;
+    const budgetsMalformed = [];
     let goalAncestry = null;
     try {
       const projectTxt = fs.readFileSync(projectMdPath, 'utf8');
-      const sectionMatch = projectTxt.match(/^agent-budget:\s*\n((?:[ \t]+\S[^\n]*\n?)*)/m);
-      if (sectionMatch) {
-        for (const line of sectionMatch[1].split('\n')) {
-          const m = line.match(/^\s+([a-z][a-z0-9-]*):\s*(\d+(?:\.\d+)?)/);
-          if (m) budgets[m[1]] = parseFloat(m[2]);
-        }
-      }
+      // One parser, in scripts/lib/agent-budget.mjs — the same one the pipeline
+      // dispatcher enforces with and the fleet view judges with. This was an
+      // inline regex reading a different key (`agent-budget:`) with a different
+      // meaning ("$X/run"), so the board could display a cap the dispatcher had
+      // never heard of, and vice versa.
+      const parsed = parseAgentBudgets(projectTxt);
+      for (const [agent, cap] of parsed.budgets) budgets[agent] = cap;
+      if (parsed.deprecatedKey) budgetsDeprecatedKey = parsed.deprecatedKey;
+      for (const bad of parsed.malformed) budgetsMalformed.push(bad);
       // Goal ancestry
       const archetype = (projectTxt.match(/^(?:archetype|primary):\s*(\S+)/m) || [])[1] || null;
       const compliance = (projectTxt.match(/^compliance:\s*(.+)$/m) || [])[1] || null;
@@ -1370,7 +1386,85 @@ async function dispatch(req, res, url, cwd) {
     } catch { /* no log */ }
 
     res.writeHead(200, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
-    res.end(JSON.stringify({ stuck, budgets, goal_ancestry: goalAncestry, tool_failure_rate_1h: toolFailureRate1h }));
+    // `budgets_deprecated_key` and `budgets_malformed` travel with the caps.
+    // A limit somebody wrote under the old key still works and they are told; a
+    // line the parser could not read is reported rather than dropped, because a
+    // budget silently ignored is a limit its author believes they have.
+    res.end(JSON.stringify({
+      stuck, budgets, goal_ancestry: goalAncestry, tool_failure_rate_1h: toolFailureRate1h,
+      budgets_deprecated_key: budgetsDeprecatedKey,
+      budgets_malformed: budgetsMalformed,
+    }));
+    return true;
+  }
+
+  // Set or clear one agent's spending cap, by writing PROJECT.md.
+  //
+  // POST /api/agent-budgets  { agent, limit_usd }   set / replace
+  // POST /api/agent-budgets  { agent, remove: true } clear
+  //
+  // This writes a file the operator owns and git tracks, from a browser. Same
+  // two gates as /api/projects/register, for the same reason: the board listens
+  // on 127.0.0.1, and a page the user happens to be visiting can still issue a
+  // simple cross-origin POST to localhost.
+  //
+  // The reply always reports the PREVIOUS value. A cap that silently replaced
+  // another is a change the operator cannot see they made.
+  if (pathname === '/api/agent-budgets' && req.method === 'POST') {
+    if (!originAllowed(req)) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'origin not allowed' }));
+      return true;
+    }
+    let body = '';
+    req.on('data', (c) => { body += c; if (body.length > 4096) req.destroy(); });
+    req.on('end', () => {
+      let parsed;
+      try { parsed = JSON.parse(body || '{}'); }
+      catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'invalid_json', message: String(e.message || e) }));
+        return;
+      }
+      const mdPath = path.join(cwd, '.great_cto', 'PROJECT.md');
+      let before;
+      try { before = fs.readFileSync(mdPath, 'utf8'); }
+      catch (e) {
+        // No PROJECT.md is not a project we may create one for from a browser.
+        res.writeHead(409, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'no PROJECT.md to write to', detail: String(e.message || e) }));
+        return;
+      }
+      let out;
+      try {
+        out = parsed.remove
+          ? removeAgentBudget(before, parsed.agent)
+          : upsertAgentBudget(before, parsed.agent, parsed.limit_usd);
+      } catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: String(e.message || e) }));
+        return;
+      }
+      try {
+        // Write through a temp file in the same directory, then rename: a
+        // half-written PROJECT.md is the project's own identity truncated.
+        const tmp = `${mdPath}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, out.text);
+        fs.renameSync(tmp, mdPath);
+      } catch (e) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `could not write PROJECT.md: ${String(e.message || e)}` }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: true,
+        agent: String(parsed.agent || '').toLowerCase(),
+        previous_usd: out.previousUsd,
+        removed: out.removed === true,
+        created_block: out.created === true,
+      }));
+    });
     return true;
   }
 

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 } from './beads.mjs';
+import { bdCacheInvalidate, getTasks, isSelfInflictedTouch } from './beads.mjs';
 import { getPipeline, getInbox } from './data-readers.mjs';
 
 // ── File watcher ───────────────────────────────────────────────────────────────
@@ -17,6 +17,37 @@ function watchBeads() {
   if (!dirs.includes(process.cwd())) dirs.push(process.cwd());
 
   const broadcast = (dir) => {
+    // Invalidate ONLY for a project somebody is looking at.
+    //
+    // This ran unconditionally, for all sixteen registered projects, on every
+    // file event in any of them — and an invalidated entry is deleted, so no
+    // later read can be served from cache no matter how stale it is willing to
+    // accept. The alert crons then re-ran `bd list` for all sixteen every five
+    // minutes, at 2-6 s each, synchronously. That is the pair that made the
+    // board unanswerable: watchers emptying the cache as fast as sweeps filled
+    // it, with the event loop held by `spawnSync` throughout.
+    //
+    // A project nobody is watching serves data up to BD_CACHE_TTL_MS old, which
+    // is the freshness contract everywhere else, and the read that refreshes it
+    // happens when someone actually opens it.
+    const watched = [...sseClients].some((r) => r._gctoCwd === dir);
+    if (!watched) return;
+    // Do not react at all to the echo of our own read. `bd list` touches the dolt
+    // journal this watcher watches, so every read was dropping the entry it had
+    // just filled — a loop that made the cache useless at any TTL.
+    //
+    // Return, rather than merely skipping the invalidation. I tried the narrower
+    // version — suppress the cache drop, still broadcast — reasoning that a
+    // watcher event is still an event. It is not: the broadcast reads
+    // getTasks(dir), and on a self-touch the entry was deliberately NOT
+    // invalidated, so the event carries the cache's older answer. Clients were
+    // pushed stale tasks, and `gate: SSE broadcasts updated tasks after
+    // approval` failed on exactly that.
+    //
+    // Nothing is lost by staying silent here. A write through the board calls
+    // broadcastTasks itself; a write from outside is not a self-touch and lands
+    // in the branch below.
+    if (isSelfInflictedTouch(dir)) return;
     bdCacheInvalidate(dir);
     for (const res of sseClients) {
       if (res._gctoCwd === dir) {