great-cto 2.77.0 → 2.77.1

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

@@ -0,0 +1,413 @@
+import fs from 'fs';
+import path from 'path';
+import {
+  getVapidKeys,
+  sendWebPush,
+  loadSubscriptions,
+  removeSubscription,
+} from '../push-adapter.mjs';
+import { GREAT_CTO_DIR, PUSH_SUBS_FILE, VAPID_KEYS_FILE, VAPID_SUBJECT } from './config.mjs';
+import { _reportRepublishDedupeSet } from './state.mjs';
+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';
+import { readVerdicts } from './verdicts.mjs';
+import { isFailure } from './fleet.mjs';
+import { getShareState, toggleShare } from './share.mjs';
+
+// ── Email alerts (Resend) ─────────────────────────────────────────────────
+// Dispatch model: read webhooks.json on every fire (idempotent if disabled
+// or no Resend hook configured). Each trigger has a dedupe key persisted to
+// ~/.great_cto/alerts-fired.json so we don't email the same event twice.
+
+const ALERTS_FIRED_PATH = path.join(GREAT_CTO_DIR, 'alerts-fired.json');
+
+function readAlertsFired() {
+  try { return JSON.parse(fs.readFileSync(ALERTS_FIRED_PATH, 'utf8')); } catch { return {}; }
+}
+
+function writeAlertsFired(map) {
+  try {
+    if (!fs.existsSync(GREAT_CTO_DIR)) fs.mkdirSync(GREAT_CTO_DIR, { recursive: true });
+    fs.writeFileSync(ALERTS_FIRED_PATH, JSON.stringify(map, null, 2));
+  } catch {/* best-effort */}
+}
+
+/**
+ * Fire an email alert through the greatcto.systems/notify relay (Cloudflare
+ * Worker → Resend). Idempotent per dedupeKey — same key won't email twice.
+ *
+ * Reads ~/.great_cto/notifications.json for the user's verified email + per-
+ * trigger enable flags. Silent no-op if not configured / not verified / event
+ * not in the user's selected triggers.
+ *
+ * @param {string} eventName   e.g. "incident.p0", "gate.stale"
+ * @param {string} dedupeKey   unique per event instance (e.g. "great_cto:GC-42")
+ * @param {object} payload     { title, body, level, project, link, action, kv }
+ */
+async function fireEmailAlert(eventName, dedupeKey, payload) {
+  try {
+    const stateFile = path.join(GREAT_CTO_DIR, 'notifications.json');
+    if (!fs.existsSync(stateFile)) return;
+    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    if (!state.enabled || !state.verified || !state.to) return;
+    if (!(state.triggers || []).includes(eventName)) return;
+
+    // Dedupe — never email the same instance twice
+    const fired = readAlertsFired();
+    if (fired[dedupeKey]) return;
+
+    // Mark fired optimistically BEFORE the async fetch so that concurrent
+    // calls for other projects (same cron tick) see this key immediately
+    // and don't fire duplicate sends. Also prevents infinite retry on relay
+    // errors — a failed send is still recorded so the next 5-min tick skips.
+    fired[dedupeKey] = new Date().toISOString();
+    const keys = Object.keys(fired);
+    if (keys.length > 500) {
+      const trimmed = {};
+      keys.slice(-500).forEach(k => trimmed[k] = fired[k]);
+      writeAlertsFired(trimmed);
+    } else {
+      writeAlertsFired(fired);
+    }
+
+    const relay = process.env.GREATCTO_NOTIFY_URL || 'https://greatcto.systems';
+    const res = await fetch(`${relay}/notify`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        to: state.to,
+        title: payload.title,
+        body: payload.body,
+        level: payload.level || 'info',
+        project: payload.project || 'great_cto',
+        link: payload.link,
+        action: payload.action,
+        kv: payload.kv || {},
+        event: eventName,
+      }),
+    });
+    if (!res.ok) {
+      const txt = await res.text().catch(() => '');
+      console.warn(`fireEmailAlert ${eventName}: relay HTTP ${res.status} ${txt.slice(0, 200)}`);
+      return;
+    }
+    console.log(`fireEmailAlert: sent ${eventName} (${dedupeKey})`);
+  } catch (e) {
+    console.warn(`fireEmailAlert ${eventName} failed:`, e.message);
+  }
+}
+
+/**
+ * Fire Web Push notifications to all registered browser subscriptions.
+ * Uses the same alerts-fired.json dedupe map as fireEmailAlert (keyed as
+ * "push:<dedupeKey>") so a single event never sends duplicate pushes.
+ * Expired subscriptions (HTTP 410) are removed automatically.
+ */
+async function firePushAlert(eventName, dedupeKey, payload) {
+  try {
+    const subs = loadSubscriptions(PUSH_SUBS_FILE);
+    if (!subs.length) return;
+    const vapidKeys = getVapidKeys(VAPID_KEYS_FILE);
+    const fired = readAlertsFired();
+    const pushKey = `push:${dedupeKey}`;
+    if (fired[pushKey]) return;
+    for (const sub of subs) {
+      try { await sendWebPush(sub, vapidKeys, VAPID_SUBJECT); }
+      catch (e) {
+        // 410 = subscription expired — browser unsubscribed, clean up
+        if (e.statusCode === 410) removeSubscription(PUSH_SUBS_FILE, sub.endpoint);
+        else console.warn(`firePushAlert send failed for ${sub.endpoint}:`, e.message);
+      }
+    }
+    fired[pushKey] = new Date().toISOString();
+    writeAlertsFired(fired);
+  } catch (e) { console.warn('firePushAlert failed:', e.message); }
+}
+
+// ── Cron: scan gates / cost / weekly digest ───────────────────────────────
+// Runs every 5 minutes once the server boots. Each check is idempotent
+// thanks to alerts-fired.json dedupe.
+function startAlertCron() {
+  const FIVE_MIN = 5 * 60 * 1000;
+  const ONE_HOUR = 60 * 60 * 1000;
+
+  // incident.p0: open P0 task with recent activity (last 24h).
+  // Older P0s are existing backlog — surfacing them via email is spam.
+  // If you want to be reminded about stale P0s, that's gate.stale's job.
+  const RECENT_WINDOW_MS = 24 * 3600_000;
+  setInterval(() => {
+    try {
+      const projects = listProjects();
+      const now = Date.now();
+      for (const proj of projects) {
+        const tasks = getTasks(proj.path);
+        const p0 = tasks.filter(t => {
+          if (t.priority !== 0) return false;
+          if (t.raw_status === 'closed' || t.raw_status === 'done') return false;
+          const updatedTs = new Date(t.updated_at || t.created_at || 0).getTime();
+          // Only fresh activity — silent on old backlog P0s
+          return updatedTs > 0 && (now - updatedTs) < RECENT_WINDOW_MS;
+        });
+        for (const t of p0) {
+          const dedupeKey = `incident.p0:${proj.slug}:${t.id}`;
+          const p0Payload = {
+            title: `P0 — ${t.title.slice(0, 70)} (${proj.slug})`,
+            body: `A P0 incident is open and needs your attention.\n\n${t.description || ''}`.slice(0, 600),
+            level: 'critical',
+            project: proj.slug,
+            link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}&task=${encodeURIComponent(t.id)}#inbox`,
+            action: 'Claim P0 in board',
+            kv: {
+              id: t.id,
+              title: t.title.slice(0, 80),
+              status: t.status,
+              opened: t.created_at ? new Date(t.created_at).toISOString().slice(0, 16) : 'now',
+            },
+          };
+          fireEmailAlert('incident.p0', dedupeKey, p0Payload);
+          addNotification('incident.p0', p0Payload);
+          firePushAlert('incident.p0', dedupeKey, p0Payload);
+        }
+      }
+    } catch (e) { console.warn('cron incident.p0 failed:', e.message); }
+  }, FIVE_MIN);
+
+  // gate.blocked: new BLOCKED verdict from security-officer
+  setInterval(() => {
+    try {
+      const verdicts = readVerdicts();
+      const recent = verdicts.filter(v => {
+        if (v.agent !== 'security-officer') return false;
+        if (!isFailure(v.verdict) && !/BLOCKED/i.test(v.verdict || '')) return false;
+        if (!v.ts) return false;
+        return (Date.now() - new Date(v.ts).getTime()) < 24 * 3600_000;
+      });
+      for (const v of recent) {
+        const dedupeKey = `gate.blocked:${v.ts}:${(v.task || v.reason || '').slice(0, 40)}`;
+        const taskParam = v.task ? `&task=${encodeURIComponent(v.task)}` : '';
+        const projParam = v.project ? `?project=${encodeURIComponent(v.project)}${taskParam}` : '';
+        const blockedPayload = {
+          title: `Security BLOCKED — ${(v.reason || v.task || 'unknown').slice(0, 70)}`,
+          body: `security-officer rejected a gate. Review the verdict and address the finding before re-submitting.\n\nReason: ${v.reason || '(see verdicts log)'}`,
+          level: 'error',
+          project: v.project || 'great_cto',
+          link: `http://localhost:3141/${projParam}#logs`,
+          action: 'Review verdict',
+          kv: {
+            agent: v.agent,
+            verdict: v.verdict,
+            ts: v.ts,
+            reason: (v.reason || '').slice(0, 120),
+          },
+        };
+        fireEmailAlert('gate.blocked', dedupeKey, blockedPayload);
+        addNotification('gate.blocked', blockedPayload);
+        firePushAlert('gate.blocked', dedupeKey, blockedPayload);
+      }
+    } catch (e) { console.warn('cron gate.blocked failed:', e.message); }
+  }, FIVE_MIN);
+
+  // gate.stale: gate task open between 2h and 7 days.
+  // Lower bound: 2h is the soonest you'd want a nudge.
+  // Upper bound: gates open >7d are abandoned, not stale — don't keep nagging.
+  setInterval(() => {
+    try {
+      const projects = listProjects();
+      for (const proj of projects) {
+        const tasks = getTasks(proj.path);
+        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();
+          const ageHr = (Date.now() - created) / 3600_000;
+          if (ageHr < 2 || ageHr > 24 * 7) continue;
+          const dedupeKey = `gate.stale:${proj.slug}:${g.id}`;
+          const stalePayload = {
+            title: `${proj.slug} — ${g.title.slice(0, 60)} pending ${ageHr.toFixed(1)}h`,
+            body: `A gate has been waiting for your approval for ${ageHr.toFixed(1)} hours.\n\nGate: ${g.id}\nProject: ${proj.slug}`,
+            level: 'warning',
+            project: proj.slug,
+            link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}&task=${encodeURIComponent(g.id)}#inbox`,
+            action: 'Approve in board',
+            kv: { gate: g.id, agent: g.agent || 'unknown', age: `${ageHr.toFixed(1)}h` },
+          };
+          fireEmailAlert('gate.stale', dedupeKey, stalePayload);
+          addNotification('gate.stale', stalePayload);
+          firePushAlert('gate.stale', dedupeKey, stalePayload);
+        }
+      }
+    } catch (e) { console.warn('cron gate.stale failed:', e.message); }
+  }, FIVE_MIN);
+
+  // cost.threshold: monthly LLM spend at 80% / 100% of budget
+  setInterval(() => {
+    try {
+      const projects = listProjects();
+      for (const proj of projects) {
+        const m = getMetrics(proj.path);
+        const meta = readProjectMd(proj.path) || {};
+        const budget = parseFloat(meta['monthly-budget']?.replace?.(/[$\s]/g, '') || '0');
+        if (!budget) continue;
+        const spent = m.cost?.real_llm_usd || m.cost?.llm_usd || 0;
+        const pct = (spent / budget) * 100;
+        const month = new Date().toISOString().slice(0, 7);
+        for (const threshold of [80, 100]) {
+          if (pct < threshold) continue;
+          const dedupeKey = `cost.threshold:${proj.slug}:${month}:${threshold}`;
+          const costPayload = {
+            title: `${proj.slug} — $${spent.toFixed(2)} LLM spend, ${pct.toFixed(0)}% of $${budget} monthly budget`,
+            body: threshold === 100
+              ? `Budget exceeded. Consider routing more agents to Haiku/Kimi or raising the cap in PROJECT.md.`
+              : `Approaching budget limit. Review top-cost runs before crossing 100%.`,
+            level: threshold === 100 ? 'critical' : 'warning',
+            project: proj.slug,
+            link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}#dashboard`,
+            action: 'Open cost dashboard',
+            kv: {
+              spent: `$${spent.toFixed(2)}`,
+              budget: `$${budget}`,
+              percent: `${pct.toFixed(0)}%`,
+              month,
+            },
+          };
+          fireEmailAlert('cost.threshold', dedupeKey, costPayload);
+          addNotification('cost.threshold', costPayload);
+          firePushAlert('cost.threshold', dedupeKey, costPayload);
+        }
+      }
+    } catch (e) { console.warn('cron cost.threshold failed:', e.message); }
+  }, ONE_HOUR);
+
+  // digest.weekly: Friday 09:00 UTC ± server tick
+  setInterval(async () => {
+    try {
+      const now = new Date();
+      // Friday = 5, hour 9, dedupe by ISO-week
+      if (now.getUTCDay() !== 5 || now.getUTCHours() !== 9) return;
+      // Correct ISO-8601 week number (getUTCDate is day-of-month, not day-of-year)
+      const thu = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+      thu.setUTCDate(thu.getUTCDate() + 4 - (thu.getUTCDay() || 7));
+      const isoWeek = `${thu.getUTCFullYear()}-W${Math.ceil(((thu - new Date(Date.UTC(thu.getUTCFullYear(), 0, 1))) / 86400000 + 1) / 7)}`;
+      const projects = listProjects();
+      // Sequential loop — each project awaits so file writes complete before the
+      // 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);
+        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`,
+          body: `Your week at a glance.`,
+          level: 'info',
+          project: proj.slug,
+          link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}#dashboard`,
+          action: 'Open dashboard',
+          kv: {
+            'tasks shipped': String(m.tasks?.done || 0),
+            'this week': `+${m.velocity?.this_week ?? 0}`,
+            'LLM spend': `$${(m.cost?.llm_usd || 0).toFixed(2)}`,
+            'human equiv': `$${(m.cost?.human_usd || 0).toFixed(0)}`,
+            'savings_x': m.cost?.savings_x ? `${m.cost.savings_x}×` : '—',
+            'QA pass rate': m.qa?.pass_rate != null ? `${m.qa.pass_rate}%` : 'no runs',
+          },
+        };
+        await fireEmailAlert('digest.weekly', dedupeKey, weeklyPayload);
+        addNotification('digest.weekly', weeklyPayload);
+        await firePushAlert('digest.weekly', dedupeKey, weeklyPayload);
+      }
+    } catch (e) { console.warn('cron digest.weekly failed:', e.message); }
+  }, FIVE_MIN);
+
+  // digest.daily: morning summary (Mon–Fri, 08:00 UTC).
+  // Covers yesterday's activity: spend, features shipped, blocked gates.
+  // Idempotent via date-keyed dedupe so re-starts don't re-send.
+  setInterval(async () => {
+    try {
+      const now = new Date();
+      // Mon=1 … Fri=5 only; skip weekends
+      if (now.getUTCDay() === 0 || now.getUTCDay() === 6) return;
+      if (now.getUTCHours() !== 8) return;
+      const isoDay = now.toISOString().slice(0, 10);
+      const yesterday = new Date(now.getTime() - 86400_000).toISOString().slice(0, 10);
+      const projects = listProjects();
+      for (const proj of projects) {
+        const dedupeKey = `digest.daily:${proj.slug}:${isoDay}`;
+        // Pull last 2 days so "yesterday" is always in the window
+        const cost = getCostHistory(proj.path, 2);
+        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 blocked = inbox.summary?.blocked ?? 0;
+        const gates = inbox.summary?.gates ?? 0;
+        // Tasks closed yesterday
+        const tasks = (() => { try { return getTasks(proj.path); } catch { return []; } })();
+        const doneYesterday = tasks.filter(t => {
+          if (!t.closed_at) return false;
+          return t.closed_at.slice(0, 10) === yesterday;
+        }).length;
+        // Skip digest if nothing happened yesterday
+        if (ySpend === 0 && doneYesterday === 0 && blocked === 0 && gates === 0) continue;
+        const kvObj = {
+          date: yesterday,
+          'AI spend': `$${ySpend.toFixed(2)}`,
+          'tasks shipped': String(doneYesterday),
+          'blocked': String(blocked),
+          'open gates': String(gates),
+        };
+        if (topFeatures.length > 0) {
+          kvObj['top feature'] = `${topFeatures[0].feature} ($${topFeatures[0].llm.toFixed(2)})`;
+        }
+        const bodyLines = [
+          `Yesterday: $${ySpend.toFixed(2)} AI spend · ${doneYesterday} task${doneYesterday !== 1 ? 's' : ''} shipped`,
+        ];
+        if (blocked > 0) bodyLines.push(`⚠️ ${blocked} blocked task${blocked !== 1 ? 's' : ''} need attention`);
+        if (gates > 0) bodyLines.push(`🔒 ${gates} gate${gates !== 1 ? 's' : ''} awaiting approval`);
+        if (topFeatures.length > 0) {
+          bodyLines.push('', 'Top AI spend by feature:');
+          for (const f of topFeatures) bodyLines.push(`  • ${f.feature}: $${f.llm.toFixed(2)}`);
+        }
+        const dailyPayload = {
+          title: `${proj.slug} — ${yesterday} · $${ySpend.toFixed(2)} AI · ${doneYesterday} shipped`,
+          body: bodyLines.join('\n'),
+          level: blocked > 0 || gates > 0 ? 'warning' : 'info',
+          project: proj.slug,
+          link: `http://localhost:3141/?project=${encodeURIComponent(proj.slug)}#dashboard`,
+          action: 'Open board',
+          kv: kvObj,
+        };
+        await fireEmailAlert('digest.daily', dedupeKey, dailyPayload);
+        addNotification('digest.daily', dailyPayload);
+        await firePushAlert('digest.daily', dedupeKey, dailyPayload);
+      }
+    } catch (e) { console.warn('cron digest.daily failed:', e.message); }
+  }, FIVE_MIN);
+
+  // report.daily: republish share reports every day at 09:00 UTC
+  setInterval(() => {
+    try {
+      const now = new Date();
+      if (now.getUTCHours() !== 9) return;
+      const isoDay = now.toISOString().slice(0, 10); // dedupe by date
+      const projects = listProjects();
+      for (const proj of projects) {
+        const state = getShareState(proj.path);
+        if (!state.enabled) continue;
+        const dedupeKey = `report.daily:${proj.slug}:${isoDay}`;
+        if (_reportRepublishDedupeSet.has(dedupeKey)) continue;
+        _reportRepublishDedupeSet.add(dedupeKey);
+        toggleShare(true, proj.path, true)
+          .then(() => console.log(`report.daily: republished ${proj.slug}`))
+          .catch(e => console.warn(`report.daily: ${proj.slug} failed: ${e.message}`));
+      }
+    } catch (e) { console.warn('cron report.daily failed:', e.message); }
+  }, FIVE_MIN);
+
+  console.log('Alert cron started: gate.stale (5min), sla.escalate (5min), connector.health (5min), cost.threshold (1h), digest.daily (Mon–Fri 08:00), digest.weekly (Fri 09:00), report.daily (09:00)');
+}
+
+export { readAlertsFired, writeAlertsFired, fireEmailAlert, firePushAlert, startAlertCron };

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

@@ -0,0 +1,233 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { bdCache } from './state.mjs';
+
+// ── Beads data ─────────────────────────────────────────────────────────────────
+// Cache bdList output per cwd for BD_CACHE_TTL_MS. Invalidated when the project's
+// .beads/interactions.jsonl changes (the file watcher in watchBeads() calls
+// bdCacheInvalidate(cwd) before broadcasting). This avoids spawning `bd list`
+// on every API call when 5+ projects are open in tabs.
+const BD_CACHE_TTL_MS = 2000;
+
+function bdCacheInvalidate(cwd) { bdCache.delete(cwd); }
+
+// ── bd binary resolution (BH-32) ────────────────────────────────────────────
+// A board launched from a GUI / launchd / a login shell that didn't source the
+// usual profile often has a minimal PATH (`/usr/bin:/bin`) that omits where
+// Homebrew (`/opt/homebrew/bin`) or a user install (`~/.local/bin`) put `bd`.
+// Then `spawnSync('bd', …)` → ENOENT, and a gate Approve fails with the opaque
+// "bd update failed" — even though `bd list` was served from cache. Resolve the
+// binary once against the common locations, and always spawn with an augmented
+// PATH so bd's own child processes (git) are found too.
+const BD_EXTRA_PATHS = ['/opt/homebrew/bin', '/usr/local/bin', path.join(os.homedir(), '.local', 'bin'), '/usr/bin', '/bin'];
+const BD_BIN = (() => {
+  // honor an explicit override first
+  if (process.env.GREAT_CTO_BD_BIN && fs.existsSync(process.env.GREAT_CTO_BD_BIN)) return process.env.GREAT_CTO_BD_BIN;
+  for (const dir of BD_EXTRA_PATHS) {
+    const p = path.join(dir, 'bd');
+    try { if (fs.existsSync(p)) return p; } catch { /* skip */ }
+  }
+  return 'bd'; // fall back to PATH lookup
+})();
+function bdEnv() {
+  const cur = process.env.PATH || '';
+  const have = new Set(cur.split(path.delimiter).filter(Boolean));
+  const add = BD_EXTRA_PATHS.filter((d) => !have.has(d));
+  return add.length ? { ...process.env, PATH: [...add, cur].filter(Boolean).join(path.delimiter) } : process.env;
+}
+// Centralized bd invocation — resolved binary + augmented PATH for every call site.
+function bd(args, opts = {}) {
+  return spawnSync(BD_BIN, args, { encoding: 'utf8', timeout: 8000, ...opts, env: { ...bdEnv(), ...(opts.env || {}) } });
+}
+// Turn a failed bd result into an actionable message (the bare "bd update failed" hid ENOENT).
+function bdErr(r, what) {
+  if (r.error && r.error.code === 'ENOENT') return `${what}: 'bd' not found. Install Beads (brew install beads) or set GREAT_CTO_BD_BIN to the bd path, then restart the board.`;
+  if (r.error && r.error.code === 'ETIMEDOUT') return `${what}: bd timed out — a stale .beads/.lock can cause this`;
+  return (r.stderr && r.stderr.trim()) || (r.stdout && r.stdout.trim()) || what;
+}
+
+// Check whether `bd` is initialized in the given cwd. Returns null on success,
+// or a structured error object suitable for a 409 Conflict response.
+// Used to give the admin UI a clean signal ("project not initialized") rather
+// than a 500 with a raw stderr dump.
+function checkBeadsAvailable(cwd) {
+  // Quick filesystem check first — beads stores its DB under .beads/.
+  // Some installs use ~/.beads or env-var BEADS_DIR; respect those too.
+  const candidates = [
+    path.join(cwd, '.beads'),
+    process.env.BEADS_DIR,
+  ].filter(Boolean);
+  if (candidates.some(p => { try { return fs.existsSync(p); } catch { return false; } })) {
+    return null;  // looks initialized
+  }
+  return {
+    error: 'beads_not_initialized',
+    message: `No .beads/ directory found in ${cwd}. Initialize with 'bd init' or set BEADS_DIR.`,
+    cwd,
+    hint: "Run 'bd init' in the project root, then retry.",
+  };
+}
+
+// ── bd write serialisation (BH-12, 2026-05-15) ─────────────────────────────
+//
+// bd uses Dolt-embedded DB with file-level locking. Concurrent `bd create`
+// or `bd update` calls compete for the lock; if one crashes mid-write, it
+// leaves a stale `.beads/.lock` that blocks ALL subsequent operations
+// until manually removed.
+//
+// Server-level fix: serialise bd write operations through this single
+// promise chain. Reads (`bd list`) are unaffected — Dolt's read path
+// doesn't take the write lock.
+//
+// Adds ~100ms per write under burst load; no-op under normal usage.
+let _bdWriteChain = Promise.resolve();
+function bdWriteSerialised(fn) {
+  const next = _bdWriteChain.then(() => fn()).catch((e) => {
+    console.error('[bd-write-serialised] error:', e?.message || e);
+    return null;
+  });
+  _bdWriteChain = next.then(() => undefined).catch(() => undefined);
+  return next;
+}
+
+function bdList(cwd = process.cwd()) {
+  const cached = bdCache.get(cwd);
+  if (cached && Date.now() - cached.ts < BD_CACHE_TTL_MS) return cached.data;
+  try {
+    const result = bd(['list', '--json', '--all', '--include-gates'], { cwd });
+    if (result.status !== 0) {
+      bdCache.set(cwd, { ts: Date.now(), data: [] });
+      return [];
+    }
+    const data = JSON.parse(result.stdout || '[]');
+    bdCache.set(cwd, { ts: Date.now(), data });
+    return data;
+  } catch {
+    bdCache.set(cwd, { ts: Date.now(), data: [] });
+    return [];
+  }
+}
+
+// Fallback: parse .great_cto/tasks.md when Beads isn't initialized.
+// Format: `- [ ] TASK-001: Title [agent] [~42min]\n  Description: ...\n  Depends: ...`
+function parseTasksMd(cwd) {
+  const fp = path.join(cwd, '.great_cto', 'tasks.md');
+  if (!fs.existsSync(fp)) return [];
+  try {
+    const text = fs.readFileSync(fp, 'utf8');
+    const tasks = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^-\s+\[([ x])\]\s+([A-Z]+-\d+):\s+(.+?)(?:\s+\[([\w-]+)\])?(?:\s+\[~?([^\]]+)\])?\s*$/);
+      if (!m) continue;
+      const [, done, id, title, agent, est] = m;
+      // Collect indented description lines until next blank or task
+      let desc = '';
+      for (let j = i + 1; j < lines.length; j++) {
+        if (/^\s+\S/.test(lines[j])) { desc += lines[j].trim() + ' '; }
+        else break;
+      }
+      const isGate = /^gate:/i.test(title) || (title || '').toLowerCase().includes('gate');
+      tasks.push({
+        id,
+        title: title.trim(),
+        description: desc.trim(),
+        notes: '',
+        design: '',
+        acceptance: '',
+        status: done === 'x' ? 'done' : (isGate ? 'gate' : 'backlog'),
+        raw_status: done === 'x' ? 'closed' : 'open',
+        priority: 2,
+        labels: agent ? [agent] : [],
+        owner: agent || '',
+        created_at: null,
+        updated_at: null,
+        closed_at: null,
+        close_reason: '',
+        comment_count: 0,
+        is_gate: isGate,
+        agent: agent || '',
+        estimated_minutes: est ? parseInt(est) || null : null,
+        source: 'tasks.md',
+      });
+    }
+    return tasks;
+  } catch { return []; }
+}
+
+function getTasks(cwd = process.cwd()) {
+  const all = bdList(cwd);
+  // Fallback to tasks.md when no Beads tasks (project not initialized with bd)
+  if (all.length === 0) {
+    const mdTasks = parseTasksMd(cwd);
+    if (mdTasks.length > 0) return mdTasks;
+  }
+  return all.map(t => ({
+    id: t.id,
+    title: t.title,
+    description: t.description || '',
+    notes: t.notes || '',
+    design: t.design || '',
+    acceptance: t.acceptance || '',
+    status: mapStatus(t.status, t.labels, t.issue_type),
+    raw_status: t.status,                     // bd-native status (open/in_progress/closed/blocked)
+    priority: t.priority,
+    labels: t.labels || [],
+    owner: t.owner || '',
+    created_at: t.created_at,
+    updated_at: t.updated_at,
+    closed_at: t.closed_at || null,
+    close_reason: t.close_reason || '',
+    comment_count: t.comment_count || 0,
+    // Gate detection: explicit 'gate' label OR bd decision type OR title contains 'gate:'
+    is_gate: (t.labels || []).includes('gate')
+          || t.issue_type === 'decision'
+          || (t.title || '').toLowerCase().startsWith('gate:'),
+    agent: detectAgent(t),
+  }));
+}
+
+function mapStatus(status, labels = [], issue_type = '') {
+  // Terminal status takes precedence over the 'gate' classification.
+  // Otherwise closed gate tasks would still appear as 'gate' status, which
+  // breaks Pending-decisions / P0-open / Active-pipeline aggregates that
+  // consider "anything mapped to gate" still actionable.
+  // Reported by Codex against /api/inbox showing 3 closed gates as P0 open.
+  if (status === 'closed') return 'done';
+  if (status === 'blocked') return 'blocked';
+  if ((labels || []).includes('gate') || issue_type === 'decision') return 'gate';
+  switch (status) {
+    case 'open': return 'backlog';
+    case 'in_progress': return 'in_progress';
+    default: return 'backlog';
+  }
+}
+
+function detectAgent(task) {
+  const title = (task.title || '').toLowerCase();
+  if (title.includes('architect') || title.includes('arch')) return 'architect';
+  if (title.includes('pm:') || title.includes('product-manager') || title.includes('plan ')) return 'pm';
+  if (title.includes('senior') || title.includes('impl') || title.includes('feat') || title.includes('fix')) return 'senior-dev';
+  if (title.includes('qa') || title.includes('test')) return 'qa-engineer';
+  if (title.includes('sec') || title.includes('cso')) return 'security-officer';
+  if (title.includes('deploy') || title.includes('release')) return 'devops';
+  if (title.includes('gate:')) return 'gate';
+  return '';
+}
+
+export {
+  bdCacheInvalidate,
+  BD_BIN,
+  bdEnv,
+  bd,
+  bdErr,
+  checkBeadsAvailable,
+  bdWriteSerialised,
+  bdList,
+  parseTasksMd,
+  getTasks,
+  mapStatus,
+  detectAgent,
+};