great-cto 3.61.0 → 3.62.1

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

@@ -1,7 +1,7 @@
 {
   "name": "great-cto",
   "description": "You already have the agent. This is everything around it. great_cto runs Claude Code as a pipeline of 72 specialist agents \u2014 an independent model checks each stage before the next builds on it, spending caps refuse rather than warn, and three decisions stay yours: what gets built, how, and whether it ships.",
-  "version": "3.61.0",
+  "version": "3.62.1",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"
@@ -141,6 +141,17 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 5,
+            "command": "_gd=\"$PWD\"; while [ -n \"$_gd\" ] && { [ \"$_gd\" = \"$HOME\" ] || [ ! -f \"$_gd/.great_cto/PROJECT.md\" ]; }; do _gd=\"${_gd%/*}\"; done; [ -n \"$_gd\" ] && cd \"$_gd\"; [ -n \"$GREAT_CTO_AGENT_BUDGET_FILE\" ] || exit 0; node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/agent-execution-budget.mjs\" pre; _budget_exit=$?; if [ $_budget_exit -ne 0 ]; then exit 2; fi",
+            "statusMessage": "Checking shared agent execution budget..."
+          }
+        ]
+      },
       {
         "matcher": "Bash",
         "hooks": [
@@ -195,6 +206,17 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "timeout": 5,
+            "command": "_gd=\"$PWD\"; while [ -n \"$_gd\" ] && { [ \"$_gd\" = \"$HOME\" ] || [ ! -f \"$_gd/.great_cto/PROJECT.md\" ]; }; do _gd=\"${_gd%/*}\"; done; [ -n \"$_gd\" ] && cd \"$_gd\"; [ -n \"$GREAT_CTO_AGENT_BUDGET_FILE\" ] || exit 0; node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/agent-execution-budget.mjs\" post; _budget_exit=$?; if [ $_budget_exit -ne 0 ]; then exit 2; fi",
+            "statusMessage": "Releasing completed foreground agent budget lease..."
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit|MultiEdit",
         "hooks": [

package/board/packages/board/fixtures/beads-read-owner.mjs

@@ -0,0 +1,3 @@
+// Fixed test-only parent, killed after the child-start handshake.
+import { getTasksAsync } from '../lib/beads.mjs';
+await getTasksAsync(process.cwd());

package/board/packages/board/fixtures/fake-bd-controlled.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Fixed local test protocol. No shell commands or operator stores.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+const root = process.env.FAKE_BD_CONTROL_ROOT;
+if (!root || !path.isAbsolute(root)) process.exit(2);
+const key = path.basename(process.cwd());
+const marker = name => path.join(root, `${key}.${name}`);
+if (process.argv.includes('--descendant')) {
+  process.on('SIGTERM', () => {});
+  fs.writeFileSync(marker('descendant'), String(process.pid));
+  setInterval(() => {}, 1000);
+} else {
+  fs.appendFileSync(marker('started'), `${process.pid}\n`);
+  fs.writeFileSync(marker('worker'), String(process.ppid));
+  if (process.env.FAKE_BD_CONTROL_MODE === 'fail') {
+    process.exit(1);
+  } else if (['hang', 'leader-exit'].includes(process.env.FAKE_BD_CONTROL_MODE)) {
+    process.on('SIGTERM', () => {});
+    spawn(process.execPath, [new URL(import.meta.url).pathname, '--descendant'], { stdio: 'inherit' });
+    if (process.env.FAKE_BD_CONTROL_MODE === 'leader-exit') {
+      setInterval(() => { if (fs.existsSync(marker('descendant'))) process.exit(0); }, 25);
+    }
+    setInterval(() => {}, 1000);
+  } else if (process.env.FAKE_BD_CONTROL_MODE === 'large-success') {
+    process.stdout.write(JSON.stringify([{ id: 'FIXTURE-1', title: 'x'.repeat(131072), status: 'open', priority: 0 }]), () => {
+      fs.writeFileSync(marker('output-written'), 'ready');process.exit(0);
+    });
+  } else if (['closed-success', 'closed-fail'].includes(process.env.FAKE_BD_CONTROL_MODE)) {
+    const descendant = spawn(process.execPath, [new URL(import.meta.url).pathname, '--descendant'], { stdio: 'ignore' });
+    descendant.unref();
+    const ready = setInterval(() => {
+      if (!fs.existsSync(marker('descendant'))) return;
+      clearInterval(ready);
+      process.stdout.write(JSON.stringify([{ id: 'FIXTURE-1', title: 'Fixture task', status: 'open', priority: 0 }]),
+        () => process.exit(process.env.FAKE_BD_CONTROL_MODE === 'closed-fail' ? 1 : 0));
+    }, 25);
+  } else if (process.env.FAKE_BD_CONTROL_MODE === 'oversize') {
+    process.stdout.write(Buffer.alloc(16 * 1024 * 1024 + 1, 120));
+    setInterval(() => {}, 1000);
+  } else {
+    const timer = setInterval(() => {
+      if (!fs.existsSync(marker('release'))) return;
+      clearInterval(timer);
+      process.stdout.write(JSON.stringify([{ id: 'FIXTURE-1', title: 'Fixture task', status: 'open', priority: 0 }]));
+    }, 25);
+  }
+}

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

@@ -27,7 +27,7 @@ import { getCostHistory, getInbox } from './data-readers.mjs';
 // 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';
+import { getTasks, getTasksAsync, getReadDegradation, SWEEP_MAX_AGE_MS } from './beads.mjs';
 const SWEEP = { maxAgeMs: SWEEP_MAX_AGE_MS, sweep: true };
 import { readVerdicts } from './verdicts.mjs';
 import { isFailure } from './fleet.mjs';
@@ -303,11 +303,16 @@ function startAlertCron() {
   }, FIVE_MIN);
 
   // cost.threshold: monthly LLM spend at 80% / 100% of budget
-  setInterval(() => {
+  setInterval(async () => {
     try {
       const projects = listProjects();
       for (const proj of projects) {
-        const m = getMetrics(proj.path);
+        let tasks;
+        try {
+          tasks = await getTasksAsync(proj.path);
+          if (getReadDegradation(proj.path)) continue;
+        } catch { continue; } // Unknown spend must not be treated as zero.
+        const m = getMetrics(proj.path, 30, { tasks });
         const meta = readProjectMd(proj.path) || {};
         const budget = parseFloat(meta['monthly-budget']?.replace?.(/[$\s]/g, '') || '0');
         if (!budget) continue;
@@ -356,7 +361,12 @@ function startAlertCron() {
       // next project reads alerts-fired.json. Prevents the race condition where
       // all N projects read an empty map simultaneously and all fire.
       for (const proj of projects) {
-        const m = getMetrics(proj.path);
+        let tasks;
+        try {
+          tasks = await getTasksAsync(proj.path);
+          if (getReadDegradation(proj.path)) continue;
+        } catch { continue; } // Unknown is not a zero-activity weekly report.
+        const m = getMetrics(proj.path, 30, { tasks });
         const dedupeKey = `digest.weekly:${proj.slug}:${isoWeek}`;
         const weeklyPayload = {
           title: `${proj.slug} weekly — ${m.tasks?.done || 0} shipped, $${(m.cost?.llm_usd || 0).toFixed(2)} spent`,
@@ -395,18 +405,22 @@ function startAlertCron() {
       const projects = listProjects();
       for (const proj of projects) {
         const dedupeKey = `digest.daily:${proj.slug}:${isoDay}`;
+        let tasks;
+        try {
+          tasks = await getTasksAsync(proj.path);
+          if (getReadDegradation(proj.path)) continue;
+        } catch { continue; } // Do not send or record a fabricated quiet day.
         // Pull last 2 days so "yesterday" is always in the window
-        const cost = getCostHistory(proj.path, 2);
+        const cost = getCostHistory(proj.path, 2, { tasks });
         const yBucket = (cost.series || []).find(s => s.date === yesterday);
         const ySpend = yBucket ? yBucket.llm : 0;
         // Feature breakdown for yesterday
         const topFeatures = (cost.by_feature || []).slice(0, 3);
         // Inbox for blocked + gates
-        const inbox = (() => { try { return getInbox(proj.path); } catch { return {}; } })();
+        const inbox = getInbox(proj.path, { tasks });
         const blocked = inbox.summary?.blocked ?? 0;
         const gates = inbox.summary?.gates ?? 0;
         // Tasks closed yesterday
-        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/bd-read-worker.mjs

@@ -0,0 +1,64 @@
+// A read's process-group lifetime must not depend on the HTTP event loop.
+// Forked into a newly owned group; ordinary module imports do not start work.
+import { fork, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const entry = fileURLToPath(import.meta.url);
+export function spawnBdRead(binary, { readDeadlineMs = 20250, ...options }) {
+  return fork(entry, [binary, String(readDeadlineMs)], { ...options, silent: true });
+}
+if (process.argv[1] === entry) {
+  const grouped = process.platform !== 'win32';
+  let child;
+  function killOwnedGroup() {
+    // POSIX fork is detached: the worker PID is exclusively this read's PGID.
+    if (grouped) {
+      try { process.kill(-process.pid, 'SIGKILL'); } catch { process.exit(1); }
+    } else {
+      try { child?.kill('SIGKILL'); } catch { /* already gone */ }
+      process.exit(1);
+    }
+  }
+  process.on('disconnect', killOwnedGroup);
+  process.on('SIGTERM', () => {}); // keep the independent KILL deadline alive
+  process.stdout.on('error', killOwnedGroup);
+  process.stderr.on('error', killOwnedGroup);
+  // Independent upper bound even if the parent's event loop is stalled.
+  const budget = Number(process.argv[3]);
+  if (!Number.isFinite(budget) || budget < 1 || budget > 20250) process.exit(2);
+  setTimeout(killOwnedGroup, budget);
+  let completing = false;
+  function complete(code) {
+    if (completing) return;
+    completing = true;
+    // A successful leader can leave descendants with closed/ignored pipes.
+    // Flush the result over IPC before killing the whole owned group. Keep
+    // the independent deadline alive until cleanup, even if IPC stalls.
+    if (!process.connected) return killOwnedGroup();
+    // child 'close' means its pipes ended, not that this worker's output
+    // queues reached the parent. Flush before announcing success or KILL
+    // can truncate an otherwise valid snapshot under pipe backpressure.
+    try { process.stdout.write('', stdoutError => {
+      if (stdoutError) return killOwnedGroup();
+      process.stderr.write('', stderrError => {
+        if (stderrError || !process.connected) return killOwnedGroup();
+        try { process.send({ type: 'bd-read-result', code }, () => killOwnedGroup()); }
+        catch { killOwnedGroup(); }
+      });
+    }); }
+    catch { killOwnedGroup(); }
+  }
+  try {
+    child = spawn(process.argv[2], ['list', '--json', '--all', '--include-gates'], {
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    child.stdout.pipe(process.stdout, { end: false });
+    child.stderr.pipe(process.stderr, { end: false });
+    child.on('error', () => complete(1));
+    child.on('close', code => {
+      // No background descendants are part of a completed read contract.
+      // Wait for inherited pipes too: exiting on leader 'exit' would remove
+      // the IPC watchdog while a descendant was still holding those pipes.
+      complete(Number.isInteger(code) ? code : 1);
+    });
+  } catch { complete(1); }
+}

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

@@ -5,6 +5,7 @@ import { spawnSync, spawn } from 'child_process';
 import { readSafe } from './util.mjs';
 import { bdCache } from './state.mjs';
 import { log } from './log.mjs';
+import { spawnBdRead } from './bd-read-worker.mjs';
 
 // ── Beads data ─────────────────────────────────────────────────────────────────
 // Cache bdList output per cwd for BD_CACHE_TTL_MS. Invalidated when the project's
@@ -39,13 +40,11 @@ import { log } from './log.mjs';
 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.
+ * Per-project invalidation generation. A background fetch may publish only
+ * when its generation is still current. Wall-clock timestamps cannot order
+ * an invalidate followed by a read within the same millisecond.
  */
-const lastInvalidatedAt = new Map();
+const invalidationGeneration = new Map();
 
 /**
  * Drop a directory's entry so the next read is guaranteed fresh.
@@ -56,7 +55,7 @@ const lastInvalidatedAt = new Map();
  */
 function bdCacheInvalidate(cwd) {
   clearSelfTouch(cwd);
-  lastInvalidatedAt.set(cwd, Date.now());
+  invalidationGeneration.set(cwd, (invalidationGeneration.get(cwd) || 0) + 1);
   bdCache.delete(cwd);
 }
 
@@ -73,7 +72,7 @@ function bdCacheInvalidate(cwd) {
  */
 function bdCacheStale(cwd) {
   clearSelfTouch(cwd);
-  lastInvalidatedAt.set(cwd, Date.now());
+  invalidationGeneration.set(cwd, (invalidationGeneration.get(cwd) || 0) + 1);
   const cached = bdCache.get(cwd);
   if (cached) bdCache.set(cwd, { ...cached, ts: 0 });
 }
@@ -297,6 +296,17 @@ const EMPTY_TTL_MS = Number(process.env.GREAT_CTO_BD_EMPTY_TTL_MS || 5000);
  * Without this, ten requests arriving while one refresh runs start ten more.
  */
 const refreshing = new Set();
+const refreshWaiters = new Map();
+const refreshQueue = [];
+let activeReads = 0;
+const READ_TIMEOUT_MS = 20000;
+const READ_MAX_BYTES = 16 * 1024 * 1024;
+function drainRefreshQueue() {
+  while (activeReads < 4 && refreshQueue.length) {
+    activeReads++;
+    refreshQueue.shift()();
+  }
+}
 
 /**
  * Refresh a directory's entry WITHOUT holding the event loop.
@@ -304,44 +314,108 @@ const refreshing = new Set();
  * `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.
+ * moved the first stall out of sight; HTTP cold reads now await this path.
+ * Direct synchronous write broadcasts and background readers remain separate.
  *
- * `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.
+ * `onDone`, if given, fires exactly once when the shared read finishes. A
+ * concurrent reader joins it rather than receiving a premature "skipped".
+ * Background callers omit it and stay fire-and-forget. Boot warm-up and
+ * interactive cold reads join the same completion through `warmTasksAsync`.
  */
-function bdRefreshAsync(cwd, onDone = () => {}) {
-  if (refreshing.has(cwd)) { onDone({ ok: false, skipped: true }); return; }
+function bdRefreshAsync(cwd, onDone = null) {
+  if (refreshing.has(cwd)) { if (onDone) refreshWaiters.get(cwd).push(onDone); return; }
   refreshing.add(cwd);
+  refreshWaiters.set(cwd, onDone ? [onDone] : []);
+  const due = performance.now() + READ_TIMEOUT_MS;
+  const run = () => {
+    clearTimeout(queuedDeadline);
+    startRefresh(cwd, Math.max(1, due - performance.now()));
+  };
+  const queuedDeadline = setTimeout(() => {
+    const index = refreshQueue.indexOf(run);
+    if (index < 0) return;
+    refreshQueue.splice(index, 1);
+    refreshing.delete(cwd);
+    bdFailures.set(cwd, 'bd read timed out waiting for a slot');
+    const waiters = refreshWaiters.get(cwd) || [];
+    refreshWaiters.delete(cwd);
+    for (const done of waiters) done({ ok: false });
+  }, READ_TIMEOUT_MS);
+  refreshQueue.push(run);
+  drainRefreshQueue();
+}
+
+function startRefresh(cwd, remainingMs) {
   const startedAt = Date.now();
+  const generation = invalidationGeneration.get(cwd) || 0;
   lastBdRunAt.set(cwd, startedAt);
-  let out = '';
+  let out = '', outBytes = 0;
+  let child, deadline, killDeadline, finished = false, workerResult;
+  const grouped = process.platform !== 'win32';
+  function signalOwned(signal) {
+    if (!child?.pid) return;
+    try { if (grouped) process.kill(-child.pid, signal); else child.kill(signal); } catch { /* already exited */ }
+  }
+  function finish(result) {
+    if (finished) return;
+    finished = true;
+    clearTimeout(deadline); clearTimeout(killDeadline);
+    refreshing.delete(cwd);
+    const waiters = refreshWaiters.get(cwd) || [];
+    refreshWaiters.delete(cwd);
+    activeReads--;
+    for (const done of waiters) done(result);
+    drainRefreshQueue();
+  }
+  function stop(reason) {
+    if (finished || killDeadline) return;
+    bdFailures.set(cwd, reason);
+    signalOwned('SIGTERM');
+    // TERM alone can leave a read and inherited pipes alive indefinitely.
+    killDeadline = setTimeout(() => {
+      signalOwned('SIGKILL');
+      child.stdout?.destroy(); child.stderr?.destroy();
+      finish({ ok: false });
+    }, 250);
+  }
   try {
-    // Bounded like every other bd call. Without a timeout a hung bd never fires
-    // 'close', so `refreshing` stays held for this cwd forever and the cache
-    // silently serves stale tasks with no error anywhere — the async twin of the
-    // sync path's 500s. Node kills on timeout, which DOES fire 'close' with a
-    // non-zero code, so the failure handling below reports it rather than the
-    // board simply going quiet.
-    const child = spawn(BD_BIN, ['list', '--json', '--all', '--include-gates'], { cwd, env: bdEnv(), timeout: 20000 });
-    child.stdout?.on('data', (d) => { out += d; });
+    // At most four reads run concurrently. The fixed deadline escalates TERM
+    // to KILL for this newly owned process group; Node's TERM-only timeout did
+    // not release the slot when a child ignored it or inherited pipes stayed open.
+    child = spawnBdRead(BD_BIN, { cwd, env: bdEnv(), detached: grouped, readDeadlineMs: Math.ceil(remainingMs) + 250 });
+    child.on('message', message => {
+      if (message?.type === 'bd-read-result' && Number.isInteger(message.code)) workerResult = message.code;
+    });
+    deadline = setTimeout(() => stop('bd read timed out'), remainingMs);
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', (d) => {
+      if (finished || killDeadline) return;
+      outBytes += Buffer.byteLength(d);
+      if (outBytes > READ_MAX_BYTES) { stop('bd output exceeded limit'); return; }
+      out += d;
+    });
+    // Drain stderr without retaining arbitrary private subprocess output.
+    child.stderr?.resume();
     child.on('error', (e) => {
-      refreshing.delete(cwd);
       bdFailures.set(cwd, `bd could not be run: ${e?.message || e}`.slice(0, 300));
-      onDone({ ok: false });
+      finish({ ok: false });
     });
     child.on('close', (code) => {
-      refreshing.delete(cwd);
+      if (finished) return;
+      if (killDeadline) { signalOwned('SIGKILL'); finish({ ok: false }); return; }
+      // The worker reports its leader result, then terminates its entire
+      // owned group, including itself. A bare signal without that result
+      // remains a failed read, never a fabricated successful empty list.
+      code = workerResult ?? code;
       lastBdRunAt.set(cwd, Date.now());
-      if (code !== 0) { bdFailures.set(cwd, `bd exited ${code}`); onDone({ ok: false }); return; }
+      if (code !== 0) { bdFailures.set(cwd, `bd exited ${code}`); finish({ 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 });
+          finish({ ok: false });
           return;
         }
         // This fetch answers "what was true at `startedAt`?" — if anyone has
@@ -353,24 +427,23 @@ function bdRefreshAsync(cwd, onDone = () => {}) {
         // `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 supersededByInvalidation = (invalidationGeneration.get(cwd) || 0) !== generation;
         const supersededByFresherEntry = (bdCache.get(cwd)?.ts || 0) >= startedAt;
         if (supersededByInvalidation || supersededByFresherEntry) {
-          onDone({ ok: true, count: parsed.length, discarded: true });
+          finish({ 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 });
+        finish({ 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 });
+        finish({ ok: false });
       }
     });
   } catch (e) {
-    refreshing.delete(cwd);
     bdFailures.set(cwd, `bd could not be spawned: ${e?.message || e}`.slice(0, 300));
-    onDone({ ok: false });
+    finish({ ok: false });
   }
 }
 
@@ -410,6 +483,34 @@ function warmTasksAsync(cwd) {
   });
 }
 
+/** Wait for an actual cold snapshot without blocking Node or inventing []. */
+async function getTasksAsync(cwd = process.cwd()) {
+  if (!bdCache.has(cwd)) {
+    const result = await warmTasksAsync(cwd);
+    if (!bdCache.has(cwd)) {
+      // tasks.md-only projects remain supported, but never hide a failed
+      // initialized Beads store or a snapshot invalidated during this read.
+      if (!result.ok && checkBeadsAvailable(cwd)) {
+        bdCache.set(cwd, { ts: Date.now(), data: [] });
+        return getTasks(cwd);
+      }
+      throw new Error(bdFailureFor(cwd) || 'Task snapshot changed while being read; retry');
+    }
+  }
+  return getTasks(cwd);
+}
+
+/** Other-project badges may be incomplete, but must never block HTTP. */
+function getTasksCached(cwd = process.cwd()) {
+  if (!bdCache.has(cwd)) {
+    bdRefreshAsync(cwd);
+    throw new Error('Task snapshot is loading');
+  }
+  const tasks = getTasks(cwd);
+  if (getReadDegradation(cwd)) throw new Error('Task snapshot is unavailable');
+  return tasks;
+}
+
 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);
@@ -864,6 +965,8 @@ export {
   getReadDegradation,
   setTaskStatusInTasksMd,
   getTasks,
+  getTasksAsync,
+  getTasksCached,
   mapStatus,
   detectAgent,
 };

package/board/packages/board/lib/config.mjs

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import os from 'os';
+import { stateHome } from '../../cli/src/state-home.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // `--port N` (or `--port=N`) first — server.mjs's usage line documents it, and
@@ -28,17 +28,24 @@ const HOST = (() => {
   const i = process.argv.indexOf('--host');
   return String(i > -1 ? process.argv[i + 1] : process.env.GREAT_CTO_HOST || '127.0.0.1');
 })();
-const GREAT_CTO_DIR = path.join(os.homedir(), '.great_cto');
+// Shared dedicated namespace with the CLI; unset/empty keeps the operator default.
+const GREAT_CTO_DIR = stateHome();
 const SHARE_STATE_FILE = path.join(GREAT_CTO_DIR, 'board-share.json');
 // Test seam: honor an explicit override so tests can point the registry at a
 // tmp fixture without touching the real ~/.great_cto/projects.json (same
 // convention as GREAT_CTO_BD_BIN in lib/beads.mjs). Unset in production —
 // zero behavior change at runtime.
-const PROJECTS_FILE = process.env.GREAT_CTO_PROJECTS_FILE || path.join(GREAT_CTO_DIR, 'projects.json');
+function stateFileOverride(name, fallback) {
+  const value = process.env[name];
+  if (!value) return path.join(GREAT_CTO_DIR, fallback);
+  if (!path.isAbsolute(value) || value.includes('\0')) throw new Error(`${name} must be absolute and contain no NUL`);
+  return path.resolve(value);
+}
+const PROJECTS_FILE = stateFileOverride('GREAT_CTO_PROJECTS_FILE', 'projects.json');
 const SHARE_ENDPOINT = 'https://greatcto.systems/r/';
 const VAPID_KEYS_FILE = path.join(GREAT_CTO_DIR, 'vapid-keys.json');
 const PUSH_SUBS_FILE = path.join(GREAT_CTO_DIR, 'push-subscriptions.json');
-const NOTIF_HISTORY_FILE = process.env.GREAT_CTO_NOTIF_HISTORY_FILE || path.join(GREAT_CTO_DIR, 'notif-history.json');
+const NOTIF_HISTORY_FILE = stateFileOverride('GREAT_CTO_NOTIF_HISTORY_FILE', 'notif-history.json');
 const VAPID_SUBJECT = 'mailto:hi@updates.greatcto.systems';
 
 export {

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

@@ -1,10 +1,9 @@
 import { reversibilityOf } from '../../../scripts/lib/gate-reversibility.mjs';
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { GREAT_CTO_DIR } from './config.mjs';
 import { readFileSafe } from './util.mjs';
-import { getTasks } from './beads.mjs';
+import { getTasks, getTasksAsync, getTasksCached } from './beads.mjs';
 import { readVerdicts, readSecStats } from './verdicts.mjs';
 import { datePlans } from './plan-date.mjs';
 
@@ -21,7 +20,6 @@ function gateNameOf(task) {
 }
 
 function getMemory(cwd = process.cwd()) {
-  const home = os.homedir();
   const layers = [
     // Project-local (.great_cto/) — L1 archetype + L2 codebase + L3 retros
     { id: 'project',     scope: 'project', layer: 'L1', name: 'PROJECT.md',    desc: 'Archetype, size, compliance, owners',           path: path.join(cwd, '.great_cto', 'PROJECT.md') },
@@ -33,9 +31,9 @@ function getMemory(cwd = process.cwd()) {
     { id: 'handoff',     scope: 'project', layer: 'L3', name: 'HANDOFF.md',    desc: 'Auto-written on context compaction',            path: path.join(cwd, '.great_cto', 'HANDOFF.md') },
     { id: 'local',       scope: 'project', layer: 'L3', name: 'local.md',      desc: 'Project-local notes (gitignored)',              path: path.join(cwd, '.great_cto', 'local.md') },
     // Cross-project (~/.great_cto/) — L4 global memory shared across all projects
-    { id: 'g-decisions', scope: 'global',  layer: 'L4', name: 'decisions.md',  desc: 'Append-only ADR log — every gate approval',     path: path.join(home, '.great_cto', 'decisions.md') },
-    { id: 'g-prefs',     scope: 'global',  layer: 'L4', name: 'preferences.md',desc: 'User-level CTO preferences (style, defaults)',  path: path.join(home, '.great_cto', 'preferences.md') },
-    { id: 'g-lessons',   scope: 'global',  layer: 'L4', name: 'lessons.md',    desc: 'Cross-project lessons promoted from L3',        path: path.join(home, '.great_cto', 'lessons.md') },
+    { id: 'g-decisions', scope: 'global',  layer: 'L4', name: 'decisions.md',  desc: 'Append-only ADR log — every gate approval',     path: path.join(GREAT_CTO_DIR, 'decisions.md') },
+    { id: 'g-prefs',     scope: 'global',  layer: 'L4', name: 'preferences.md',desc: 'User-level CTO preferences (style, defaults)',  path: path.join(GREAT_CTO_DIR, 'preferences.md') },
+    { id: 'g-lessons',   scope: 'global',  layer: 'L4', name: 'lessons.md',    desc: 'Cross-project lessons promoted from L3',        path: path.join(GREAT_CTO_DIR, 'lessons.md') },
   ];
   const result = layers.map(l => ({
     ...l,
@@ -45,7 +43,7 @@ function getMemory(cwd = process.cwd()) {
     // is photographed. The layer already knows its scope, so the display form is
     // derived rather than guessed.
     displayPath: l.scope === 'global'
-      ? path.join('~', path.relative(home, l.path)).split(path.sep).join('/')
+      ? path.join(process.env.GREAT_CTO_HOME ? '$GREAT_CTO_HOME' : path.join('~', '.great_cto'), path.relative(GREAT_CTO_DIR, l.path)).split(path.sep).join('/')
       : path.relative(cwd, l.path).split(path.sep).join('/'),
     content: readFileSafe(l.path),
     exists: fs.existsSync(l.path),
@@ -75,7 +73,7 @@ function getMemory(cwd = process.cwd()) {
 }
 
 // ── Pipeline state ────────────────────────────────────────────────────────────
-function getPipeline(cwd = process.cwd()) {
+function getPipeline(cwd = process.cwd(), { tasks = getTasks(cwd) } = {}) {
   const stages = ['product-owner', 'architect', 'pm', 'senior-dev', 'reviewers', 'qa-engineer', 'security-officer', 'devops', 'l3-support'];
   const verdicts = readVerdicts(cwd);
   const now = Date.now();
@@ -89,7 +87,6 @@ function getPipeline(cwd = process.cwd()) {
   }
 
   // Tasks in_progress give us "active" agents
-  const tasks = getTasks(cwd);
   const activeAgents = new Set(
     tasks.filter(t => t.status === 'in_progress').map(t => (t.agent || '').toLowerCase()).filter(Boolean)
   );
@@ -181,7 +178,7 @@ function getPipeline(cwd = process.cwd()) {
 }
 
 // ── Cost history (daily LLM burn) ────────────────────────────────────────────
-function getCostHistory(cwd = process.cwd(), days = 30) {
+function getCostHistory(cwd = process.cwd(), days = 30, { tasks: suppliedTasks } = {}) {
   // Build a map<dateISO, { llm, human, plans, verdictCost }>.
   // Inclusive window: `days=30` means [today-30 ... today] = 31 buckets.
   // Previous behaviour (days buckets only) created a one-day gap on the
@@ -317,7 +314,7 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
   const LLM_RATE_PER_HR   = parseFloat(process.env.GREATCTO_LLM_RATE_PER_HR || '0.30');
   const DEFAULT_TASK_MIN  = 30;
   try {
-    const tasks = getTasks(cwd);
+    const tasks = suppliedTasks ?? getTasks(cwd);
     for (const t of tasks) {
       if (!t.closed_at) continue;
       if (!t.agent) continue;
@@ -403,8 +400,7 @@ function getCostHistory(cwd = process.cwd(), days = 30) {
 }
 
 // ── Inbox: what needs the user's decision right now ──────────────────────────
-function getInbox(cwd = process.cwd()) {
-  const tasks = getTasks(cwd);
+function getInbox(cwd = process.cwd(), { tasks = getTasks(cwd) } = {}) {
   // Use raw_status here: mapStatus() rewrites status to 'gate' for any task with the
   // 'gate' label, regardless of bd-native state. Filtering on the mapped value would
   // leave closed/blocked gates in the inbox forever.
@@ -504,7 +500,7 @@ function getInbox(cwd = process.cwd()) {
  * `readInbox` is injectable so the walk can be tested with stub projects
  * without a beads store behind each one.
  */
-function inboxElsewhere(projects, currentPath, { readInbox = getInbox } = {}) {
+function inboxElsewhere(projects, currentPath, { readInbox = getInboxCached } = {}) {
   const same = (a, b) => {
     if (!a || !b) return false;
     try { return fs.realpathSync(a) === fs.realpathSync(b); } catch { return path.resolve(a) === path.resolve(b); }
@@ -523,4 +519,6 @@ function inboxElsewhere(projects, currentPath, { readInbox = getInbox } = {}) {
   return out;
 }
 
-export { getMemory, getPipeline, getCostHistory, getInbox, inboxElsewhere };
+async function getInboxAsync(cwd) { return getInbox(cwd, { tasks: await getTasksAsync(cwd) }); }
+function getInboxCached(cwd) { return getInbox(cwd, { tasks: getTasksCached(cwd) }); }
+export { getMemory, getPipeline, getCostHistory, getInbox, getInboxAsync, getInboxCached, inboxElsewhere };

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

@@ -43,11 +43,10 @@ function acceptanceMetrics(verdicts = [], windowCostUsd = null) {
 }
 
 // ── Metrics ────────────────────────────────────────────────────────────────────
-function getMetrics(cwd = process.cwd(), days = 30) {
+function getMetrics(cwd = process.cwd(), days = 30, { tasks = getTasks(cwd) } = {}) {
   // `days` controls the window for cost/agents_cost and for "shipped in window".
   // Tasks shipped within the window are returned in `tasks.done_in_window`.
   // Full lifetime `tasks.done` is still returned for backwards compatibility.
-  const tasks = getTasks(cwd);
   // BH-28: resolved gates (approve→closed, reject→blocked) get mapped to
   // status='done' by mapStatus(). Those are governance decisions, not shipped
   // features — counting them inflates velocity / tasks-shipped on the report.