@stravica-ai/digital-operator-pa 0.1.67 → 0.1.69

package/dist/engineering-pa-cli/src/pa/board-check.mjs

@@ -0,0 +1,633 @@
+// board-check.mjs - `pa board check [--json] [--hook-envelope] [--agent <name>]`.
+//
+// Read-only. Compares the PA's daily status board
+// (agents/<agent>/workspace/status-board.json) with its spawn-log
+// (agents/<agent>/spawn-log.json, every shape, through the core reader) and,
+// when the instance keeps initiatives records, with the open questions under
+// initiatives/<id>/questions/. It writes nothing anywhere: no cache, no lock.
+// It reads the spawn-log's lock file (agents/<agent>/spawn-log.json.lock) and
+// never writes, breaks or sweeps it.
+//
+// One problem line each for:
+//   - the board's updatedAt 90 minutes old or more (the Status page's red
+//     threshold) while a dispatch is open, or no board at all while one is;
+//   - an open dispatch with no board item (an item in groups[].items[] whose
+//     ids holds the dispatch id; a mention in a title does not count);
+//   - an open dispatch that has been open 24 to 48 hours (close it or check it);
+//   - the spawn-log lock held for longer than the stale window
+//     (LOCK_STALE_AFTER_MS, one minute): the line leads with
+//     `pa dispatch unlock` and the holder's pid, and its host and
+//     acquiredAt are capped for display (core capForDisplay), so the
+//     envelope's 360-character cut never reaches them; writers wait 10 s on
+//     it and then fail;
+//   - with initiatives records only: an open dispatch with no `initiative`,
+//     an open tagged dispatch with no `stage` (a stage is a non-empty string
+//     or an object with a numeric `n` and `m`), and an open question
+//     (status "open") whose id is in no onMe[].ids.
+// "Open" is the core rule (isOpenDispatch) inside the 48 hour window: live
+// under 24 hours, stale from 24 to 48.
+// Status or outcome words on a dispatch launched in the last 48 hours that
+// begin with neither a package OPEN word nor a known closed word are
+// `unrecognised status` warnings: the human output gives one line per word
+// with its count and at most five ids, `--json` lists every one. They never
+// change the exit code.
+//
+// Exit codes: 0 clean | 1 usage error | 2 one or more problems |
+// 3 the check could not run (no repo root, the spawn-log or the board
+// unreadable or not valid JSON, or the board failing the schema).
+// `--hook-envelope` prints one SessionStart hook envelope line and exits 0 on
+// every path, so a session boot never sees a hook error.
+//
+// The logic is the pure `checkBoard`, so the workspace Status page banner
+// and this command cannot disagree.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  SpawnLogError,
+  describeDispatch,
+  openDispatches,
+  readSpawnLogSync,
+  unrecognisedWords,
+  windowFor,
+} from '../../../engineering-pa-core/src/spawn-log/read.mjs';
+import {
+  LOCK_STALE_AFTER_MS,
+  describeLockHolder,
+  readSpawnLogLock,
+} from '../../../engineering-pa-core/src/spawn-log/write.mjs';
+
+import { getRepoRoot } from './repo-root.mjs';
+import {
+  boardPath,
+  boardRelPath,
+  isValidAgentName,
+  readBoard,
+  resolveAgentName,
+} from './status-board.mjs';
+
+export const BOARD_STALE_MINUTES = 90;
+export const HOOK_ENVELOPE_MAX_CHARS = 2000;
+export const SUBVERBS = ['check'];
+
+const USAGE = `pa board - check the daily status board against the spawn-log
+
+Usage:
+  pa board check [--json] [--hook-envelope] [--agent <name>]
+  pa board check --help
+
+Reports, one line each:
+  - the board not updated for ${BOARD_STALE_MINUTES} minutes (or missing) while a dispatch is open
+  - an open dispatch with no board item (an item whose ids hold the dispatch id)
+  - a dispatch open 24 to 48 hours (close it or check it)
+  - the spawn-log lock held for more than ${LOCK_STALE_AFTER_MS / 60000} minute, naming its holder and
+    pa dispatch unlock (writers wait on it and then fail)
+  - with initiatives records: an open dispatch with no initiative, a tagged
+    dispatch with no stage, and an open question with no on-me entry
+Unrecognised status or outcome words are warnings (exit 0): one line per word,
+with its count and at most 5 ids; --json lists every one.
+
+Flags:
+  --json            One JSON object on stdout
+  --hook-envelope   A Claude Code SessionStart hook envelope on stdout; always exits 0
+  --agent <name>    The agent folder (default: preferences paName, else the
+                    single agents/* folder holding next-session.md)
+
+Read-only: never writes a file, and never breaks or removes the spawn-log lock.
+
+Exit codes:
+  0 clean | 1 usage error | 2 problems found | 3 the check could not run
+`;
+
+class UsageError extends Error {
+  constructor(msg) { super(msg); this.exitCode = 1; }
+}
+class PreconditionError extends Error {
+  constructor(msg) { super(msg); this.exitCode = 3; }
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function toMs(now) {
+  if (now === undefined) return Date.now();
+  if (now instanceof Date) return now.getTime();
+  if (typeof now === 'function') return toMs(now());
+  return Number(now);
+}
+
+function nonEmptyString(v) {
+  return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+}
+
+/**
+ * A dispatch's stage, or null when it has none. A stage is present as a
+ * non-empty string (returned trimmed) or as an object with a finite numeric
+ * `n` and `m` (returned as `{ n, m }`, plus `label` when that is a
+ * non-empty string). Anything else is no stage.
+ */
+export function normaliseStage(v) {
+  const text = nonEmptyString(v);
+  if (text !== null) return text;
+  if (!isPlainObject(v) || !Number.isFinite(v.n) || !Number.isFinite(v.m)) return null;
+  const label = nonEmptyString(v.label);
+  return label === null ? { n: v.n, m: v.m } : { n: v.n, m: v.m, label };
+}
+
+function plural(n, one, many) {
+  return n + ' ' + (n === 1 ? one : many);
+}
+
+/** "6 h", "6 h 5 min", "12 min", "2 d 3 h". */
+export function formatAge(minutes) {
+  if (minutes === null || minutes === undefined || !Number.isFinite(minutes)) return 'an unknown time';
+  const m = Math.max(0, Math.floor(minutes));
+  if (m < 60) return m + ' min';
+  const h = Math.floor(m / 60);
+  if (h < 24) return h + ' h' + (m % 60 ? ' ' + (m % 60) + ' min' : '');
+  const d = Math.floor(h / 24);
+  return d + ' d' + (h % 24 ? ' ' + (h % 24) + ' h' : '');
+}
+
+function summarise(item, state) {
+  const rec = item.record;
+  return {
+    id: item.id,
+    description: describeDispatch(rec),
+    launchedAt: item.launchedAtMs === null ? null : new Date(item.launchedAtMs).toISOString(),
+    initiative: nonEmptyString(rec.initiative),
+    stage: normaliseStage(rec.stage),
+    state,
+  };
+}
+
+function boardIdSet(board, key) {
+  const ids = new Set();
+  if (!isPlainObject(board)) return ids;
+  const add = (list) => {
+    for (const it of Array.isArray(list) ? list : []) {
+      if (isPlainObject(it) && Array.isArray(it.ids)) for (const id of it.ids) if (typeof id === 'string') ids.add(id);
+    }
+  };
+  if (key === 'groups') {
+    for (const g of Array.isArray(board.groups) ? board.groups : []) if (isPlainObject(g)) add(g.items);
+  } else {
+    add(board.onMe);
+  }
+  return ids;
+}
+
+/**
+ * The check itself. Pure: no IO, injected clock, never throws on malformed
+ * input.
+ *
+ * @param {object} input
+ * @param {object|null} input.board        the normalised board, or null when there is none
+ * @param {Array} input.dispatches         merged spawn-log items from the core reader
+ * @param {Array<{id: string, initiative?: string}>} [input.questions]  open questions
+ * @param {boolean} [input.hasInitiatives] at least one initiatives/<id>/initiative.json exists
+ * @param {object|null} [input.lock]      the spawn-log lock as read (readSpawnLogLock),
+ *                                        or null/absent when there is none or it was not read
+ * @param {string} [input.lockRelPath]    the lock's path for the message
+ * @param {Date|number|Function} [input.now]
+ */
+export function checkBoard(input = {}) {
+  const nowMs = toMs(input.now);
+  const board = isPlainObject(input.board) ? input.board : null;
+  const dispatches = Array.isArray(input.dispatches) ? input.dispatches : [];
+  const questions = Array.isArray(input.questions) ? input.questions : [];
+  const hasInitiatives = input.hasInitiatives === true;
+
+  const { live, stale } = openDispatches(dispatches, { now: nowMs });
+  const open = [...live.map((d) => summarise(d, 'live')), ...stale.map((d) => summarise(d, 'stale'))];
+
+  const updatedAtMs = board ? Date.parse(board.updatedAt) : NaN;
+  const ageMinutes = Number.isFinite(updatedAtMs) ? Math.max(0, Math.floor((nowMs - updatedAtMs) / 60000)) : null;
+  const onBoard = boardIdSet(board, 'groups');
+  const onMe = boardIdSet(board, 'onMe');
+
+  const problems = [];
+  const n = open.length;
+  if (n > 0) {
+    const openText = plural(n, 'dispatch is', 'dispatches are') + ' open';
+    if (!board) {
+      problems.push({ kind: 'board-missing', message: 'no board yet while ' + openText });
+    } else if (ageMinutes === null || ageMinutes >= BOARD_STALE_MINUTES) {
+      problems.push({
+        kind: 'board-stale',
+        message: 'board last updated ' + formatAge(ageMinutes) + ' ago (' + board.updatedAt + ') while ' + openText,
+      });
+    }
+  }
+
+  const openNotOnBoard = [];
+  for (const d of open) {
+    if (d.id !== null && onBoard.has(d.id)) continue;
+    openNotOnBoard.push({ id: d.id, description: d.description, launchedAt: d.launchedAt, state: d.state });
+    problems.push({
+      kind: 'not-on-board',
+      dispatchId: d.id,
+      message: (d.id ?? 'a dispatch with no id') + ' is open and not on the board: ' + d.description,
+    });
+  }
+  for (const d of open) {
+    if (d.state !== 'stale') continue;
+    problems.push({
+      kind: 'stale-open',
+      dispatchId: d.id,
+      message: (d.id ?? 'a dispatch with no id') + ' has been open 24 to 48 hours: close it or check it',
+    });
+  }
+  if (hasInitiatives) {
+    for (const d of open) {
+      if (d.initiative === null) {
+        problems.push({ kind: 'untagged', dispatchId: d.id, message: (d.id ?? 'a dispatch with no id') + ' is open with no initiative' });
+      } else if (d.stage === null) {
+        problems.push({
+          kind: 'no-stage',
+          dispatchId: d.id,
+          message: (d.id ?? 'a dispatch with no id') + ' is tagged ' + d.initiative + ' and has no stage',
+        });
+      }
+    }
+    for (const q of questions) {
+      if (!isPlainObject(q) || typeof q.id !== 'string') continue;
+      if (onMe.has(q.id)) continue;
+      problems.push({ kind: 'question-not-on-me', questionId: q.id, message: q.id + ' is an open question with no on-me entry' });
+    }
+  }
+
+  const lock = isPlainObject(input.lock) && typeof input.lock.text === 'string' && Number.isFinite(input.lock.mtimeMs) ? input.lock : null;
+  if (lock) {
+    const holder = describeLockHolder(lock, nowMs);
+    if (holder.ageMs > LOCK_STALE_AFTER_MS) {
+      const rel = typeof input.lockRelPath === 'string' ? input.lockRelPath : 'the spawn-log lock';
+      problems.push({
+        kind: 'lock-held',
+        lockPath: rel,
+        holder: { state: holder.state, pid: holder.pid, hostname: holder.hostname, acquiredAt: holder.acquiredAt, ageMinutes: Math.floor(holder.ageMs / 60000) },
+        // The command and the holder's pid lead; every variable part is
+        // bounded (a pid, capped names, an age), so the envelope's
+        // 360-character cut can reach only the end of the --force sentence.
+        // lockPath and holder stay whole.
+        message: 'run `pa dispatch unlock` for the spawn-log lock' + (holder.pid !== null ? ' held by ' : ', ') + holder.text
+          + '; writers wait 10 s, then fail'
+          + (holder.provablyDead ? '' : '. If it refuses, use `--force` only once the holder\'s process is gone or stuck, never while it is still running')
+          + '.',
+      });
+    }
+  }
+
+  const unrecognisedStatuses = [];
+  for (const d of dispatches) {
+    if (!isPlainObject(d) || !isPlainObject(d.record)) continue;
+    if (windowFor(d.launchedAtMs, nowMs) === null) continue;
+    for (const word of unrecognisedWords(d.record)) unrecognisedStatuses.push({ id: d.id ?? null, word });
+  }
+
+  const strip = ({ state, ...rest }) => rest;
+  return {
+    ok: problems.length === 0,
+    exitCode: problems.length === 0 ? 0 : 2,
+    board: {
+      present: board !== null,
+      updatedAt: board ? (board.updatedAt ?? null) : null,
+      ageMinutes,
+    },
+    open: {
+      live: open.filter((d) => d.state === 'live').map(strip),
+      stale: open.filter((d) => d.state === 'stale').map(strip),
+    },
+    openNotOnBoard,
+    problems,
+    unrecognisedStatuses,
+  };
+}
+
+/**
+ * Read the instance's initiatives records, read-only. `hasRecords` is true
+ * when at least one initiatives/<id>/initiative.json exists; `questions`
+ * lists every questions/*.json record whose status is "open".
+ */
+export function readInitiativesSync(repoRoot) {
+  const dir = join(repoRoot, 'initiatives');
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return { hasRecords: false, questions: [] };
+  }
+  let hasRecords = false;
+  const questions = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (existsSync(join(dir, e.name, 'initiative.json'))) hasRecords = true;
+    const qdir = join(dir, e.name, 'questions');
+    let files;
+    try { files = readdirSync(qdir); } catch { continue; }
+    for (const f of files.sort()) {
+      if (!f.endsWith('.json')) continue;
+      let q;
+      try { q = JSON.parse(readFileSync(join(qdir, f), 'utf8')); } catch { continue; }
+      if (!isPlainObject(q) || typeof q.status !== 'string' || q.status.trim().toLowerCase() !== 'open') continue;
+      const id = nonEmptyString(q.id) ?? f.slice(0, -'.json'.length);
+      questions.push({ id, initiative: e.name });
+    }
+  }
+  return { hasRecords, questions };
+}
+
+/** Spawn-log path of an agent, repo-relative. */
+export function spawnLogRelPath(agent) {
+  return 'agents/' + agent + '/spawn-log.json';
+}
+
+// -- rendering --------------------------------------------------------------
+
+function summaryLine(agent, result) {
+  const parts = [];
+  const live = result.open.live.length;
+  const stale = result.open.stale.length;
+  const nProblems = result.problems.length;
+  const nWarnings = result.unrecognisedStatuses.length;
+  const head = nProblems === 0
+    ? 'board check: clean for ' + agent
+    : 'board check: ' + plural(nProblems, 'problem', 'problems') + ' for ' + agent;
+  parts.push(head + (nWarnings ? ', ' + plural(nWarnings, 'warning', 'warnings') : ''));
+  parts.push(result.board.present ? 'board updated ' + formatAge(result.board.ageMinutes) + ' ago' : 'no board yet');
+  const notOn = result.openNotOnBoard.length;
+  parts.push((live + stale) + ' open (' + live + ' live, ' + stale + ' stale), '
+    + (notOn === 0 ? 'all on the board' : notOn + ' not on the board'));
+  return parts.join('; ');
+}
+
+/** Ids shown per unrecognised word in the human output; `--json` lists all. */
+export const WARNING_IDS_SHOWN = 5;
+
+/**
+ * One warning line per unrecognised word (the trimmed word as written, in
+ * first-seen order): its count, then at most WARNING_IDS_SHOWN ids, then
+ * "+N more" when there are more.
+ */
+export function warningLines(unrecognisedStatuses) {
+  const byWord = new Map();
+  for (const w of Array.isArray(unrecognisedStatuses) ? unrecognisedStatuses : []) {
+    if (!isPlainObject(w)) continue;
+    const word = String(w.word ?? '').trim();
+    if (!byWord.has(word)) byWord.set(word, []);
+    byWord.get(word).push(w.id ?? '(no id)');
+  }
+  const lines = [];
+  for (const [word, ids] of byWord) {
+    const more = ids.length - WARNING_IDS_SHOWN;
+    lines.push('warning: unrecognised status "' + word + '" on ' + plural(ids.length, 'dispatch', 'dispatches') + ': '
+      + ids.slice(0, WARNING_IDS_SHOWN).join(', ') + (more > 0 ? ' +' + more + ' more' : ''));
+  }
+  return lines;
+}
+
+/**
+ * Human lines: one per problem, one per unrecognised word (a count and at
+ * most five ids each), then the summary line.
+ */
+export function renderHuman(agent, result) {
+  const lines = [];
+  for (const p of result.problems) lines.push('problem: ' + p.message);
+  lines.push(...warningLines(result.unrecognisedStatuses));
+  lines.push(summaryLine(agent, result));
+  return lines.join('\n') + '\n';
+}
+
+function oneLine(text, max) {
+  const flat = String(text).replace(/\s+/g, ' ').trim();
+  const cps = Array.from(flat);
+  return cps.length > max ? cps.slice(0, max).join('') + '...' : flat;
+}
+
+function envelope(context) {
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context } });
+}
+
+function fitSections(fixed, sections, footer, budget) {
+  const MORE_RESERVE = '- +99999 more'.length + 1;
+  const out = [...fixed];
+  let used = fixed.reduce((s, l) => s + l.length + 1, 0) + footer.reduce((s, l) => s + l.length + 1, 0);
+  for (const sec of sections) {
+    if (!sec.lines.length) continue;
+    if (used + sec.heading.length + 1 + MORE_RESERVE > budget) {
+      out.push('- +' + sec.lines.length + ' more ' + sec.unit);
+      used += MORE_RESERVE;
+      continue;
+    }
+    out.push(sec.heading);
+    used += sec.heading.length + 1;
+    for (let i = 0; i < sec.lines.length; i++) {
+      const line = sec.lines[i];
+      const rest = sec.lines.length - i - 1;
+      const reserve = rest > 0 ? MORE_RESERVE : 0;
+      if (used + line.length + 1 + reserve > budget) {
+        out.push('- +' + (sec.lines.length - i) + ' more');
+        used += MORE_RESERVE;
+        break;
+      }
+      out.push(line);
+      used += line.length + 1;
+    }
+  }
+  return [...out, ...footer].join('\n');
+}
+
+/**
+ * The SessionStart additionalContext for a finished check: the board's age,
+ * the open dispatches, the untagged ones and those with no board item, then
+ * the same problem lines as the human output. Lists are cut with a
+ * "+N more" line so the whole envelope stays under 2,000 characters; counts
+ * are never cut.
+ */
+export function buildHookEnvelope(agent, result, hasInitiatives) {
+  const live = result.open.live.length;
+  const stale = result.open.stale.length;
+  const untagged = result.problems.filter((p) => p.kind === 'untagged').length;
+  const fixed = [
+    '## Board check (live), agent ' + agent,
+    result.board.present
+      ? 'Board: updated ' + formatAge(result.board.ageMinutes) + ' ago (' + result.board.updatedAt + ').'
+      : 'Board: none yet.',
+    'Open dispatches: ' + (live + stale) + ' (' + live + ' live, ' + stale + ' stale). Not on the board: '
+      + result.openNotOnBoard.length + '. Untagged: ' + (hasInitiatives ? untagged : 'not checked (no initiatives records)') + '.',
+  ];
+  const openLines = [...result.open.live.map((d) => ({ ...d, state: 'live' })), ...result.open.stale.map((d) => ({ ...d, state: 'stale' }))]
+    .map((d) => {
+      const flags = [d.state];
+      if (result.openNotOnBoard.some((x) => x.id === d.id)) flags.push('not on board');
+      if (hasInitiatives && d.initiative === null) flags.push('untagged');
+      return '- ' + (d.id ?? '(no id)') + ' [' + flags.join(', ') + '] ' + oneLine(d.description, 90);
+    });
+  const problemLines = result.problems.map((p) => '- ' + oneLine(p.message, p.kind === 'lock-held' ? 360 : 160));
+  const footer = [];
+  if (result.unrecognisedStatuses.length) {
+    footer.push('Unrecognised status words: ' + result.unrecognisedStatuses.length + ' (warnings; `pa board check` lists them).');
+  }
+  footer.push(result.problems.length
+    ? 'Result: ' + plural(result.problems.length, 'problem', 'problems') + '. Put every open dispatch on the board, refresh it, and run `pa board check` until it passes.'
+    : 'Result: clean.');
+
+  let budget = HOOK_ENVELOPE_MAX_CHARS - 150;
+  for (;;) {
+    const context = fitSections(fixed, [
+      { heading: 'Problems (' + problemLines.length + '):', lines: problemLines, unit: 'problems' },
+      { heading: 'Open dispatches (' + openLines.length + '):', lines: openLines, unit: 'open dispatches' },
+    ], footer, budget);
+    const text = envelope(context);
+    if (text.length < HOOK_ENVELOPE_MAX_CHARS || budget <= 300) return text;
+    budget -= 100;
+  }
+}
+
+/** An envelope for a check that could not run or was called wrongly. */
+export function buildFailureEnvelope(message) {
+  const context = '## Board check (live)\nThe board check could not run: ' + oneLine(message, 400)
+    + '\nRun `pa board check` in a terminal to see why, and fix the board before the next action.';
+  return envelope(context);
+}
+
+// -- CLI --------------------------------------------------------------------
+
+const ALLOWED = ['json', 'hook-envelope', 'agent', 'help'];
+const BOOLEAN = new Set(['json', 'hook-envelope', 'help']);
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '-h') { flags.help = true; continue; }
+    if (!a.startsWith('--')) throw new UsageError('unexpected argument: ' + a);
+    const eq = a.indexOf('=');
+    const key = eq === -1 ? a.slice(2) : a.slice(2, eq);
+    if (!ALLOWED.includes(key)) throw new UsageError('unknown flag: --' + key);
+    if (BOOLEAN.has(key)) {
+      if (eq !== -1) throw new UsageError('--' + key + ' takes no value');
+      flags[key] = true;
+      continue;
+    }
+    if (eq !== -1) { flags[key] = a.slice(eq + 1); continue; }
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) throw new UsageError('--' + key + ' needs a value');
+    flags[key] = v;
+    i += 1;
+  }
+  if (flags.json && flags['hook-envelope']) throw new UsageError('give --json or --hook-envelope, not both');
+  return flags;
+}
+
+async function gather(repoRoot, agent) {
+  const spawnLogFile = join(repoRoot, 'agents', agent, 'spawn-log.json');
+  let log;
+  try {
+    log = readSpawnLogSync(spawnLogFile);
+  } catch (e) {
+    if (e instanceof SpawnLogError) {
+      throw new PreconditionError(e.message.replace(spawnLogFile, spawnLogRelPath(agent)));
+    }
+    throw e;
+  }
+  let parsed;
+  try {
+    parsed = await readBoard(boardPath(repoRoot, agent), { strictStatus: false });
+  } catch (e) {
+    if (e instanceof SyntaxError) throw new PreconditionError('board at ' + boardRelPath(agent) + ' is not valid JSON: ' + e.message);
+    throw new PreconditionError('could not read the board at ' + boardRelPath(agent) + ': ' + (e.message || e));
+  }
+  if (parsed && parsed.problems.length) {
+    throw new PreconditionError('board at ' + boardRelPath(agent) + ' does not match the schema: ' + parsed.problems.join('; '));
+  }
+  const initiatives = readInitiativesSync(repoRoot);
+  // Read-only: the lock file is read, never written, broken or swept.
+  let lock = null;
+  try { lock = await readSpawnLogLock(spawnLogFile); } catch { lock = null; }
+  return {
+    board: parsed ? parsed.board : null,
+    dispatches: log.dispatches,
+    questions: initiatives.questions,
+    hasInitiatives: initiatives.hasRecords,
+    lock,
+    lockRelPath: spawnLogRelPath(agent) + '.lock',
+  };
+}
+
+/**
+ * @param {string[]} argv  argv after `board` (subverb first)
+ * @param {object} [opts]  test seams: repoRoot, now, stdout, stderr
+ */
+export async function run(argv, opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const args = Array.isArray(argv) ? argv : [];
+  const hookMode = args.includes('--hook-envelope');
+  try {
+    const verb = args[0];
+    if ((verb === '-h' || verb === '--help') && !hookMode) { out.write(USAGE); return 0; }
+    if (verb === undefined) throw new UsageError('pa board needs a subverb: check');
+    if (!SUBVERBS.includes(verb)) throw new UsageError('unknown subverb: ' + verb);
+    const flags = parseFlags(args.slice(1));
+    if (flags.help && !hookMode) { out.write(USAGE); return 0; }
+    if (flags.agent !== undefined && !isValidAgentName(flags.agent)) {
+      throw new UsageError('--agent must be a lowercase agent folder name, got "' + flags.agent + '"');
+    }
+
+    let repoRoot = opts.repoRoot;
+    if (!repoRoot) {
+      try {
+        repoRoot = await getRepoRoot();
+      } catch (e) {
+        throw new PreconditionError(e.message || String(e));
+      }
+    }
+    const agent = flags.agent ?? resolveAgentName(repoRoot);
+    let input;
+    try {
+      input = await gather(repoRoot, agent);
+    } catch (e) {
+      if (e instanceof PreconditionError && flags.json) {
+        out.write(JSON.stringify({ ok: false, exitCode: 3, agent, error: e.message }, null, 2) + '\n');
+      }
+      throw e;
+    }
+    const result = checkBoard({ ...input, now: opts.now });
+
+    if (hookMode) {
+      out.write(buildHookEnvelope(agent, result, input.hasInitiatives) + '\n');
+      return 0;
+    }
+    if (flags.json) {
+      const payload = {
+        ok: result.ok,
+        exitCode: result.exitCode,
+        agent,
+        board: { path: boardRelPath(agent), ...result.board },
+        spawnLog: { path: spawnLogRelPath(agent) },
+        open: result.open,
+        problems: result.problems,
+        unrecognisedStatuses: result.unrecognisedStatuses,
+      };
+      out.write(JSON.stringify(payload, null, 2) + '\n');
+      return result.exitCode;
+    }
+    out.write(renderHuman(agent, result));
+    return result.exitCode;
+  } catch (e) {
+    if (hookMode) {
+      const prefix = e instanceof UsageError ? 'usage error: ' : '';
+      out.write(buildFailureEnvelope(prefix + (e && e.message ? e.message : String(e))) + '\n');
+      return 0;
+    }
+    err.write('[pa board] ' + (e && e.message ? e.message : String(e)) + '\n');
+    if (e instanceof UsageError) {
+      err.write('Run `pa board check --help` for usage.\n');
+      return 1;
+    }
+    return 3;
+  }
+}