great-cto 3.28.8 → 3.29.0

package/board/packages/board/public/index.html

@@ -1582,6 +1582,28 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
   border-radius: 0;
   overflow-x: auto;
 }
+.agent-activity { margin-top: 8px; font-size: var(--fs-small); }
+.agent-activity .aa-row { display: flex; gap: 10px; align-items: baseline; padding: 2px 16px; }
+/* ADR-023: what each agent turn changed. */
+.turns-panel { margin: 8px 16px 0; font-size: var(--fs-small); }
+.turns-panel > summary { cursor: pointer; color: var(--text2); }
+.turns-panel .tp-session { margin-top: 6px; }
+.turns-panel .tp-turns { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 4px; }
+.turns-panel .tp-turn { font: inherit; padding: 1px 6px; border: 1px solid var(--border); border-radius: 4px; background: transparent; cursor: pointer; }
+.turns-panel .tp-diff { margin-top: 8px; max-height: 420px; overflow: auto; white-space: pre; font-family: var(--mono); font-size: 12px; padding: 8px; border: 1px solid var(--border); border-radius: 4px; }
+.turns-panel .tp-add { color: var(--status-done); }
+.turns-panel .tp-del { color: var(--status-blocked); }
+/* The panel reuses the agent strip's state classes, which are scoped to .agent-activity. */
+.turns-panel .aa-time { font-family: var(--mono); opacity: 0.7; }
+.turns-panel .aa-row { padding: 2px 0; }
+.turns-panel .aa-empty { padding: 2px 0; opacity: 0.75; }
+.turns-panel .aa-bad { color: var(--status-blocked); }
+.turns-panel .aa-attn { color: var(--status-progress); }
+.agent-activity .aa-time { font-family: var(--mono); opacity: 0.7; min-width: 64px; }
+.agent-activity .aa-ok { color: var(--status-done); }
+.agent-activity .aa-bad { color: var(--status-blocked); }
+.agent-activity .aa-attn { color: var(--status-progress); }
+.agent-activity .aa-empty { padding: 2px 16px; opacity: 0.75; }
 .pl-stage {
     /* `flex: 1` let a cell shrink below its own label, and `.pl-name` below
        refuses to wrap — so the text simply ran over its neighbour. Measured at
@@ -3424,6 +3446,14 @@ h1, h2, h3, h4 { font-weight: 600; font-family: var(--sans); }
             <span class="tier-badge" id="harness-badge" title="which harness gives the second opinion in review — from capabilities: second_opinion in PROJECT.md"></span>
           </div>
           <div class="pipeline-track" id="pipeline-track"></div>
+          <!-- ADR-021: what agents are doing, streamed as it happens. -->
+          <div class="agent-activity" id="agent-activity" aria-live="polite"></div>
+          <!-- ADR-023: what each agent turn changed, from the turn snapshots. -->
+          <details class="turns-panel" id="turns-panel">
+            <summary>Turns — what each agent turn changed</summary>
+            <div id="turns-body"></div>
+            <div id="turn-diff" aria-live="polite"></div>
+          </details>
         </div>
 
         <!-- Harnesses: the host that runs the pipeline, and the second harness
@@ -4136,7 +4166,24 @@ function renderInbox(d) {
 function renderStatusVerdict(d, ageH) {
   const el = document.getElementById('proj-status-verdict');
   if (!el) return;
+  // Kept so the agent activity strip, which loads after this line is first drawn,
+  // can redraw it.
+  window.__statusVerdictArgs = [d, ageH];
+  // ADR-021: agent events count as activity, and a stage that did not chain is
+  // said on this collapsed line. The strip sits inside the closed disclosure, and
+  // a warning behind a closed disclosure is as unseen as the journal line it
+  // replaced — the first look at the page showed "no activity recorded" beside
+  // five events and a stalled stage.
+  const aa = window.__agentActivity;
+  const events = aa && aa.state === 'live' && Array.isArray(aa.events) ? aa.events : [];
+  const lastEvent = events.length ? Date.parse(events[events.length - 1].ts) : NaN;
+  if (Number.isFinite(lastEvent)) {
+    const eventH = Math.max(0, (Date.now() - lastEvent) / 3600000);
+    if (ageH == null || eventH < ageH) ageH = eventH;
+  }
   const parts = [];
+  const stalled = aa && Array.isArray(aa.attention) ? aa.attention.length : 0;
+  if (stalled) parts.push(`⚠ ${stalled} stage${stalled > 1 ? 's' : ''} did not chain`);
   if (ageH == null) parts.push('no activity recorded');
   else if (ageH < 1) parts.push(`last activity ${Math.max(1, Math.round(ageH * 60))}m ago`);
   else if (ageH < 48) parts.push(`last activity ${Math.round(ageH)}h ago`);
@@ -5589,6 +5636,136 @@ async function refreshPipeline() {
   if (Array.isArray(d)) renderPipeline(d);
   renderTierBadge();
   renderHarnesses();
+  loadAgentActivity();
+  loadTurns();
+}
+
+// ADR-021 phase 1: what agents are doing, streamed as it happens. Three states,
+// and each says which: no events recorded is not an idle agent, and events the
+// board could not read are "not measured", never an empty strip.
+// ADR-023: the turns a project's agents took, and what each one changed.
+async function loadTurns() {
+  const root = document.getElementById('turns-body');
+  if (!root) return;
+  const snap = await api(`/api/turns${pqs()}`).catch(() => null);
+  root.innerHTML = renderTurns(snap);
+}
+
+function renderTurns(snap) {
+  // Three states, never an empty list that could mean either "nothing" or "could not read".
+  if (!snap) return `<div class="aa-empty aa-bad">Turns not measured: the board could not load them.</div>`;
+  if (snap.state === 'none') return `<div class="aa-empty">No turn history: ${esc(snap.why || 'not available for this project')}</div>`;
+  if (snap.state === 'unreadable') return `<div class="aa-empty aa-bad">Turns not measured: ${esc(snap.why || 'git refused')}</div>`;
+  const sessions = Array.isArray(snap.sessions) ? snap.sessions : [];
+  if (!sessions.length) return `<div class="aa-empty">No turn snapshots yet — they start with the next agent turn.</div>`;
+  const when = (ms) => { try { return ms ? new Date(ms).toLocaleString([], { hour12: false }) : ''; } catch { return ''; } };
+  return sessions.map((s) => {
+    const count = Math.min(Number(s.turns) || 0, 50);
+    const first = Math.max(0, (Number(s.newestTurn) || 0) - count + 1);
+    const buttons = [];
+    for (let n = Number(s.newestTurn) || 0; n >= first; n--) {
+      // The session goes in as a JSON string, escaped for the attribute: esc() turns '
+      // into &#39;, which the browser decodes before the handler runs, so a quoted
+      // string built from esc() alone could be broken out of.
+      buttons.push(`<button type="button" class="tp-turn" onclick="showTurnDiff(${esc(JSON.stringify(String(s.session)))}, ${n})">${n}</button>`);
+    }
+    return `<div class="tp-session"><span class="aa-time">${esc(when(s.newestAt))}</span> <code>${esc(String(s.session).slice(0, 8))}</code> · ${esc(String(s.turns))} turn(s)`
+      + `<div class="tp-turns">${buttons.join('')}</div></div>`;
+  }).join('');
+}
+
+async function showTurnDiff(session, turn) {
+  const root = document.getElementById('turn-diff');
+  if (!root) return;
+  root.innerHTML = `<div class="aa-empty">Loading turn ${esc(String(turn))}…</div>`;
+  const q = pqs() ? `&${pqs().slice(1)}` : '';
+  const d = await api(`/api/turns/diff?session=${encodeURIComponent(session)}&turn=${encodeURIComponent(turn)}${q}`).catch(() => null);
+  root.innerHTML = renderTurnDiff(d);
+}
+
+function renderTurnDiff(d) {
+  // A diff is file content: every line is escaped before it is drawn.
+  if (!d || d.state !== 'ok') return `<div class="aa-empty aa-bad">This turn could not be shown: ${esc((d && d.why) || 'the board could not load it')}</div>`;
+  const paths = (Array.isArray(d.paths) ? d.paths : []).map((p) => `<code>${esc(p)}</code>`).join(', ') || 'no files changed';
+  const lines = String(d.patch || '').split('\n').map((l) => {
+    const cls = l.startsWith('+') && !l.startsWith('+++') ? 'tp-add' : l.startsWith('-') && !l.startsWith('---') ? 'tp-del' : '';
+    return cls ? `<span class="${cls}">${esc(l)}</span>` : esc(l);
+  }).join('\n');
+  const cut = d.truncated ? `<div class="aa-row aa-attn">⚠ The diff was cut at the size limit — the file list above is complete.</div>` : '';
+  return `<div class="aa-row">Changed: ${paths}</div>${cut}<div class="tp-diff">${lines}</div>`;
+}
+
+async function loadAgentActivity() {
+  // Once the stream holds a cursor for this project it owns the strip: a GET
+  // snapshot landing after its deltas would show those events twice.
+  const c = window.__agentCursor;
+  if (c && c.project === currentProject && window.__agentActivity) return;
+  const snap = await api(`/api/agent-events${pqs()}`).catch(() => null);
+  renderAgentActivity(snap);
+}
+
+// ADR-021 phase 2: the stream resumes. A delta appends to what the strip holds; a
+// snapshot replaces it (and one that skipped events keeps saying so until the next).
+function mergeAgentActivity(prev, frame) {
+  if (!frame) return prev || null;
+  const cap = (a, n) => (Array.isArray(a) ? a : []).slice(-n);
+  if (frame.mode !== 'delta') return frame;
+  if (!prev || prev.state !== 'live') return { ...frame, events: cap(frame.events, 50), attention: cap(frame.attention, 3) };
+  return {
+    ...frame,
+    events: cap([...(prev.events || []), ...(frame.events || [])], 50),
+    attention: cap([...(prev.attention || []), ...(frame.attention || [])], 3),
+    gap: prev.gap === true,
+  };
+}
+
+// The cursor belongs to one project's events file; another project's file has other offsets.
+function agentSinceParam() {
+  const c = window.__agentCursor;
+  return c && c.id && c.project === currentProject ? `since=${encodeURIComponent(c.id)}` : '';
+}
+
+function renderAgentActivity(snap) {
+  // Stored before anything else, so the collapsed status line can say what the
+  // strip knows even when the strip itself is not on the page.
+  window.__agentActivity = snap;
+  if (window.__statusVerdictArgs) {
+    try { renderStatusVerdict(...window.__statusVerdictArgs); } catch { /* the strip still renders */ }
+  }
+  const root = document.getElementById('agent-activity');
+  if (!root) return;
+  if (!snap) {
+    root.innerHTML = `<div class="aa-empty aa-bad">Agent events not measured: the board could not load them.</div>`;
+    return;
+  }
+  if (snap.state === 'unreadable') {
+    root.innerHTML = `<div class="aa-empty aa-bad">Agent events not measured: ${esc(snap.why || 'the events file could not be read')}</div>`;
+    return;
+  }
+  const events = Array.isArray(snap.events) ? snap.events : [];
+  if (snap.state === 'none' || !events.length) {
+    root.innerHTML = `<div class="aa-empty">No agent events recorded yet — they start with the next agent run.</div>`;
+    return;
+  }
+  const time = (ts) => { try { return new Date(ts).toLocaleTimeString([], { hour12: false }); } catch { return ''; } };
+  const what = (e) => {
+    if (e.kind === 'tool') {
+      const p = Array.isArray(e.paths) && e.paths.length ? ` ${esc(e.paths[0])}${e.paths.length > 1 ? ` +${e.paths.length - 1}` : ''}` : '';
+      return `${esc(e.tool || 'tool')}${p}`;
+    }
+    if (e.kind === 'pipeline') return `pipeline: ${esc(e.outcome || '')}${e.verdict ? ' · ' + esc(e.verdict) : ''}`;
+    return esc(e.kind || '');
+  };
+  const attention = (Array.isArray(snap.attention) ? snap.attention : []).map((e) =>
+    `<div class="aa-row aa-attn" title="The pipeline did not move on after this stage">⚠ <span>${esc(e.agent || 'stage')}: ${esc(e.outcome || '')} — the pipeline did not chain</span></div>`).join('');
+  const rows = events.slice(-8).reverse().map((e) => {
+    const mark = e.ok === true ? '<span class="aa-ok">✓</span>' : e.ok === false ? '<span class="aa-bad">✗</span>' : '';
+    return `<div class="aa-row"><span class="aa-time">${esc(time(e.ts))}</span><span>${esc(e.agent || '')}</span><span>${what(e)}</span>${mark}</div>`;
+  }).join('');
+  const gap = snap.gap === true
+    ? `<div class="aa-row aa-attn" title="More events arrived while the board was disconnected than a resume sends">⚠ <span>Some agent events were skipped while the board was disconnected — showing the newest.</span></div>`
+    : '';
+  root.innerHTML = gap + attention + rows;
 }
 
 // change_tier badge — the gate + judge plan for the current working-tree diff (ADR-003/004).
@@ -7125,7 +7302,10 @@ function api(url, opts) {
 
 function connectSSE() {
   if (window._gctoSSE) { try { window._gctoSSE.close(); } catch {} }
-  const es = new EventSource(`/api/sse${pqs()}`);
+  // This page recreates its EventSource after an error, so the browser never sends
+  // Last-Event-ID by itself: hand the agent cursor back explicitly.
+  const since = agentSinceParam();
+  const es = new EventSource(`/api/sse${pqs()}${since ? (pqs() ? '&' : '?') + since : ''}`);
   window._gctoSSE = es;
   const applyTasksSnapshot = (newTasks) => {
     // Detect status transitions for toast feed
@@ -7177,6 +7357,12 @@ function connectSSE() {
       renderPipeline(stages);
     } catch {}
   });
+  es.addEventListener('agent', e => {
+    try {
+      if (e.lastEventId) window.__agentCursor = { project: currentProject, id: e.lastEventId };
+      renderAgentActivity(mergeAgentActivity(window.__agentActivity, JSON.parse(e.data)));
+    } catch {}
+  });
   es.addEventListener('inbox', e => {
     try { renderInbox(JSON.parse(e.data)); } catch {}
   });
@@ -7434,48 +7620,37 @@ function approveConsequence(id, reversibility) {
   return lines.join('\n');
 }
 
-async function gateAction(id, action, runAgent) {
+async function gateAction(id, action) {
+  // ADR-024 §1: the server refuses a decision without the token the inbox issued for
+  // this gate, and an approval of an expensive gate without its typed name. The page
+  // sends both; it no longer decides alone.
+  const token = ((window.__inboxData && window.__inboxData.pending_gates) || []).find((g) => g.id === id)?.token || null;
   let body;
   if (action === 'reject') {
     const reason = prompt(`Reject ${id}. Reason (optional)?`);
     if (reason === null) return;
-    body = { action, reason, project: currentProject };
+    body = { action, reason, token, project: currentProject };
   } else {
     // The gate is the human signature the pipeline waits on. Rejecting has
     // always asked for a reason and approving asked for nothing, so the cheaper
     // click was the one that advanced work nobody can un-advance — friction
     // pointing exactly the wrong way.
     //
-    // Medium cost-of-undo (ADR-009): one confirm that NAMES the consequence, not
-    // a typed-name ritual on a button pressed several times a day. The runAgent
-    // path already shows an editable prompt that says what it will approve and
-    // run, and is cancellable — a second dialog there would be pure friction.
-    // Approve ritual follows cost of undo (DESIGN §6.2). `routine`: one confirm
-    // naming the consequence. `expensive` and `unclassified`: the operator types
-    // the gate name — exact, case-sensitive — before the approval is posted; an
-    // unclassified gate gets the expensive ritual because nobody judged it cheap.
+    // Approve ritual follows cost of undo (ADR-009, DESIGN §6.2). `routine`: one
+    // confirm naming the consequence. `expensive` and `unclassified`: the operator
+    // types the gate name — exact, case-sensitive — and the server checks the same
+    // name; an unclassified gate gets the expensive ritual because nobody judged it
+    // cheap.
     const rev = GATE_REVERSIBILITY[id] || null;
     const guarded = rev && (rev.state === 'expensive' || rev.state === 'unclassified');
-    if (!runAgent && guarded) {
+    body = { action, token, project: currentProject };
+    if (guarded) {
       const gateName = rev.gate ? `gate:${rev.gate}` : id;
       const typed = prompt(`${approveConsequence(id, rev)}\n\nType ${gateName} to approve:`, '');
       if (typed === null) return;
       if (typed.trim() !== gateName) { alert(`Not approved — "${typed.trim()}" is not ${gateName}.`); return; }
-    } else if (!runAgent && !confirm(approveConsequence(id, rev))) return;   // routine
-    body = { action, project: currentProject };
-    if (runAgent) {
-      const generic = `Gate ${id} was just approved. Continue the great_cto pipeline: claim the next ready task and implement it with TDD.`;
-      // Prefer a ready-to-run prompt derived from the task's own body (title/description/labels),
-      // falling back to the generic one. The operator still sees and edits it before launch.
-      let dflt = generic;
-      try {
-        const pf = await api(`/api/agent/prompt-for?id=${encodeURIComponent(id)}${pqs().replace(/^\?/, '&')}`);
-        if (pf && pf.prompt) dflt = pf.prompt;
-      } catch (_) { /* fall back to generic */ }
-      const p = prompt(`Approve ${id} and run an agent in the project.\n\nPrompt for the agent (edit as needed):`, dflt);
-      if (p === null) return;                 // cancelled the whole action
-      body.runAgent = true; body.agentPrompt = p.trim() || dflt;
-    }
+      body.confirm = typed.trim();
+    } else if (!confirm(approveConsequence(id, rev))) return;   // routine
   }
   const res = await api(`/api/gates/${encodeURIComponent(id)}${pqs()}`, {
     method: 'POST',
@@ -7484,6 +7659,8 @@ async function gateAction(id, action, runAgent) {
   });
   if (!res || res.error) {
     alert('Gate action failed: ' + (res?.error || 'network error'));
+    // A refused token or a changed project: reload, so the gate is shown as it is now.
+    api(`/api/inbox${pqs()}`).then(d => d && renderInbox(d));
     return;
   }
   showToast(`Gate <strong>${esc(id)}</strong> ${action === 'approve' ? '✓ approved' : '✗ rejected'}`, action === 'approve' ? 'success' : 'error', 3000);

package/board/packages/board/server.mjs

@@ -14,10 +14,10 @@ import path from 'path';
 import { spawnSync } from 'child_process';
 import { PORT, PUBLIC, HOST } from './lib/config.mjs';
 import { warmTasksAsync } from './lib/beads.mjs';
-import { originAllowed, isInsideDir } from './lib/util.mjs';
+import { originAllowed, hostAllowed, parseAllowedHosts, isInsideDir } from './lib/util.mjs';
 import { discoverProjects, resolveProjectInfo } from './lib/projects.mjs';
 import { startAlertCron } from './lib/alerts.mjs';
-import { watchBeads, watchVerdicts } from './lib/watchers.mjs';
+import { watchBeads, watchVerdicts, watchAgentEvents } from './lib/watchers.mjs';
 import { dispatch } from './lib/routes.mjs';
 import { log } from './lib/log.mjs';
 
@@ -39,6 +39,18 @@ const server = http.createServer(async (req, res) => {
       }
     });
   }
+  // ── Host allowlist (great_cto-xq9h) ─────────────────────────────────────────
+  // Before anything is read or written: a request addressed to a name the board
+  // does not know is a DNS-rebinding page, not the user. Reads count — the SSE
+  // stream and every GET carry the project's tasks, verdicts and costs.
+  if (!hostAllowed(req.headers.host)) {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'host not allowed — the board answers only on localhost, 127.0.0.1, its bind address, or a host listed in GREAT_CTO_ALLOWED_HOSTS',
+    }));
+    return;
+  }
+
   const url = new URL(req.url, `http://localhost:${PORT}`);
   const pathname = url.pathname;
   const proj = url.searchParams.get('project');
@@ -121,6 +133,10 @@ server.listen(PORT, HOST, () => {
     log.info(`  ⚠ bound to ${HOST} — reachable beyond this machine. Operators authenticate via invite`);
     log.info(`    links; put your reverse-proxy auth in front for anything admin-grade.`);
   }
+  if (['0.0.0.0', '::'].includes(HOST) && parseAllowedHosts().length === 0) {
+    log.info(`  ⚠ bound to ${HOST} with no GREAT_CTO_ALLOWED_HOSTS — only localhost / 127.0.0.1 names are answered.`);
+    log.info(`    Reaching it by LAN address or through a tunnel? Set GREAT_CTO_ALLOWED_HOSTS=<host[:port]>,...`);
+  }
   // Warm the task cache for THIS project before a browser asks — asynchronously.
   //
   // `bd list` costs seconds. This used to call `getTasks(cwd)` directly, which
@@ -159,6 +175,7 @@ server.listen(PORT, HOST, () => {
   watchBeads();
   startAlertCron();
   watchVerdicts();
+  watchAgentEvents();
 
   // Auto-open browser unless --no-open
   if (!process.argv.includes('--no-open')) {

package/board/scripts/codex-pipeline.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, writeFileSync, renameSync, rmdirSync, realpathSync } from 'node:fs';
+import { join, resolve, relative, sep, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { newRun, runStage, approve, recover, cancel } from './lib/codex-pipeline.mjs';
+import { approveRelease } from './lib/codex-release.mjs';
+import { codexRunStore, listCodexRuns, codexHostDoctor } from './lib/codex-host-state.mjs';
+
+// State is outside the worker workspace. A per-run exclusive lock covers the entire subprocess lifetime.
+const args = process.argv.slice(2);
+const command = args.shift();
+const value = name => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+const store = codexRunStore();
+mkdirSync(store, { recursive: true, mode: 0o700 });
+const save = state => {
+  const file = join(store, `${state.id}.json`);
+  writeFileSync(`${file}.tmp`, JSON.stringify(state, null, 2), { mode: 0o600 });
+  renameSync(`${file}.tmp`, file);
+};
+let locked = null;
+try {
+  if (command === 'doctor') {
+    const result = codexHostDoctor({ pluginRoot: resolve(value('--plugin-root') || join(dirname(fileURLToPath(import.meta.url)), '..')), store });
+    console.log(JSON.stringify(result, null, 2)); process.exit(result.state === 'ready' ? 0 : 2);
+  }
+  if (command === 'list') {
+    console.log(JSON.stringify(listCodexRuns({ root: value('--dir') ? realpathSync(resolve(value('--dir'))) : null, store }), null, 2));
+    process.exit(0);
+  }
+  let state;
+  if (command === 'start') {
+    const root = realpathSync(resolve(value('--dir') || '.'));
+    let checkPolicy = null;
+    if (value('--checks-policy')) {
+      const policyPath = realpathSync(value('--checks-policy'));
+      const rel = relative(root, policyPath);
+      if (rel !== '..' && !rel.startsWith(`..${sep}`)) throw Error('checks policy must be operator-owned outside the target workspace');
+      checkPolicy = JSON.parse(readFileSync(policyPath, 'utf8'));
+    }
+    let releasePolicy = null;
+    if (value('--release-policy')) {
+      const policyPath = realpathSync(value('--release-policy'));
+      const rel = relative(root, policyPath);
+      if (rel !== '..' && !rel.startsWith(`..${sep}`)) throw Error('release policy must be operator-owned outside the target workspace');
+      releasePolicy = JSON.parse(readFileSync(policyPath, 'utf8'));
+    }
+    state = newRun({ root, prompt: value('--prompt'), checkPolicy, releasePolicy,
+      allowed: (value('--allow') || '').split(',').filter(Boolean), entry: value('--entry') || 'product-owner',
+      maxAttempts: value('--max-attempts') === null ? 3 : Number(value('--max-attempts')) });
+    save(state);
+  } else {
+    const id = args[0];
+    if (!/^[0-9a-f-]{36}$/.test(id || '')) throw Error('a run UUID is required');
+    state = JSON.parse(readFileSync(join(store, `${id}.json`), 'utf8'));
+    if (state.id !== id || state.version !== 1) throw Error('invalid run state');
+  }
+  if (!['start', 'resume', 'status', 'approve', 'approve-release', 'recover', 'cancel'].includes(command)) throw Error('expected start, resume, status, approve, approve-release, recover, cancel, list or doctor');
+  if (command !== 'status') {
+    const lock = join(store, `${state.id}.lock`);
+    mkdirSync(lock); locked = lock;
+    // Reload under lock so simultaneous approvals cannot overwrite one another.
+    state = JSON.parse(readFileSync(join(store, `${state.id}.json`), 'utf8'));
+    if (command === 'approve') { approve(state, value('--token')); save(state); }
+    else if (command === 'approve-release') { approveRelease(state, value('--token')); save(state); }
+    else if (command === 'recover') { recover(state); save(state); }
+    else if (command === 'cancel') { cancel(state); save(state); }
+    else while (state.status === 'ready') await runStage(state, { save });
+  }
+  console.log(JSON.stringify({ id: state.id, status: state.status, reason: state.reason,
+    release: state.release ? { status: state.release.status, token: state.release.token, adapter: state.release.adapter,
+      artifactDigest: state.release.artifactDigest, target: state.release.target, path: state.release.path, url: state.release.url,
+      activation: state.release.activation, rollback: state.release.rollback } : null,
+    pending: state.pending, queue: state.queue, rolesCompleted: Object.keys(state.results), stateFile: join(store, `${state.id}.json`) }, null, 2));
+  process.exitCode = ['blocked', 'manual-action', 'join-wait'].includes(state.status) ? 2 : 0;
+} catch (error) {
+  console.error(`codex-pipeline: ${error.message}`);
+  process.exitCode = 2;
+} finally {
+  if (locked) rmdirSync(locked);
+}

package/board/scripts/lib/agent-events.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// agent-events — what agents are doing, recorded as it happens (ADR-021, phase 1).
+//
+// The board showed outcomes after the fact. On 2026-09-14 a live pipeline run
+// stopped after its first stage and nothing said so: the only record was a
+// journal line, found by reading the file by hand. The hooks the plugin already
+// runs now append one line per event to <project>/.great_cto/events.jsonl, and the
+// board streams the file.
+//
+// Three rules, each one the reason this is a separate module rather than a
+// appendFileSync in five hooks:
+//
+//   - An event carries FACTS, never content. Command text, file contents, prompts
+//     and tool output can hold secrets; the transcript already has them for anyone
+//     who needs them. `makeEvent` keeps an allowlist and types every value, so a
+//     caller that passes the whole hook payload still records only facts.
+//   - Recording never breaks a hook. Every failure comes back as `{ok:false, why}`.
+//   - The reader reports which of three things it found. No file is `none` — not an
+//     idle agent. A file it cannot read is `unreadable` — not zero events.
+//
+// Local only: the file stays in the project and nothing is sent anywhere.
+// GREAT_CTO_DISABLE_EVENTS=1 turns recording off.
+//
+// CLI (for hooks written in shell):
+//   node scripts/lib/agent-events.mjs --emit <kind> [--tool <name>] [--agent <name>]
+
+import { appendFileSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const EVENTS_FILE = 'events.jsonl';
+export const EVENT_KINDS = Object.freeze(['agent-start', 'agent-stop', 'tool', 'denied', 'stop', 'pipeline']);
+export const EVENT_FIELDS = Object.freeze(['v', 'ts', 'kind', 'session', 'agent', 'tool', 'paths', 'ok', 'duration_ms', 'outcome', 'verdict']);
+export const MAX_BYTES = 5 * 1024 * 1024;
+
+const MAX_PATHS = 10;
+const short = (v, n) => (typeof v === 'string' && v.trim() ? v.trim().slice(0, n) : undefined);
+const iso = (ms) => new Date(ms).toISOString().replace(/\.\d+Z$/, 'Z');
+
+/**
+ * One event, reduced to the allowed fields. Null for a kind that is not an event.
+ * Values that are not the expected type are dropped, not coerced: a string "yes"
+ * is not `ok: true`.
+ */
+export function makeEvent(input, { now = Date.now() } = {}) {
+  if (!input || !EVENT_KINDS.includes(input.kind)) return null;
+  const e = { v: 1, ts: iso(now), kind: input.kind };
+  const session = short(input.session, 80); if (session) e.session = session;
+  const agent = short(input.agent, 80); if (agent) e.agent = agent;
+  const tool = short(input.tool, 80); if (tool) e.tool = tool;
+  if (Array.isArray(input.paths)) {
+    const paths = input.paths.filter((p) => typeof p === 'string' && p.trim()).map((p) => p.slice(0, 300)).slice(0, MAX_PATHS);
+    if (paths.length) e.paths = paths;
+  }
+  if (typeof input.ok === 'boolean') e.ok = input.ok;
+  if (Number.isFinite(input.duration_ms) && input.duration_ms >= 0) e.duration_ms = Math.round(input.duration_ms);
+  if (typeof input.outcome === 'string' && /^[a-z][a-z-]{0,39}$/.test(input.outcome)) e.outcome = input.outcome;
+  if (typeof input.verdict === 'string' && /^[A-Z][A-Z_-]{0,39}$/.test(input.verdict)) e.verdict = input.verdict;
+  return e;
+}
+
+/**
+ * Append one event to <dir>/events.jsonl. Never throws.
+ *
+ * @param {string} dir  the project's .great_cto directory
+ * @returns {{ok:true} | {ok:false, why:string}}
+ */
+export function appendEvent(dir, input, { now = Date.now(), env = process.env, maxBytes = MAX_BYTES } = {}) {
+  try {
+    if (env.GREAT_CTO_DISABLE_EVENTS === '1') return { ok: false, why: 'disabled by GREAT_CTO_DISABLE_EVENTS=1' };
+    const e = makeEvent(input, { now });
+    if (!e) return { ok: false, why: `not an event kind: ${JSON.stringify(input?.kind)}` };
+    const line = JSON.stringify(e) + '\n';
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, EVENTS_FILE);
+    let size = 0;
+    try { size = statSync(file).size; } catch { /* no file yet */ }
+    // One previous generation: enough for the board to replay a restart, small
+    // enough that a busy project cannot fill a disk with its own activity log.
+    // Bytes, not characters: a path in Cyrillic is two bytes a letter, and the
+    // board's replay cursor is a byte offset into this file.
+    if (size > 0 && size + Buffer.byteLength(line) > maxBytes) renameSync(file, join(dir, 'events.1.jsonl'));
+    appendFileSync(file, line);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, why: String(err?.code || err?.message || err) };
+  }
+}
+
+/**
+ * The newest events, oldest first.
+ *
+ * @returns {{state:'live'|'none'|'unreadable', events:object[], bad?:number, why?:string}}
+ */
+export function readEvents(dir, { limit = 50 } = {}) {
+  let text;
+  try {
+    text = readFileSync(join(dir, EVENTS_FILE), 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { state: 'none', events: [] };
+    return { state: 'unreadable', events: [], why: String(err?.code || err?.message || err) };
+  }
+  const { events, bad } = parseLines(text);
+  return { state: 'live', events: events.slice(-Math.max(1, limit)), bad };
+}
+
+/** Events and the count of lines that were not one. Shared, so both readers agree. */
+function parseLines(text) {
+  const events = [];
+  let bad = 0;
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let rec;
+    try { rec = JSON.parse(line); } catch { bad++; continue; }
+    if (rec && EVENT_KINDS.includes(rec.kind)) events.push(rec); else bad++;
+  }
+  return { events, bad };
+}
+
+// ── resuming (ADR-021 phase 2, great_cto-c0hb) ─────────────────────────────
+
+/** The most events one replay sends before it gives up and sends a snapshot. */
+export const MAX_DELTA = 500;
+
+function parseCursor(cursor) {
+  const m = /^(\d+)-(\d+)$/.exec(String(cursor ?? ''));
+  return m ? { ino: Number(m[1]), offset: Number(m[2]) } : null;
+}
+
+/**
+ * Events after a cursor, or a snapshot when the cursor no longer points into this file.
+ *
+ * The cursor is `<inode>-<byte offset>`: the offset just past the last complete line
+ * consumed. A snapshot — never a read from the wrong place — when there is no cursor,
+ * it is not one of ours, the inode differs (the file rotated or was replaced), the
+ * file is shorter than the offset (truncated), the offset does not sit just after a
+ * newline (truncated and grown back past it), or the gap holds more than maxDelta
+ * events (then `gap: true`, so the board can say events were skipped).
+ *
+ * Not caught: a file truncated and regrown so that a newline lands exactly on the old
+ * offset. Same inode, a plausible boundary — indistinguishable from a real resume.
+ * Nothing in the plugin truncates this file; rotation renames it.
+ *
+ * @returns {{state:'live'|'none'|'unreadable', mode?:'delta'|'snapshot', events:object[],
+ *            cursor:string|null, bad?:number, gap?:boolean, why?:string}}
+ */
+export function readEventsSince(dir, cursor, { limit = 50, maxDelta = MAX_DELTA } = {}) {
+  let buf, ino;
+  try {
+    const fd = openSync(join(dir, EVENTS_FILE), 'r');
+    try {
+      const st = fstatSync(fd);
+      ino = st.ino;
+      buf = Buffer.alloc(st.size);
+      let read = 0;
+      while (read < st.size) {
+        const n = readSync(fd, buf, read, st.size - read, read);
+        if (n === 0) break;
+        read += n;
+      }
+      buf = buf.subarray(0, read);
+    } finally { closeSync(fd); }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { state: 'none', events: [], cursor: null };
+    return { state: 'unreadable', events: [], cursor: null, why: String(err?.code || err?.message || err) };
+  }
+  // Only complete lines: a hook may be mid-append.
+  const end = buf.lastIndexOf(0x0a) + 1;
+  const next = `${ino}-${end}`;
+  const snapshot = (extra = {}) => {
+    const { events, bad } = parseLines(buf.subarray(0, end).toString('utf8'));
+    return { state: 'live', mode: 'snapshot', events: events.slice(-Math.max(1, limit)), cursor: next, bad, ...extra };
+  };
+  const c = parseCursor(cursor);
+  if (!c || c.ino !== ino || c.offset > end || (c.offset > 0 && buf[c.offset - 1] !== 0x0a)) return snapshot();
+  const { events, bad } = parseLines(buf.subarray(c.offset, end).toString('utf8'));
+  if (events.length > maxDelta) return snapshot({ gap: true });
+  return { state: 'live', mode: 'delta', events, cursor: next, bad };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const argv = process.argv.slice(2);
+    const arg = (name) => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+    if (argv.includes('--emit')) {
+      appendEvent(process.env.GREAT_CTO_DIR || '.great_cto', {
+        kind: arg('--emit'), tool: arg('--tool'), agent: arg('--agent'), session: arg('--session'),
+      });
+    }
+  } catch { /* a hook must never fail because an event could not be recorded */ }
+  process.exit(0);
+}