great-cto 3.28.9 → 3.29.0

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 70 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.28.9",
+  "version": "3.29.0",
   "author": {
     "name": "Alexander Velikiy",
     "url": "https://hashnode.com/@Greatcto"
@@ -121,6 +121,11 @@
             "command": "PLUGIN_DIR=${CLAUDE_PLUGIN_ROOT:-$(ls -d ~/.claude/plugins/cache/*/great_cto/*/ 2>/dev/null | sort -V | tail -1 | sed 's|/$||')}; node \"${PLUGIN_DIR}/scripts/hooks/subagent-stop-completion.mjs\" 2>&1; EXIT=$?; if [ $EXIT -eq 2 ]; then exit 2; fi; exit 0",
             "timeout": 5,
             "statusMessage": "Three-state completion check..."
+          },
+          {
+            "type": "command",
+            "async": true,
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/turn-snapshot.mjs\" 2>/dev/null || true"
           }
         ]
       }
@@ -272,7 +277,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "INPUT=$(cat 2>/dev/null); TOOL=$(echo \"$INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('tool_name','unknown'))\" 2>/dev/null); mkdir -p .great_cto 2>/dev/null; printf '%s PERMISSION_DENIED tool=%s\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \"$TOOL\" >> .great_cto/permission-denied.log 2>/dev/null; if [ \"$TOOL\" = \"Bash\" ] || [ \"$TOOL\" = \"Write\" ]; then printf '%s PERMISSION_DENIED %s \u2014 agent may be stuck. Run /inbox.\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \"$TOOL\" >> .great_cto/permission-denied.log 2>/dev/null; fi; true",
+            "command": "INPUT=$(cat 2>/dev/null); TOOL=$(echo \"$INPUT\" | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('tool_name','unknown'))\" 2>/dev/null); mkdir -p .great_cto 2>/dev/null; printf '%s PERMISSION_DENIED tool=%s\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \"$TOOL\" >> .great_cto/permission-denied.log 2>/dev/null; if [ \"$TOOL\" = \"Bash\" ] || [ \"$TOOL\" = \"Write\" ]; then printf '%s PERMISSION_DENIED %s \u2014 agent may be stuck. Run /inbox.\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" \"$TOOL\" >> .great_cto/permission-denied.log 2>/dev/null; fi; true; node \"${CLAUDE_PLUGIN_ROOT}/scripts/lib/agent-events.mjs\" --emit denied --tool \"$TOOL\" 2>/dev/null || true",
             "timeout": 3
           }
         ]
@@ -288,6 +293,11 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/cross-review-gate.mjs\" 2>/dev/null || true"
+          },
+          {
+            "type": "command",
+            "async": true,
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/turn-snapshot.mjs\" 2>/dev/null || true"
           }
         ]
       }

package/board/packages/board/lib/agent-activity.mjs

@@ -0,0 +1,53 @@
+// Agent activity for the board (ADR-021, phase 1).
+//
+// The hooks append agent events to <project>/.great_cto/events.jsonl through
+// scripts/lib/agent-events.mjs; this reads them for one project, and gives the
+// watcher a cheap stamp to notice that something new arrived.
+//
+// Three states come straight from the reader and are passed through unchanged:
+// `none` (no file — no events recorded, which is not an idle agent), `live`, and
+// `unreadable` (a file the board could not read — not zero events). `attention`
+// is the pipeline events whose outcome means the chain did not move: on
+// 2026-09-14 a run stopped on `no-rule` and nothing on the board said so.
+
+import fs from 'fs';
+import path from 'path';
+import { readEvents, readEventsSince, EVENTS_FILE } from '../../../scripts/lib/agent-events.mjs';
+
+/** Journal outcomes after which the pipeline did not move on. */
+export const STALLED_OUTCOMES = Object.freeze(['no-rule', 'no-verdict', 'unknown-verdict', 'no-map', 'breaker', 'blocked-budget']);
+
+export function agentActivity(cwd, { limit = 20 } = {}) {
+  const r = readEvents(path.join(cwd, '.great_cto'), { limit });
+  const attention = r.events.filter((e) => e.kind === 'pipeline' && STALLED_OUTCOMES.includes(e.outcome)).slice(-3);
+  return { state: r.state, why: r.why ?? null, events: r.events, attention, bad: r.bad ?? 0 };
+}
+
+/**
+ * The same, resumable (ADR-021 phase 2): events after `cursor` as a `delta`, or a
+ * `snapshot` when the cursor no longer points into this project's file. `cursor` is
+ * what the next call should pass; `gap` says a snapshot replaced more events than a
+ * replay sends. `attention` covers only the events returned — the page merges.
+ */
+export function agentActivitySince(cwd, cursor, { limit = 20 } = {}) {
+  const r = readEventsSince(path.join(cwd, '.great_cto'), cursor, { limit });
+  const attention = r.events.filter((e) => e.kind === 'pipeline' && STALLED_OUTCOMES.includes(e.outcome)).slice(-3);
+  return {
+    state: r.state, mode: r.mode ?? 'snapshot', why: r.why ?? null, events: r.events, attention,
+    bad: r.bad ?? 0, cursor: r.cursor, gap: r.gap === true,
+  };
+}
+
+/**
+ * What the watcher compares between polls. `none` when there is no file; the
+ * error code when it cannot be stat'ed, so a file that turns unreadable is a
+ * change too.
+ */
+export function activityStamp(cwd) {
+  try {
+    const s = fs.statSync(path.join(cwd, '.great_cto', EVENTS_FILE));
+    return `${s.size}:${s.mtimeMs}`;
+  } catch (err) {
+    return err?.code === 'ENOENT' ? 'none' : `error:${err?.code || 'unknown'}`;
+  }
+}

package/board/packages/board/lib/gate-tokens.mjs

@@ -0,0 +1,151 @@
+// Gate approval tokens (ADR-024 §1).
+//
+// POST /api/gates/:id closed a gate, logged it, woke the pipeline and, with sharing
+// on, republished the public report — guarded by the Host allowlist and the Origin
+// check alone. The controlled Codex host already refused an approval without the
+// token issued for that pending gate, or after the tree changed; the board did not.
+//
+// A token here is minted when the board lists a pending gate, is single-use,
+// expires, and is bound to the project tree OUTSIDE .great_cto/ as it was when the
+// board first showed the gate. .great_cto/ is excluded because an approval writes
+// the pipeline's own files there (gate row, decision log, wake record, this store),
+// and `init` does not gitignore it: bound to the whole tree, the first approval
+// would invalidate every other open gate though no reviewed code moved.
+//
+// Every check fails closed and says why. A store that cannot be read issues no
+// tokens and accepts none — it is never silently overwritten.
+
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import { treeReceipt, receiptHash, compareReceipts } from '../../../scripts/lib/receipt.mjs';
+
+export const TOKENS_FILE = 'gate-tokens.json';
+export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+// Why these are outside the binding: both are the pipeline's own state, and a
+// decision itself writes to them — .great_cto/ gets the gate row, decision log, wake
+// and this store; .beads/ gets `bd update`'s interactions.jsonl. Counting either would
+// let one approval refuse every other open gate as "changed". .beads/ was found by
+// tests/pipeline-e2e.test.mjs: approving gate:plan made gate:ship read stale.
+export const BINDING_EXCLUDE = Object.freeze(['.great_cto', '.beads']);
+
+/** Test seam: GREAT_CTO_GATE_TOKEN_TTL_MS; production is 24 h. */
+export function tokenTtlMs(env = process.env) {
+  const n = Number(env.GREAT_CTO_GATE_TOKEN_TTL_MS);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_TTL_MS;
+}
+
+const storePath = (cwd) => path.join(cwd, '.great_cto', TOKENS_FILE);
+
+/** @returns {{state:'none'|'ok'|'unreadable', tokens:object, why?:string}} */
+export function readTokens(cwd) {
+  let raw;
+  try { raw = fs.readFileSync(storePath(cwd), 'utf8'); }
+  catch (err) {
+    if (err?.code === 'ENOENT') return { state: 'none', tokens: {} };
+    return { state: 'unreadable', tokens: {}, why: String(err?.code || err?.message || err) };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw Error('not an object');
+    return { state: 'ok', tokens: parsed };
+  } catch (err) {
+    return { state: 'unreadable', tokens: {}, why: `the token store could not be parsed: ${err.message}` };
+  }
+}
+
+function writeTokens(cwd, tokens) {
+  fs.mkdirSync(path.join(cwd, '.great_cto'), { recursive: true });
+  const file = storePath(cwd);
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(tokens, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/** The tree a token is bound to: the project outside .great_cto/. Null outside git. */
+export function bindingReceipt(cwd) {
+  return treeReceipt(cwd, { exclude: BINDING_EXCLUDE });
+}
+
+/**
+ * Tokens for the pending gates, minting what is missing or expired.
+ *
+ * `gates` is the FULL pending list — entries for gates no longer pending are
+ * dropped. At most one receipt is computed per call (about 300 ms on a real tree),
+ * and only when something has to be minted.
+ *
+ * @param {{id:string, gate?:string, guarded?:boolean}[]} gates
+ * @returns {{state:'ok'|'unreadable', tokens:Record<string,string>, why?:string}}
+ */
+export function issueTokens(cwd, gates, { now = Date.now(), env = process.env } = {}) {
+  const store = readTokens(cwd);
+  if (store.state === 'unreadable') return { state: 'unreadable', tokens: {}, why: store.why };
+  const ttl = tokenTtlMs(env);
+  const pending = new Map((gates || []).filter((g) => g && typeof g.id === 'string' && g.id).map((g) => [g.id, g]));
+  const next = {};
+  const toMint = [];
+  for (const [id, g] of pending) {
+    const e = store.tokens[id];
+    if (e && typeof e.token === 'string' && Number.isFinite(e.firstSeenAt) && now - e.firstSeenAt <= ttl) next[id] = e;
+    else toMint.push(g);
+  }
+  if (toMint.length) {
+    const receipt = bindingReceipt(cwd);
+    const hash = receiptHash(receipt);
+    for (const g of toMint) {
+      next[g.id] = {
+        token: randomUUID(), firstSeenAt: now, receiptHash: hash, receipt,
+        gate: typeof g.gate === 'string' ? g.gate : '', guarded: g.guarded === true,
+      };
+    }
+  }
+  const changed = toMint.length || Object.keys(store.tokens).some((id) => !pending.has(id));
+  if (changed) writeTokens(cwd, next);
+  return { state: 'ok', tokens: Object.fromEntries(Object.entries(next).map(([id, e]) => [id, e.token])) };
+}
+
+/**
+ * Is `token` the live token for gate `id`?
+ * @returns {{ok:true, entry:object} | {ok:false, status:number, outcome:string, why:string}}
+ */
+export function checkToken(cwd, id, token, { now = Date.now(), env = process.env } = {}) {
+  const store = readTokens(cwd);
+  if (store.state === 'unreadable') {
+    return { ok: false, status: 403, outcome: 'refused-unreadable', why: `approval tokens could not be read: ${store.why}` };
+  }
+  const entry = store.tokens[id];
+  if (!entry || typeof token !== 'string' || !token || token !== entry.token) {
+    return { ok: false, status: 403, outcome: 'refused-token', why: 'no valid approval token for this gate — reload the inbox and try again' };
+  }
+  if (!Number.isFinite(entry.firstSeenAt) || now - entry.firstSeenAt > tokenTtlMs(env)) {
+    return { ok: false, status: 403, outcome: 'refused-expired', why: 'this approval token has expired — reload the inbox to see the gate as it is now' };
+  }
+  return { ok: true, entry };
+}
+
+/**
+ * Is the tree outside .great_cto/ still the one the gate was shown with?
+ * @returns {{ok:true, bound:boolean} | {ok:false, status:409, outcome:'refused-stale', why:string, changed:string[]}}
+ */
+export function checkBinding(cwd, entry) {
+  const current = bindingReceipt(cwd);
+  if (!entry.receipt && !current) return { ok: true, bound: false };   // not a git repository: nothing to bind to, and said so
+  if (receiptHash(current) === entry.receiptHash) return { ok: true, bound: true };
+  const cmp = compareReceipts(entry.receipt, current, { cwd });
+  const changed = [...(cmp.changed || []), ...(cmp.removed || []), ...(cmp.added || [])];
+  return {
+    ok: false, status: 409, outcome: 'refused-stale', changed,
+    why: changed.length
+      ? `the project changed since this gate was shown: ${changed.slice(0, 10).join(', ')}${changed.length > 10 ? ` and ${changed.length - 10} more` : ''}`
+      : 'the project changed since this gate was shown (a commit or an unreadable tree)',
+  };
+}
+
+/** Single use: drop the gate's token once it has been decided. */
+export function consumeToken(cwd, id) {
+  const store = readTokens(cwd);
+  if (store.state !== 'ok' || !(id in store.tokens)) return;
+  const next = { ...store.tokens };
+  delete next[id];
+  writeTokens(cwd, next);
+}

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

@@ -20,10 +20,20 @@ import { getMemory, getPipeline, getCostHistory, getInbox, inboxElsewhere } from
 import { log } from './log.mjs';
 import { bdCacheInvalidate, checkBeadsAvailable, bdWriteSerialised, bd, bdErr, getTasks, setTaskStatusInTasksMd, getReadDegradation } from './beads.mjs';
 import { getMetrics } from './metrics.mjs';
+import { agentActivity, agentActivitySince } from './agent-activity.mjs';
+import { issueTokens, checkToken, checkBinding, consumeToken } from './gate-tokens.mjs';
+import { readTurns, turnPatch } from '../../../scripts/lib/turn-snapshot.mjs';
+import { appendEvent } from '../../../scripts/lib/agent-events.mjs';
+
+/** A gate decision — made or refused — as an agent event (ADR-024 §1). */
+function recordGateEvent(cwd, id, outcome) {
+  return appendEvent(path.join(cwd, '.great_cto'), { kind: 'pipeline', agent: id, outcome });
+}
 import { readVerdicts } from './verdicts.mjs';
 import { parseAgentBudgets, upsertAgentBudget, removeAgentBudget } from '../../../scripts/lib/agent-budget.mjs';
 import { resolveSecondOpinion, SECOND_OPINION_PROVIDERS } from '../../../scripts/lib/second-opinion.mjs';
 import { detectCodex } from '../../../scripts/lib/codex-exec.mjs';
+import { listCodexRuns } from '../../../scripts/lib/codex-host-state.mjs';
 import { upsertCapability, capabilitiesFromProjectMd } from '../../../scripts/lib/stack-capabilities.mjs';
 // Moved to scripts/lib so the cross-review Stop hook can ask the same question
 // without importing a server. Re-exported here: this module's callers are unchanged.
@@ -92,6 +102,19 @@ async function dispatch(req, res, url, cwd) {
     res._gctoCwd = cwd;  // remember which project this client wants
     sseClients.add(res);
     res.write(`event: tasks\ndata: ${JSON.stringify(getTasks(cwd))}\n\n`);
+    // ADR-021: the agent activity strip starts from a snapshot, then follows pushes.
+    // Phase 2: a client that hands back the cursor of the last frame it saw — the
+    // Last-Event-ID header, or ?since= from a page that had to recreate its
+    // EventSource — gets only what came after it. Each frame names its cursor.
+    let a;
+    try {
+      a = agentActivitySince(cwd, req.headers['last-event-id'] || url.searchParams.get('since') || null);
+    } catch (err) {
+      // Not "no events": the strip must say it could not measure them.
+      a = { state: 'unreadable', mode: 'snapshot', why: String(err?.message || err), events: [], attention: [], bad: 0, cursor: null, gap: false };
+    }
+    res._gctoAgentCursor = a.cursor;
+    res.write(`${a.cursor ? `id: ${a.cursor}\n` : ''}event: agent\ndata: ${JSON.stringify(a)}\n\n`);
     req.on('close', () => sseClients.delete(res));
     return true;
   }
@@ -520,6 +543,26 @@ async function dispatch(req, res, url, cwd) {
         res.end(JSON.stringify({ error: 'invalid action' }));
         return;
       }
+      // ADR-024 §1 — an approval is bound to one request and one state. Checked before
+      // anything is written: a refused request changes no gate, logs no decision,
+      // wakes nothing and publishes nothing. A rejection needs the token too (a forged
+      // reject is still a forged request) but is never refused for a changed tree.
+      const refuse = (r) => {
+        recordGateEvent(gateCwd, id, r.outcome);
+        res.writeHead(r.status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: r.why, outcome: r.outcome, ...(r.changed ? { changed: r.changed } : {}) }));
+      };
+      const tok = checkToken(gateCwd, id, parsed.token);
+      if (!tok.ok) { refuse(tok); return; }
+      if (action === 'approve') {
+        // The typed-name ritual used to live only in the page; the server now agrees.
+        if (tok.entry.guarded && String(parsed.confirm ?? '').trim() !== tok.entry.gate) {
+          refuse({ status: 403, outcome: 'refused-confirm', why: `this gate is expensive to undo — type ${tok.entry.gate} to approve it` });
+          return;
+        }
+        const bound = checkBinding(gateCwd, tok.entry);
+        if (!bound.ok) { refuse(bound); return; }
+      }
       // A project can be tasks.md-backed (no working beads — e.g. its path
       // contains a space, which embedded-dolt can't open). Only 409 when there
       // is neither a beads store NOR a tasks.md to record the decision in.
@@ -610,6 +653,9 @@ async function dispatch(req, res, url, cwd) {
         res.end(JSON.stringify({ error: (result && result.error) || 'bd update failed' }));
         return;
       }
+      // Single use: the decision landed, so its token is spent.
+      consumeToken(gateCwd, id);
+      recordGateEvent(gateCwd, id, action === 'approve' ? 'approved' : 'rejected');
       // An approval is evidence that the pipeline is waiting — record it.
       //
       // `session-pipeline-resume` opens with a freshness shortcut: a pipeline
@@ -677,8 +723,19 @@ async function dispatch(req, res, url, cwd) {
     let elsewhere;
     try { elsewhere = inboxElsewhere(listProjects(), cwd, { readInbox: getInbox }); }
     catch (e) { elsewhere = { state: 'unreadable', why: String(e?.message || e) }; }
+    // ADR-024 §1: each pending gate carries the token an approval must present,
+    // bound to the project as it is now. The typed name stored with it is the one
+    // the page asks for; a store that cannot be read issues nothing and says so.
+    const gates = inbox.pending_gates || [];
+    const issued = issueTokens(cwd, gates.map((g) => ({
+      id: g.id,
+      gate: g.reversibility?.gate ? `gate:${g.reversibility.gate}` : g.id,
+      guarded: ['expensive', 'unclassified'].includes(g.reversibility?.state),
+    })));
+    const pending_gates = gates.map((g) => ({ ...g, token: issued.tokens[g.id] || null }));
+    const approval_tokens = { state: issued.state, ...(issued.why ? { why: issued.why } : {}) };
     res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
-    res.end(JSON.stringify({ ...inbox, elsewhere, second_opinion }));
+    res.end(JSON.stringify({ ...inbox, pending_gates, approval_tokens, elsewhere, second_opinion }));
     return true;
   }
 
@@ -902,12 +959,56 @@ async function dispatch(req, res, url, cwd) {
   }
 
   // Pipeline — current stage states (idle / active / done / failed)
+  // ADR-021: agent events for this project — three states, never an empty list
+  // that could mean either "nothing happened" or "could not read".
+  if (pathname === '/api/agent-events') {
+    let limit = parseInt(url.searchParams.get('limit') || '20', 10);
+    if (!Number.isFinite(limit) || limit < 1) limit = 20;
+    if (limit > 200) limit = 200;
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(agentActivity(cwd, { limit })));
+    return true;
+  }
+
+  // ADR-023: what each agent turn changed. Turns are git refs in the project's own
+  // repository; these read them and nothing else. A diff is file content, served only
+  // on a Host the board knows (xq9h) and escaped by the page before it is drawn.
+  if (pathname === '/api/turns') {
+    let limit = parseInt(url.searchParams.get('limit') || '10', 10);
+    if (!Number.isFinite(limit) || limit < 1) limit = 10;
+    if (limit > 50) limit = 50;
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(readTurns(cwd, { limit })));
+    return true;
+  }
+  if (pathname === '/api/turns/diff') {
+    const turnParam = url.searchParams.get('turn');
+    const turn = /^\d{1,9}$/.test(turnParam || '') ? Number(turnParam) : NaN;
+    const p = turnPatch(cwd, { session: url.searchParams.get('session') || '', turn });
+    const status = p.state === 'ok' ? 200 : p.state === 'invalid' ? 400 : 404;
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(p));
+    return true;
+  }
+
   if (pathname === '/api/pipeline') {
     res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));
     res.end(JSON.stringify(getPipeline(cwd)));
     return true;
   }
 
+  // Controlled Codex host runs are stored outside worker projects. Return the
+  // shared sanitized projection only: prompts, approval tokens and artifact
+  // bytes never cross into the browser payload.
+  if (pathname === '/api/codex-runs') {
+    const result = listCodexRuns({ root: cwd });
+    const headers = { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' };
+    if (result.state === 'degraded') headers['X-Board-Degraded'] = encodeURIComponent(`${result.unreadable} unreadable Codex run state file(s)`);
+    res.writeHead(200, headers);
+    res.end(JSON.stringify(result));
+    return true;
+  }
+
   // change_tier for the current working-tree diff — the gate + judge plan (ADR-003/004).
   if (pathname === '/api/change-tier') {
     res.writeHead(200, verdictHeaders(cwd, { 'Content-Type': 'application/json' }));

package/board/packages/board/lib/util.mjs

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { PORT } from './config.mjs';
+import { PORT, HOST } from './config.mjs';
 
 /**
  * Escape a single value for inclusion in a CSV cell.
@@ -14,13 +14,41 @@ function csvCell(v) {
 }
 
 // Only same-origin (the board's own page) may make a state-changing request — a malicious page must not.
+//
+// "Same origin" used to mean: the Origin matches the Host this request arrived with.
+// A DNS-rebinding page points its own domain at 127.0.0.1, so the browser sends
+// Host: evil.test:PORT and Origin: http://evil.test:PORT — a perfect match. It could
+// read every GET and pass this guard for POST, gate approvals included (great_cto-xq9h).
+// So the Host itself must be a name the board was told about: loopback on its port,
+// the concrete bind host, or an entry in GREAT_CTO_ALLOWED_HOSTS (a tunnel or hosted
+// console). server.mjs checks it for every request; the Origin must name one too.
+const WILDCARD_BINDS = new Set(['0.0.0.0', '::', '[::]', '']);
+
+function parseAllowedHosts(raw = process.env.GREAT_CTO_ALLOWED_HOSTS) {
+  return String(raw || '').split(',').map((h) => h.trim().toLowerCase()).filter(Boolean);
+}
+
+function allowedHostList({ port = PORT, bindHost = HOST, extra = parseAllowedHosts() } = {}) {
+  const list = [`localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`];
+  const b = String(bindHost || '').toLowerCase();
+  if (!WILDCARD_BINDS.has(b)) list.push(`${b.includes(':') && !b.startsWith('[') ? `[${b}]` : b}:${port}`);
+  return [...list, ...extra];
+}
+
+function hostAllowed(hostHeader, opts = {}) {
+  if (typeof hostHeader !== 'string' || !hostHeader.trim()) return false;
+  return allowedHostList(opts).includes(hostHeader.trim().toLowerCase());
+}
+
 function originAllowed(req) {
   const o = req.headers.origin || req.headers.referer || '';
   if (!o) return true; // same-origin fetch / curl with no Origin
-  // True same-origin: the browser's Origin matches the host this request arrived on
-  // (covers a tunnelled/hosted console at console.client.com, http or https).
-  const self = req.headers.host ? [`http://${req.headers.host}`, `https://${req.headers.host}`] : [];
-  return [`http://localhost:${PORT}`, `http://127.0.0.1:${PORT}`, ...self].some((e) => o === e || o.startsWith(e + '/'));
+  let u;
+  try { u = new URL(o); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  // u.host keeps an explicit port and drops a default one (https://x → "x"), which is
+  // how a tunnel host is listed. Never "whatever Host this request came with".
+  return allowedHostList().includes(u.host.toLowerCase());
 }
 
 // Which surface an alert belongs to. Operate-side events (autopilot runtime: dead-letters,
@@ -93,4 +121,4 @@ function isInsideDir(base, target) {
   return resolvedTarget === resolvedBase || resolvedTarget.startsWith(resolvedBase + path.sep);
 }
 
-export { csvCell, originAllowed, eventSurface, readFileSafe, readSafe, parseSafe, isInsideDir };
+export { csvCell, originAllowed, hostAllowed, allowedHostList, parseAllowedHosts, eventSurface, readFileSafe, readSafe, parseSafe, isInsideDir };

package/board/packages/board/lib/watchers.mjs

@@ -5,6 +5,7 @@ import { sseClients } from './state.mjs';
 import { listProjects } from './projects.mjs';
 import { bdCacheStale, getTasks, isSelfInflictedTouch } from './beads.mjs';
 import { getPipeline, getInbox } from './data-readers.mjs';
+import { agentActivitySince, activityStamp } from './agent-activity.mjs';
 
 // ── File watcher ───────────────────────────────────────────────────────────────
 function watchBeads() {
@@ -147,4 +148,36 @@ function watchVerdicts() {
   } catch {}
 }
 
-export { watchBeads, watchVerdicts };
+// ADR-021: push agent events to the clients watching the project that wrote them.
+//
+// Polled, not fs.watch'd: events.jsonl is created on the first event and rotated
+// at its cap, and a watch on a file that does not exist yet — or was just renamed
+// away — silently watches nothing. One stat per watched project per second is
+// cheap, and it meets the ADR's "on the board within two seconds".
+function watchAgentEvents({ intervalMs = 1000 } = {}) {
+  const stamps = new Map();
+  const timer = setInterval(() => {
+    const cwds = new Set();
+    for (const res of sseClients) cwds.add(res._gctoCwd || process.cwd());
+    for (const cwd of cwds) {
+      const stamp = activityStamp(cwd);
+      if (stamps.get(cwd) === stamp) continue;
+      stamps.set(cwd, stamp);
+      // Phase 2: each client gets what came after ITS cursor — a delta, or a snapshot
+      // when its cursor stopped pointing into this file — and the frame names the new
+      // cursor. Nothing new for a client is nothing sent.
+      for (const res of sseClients) {
+        if ((res._gctoCwd || process.cwd()) !== cwd) continue;
+        let a;
+        try { a = agentActivitySince(cwd, res._gctoAgentCursor ?? null); } catch { continue; }
+        res._gctoAgentCursor = a.cursor;
+        if (a.mode === 'delta' && a.events.length === 0) continue;
+        try { res.write(`${a.cursor ? `id: ${a.cursor}\n` : ''}event: agent\ndata: ${JSON.stringify(a)}\n\n`); } catch { sseClients.delete(res); }
+      }
+    }
+  }, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  return timer;
+}
+
+export { watchBeads, watchVerdicts, watchAgentEvents };