sentinelayer-cli 0.41.0 → 0.42.0

package/README.md

@@ -138,6 +138,24 @@ daemon per session is enforced via `senti-daemon.json` in the session directory
 (logs in `senti-daemon.log` next to it), and the daemon exits on its own when
 the session expires.
 
+Startup uses optional cached `.sentinelayer/CODEBASE_INGEST.json` context only;
+it does not recursively scan your working directory. A missing, invalid, oversized
+or slow cache yields empty context. Run `sl ingest map --path .` separately
+when you need a full scan. The cache reader has a 750ms budget and is terminated
+before returning; resume probes have a 2s deadline per attempt (one retry), while
+the existing workspace-list lookup keeps its 5s deadline. Optional title,
+metadata and welcome synchronization are bounded; startup does not rotate auth
+or wait through a title `Retry-After` retry. No hard wall-clock guarantee applies
+to required local filesystem writes or a stalled OS filesystem.
+
+With `--json`, stdout remains one JSON document. `remoteSync.status` reports
+`synced` only after metadata acknowledgement, otherwise `degraded` (or the
+existing `disabled`/`auth_required` states). `firstMessage.posted` retains its
+**local stream durability** meaning; `firstMessage.remoteSynced` and
+`firstMessage.remoteSync` separately report API acknowledgement/failure. An
+acknowledgement is not a browser or teammate-access test. A transient resume
+timeout keeps the existing local ID rather than minting a duplicate.
+
 Then point your agents at it:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {
@@ -12,7 +12,8 @@
     "test:e2e": "node --import ./tests/setup-env.mjs --test tests/e2e*.test.mjs",
     "test:coverage": "c8 node --import ./tests/setup-env.mjs --test tests/unit*.test.mjs",
     "verify": "npm run check && npm run docs:build && npm run test:e2e && npm run test:coverage && npm pack --dry-run",
-    "release:publish": "node scripts/release-publish.mjs"
+    "release:publish": "node scripts/release-publish.mjs",
+    "test:conformance": "node --import ./tests/setup-env.mjs --test tests/conformance.engram-21-3.test.mjs"
   },
   "bin": {
     "sentinelayer-cli": "bin/sentinelayer-cli.js",

package/src/auth/admission-scope.js

@@ -0,0 +1,34 @@
+// admission-scope.js — the admitted-agent scope, as a leaf module.
+//
+// While a command runs as an admitted agent (see src/session/admission-auth.js),
+// this AsyncLocalStorage holds its admission credential. resolveActiveAuthSession
+// consults it FIRST, so every credential lookup made anywhere inside the command --
+// session transport, remote verification, confirmation reads, helpers of helpers --
+// gets the admission credential or nothing. The human's own token is unreachable
+// from inside the scope, so no human-authenticated subrequest can hide behind a
+// scoped main request.
+//
+// It imports nothing from this codebase, so the auth service can depend on it
+// without an import cycle.
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const admittedAgentScope = new AsyncLocalStorage();
+
+/**
+ * undefined -> not inside an admitted-agent scope (resolve auth normally)
+ * null      -> inside one, but the credential has expired: nothing to send
+ * object    -> the admission credential, bound to the API that issued it
+ */
+export function scopedAdmissionAuth() {
+  const credential = admittedAgentScope.getStore();
+  if (!credential) return undefined;
+  if (!(credential.expiresAt * 1000 > Date.now())) return null;
+  return {
+    apiUrl: credential.apiUrl,
+    token: credential.token,
+    source: "session_admission",
+    user: null,
+    admissionId: credential.admissionId,
+  };
+}

package/src/auth/gate.js

@@ -5,6 +5,7 @@ import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 import { resolveActiveAuthSession } from "./service.js";
+import { resolveAgentAdmissionTarget } from "../session/admission-auth.js";
 import { authLoginHint } from "../ui/command-hints.js";
 
 /**
@@ -383,6 +384,11 @@ export async function checkAuthGate(args) {
     resolveError = error instanceof Error ? `session_read_error: ${error.message}` : "session_read_error";
   }
 
+  // An agent command whose admission is stored here: its credential IS the admission
+  // (runCli then dispatches it inside that scope, or it refuses a tombstone).
+  if (await resolveAgentAdmissionTarget(args)) {
+    return { authenticated: true, session: null, bypassReason: "session_admission", failureReason: null };
+  }
   return { authenticated: false, session: null, bypassReason: null, failureReason: resolveError };
 }
 

package/src/auth/http.js

@@ -3,6 +3,10 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { installTestEgressGuard } from "../net/test-egress-guard.js";
+
+// No-op outside tests; see src/net/test-egress-guard.js.
+installTestEgressGuard();
 
 /**
  * Default timeout applied to Sentinelayer API requests when no override is provided.

package/src/auth/service.js

@@ -5,6 +5,7 @@ import { setTimeout as sleep } from "node:timers/promises";
 import open from "open";
 
 import { loadConfig } from "../config/service.js";
+import { scopedAdmissionAuth } from "./admission-scope.js";
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "./http.js";
 import {
   clearStoredSession,
@@ -667,6 +668,11 @@ export async function resolveActiveAuthSession({
   tokenTtlDays = DEFAULT_API_TOKEN_TTL_DAYS,
   homeDir,
 } = {}) {
+  // Inside an admitted agent's command the ONLY credential is its admission (or,
+  // once expired, none). The human token is never reachable from there.
+  const scoped = scopedAdmissionAuth();
+  if (scoped !== undefined) return scoped;
+
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
 
   const envToken = String(env.SENTINELAYER_TOKEN || "").trim();

package/src/board/done-gate.js

@@ -0,0 +1,155 @@
+/**
+ * BOARD — the deterministic done-gate.
+ *
+ * Carter's ask (room 431032) was "the free in-house model checks to see if items are
+ * done and marks them done, so I know it's done." A model deciding done-ness defeats
+ * the thing the board is for: the instant "done" means "Gemma believed it", the mark
+ * is worth nothing and he is back to checking everything himself. **A ticket wrongly
+ * marked done is worse than one left open** — an open ticket still has his attention,
+ * a closed one has left his field of view.
+ *
+ * So: the model may PROPOSE a link between a ticket and some evidence. Only a
+ * deterministic check of a verifiable fact may STAMP it. Model proposes, evidence
+ * disposes. Nothing in this file imports a model, and that is structural, not stylistic.
+ *
+ * THREE STATES, NOT TWO — the point of the module:
+ *
+ *   done           the evidence was checked and it holds
+ *   not-done       the evidence was checked and it does not hold
+ *   cannot-verify  the check could not be made
+ *
+ * `cannot-verify` must never collapse into either neighbour. Folding it into
+ * `not-done` nags about finished work until the board is ignored; folding it into
+ * `done` closes tickets nobody completed, which is the failure that makes the whole
+ * board worthless. An unknown answer gets its own name and refuses — the same shape as
+ * `absent | building | ready` in the engram lifecycle.
+ *
+ * PURE BY CONSTRUCTION: the actual lookups are INJECTED as a resolver. This module
+ * decides what the evidence MEANS; it never fetches anything. That makes every branch
+ * — including every failure branch — reachable in a test without a network.
+ */
+
+export const VERDICTS = Object.freeze({
+  DONE: "done",
+  NOT_DONE: "not-done",
+  CANNOT_VERIFY: "cannot-verify",
+});
+
+/**
+ * The evidence kinds a ticket may claim. CLOSED SET: an unrecognised kind resolves to
+ * `cannot-verify`, never to a guess. Adding a kind is a deliberate edit here plus a
+ * resolver that can answer it.
+ */
+export const EVIDENCE_KINDS = Object.freeze({
+  /** A pull request is merged. { repo, number } */
+  PR_MERGED: "pr-merged",
+  /** A commit is an ancestor of the named branch. { repo, sha, branch } */
+  SHA_ON_BRANCH: "sha-on-branch",
+  /** A named check concluded successfully on a ref. { repo, ref, check } */
+  CHECK_CONCLUSIVE: "check-conclusive",
+  /** A deployment is serving the named build. { service, sha } */
+  DEPLOY_SHA: "deploy-sha",
+});
+
+const KIND_REQUIRED_FIELDS = Object.freeze({
+  [EVIDENCE_KINDS.PR_MERGED]: ["repo", "number"],
+  [EVIDENCE_KINDS.SHA_ON_BRANCH]: ["repo", "sha", "branch"],
+  [EVIDENCE_KINDS.CHECK_CONCLUSIVE]: ["repo", "ref", "check"],
+  [EVIDENCE_KINDS.DEPLOY_SHA]: ["service", "sha"],
+});
+
+function cannotVerify(reason) {
+  return { verdict: VERDICTS.CANNOT_VERIFY, reason };
+}
+
+/**
+ * Validate an evidence descriptor's SHAPE before anything is looked up.
+ *
+ * A malformed descriptor is `cannot-verify`, never `not-done`: we did not learn that
+ * the work is incomplete, only that the ticket does not say how to check it.
+ */
+export function describeEvidence(evidence) {
+  if (!evidence || typeof evidence !== "object") {
+    return cannotVerify("evidence is missing");
+  }
+  const kind = typeof evidence.kind === "string" ? evidence.kind.trim() : "";
+  if (!kind) return cannotVerify("evidence has no kind");
+  const required = KIND_REQUIRED_FIELDS[kind];
+  if (!required) return cannotVerify(`unrecognised evidence kind: ${kind}`);
+  const missing = required.filter((field) => {
+    const value = evidence[field];
+    return value === undefined || value === null || (typeof value === "string" && !value.trim());
+  });
+  if (missing.length > 0) {
+    return cannotVerify(`evidence kind ${kind} is missing: ${missing.join(", ")}`);
+  }
+  return { verdict: null, kind, required };
+}
+
+/**
+ * Decide whether a ticket's evidence holds.
+ *
+ * @param {object} evidence   the ticket's evidence claim
+ * @param {object} deps
+ * @param {(evidence:object)=>Promise<boolean|null>} deps.resolve
+ *        Performs the lookup. `true` -> the fact holds, `false` -> it does not,
+ *        `null`/`undefined` -> INDETERMINATE. A thrown error is also indeterminate:
+ *        an unreachable API tells us nothing about the work, so it must not be
+ *        reported as either answer.
+ * @returns {Promise<{verdict:string, reason?:string, kind?:string}>}
+ */
+export async function checkDone(evidence, { resolve } = {}) {
+  const shape = describeEvidence(evidence);
+  if (shape.verdict === VERDICTS.CANNOT_VERIFY) return shape;
+
+  if (typeof resolve !== "function") {
+    return cannotVerify("no resolver was provided");
+  }
+
+  let answer;
+  try {
+    answer = await resolve(evidence);
+  } catch (error) {
+    // An unreachable resolver is not evidence of incompleteness.
+    const detail = error && error.message ? error.message : String(error);
+    return { ...cannotVerify(`resolver failed: ${detail}`), kind: shape.kind };
+  }
+
+  if (answer === true) return { verdict: VERDICTS.DONE, kind: shape.kind };
+  if (answer === false) return { verdict: VERDICTS.NOT_DONE, kind: shape.kind };
+  return { ...cannotVerify("resolver returned an indeterminate answer"), kind: shape.kind };
+}
+
+/**
+ * Decide a whole ticket, which may carry several pieces of evidence.
+ *
+ * ALL of them must hold. One `not-done` makes the ticket not done; otherwise a single
+ * `cannot-verify` makes the whole ticket unverifiable. A ticket is never `done` on a
+ * partial reading of its own evidence — that would let an unreachable check quietly
+ * become a passing one, which is `cannot-verify` collapsing into `done` by the back
+ * door rather than the front.
+ *
+ * A ticket claiming NO evidence is `cannot-verify`: nothing about it can be checked,
+ * and it must not be closable by a checker.
+ */
+export async function checkTicketDone(ticket, deps = {}) {
+  const claims = Array.isArray(ticket?.evidence) ? ticket.evidence : [];
+  if (claims.length === 0) {
+    return { verdict: VERDICTS.CANNOT_VERIFY, reason: "ticket claims no evidence", results: [] };
+  }
+
+  const results = [];
+  for (const claim of claims) {
+    results.push(await checkDone(claim, deps));
+  }
+
+  const notDone = results.find((r) => r.verdict === VERDICTS.NOT_DONE);
+  if (notDone) {
+    return { verdict: VERDICTS.NOT_DONE, reason: notDone.reason ?? "an evidence claim does not hold", results };
+  }
+  const unverifiable = results.find((r) => r.verdict === VERDICTS.CANNOT_VERIFY);
+  if (unverifiable) {
+    return { verdict: VERDICTS.CANNOT_VERIFY, reason: unverifiable.reason, results };
+  }
+  return { verdict: VERDICTS.DONE, results };
+}

package/src/board/evidence-resolvers.js

@@ -0,0 +1,138 @@
+/**
+ * BOARD — resolvers: the code that actually asks whether a ticket's evidence holds.
+ *
+ * `done-gate.js` decides what an answer MEANS. This decides what the answer IS. The
+ * split matters because the gate must stay pure and testable while the lookups are
+ * inherently messy — networks time out, repos get renamed, tokens expire.
+ *
+ * THE ONE RULE THAT GOVERNS EVERY RESOLVER HERE:
+ *
+ *   true   the fact was checked and HOLDS
+ *   false  the fact was checked and DOES NOT hold
+ *   null   we could not find out
+ *
+ * `null` is not a failure to be tidied away into `false`. **"I could not reach GitHub"
+ * and "the PR is not merged" are different facts, and only one of them is about the
+ * work.** Collapsing them means every network blip re-opens finished tickets until
+ * nobody trusts the board.
+ *
+ * THE SUBTLER HALF, and the one this file exists to get right: **absence is not
+ * failure.** A check that has not started yet contributes no row and no conclusion.
+ * Reading that silence as `false` is the same defect as reading a missing CI row as
+ * green, just pointed the other way — and it is the mistake most likely to be made by
+ * someone writing these resolvers in a hurry.
+ *
+ * Every lookup is INJECTED (`run`), so each branch above -- including every failure
+ * branch -- is reachable in a test without a network.
+ */
+
+/** Shape a resolver must return. Anything else is treated as indeterminate. */
+const YES = true;
+const NO = false;
+const UNKNOWN = null;
+
+function parseJson(stdout) {
+  try {
+    return JSON.parse(String(stdout ?? ""));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {(argv:string[])=>Promise<{ok:boolean,stdout?:string,stderr?:string}>} deps.run
+ *        Executes a `gh` invocation. `ok:false` means the call failed for ANY reason
+ *        -- that is indeterminate, never a negative verdict.
+ * @param {(sha:string)=>Promise<boolean|null>} [deps.probeDeployedSha]
+ *        Optional. Without it, `deploy-sha` evidence resolves to UNKNOWN rather than
+ *        being guessed at -- this module will not pretend to know what is live.
+ */
+export function createEvidenceResolver({ run, probeDeployedSha } = {}) {
+  if (typeof run !== "function") throw new TypeError("a run() is required");
+
+  async function prMerged({ repo, number }) {
+    const res = await run(["pr", "view", String(number), "--repo", repo, "--json", "state,mergedAt"]);
+    if (!res || !res.ok) return UNKNOWN; // unreachable, missing, or unauthorised
+    const data = parseJson(res.stdout);
+    if (!data || typeof data.state !== "string") return UNKNOWN;
+    if (data.state === "MERGED") return YES;
+    // OPEN or CLOSED-without-merge is a real negative: the PR exists and did not merge.
+    if (data.state === "OPEN" || data.state === "CLOSED") return NO;
+    return UNKNOWN;
+  }
+
+  async function shaOnBranch({ repo, sha, branch }) {
+    const res = await run(["api", `repos/${repo}/compare/${branch}...${sha}`, "--jq", ".status"]);
+    if (!res || !res.ok) return UNKNOWN;
+    const status = String(res.stdout ?? "").trim();
+    // GitHub's compare status, base=branch head=sha:
+    //   identical / behind -> sha is contained in branch
+    //   ahead / diverged   -> it is not
+    if (status === "identical" || status === "behind") return YES;
+    if (status === "ahead" || status === "diverged") return NO;
+    return UNKNOWN;
+  }
+
+  async function checkConclusive({ repo, ref, check }) {
+    const res = await run(["api", `repos/${repo}/commits/${ref}/check-runs`, "--jq", ".check_runs"]);
+    if (!res || !res.ok) return UNKNOWN;
+    const runs = parseJson(res.stdout);
+    if (!Array.isArray(runs)) return UNKNOWN;
+
+    const named = runs.filter((r) => r && r.name === check);
+    // ABSENCE IS NOT FAILURE. A check that never started contributes no row, so an
+    // empty match means we do not know -- exactly the "missing row reads as green"
+    // trap, inverted. Reporting NO here would mark finished work as incomplete
+    // whenever a workflow was renamed or skipped.
+    if (named.length === 0) return UNKNOWN;
+
+    // Any still running -> the answer is not in yet.
+    if (named.some((r) => r.status !== "completed")) return UNKNOWN;
+
+    const conclusions = named.map((r) => r.conclusion);
+    if (conclusions.every((c) => c === "success" || c === "skipped")) return YES;
+    if (conclusions.some((c) => c === "failure" || c === "timed_out" || c === "cancelled")) return NO;
+    return UNKNOWN;
+  }
+
+  async function deploySha({ sha }) {
+    if (typeof probeDeployedSha !== "function") return UNKNOWN;
+    try {
+      const live = await probeDeployedSha(sha);
+      return live === true ? YES : live === false ? NO : UNKNOWN;
+    } catch {
+      return UNKNOWN;
+    }
+  }
+
+  const BY_KIND = {
+    "pr-merged": prMerged,
+    "sha-on-branch": shaOnBranch,
+    "check-conclusive": checkConclusive,
+    "deploy-sha": deploySha,
+  };
+
+  /**
+   * The function `checkDone` expects: evidence -> true | false | null.
+   * An unrecognised kind returns UNKNOWN here, though the gate refuses it before we
+   * are ever called -- defence in depth, since this module is exported on its own.
+   */
+  return async function resolve(evidence) {
+    const handler = BY_KIND[evidence?.kind];
+    if (!handler) return UNKNOWN;
+    return handler(evidence);
+  };
+}
+
+/** A `run` backed by the real `gh` CLI. Never throws: a failure is indeterminate. */
+export function createGhRunner({ spawn }) {
+  return async function run(argv) {
+    try {
+      const res = await spawn("gh", argv);
+      return { ok: res.code === 0, stdout: res.stdout, stderr: res.stderr };
+    } catch (error) {
+      return { ok: false, stderr: error?.message ?? String(error) };
+    }
+  };
+}

package/src/cli.js

@@ -14,6 +14,11 @@ const COMMAND_REGISTRARS = {
     exportName: "registerOmarGateCommand",
     needsLegacy: true,
   },
+  board: {
+    loader: () => import("./commands/board.js"),
+    exportName: "registerBoardCommand",
+    needsLegacy: false,
+  },
   audit: {
     loader: () => import("./commands/audit.js"),
     exportName: "registerAuditCommand",
@@ -257,6 +262,24 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
     invokeLegacy: runLegacyCliWithErrorHandling,
     onlyCommand: normalizedArgs[0],
   });
-  await program.parseAsync(["node", "sentinelayer-cli", ...normalizedArgs]);
+  const dispatch = () => program.parseAsync(["node", "sentinelayer-cli", ...normalizedArgs]);
+
+  // THE choke point for agent authority: a `session` command naming an agent whose
+  // admission is stored here runs entirely inside that admission's scope, whatever
+  // the subcommand (say, post-agent, observe, locks, checkpoints, ...), so no
+  // subcommand, present or future, can reach the human token. A tombstoned
+  // admission refuses here, before any request.
+  const { assertDispatchMatchesScope, resolveAgentAdmissionTarget, withAgentAdmission } = await import(
+    "./session/admission-auth.js"
+  );
+  const target = await resolveAgentAdmissionTarget(normalizedArgs);
+  // Execution must match authorization: before ANY action runs, re-derive the identity
+  // from Commander's resolved options and compare it with the scope in force.
+  program.hook("preAction", (_hooked, actionCommand) => assertDispatchMatchesScope(actionCommand));
+  if (target) {
+    await withAgentAdmission(target.sessionId, target.agentId, dispatch);
+    return;
+  }
+  await dispatch();
 }
 

package/src/commands/board.js

@@ -0,0 +1,116 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { spawn as nodeSpawn } from "node:child_process";
+
+import { VERDICTS, checkTicketDone } from "../board/done-gate.js";
+import { createEvidenceResolver, createGhRunner } from "../board/evidence-resolvers.js";
+
+/**
+ * `sl board check` — ask whether a ticket's evidence actually holds.
+ *
+ * This is the command that makes the done-gate real. Without a caller, the gate and
+ * its resolvers are correct code that never runs, which this repo established the
+ * hard way tonight.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: mark anything done. It reports a verdict and
+ * exits. Closing a ticket is a write, and a checker that closes tickets on its own
+ * judgement is the thing the whole design exists to prevent -- a model or a script
+ * deciding "done" instead of a person acting on verified evidence.
+ *
+ * EXIT CODES, chosen so a script cannot mistake one outcome for another:
+ *   0  done           every claim was checked and holds
+ *   1  not-done       a claim was checked and does not hold
+ *   2  cannot-verify  something could not be checked -- NOT a failure of the work
+ *
+ * `cannot-verify` gets its own code rather than sharing with `not-done`, because a
+ * caller that treats "GitHub was down" as "the work is incomplete" reintroduces the
+ * collapse at the shell level, one layer below where we prevented it.
+ */
+
+function spawnCapture(cmd, argv) {
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    const child = nodeSpawn(cmd, argv, { stdio: ["ignore", "pipe", "pipe"] });
+    child.on("error", reject);
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.stderr.on("data", (d) => { stderr += d; });
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+const EXIT = {
+  [VERDICTS.DONE]: 0,
+  [VERDICTS.NOT_DONE]: 1,
+  [VERDICTS.CANNOT_VERIFY]: 2,
+};
+
+/**
+ * Read a ticket from a JSON file: `{ id?, title?, evidence: [ ... ] }`.
+ * A file that is missing, unreadable or unparseable is CANNOT-VERIFY, never NOT-DONE:
+ * we learned nothing about the work, only about the file.
+ */
+export async function loadTicket(file) {
+  let raw;
+  try {
+    raw = await fsp.readFile(file, "utf-8");
+  } catch (error) {
+    return { error: `cannot read ticket file: ${error?.message ?? error}` };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return { error: "ticket file is not an object" };
+    return { ticket: parsed };
+  } catch (error) {
+    return { error: `ticket file is not valid JSON: ${error?.message ?? error}` };
+  }
+}
+
+export async function runBoardCheck({ file, emitJson, deps = {} } = {}) {
+  const { ticket, error } = await loadTicket(file);
+  if (error) {
+    const out = { verdict: VERDICTS.CANNOT_VERIFY, reason: error };
+    print(out, emitJson);
+    return EXIT[VERDICTS.CANNOT_VERIFY];
+  }
+
+  const run = deps.run ?? createGhRunner({ spawn: deps.spawn ?? spawnCapture });
+  const resolve = deps.resolve ?? createEvidenceResolver({ run });
+  const result = await checkTicketDone(ticket, { resolve });
+
+  print({ ...result, ticket: ticket.id ?? ticket.title ?? path.basename(file) }, emitJson);
+  return EXIT[result.verdict] ?? EXIT[VERDICTS.CANNOT_VERIFY];
+}
+
+function print(result, emitJson) {
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+  const lines = [`verdict: ${result.verdict}`];
+  if (result.reason) lines.push(`reason:  ${result.reason}`);
+  for (const r of result.results ?? []) {
+    lines.push(`  - ${r.kind ?? "?"}: ${r.verdict}${r.reason ? ` (${r.reason})` : ""}`);
+  }
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
+export function registerBoardCommand(program) {
+  const board = program.command("board").description("Check ticket evidence deterministically");
+
+  board
+    .command("check")
+    .description("Check whether a ticket's evidence holds (done | not-done | cannot-verify)")
+    .requiredOption("--file <path>", "Ticket JSON file with an `evidence` array")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options) => {
+      const code = await runBoardCheck({
+        file: path.resolve(process.cwd(), String(options.file)),
+        emitJson: Boolean(options.json),
+      });
+      process.exitCode = code;
+    });
+
+  return board;
+}