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

package/board/packages/board/fixtures/fake-bd-fail.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Test fixture: a `bd` stand-in that always exits non-zero, for testing the
+# failure path of warmTasksAsync (packages/board/beads-warm-async.test.mjs).
+if [ "$1" = "--version" ]; then
+  echo "bd-fake 0.0.0"
+  exit 0
+fi
+echo "dolt: database is locked" >&2
+exit 1

package/board/packages/board/fixtures/fake-bd-slow.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Test fixture: a `bd` stand-in that sleeps before answering, so the
+# boot-responsiveness tests can prove the board stays answerable DURING a
+# slow `bd list` — not just that the code calls the right function. Loaded
+# only via GREAT_CTO_BD_BIN in packages/board/*.test.mjs; never used outside
+# tests.
+if [ "$1" = "--version" ]; then
+  echo "bd-fake 0.0.0"
+  exit 0
+fi
+sleep "${FAKE_BD_DELAY_SECS:-3}"
+echo "[]"

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

@@ -12,14 +12,20 @@ import { listProjects, readProjectMd } from './projects.mjs';
 import { addNotification } from './notifications.mjs';
 import { getMetrics } from './metrics.mjs';
 import { getCostHistory, getInbox } from './data-readers.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".
+// Every sweep below runs over EVERY registered project. `sweep: true` opts a
+// COLD project (never read this process) into bdList()'s non-blocking fill
+// path instead of its synchronous one — the same escape hatch a WARM-but-
+// stale entry already gets. Without it: a real board's first cron tick
+// (t=+5:10, no request in flight) lagged the event loop 9.8s reading a
+// single project synchronously; at 16 projects and 2-6s each that is ~60s
+// per sweep, three of which fire every five minutes, indefinitely. Sweeps
+// 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". `sweep: true` must NEVER be added to
+// an interactive read's opts: an ordinary request is someone waiting on
+// THIS project's answer, and the fill path answers `[]` instead.
 import { getTasks, SWEEP_MAX_AGE_MS } from './beads.mjs';
-const SWEEP = { maxAgeMs: SWEEP_MAX_AGE_MS };
+const SWEEP = { maxAgeMs: SWEEP_MAX_AGE_MS, sweep: true };
 import { readVerdicts } from './verdicts.mjs';
 import { isFailure } from './fleet.mjs';
 import { getShareState, toggleShare } from './share.mjs';

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

@@ -38,6 +38,15 @@ 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);
 
+/**
+ * When a cwd was last told "your cache entry is wrong" — by an invalidate or
+ * a stale-mark, whichever most recently ran. A background fetch that STARTED
+ * before this timestamp answers a question nobody is asking anymore: see
+ * `bdRefreshAsync`, which compares its own start time against this map before
+ * committing its result, so a slow fetch racing a write always loses to it.
+ */
+const lastInvalidatedAt = new Map();
+
 /**
  * Drop a directory's entry so the next read is guaranteed fresh.
  *
@@ -47,6 +56,7 @@ const BD_CACHE_TTL_MS = Number(process.env.GREAT_CTO_BD_CACHE_TTL_MS || 300000);
  */
 function bdCacheInvalidate(cwd) {
   clearSelfTouch(cwd);
+  lastInvalidatedAt.set(cwd, Date.now());
   bdCache.delete(cwd);
 }
 
@@ -63,6 +73,7 @@ function bdCacheInvalidate(cwd) {
  */
 function bdCacheStale(cwd) {
   clearSelfTouch(cwd);
+  lastInvalidatedAt.set(cwd, Date.now());
   const cached = bdCache.get(cwd);
   if (cached) bdCache.set(cwd, { ...cached, ts: 0 });
 }
@@ -290,13 +301,16 @@ const refreshing = new Set();
  * 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.
+ * `onDone`, if given, fires exactly once at every exit point (success,
+ * failure, or "already refreshing"). Every existing caller omits it and stays
+ * fire-and-forget — the ONE caller that wants to know when the fill finished
+ * is the boot warm-up (see `warmTasksAsync`), which logs how long it took.
  */
-function bdRefreshAsync(cwd) {
-  if (refreshing.has(cwd)) return;
+function bdRefreshAsync(cwd, onDone = () => {}) {
+  if (refreshing.has(cwd)) { onDone({ ok: false, skipped: true }); return; }
   refreshing.add(cwd);
-  lastBdRunAt.set(cwd, Date.now());
+  const startedAt = Date.now();
+  lastBdRunAt.set(cwd, startedAt);
   let out = '';
   try {
     const child = spawn(BD_BIN, ['list', '--json', '--all', '--include-gates'], { cwd, env: bdEnv() });
@@ -304,31 +318,87 @@ function bdRefreshAsync(cwd) {
     child.on('error', (e) => {
       refreshing.delete(cwd);
       bdFailures.set(cwd, `bd could not be run: ${e?.message || e}`.slice(0, 300));
+      onDone({ ok: false });
     });
     child.on('close', (code) => {
       refreshing.delete(cwd);
       lastBdRunAt.set(cwd, Date.now());
-      if (code !== 0) { bdFailures.set(cwd, `bd exited ${code}`); return; }
+      if (code !== 0) { bdFailures.set(cwd, `bd exited ${code}`); onDone({ ok: false }); 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));
+          onDone({ ok: false });
+          return;
+        }
+        // This fetch answers "what was true at `startedAt`?" — if anyone has
+        // since told the cache it's wrong (a write's invalidate/stale-mark)
+        // or already written something newer (a synchronous cold read that
+        // raced us and won), our answer is superseded. Committing it now
+        // would silently resurrect data from before a change a caller is
+        // already waiting to see reflected — exactly what made
+        // `tests/pipeline-e2e.test.mjs`'s gate-approval assertions flake once
+        // this function started running from a COLD cache (the boot warm-up)
+        // instead of only ever refreshing an already-populated one.
+        const supersededByInvalidation = (lastInvalidatedAt.get(cwd) || 0) >= startedAt;
+        const supersededByFresherEntry = (bdCache.get(cwd)?.ts || 0) >= startedAt;
+        if (supersededByInvalidation || supersededByFresherEntry) {
+          onDone({ ok: true, count: parsed.length, discarded: true });
           return;
         }
         bdFailures.delete(cwd);
         bdCache.set(cwd, { ts: Date.now(), data: parsed });
+        onDone({ ok: true, count: parsed.length });
       } catch (e) {
         bdFailures.set(cwd, `bd output could not be parsed: ${e?.message || e}`.slice(0, 300));
+        onDone({ ok: false });
       }
     });
   } catch (e) {
     refreshing.delete(cwd);
     bdFailures.set(cwd, `bd could not be spawned: ${e?.message || e}`.slice(0, 300));
+    onDone({ ok: false });
   }
 }
 
+/**
+ * Warm a directory's task cache at boot, WITHOUT blocking the event loop.
+ *
+ * The boot warm-up used to call `getTasks(cwd)` directly — `bdList()`'s
+ * COLD-cache path, which is `bd()`'s synchronous `spawnSync`, because a cold
+ * cache has nothing to serve while a background refresh runs, so it has
+ * always been the one path in this file that blocks. That's the right call
+ * for a REQUEST (something is waiting and there's no stale data to fall back
+ * on); it was the wrong call at boot, because a boot warm-up has nobody
+ * waiting on it — its only job is to be ready before someone asks.
+ *
+ * Measured with an artificially slow `bd` (GREAT_CTO_BD_BIN pointed at a
+ * fixture that sleeps N seconds before answering): the board bound its port,
+ * then answered `000` on EVERY endpoint — including /api/version, a plain
+ * readdirSync with nothing to do with bd — for the fixture's entire delay.
+ * The port being open did not matter; the single process serving it was
+ * blocked inside `spawnSync` the whole time. `bd()`'s own 8s spawnSync
+ * timeout capped that run at ~8s; a real cold Dolt store or lock contention
+ * has no such cap, which is consistent with the up-to-2-minute stalls
+ * reported in production.
+ *
+ * This calls `bdRefreshAsync` — the SAME `spawn`-based, non-blocking path
+ * already used for warm-cache "stale-while-revalidate" reads — for the cold
+ * boot case too. The returned Promise exists only so the boot log can report
+ * how long the fill took; nothing waits on it, and the server is accepting
+ * and answering connections for the entire duration either way.
+ *
+ * @returns {Promise<{ok: boolean, count?: number, skipped?: boolean, ms: number}>}
+ */
+function warmTasksAsync(cwd) {
+  const t0 = Date.now();
+  return new Promise((resolve) => {
+    bdRefreshAsync(cwd, (result) => resolve({ ...result, ms: Date.now() - t0 }));
+  });
+}
+
 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);
@@ -338,14 +408,7 @@ function bdList(cwd = process.cwd(), runner = bd, opts = {}) {
   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.
+  // old, and refreshed off the event loop.
   //
   // 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
@@ -354,6 +417,32 @@ function bdList(cwd = process.cwd(), runner = bd, opts = {}) {
     bdRefreshAsync(cwd);
     return cached.data;
   }
+
+  // A directory with NO entry at all — genuinely never read. Left
+  // synchronous for an ordinary caller: a request FOR this project is
+  // waiting on the answer, and returning `[]` while a background fill
+  // catches up would be wrong data handed to a caller who cannot tell it
+  // apart from "no tasks" — confirmed the hard way. This branch originally
+  // covered every caller, and tests/board-gate.test.mjs,
+  // tests/pipeline-e2e.test.mjs and tests/resume-e2e.test.mjs all went red:
+  // a gate approved seconds after project creation read back as "no gates",
+  // because the read that should have shown it took the async path and
+  // answered empty instead.
+  //
+  // `opts.sweep` is the one caller allowed to skip the wait: the alert cron,
+  // which already has its own looser freshness contract (SWEEP_MAX_AGE_MS)
+  // and iterates EVERY registered project on a timer nobody is blocking on.
+  // Measured live, unprompted: a real board's first cron tick (t=+5:10, no
+  // request in flight) lagged the event loop 9.8s doing exactly this
+  // synchronous cold read, once per registered project, every five minutes,
+  // indefinitely. For that caller specifically, the same non-blocking fill
+  // stale-while-revalidate already uses for a WARM entry is safe on a COLD
+  // one too — the cron does not need this tick's answer to be correct, only
+  // bounded in staleness, which the background fill still gives it.
+  if (!cached && runner === bd && opts.sweep) {
+    bdRefreshAsync(cwd);
+    return [];
+  }
   try {
     lastBdRunAt.set(cwd, Date.now());
     const result = runner(['list', '--json', '--all', '--include-gates'], { cwd });
@@ -743,6 +832,7 @@ export {
   checkBeadsAvailable,
   bdWriteSerialised,
   bdList,
+  warmTasksAsync,
   bdFailureFor,
   parseTasksMd,
   getReadDegradation,

package/board/packages/board/lib/data-readers.mjs

@@ -114,8 +114,21 @@ function getPipeline(cwd = process.cwd()) {
   // signature. Surface that checkpoint AS A STAGE in the pipeline, sitting just
   // before the irreversible steps (devops/ship). It lights up when a gate is
   // awaiting a human — so the operator always sees where the rails are.
+  // Awaiting a signature and blocked are not the same thing, and this said they
+  // were. `getInbox`'s pendingGates excludes blocked gates — deliberately, and
+  // under test: in a tasks.md project a gate marked `blocked` carried raw_status
+  // 'open' and never left the inbox. This filter excluded only done/closed, so
+  // the same gate the tile reported as 0 PENDING DECISIONS was announced here as
+  // 1 GATE AWAITING SIGNATURE. Two counts of one concept, on one screen,
+  // disagreeing over a single word.
+  //
+  // Dropping it from the rail would have been the other wrong answer: a gate
+  // stuck for 29 days is exactly what the rail exists to show. It is still
+  // shown, and now it is named for what it is.
   const openGates = tasks.filter(t => t.is_gate && t.status !== 'done' && t.status !== 'closed' && t.raw_status !== 'closed');
-  const pending = openGates.length;
+  const blockedGates = openGates.filter(t => t.raw_status === 'blocked' || t.status === 'blocked');
+  const awaitingGates = openGates.filter(t => !blockedGates.includes(t));
+  const pending = awaitingGates.length;
   const newestGate = openGates.reduce((acc, t) => {
     const ts = t.updated_at || t.created_at; return (!acc || (ts && ts > acc)) ? ts : acc;
   }, null);
@@ -123,11 +136,15 @@ function getPipeline(cwd = process.cwd()) {
   const gateNode = {
     stage: 'human-gate',
     is_human_gate: true,
-    status: pending > 0 ? 'active' : 'idle',
+    // Blocked is not active: an active stage is one somebody can act on now.
+    status: pending > 0 ? 'active' : (blockedGates.length ? 'blocked' : 'idle'),
     pending,
+    blocked: blockedGates.length,
     last_message: pending > 0
       ? `${pending} gate${pending > 1 ? 's' : ''} awaiting signature`
-      : 'no gate pending',
+      : (blockedGates.length
+          ? `${blockedGates.length} gate${blockedGates.length > 1 ? 's' : ''} blocked`
+          : 'no gate pending'),
     verdict: null,
     ts: newestGate,
     age_min: gateAgeMs != null ? Math.round(gateAgeMs / 60000) : null,

package/board/packages/board/lib/docs.mjs

@@ -182,7 +182,7 @@ function walk(dir, root, out, depth = 0) {
  *   8. a bare README              a name that describes nothing else
  *
  * The leading filename token outranks the directory, and that ordering was
- * bought: 14 `docs/architecture/ADR-0NN-*.md` files were being filed as
+ * bought: 14 `docs/adr/ADR-0NN-*.md` files were being filed as
  * Architecture, and `docs/design/PLAN-*.md` as Design. A directory is where a
  * project dumps a category; the front of a filename is what the author called
  * THIS document. Mid-name tokens rank below the directory instead, because