@thebattlearena/corner 0.10.1-beta.78 → 0.10.1-beta.80

package/ring/scripts/brief.mjs

@@ -42,6 +42,10 @@ import {
   ringHome,
   RING_ROOT,
 } from './config.mjs';
+import { recallSection } from './engram.mjs';
+import { conceptsSinceRelay, relayDue } from './relay.mjs';
+import { reviewTurn } from './review-blocks.mjs';
+import { setPlanState } from './tech-plan-log.mjs';
 import { loadRules } from './rule-ids.mjs';
 
 const TEMPLATES = join(RING_ROOT, 'skills', 'referee', 'templates');
@@ -162,9 +166,23 @@ function boutVars({ dir, state, config }, values) {
   };
 }
 
+/** The open rebounds the human's review sent back, as a section of the brief (none: nothing). */
+function humanReview(dir) {
+  const path = join(dir, 'rebounds.md');
+  const open = (existsSync(path) ? readFileSync(path, 'utf8') : '')
+    .split('\n')
+    .filter((line) => /^- \[ \] .*Revisión humana/.test(line));
+  return open.length
+    ? [
+        '## Sent back by the human review (PR Review Lab; fix these first, the Tape shows what failed)',
+        open.join('\n'),
+      ]
+    : [];
+}
+
 const real = (path) => (existsSync(path) ? realpathSync(path) : path);
 
-function generate(kind, [pr, ...argv]) {
+async function generate(kind, [pr, ...argv]) {
   const { values } = flags(argv);
   const shape = SHAPES[kind]?.[values.mode];
   if (!pr || !shape)
@@ -172,6 +190,21 @@ function generate(kind, [pr, ...argv]) {
       `usage: ${kind} <pr> --mode ${Object.keys(SHAPES[kind]).join('|')} --vars <file.json>`,
     );
   const bout = boutOf(pr);
+  if (kind === 'wrestler' && relayDue(bout.state, bout.config.relayEvery))
+    throw new Error(
+      `a relay is due (${conceptsSinceRelay(bout.state)} concepts since the last one): rewrite the card's «How to resume», run judges-card.mjs relay ${pr}, then brief the next wrestler`,
+    );
+  if (kind === 'wrestler') {
+    // The human's verdicts from PR Review Lab first: a fail comes back as a rebound for this brief.
+    const turn = reviewTurn(
+      bout.dir,
+      bout.config.humanReviewEvery,
+      (n, to, ref) => setPlanState(bout.dir, n, to, ref),
+    );
+    if (turn.applied.length)
+      console.error(`human review applied: ${turn.applied.join(' · ')}`);
+    if (turn.due) throw new Error(turn.due);
+  }
   const own = values.vars ? JSON.parse(readFileSync(values.vars, 'utf8')) : {};
   const roots = [
     projectDir(),
@@ -198,6 +231,15 @@ function generate(kind, [pr, ...argv]) {
     files,
   );
   const rules = rulesOf(bout.config);
+  // What earlier bouts of the repo learned on these files, from Engram when it answers: context
+  // after the decisions and before the rules, never in their place (a cut-off resumes as it was).
+  const learned = shape.rules
+    ? await recallSection(bout.config, {
+        slug: repoSlug(projectDir()),
+        pr,
+        files,
+      })
+    : null;
   // The task goes first and the rules last, as the reference: a brief that opens with the rules
   // reads as a checklist, and a 2026-11 lab on #1212 found fewer real problems that way.
   const body = [
@@ -205,6 +247,8 @@ function generate(kind, [pr, ...argv]) {
     '## Decisions already taken (excerpt: every foul, the ones on these files, the last 20)',
     decisions,
     `The whole ledger: \`${decisionsPath}\`.`,
+    ...humanReview(bout.dir),
+    ...(learned ? [learned] : []),
     ...(shape.rules ? ['---', rules.block] : []),
   ].join('\n\n');
   const briefs = join(bout.dir, 'briefs');
@@ -264,7 +308,7 @@ if (isMain(import.meta.url)) {
       throw new Error(
         'usage: brief.mjs wrestler|cornerman <pr> --mode … | verify <brief.md>',
       );
-    generate(command, rest);
+    await generate(command, rest);
   } catch (error) {
     console.error(`brief: ${error.message}`);
     process.exit(1);

package/ring/scripts/config.mjs

@@ -142,6 +142,30 @@ export const DEFAULTS = Object.freeze({
   // brief-guard on every Agent launch of a wrestler or cornerman in a bout: 'warn' lets a brief
   // that brief.mjs did not generate through and says so; 'block' refuses it; 'off' does nothing.
   briefGuard: 'warn',
+  // The architecture gate (arch-gate.mjs): the repo's layers, each { name, paths (globs),
+  // mayImport (layer names), forbid (package regexes) }. Empty: only the repo's dependency-cruiser.
+  layers: [],
+  // Files the layer check leaves out (null: tests, `*.spec.*`, `*.test.*`, `__tests__/`, `test/`).
+  layersIgnore: null,
+  // Globs where every NEW code file must fall in a layer (arch-gate flags the ones that do not).
+  layersRequired: [],
+  // Findings that cite one of these rules are never sent to a ticket or discarded by the referee
+  // alone: `findings.mjs ticket|discard` asks for --judge "<what the human said>". A cleanup bout
+  // adds the architecture rules (["P14", "R6", "R11", "R12", "R19", "R22"]).
+  findingsNeedJudge: ['P14'],
+  // Concepts after which the referee relays (rewrites the card's «How to resume» and runs
+  // judges-card.mjs relay) before brief.mjs briefs the next wrestler. null: never.
+  relayEvery: 4,
+  // The human review by blocks (review-blocks.mjs, PR Review Lab's bout mode): once this many
+  // blocks of the plan (points with a reviewed range) wait on the judge, brief.mjs briefs no
+  // wrestler until the human signs a verdict on that cut. null: no pause.
+  humanReviewEvery: 2,
+  // Engram (github.com/Gentleman-Programming/engram), the memory of what earlier bouts learned:
+  // fouls, the judge's verdicts, accepted precedents, X0 findings and each bout's status. Never the
+  // rules. The scripts sync and read it when something answers at this URL (null: off). The
+  // project defaults to the repo name, as Engram names it.
+  engramUrl: 'http://127.0.0.1:7437',
+  engramProject: null,
   // The model and effort of each ring agent, passed on every launch. Who writes runs on the
   // cheaper model at high effort; who reviews keeps the strongest one (what slipped in bout #1223
   // slipped in review). A host overrides a role in `.claude/ring.json` (`agents.wrestler.model`).

package/ring/scripts/engram-memory.mjs

@@ -0,0 +1,213 @@
+// What a bout teaches, as Engram observations, and what a brief reads back. PURE, zero-dependency;
+// the HTTP side is engram.mjs.
+//
+// Engram keeps only what was LEARNED (fouls, the judge's verdicts and answers, accepted precedents,
+// findings no rule covers) and the business context of each bout (where it is, what is next, its
+// plan). The rules never go there: the rulebook, the precedents and the venues stay in files and
+// brief.mjs embeds them in full, every time. What comes back from Engram is context, never a rule.
+import { createHash } from 'node:crypto';
+
+import { classifyDecision, parseDecisionLine } from './chronicle.mjs';
+import { resumeSection } from './compact-hook.mjs';
+import { proposalsOf } from './relay.mjs';
+import { parsePlan } from './tech-plan.mjs';
+
+/** The topic keys the ring upserts on: a bout's status, and each finding no rule covers. */
+export const STATUS_TOPIC = 'ring/status/';
+const X0_TOPIC = 'ring/x0/';
+
+/** The `FOUL:` a foul's text opens with; its title already says Foul. */
+const FOUL_MARK = /^\s*(?:FOUL|falta)\s*[:·—-]\s*/i;
+
+/** A judge line that only stamps an approval (the contract's file hashes): nothing learned. */
+const STAMP = /^contract approved\b/i;
+
+const clip = (text, max) => {
+  const flat = String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+};
+
+/** `agents-studio-be#1223`: how every observation names its bout. PURE. */
+export const boutTag = (slug, pr) => `${String(slug).split('/').at(-1)}#${pr}`;
+
+/** The judge's and the fouls' lines of decisions.md. PURE. */
+function decisionItems(decisions, bout) {
+  return String(decisions ?? '')
+    .split('\n')
+    .map(parseDecisionLine)
+    .filter((entry) => entry?.id && entry.text)
+    .map((entry) => ({ entry, kind: classifyDecision(entry) }))
+    .filter(({ kind }) => kind !== 'arbitro')
+    .filter(({ entry }) => !STAMP.test(entry.text))
+    .map(({ entry, kind }) => ({
+      type: kind === 'falta' ? 'learning' : 'decision',
+      title: `${kind === 'falta' ? 'Foul' : 'Judge'} · ${bout} · ${clip(entry.text.replace(FOUL_MARK, ''), 90)}`,
+      content: `${entry.text}\n\n${bout} · ${entry.id} · ${entry.at ?? 'no time'}`,
+    }));
+}
+
+/** The judge's answers to the referee's escalations, with what was asked. PURE. */
+function answerItems(interview, bout) {
+  const asked = new Map(
+    interview
+      .filter((entry) => entry.kind === 'escalation')
+      .map((entry) => [entry.id, entry.body]),
+  );
+  return interview
+    .filter((entry) => entry.kind === 'answer' && entry.said)
+    .map((entry) => ({
+      type: 'decision',
+      title: `Judge · ${bout} · ${clip(entry.said, 90)}`,
+      content: [
+        entry.said,
+        `Asked (${entry.to}): ${clip(asked.get(entry.to), 600)}`,
+        `${bout} · ${entry.id} · ${entry.judge ?? 'the judge'} · ${entry.at}`,
+      ].join('\n\n'),
+    }));
+}
+
+/** The rulebook proposals the bout accepted: precedents the next bouts should know. PURE. */
+function precedentItems(card, bout) {
+  return proposalsOf(card)
+    .filter((proposal) => /→\s*accepted\b/.test(proposal.text))
+    .map((proposal) => ({
+      type: 'pattern',
+      title: `Precedent · ${bout} · ${clip(proposal.text.slice(2), 90)}`,
+      content: `${proposal.text.slice(2)}\n\n${bout} · proposal ${proposal.n}`,
+    }));
+}
+
+/** A finding citing X0 in its rule field (or recorded with rule X0). PURE. */
+const citesX0 = (finding) =>
+  finding.rule === 'X0' ||
+  /\bX0\b/.test(String(finding.text ?? '').split(' — ')[1] ?? '');
+
+/** The findings no rule covers, each upserted on its own topic as its status moves. PURE. */
+function x0Items(ledger, bout, repoPr) {
+  return (ledger?.findings ?? []).filter(citesX0).map((finding) => ({
+    type: 'discovery',
+    title: `No rule covers it · ${bout} · ${clip(finding.text, 90)}`,
+    content: [
+      finding.text,
+      `Status: ${[finding.status, finding.ticket, finding.decision, finding.reason].filter(Boolean).join(' · ')}`,
+      `${bout} · ${finding.id} · ${finding.at}`,
+    ].join('\n\n'),
+    topic_key: `${X0_TOPIC}${repoPr}/${finding.id}`,
+  }));
+}
+
+/** The bout's business context: where it is, what is next, its plan and its concepts. PURE. */
+function statusItem({ card, plan, state }, bout, repoPr) {
+  const resume = resumeSection(card, 2500);
+  const points = parsePlan(plan).groups.flatMap((group) =>
+    group.items.map(
+      (item) => `- [${item.state}] ${item.title} (${group.name})`,
+    ),
+  );
+  const concepts = (state.concepts ?? []).map(
+    (concept, i) => `${i + 1}. ${concept.name} (${concept.range})`,
+  );
+  if (!resume && !points.length && !concepts.length) return [];
+  const content = [
+    `${state.active === false ? 'Closed' : 'Active'} · branch ${state.branch ?? '?'} on ${state.base ?? '?'}`,
+    resume && `How to resume:\n${resume}`,
+    points.length && `Plan:\n${points.join('\n')}`,
+    concepts.length && `Concepts closed:\n${concepts.join('\n')}`,
+  ].filter(Boolean);
+  return [
+    {
+      type: 'discovery',
+      title: `Status · ${bout} · ${clip(state.branch ?? '', 60)}`,
+      content: content.join('\n\n'),
+      topic_key: `${STATUS_TOPIC}${repoPr}`,
+    },
+  ];
+}
+
+/**
+ * Everything a bout has to give Engram, from its files as read: decisions.md, interview.jsonl
+ * entries, the judges card, findings.json, plan-tecnico.md and state.json. PURE.
+ */
+export function learnedItems({
+  slug,
+  pr,
+  decisions = '',
+  interview = [],
+  card = '',
+  ledger = null,
+  plan = '',
+  state = {},
+}) {
+  const bout = boutTag(slug, pr);
+  const repoPr = `${String(slug).split('/').at(-1)}/${pr}`;
+  return [
+    ...decisionItems(decisions, bout),
+    ...answerItems(interview, bout),
+    ...precedentItems(card, bout),
+    ...x0Items(ledger, bout, repoPr),
+    ...statusItem({ card, plan, state }, bout, repoPr),
+  ];
+}
+
+/**
+ * The replay key of one save: the same item in the same project is the same operation, so a
+ * re-sync never duplicates it. PURE.
+ */
+export const operationId = (project, item) =>
+  `ring-${createHash('sha256')
+    .update(
+      JSON.stringify([
+        project,
+        item.type,
+        item.title,
+        item.content,
+        item.topic_key ?? '',
+      ]),
+    )
+    .digest('hex')
+    .slice(0, 40)}`;
+
+/** Path words that match everything: what a search on them would return is noise. */
+const NOISE = new Set(
+  'apps src lib packages test tests spec specs index main module modules service services controller controllers handler handlers mapper mappers entity entities dto dtos domain application infrastructure typeorm common shared utils types components pages hooks'.split(
+    ' ',
+  ),
+);
+
+/** The words of the files of a range a search for earlier lessons uses, at most `max`. PURE. */
+export function recallTerms(files, max = 24) {
+  const words = files.flatMap((file) =>
+    String(file)
+      .split('/')
+      .slice(-3)
+      .join(' ')
+      .replace(/\.[a-z]+$/i, '')
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      .split(/[^A-Za-z0-9]+/)
+      .map((word) => word.toLowerCase())
+      .filter((word) => word.length >= 4 && !NOISE.has(word)),
+  );
+  return [...new Set(words)].slice(0, max);
+}
+
+/**
+ * The «learned in earlier bouts» lines from Engram's compact search results: the bout's own
+ * observations and every bout's status left out (they are the card's job), at most `max`. PURE.
+ */
+export function learnedLines(results, { exclude, max = 8 } = {}) {
+  return (results ?? [])
+    .filter(
+      (result) => !(exclude && result.title?.includes(` · ${exclude} · `)),
+    )
+    .filter((result) => !result.topic_key?.startsWith(STATUS_TOPIC))
+    .slice(0, max)
+    .map((result) => {
+      // The title is «Kind · bout · start of the text» and the preview the text itself: one of each.
+      const [kind, bout] = String(result.title).split(' · ');
+      const text =
+        result.preview ?? result.title.split(' · ').slice(2).join(' · ');
+      return `- [${result.type}] ${kind} · ${bout} — ${clip(text, 280)} (engram #${result.id})`;
+    });
+}

package/ring/scripts/engram.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+// The ring's optional memory across bouts: Engram (github.com/Gentleman-Programming/engram) over
+// its local HTTP API. Zero-dependency; what goes in and what comes out is engram-memory.mjs.
+//
+//   node engram.mjs status                 is Engram there, at which URL, for which project
+//   node engram.mjs sync <pr> | --all      sends a bout (or every bout of this repo) to Engram
+//   node engram.mjs recall <pr> [--files a,b]   what a brief of that bout would read back
+//
+// The scripts write and read, never an agent: judges-card.mjs and findings.mjs sync the bout after
+// each command that changes what it learned, brief.mjs reads back the lessons on the files of the
+// range, and `judges-card.mjs summary` the repo's latest fouls and verdicts. Every save carries an
+// operation id derived from its content, so a sync repeats nothing, and the ids already sent are
+// kept per Engram store in `<bout dir>/engram-sent.json`. Engram is optional: without it (`engramUrl: null`, or
+// nothing listening) every call returns at once and the bout goes on exactly as before.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  boutDir,
+  isMain,
+  loadConfig,
+  projectDir,
+  readState,
+  repoBouts,
+  repoSlug,
+} from './config.mjs';
+import {
+  boutTag,
+  learnedItems,
+  learnedLines,
+  operationId,
+  recallTerms,
+} from './engram-memory.mjs';
+import { INTERVIEW, parseInterview } from './preparation.mjs';
+import { PLAN } from './tech-plan.mjs';
+
+export const SENT = 'engram-sent.json';
+const TIMEOUT_MS = 1500;
+
+/**
+ * Where Engram is for this repo, or null when the host turned it off. RING_ENGRAM_URL overrides the
+ * host's URL (`off` turns it off: the ring's own tests never write into the developer's Engram).
+ */
+export function engramSettings(config, slug, env = process.env) {
+  const url = env.RING_ENGRAM_URL ?? config.engramUrl;
+  if (!url || url === 'off') return null;
+  return {
+    url: String(url).replace(/\/+$/, ''),
+    project: config.engramProject ?? String(slug).split('/').at(-1),
+  };
+}
+
+async function call(settings, path, { method = 'GET', body } = {}) {
+  const response = await fetch(`${settings.url}${path}`, {
+    method,
+    headers: body ? { 'content-type': 'application/json' } : {},
+    body: body ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  const text = await response.text();
+  try {
+    return { status: response.status, json: JSON.parse(text) };
+  } catch {
+    return { status: response.status, json: null };
+  }
+}
+
+/** The id of the Engram store answering at the URL, or null. Never throws. */
+export async function instanceOf(settings) {
+  if (!settings) return null;
+  try {
+    const { status, json } = await call(settings, '/health');
+    if (status !== 200 || json?.service !== 'engram') return null;
+    return json.instance_id ?? settings.url;
+  } catch {
+    return null;
+  }
+}
+
+/** Is an Engram server answering at the URL? Never throws. */
+export const reachable = async (settings) =>
+  Boolean(await instanceOf(settings));
+
+/** The bout's Engram session (created once; an ended one goes on in its continuation). */
+async function openSession(settings, id) {
+  const body = { id, project: settings.project, directory: projectDir() };
+  const first = await call(settings, '/sessions', { method: 'POST', body });
+  const created =
+    first.json?.code === 'session_already_ended'
+      ? await call(settings, '/sessions', {
+          method: 'POST',
+          body: { ...body, resume: true },
+        })
+      : first;
+  if (created.status >= 300)
+    throw new Error(
+      `engram refused the session ${id}: ${created.status} ${created.json?.error ?? ''}`,
+    );
+  return created.json?.id ?? id;
+}
+
+/** What a bout dir holds that Engram learns from. */
+function boutFiles(dir) {
+  const read = (name) =>
+    existsSync(join(dir, name)) ? readFileSync(join(dir, name), 'utf8') : '';
+  return {
+    decisions: read('decisions.md'),
+    interview: parseInterview(read(INTERVIEW)),
+    card: read('judges-card.md'),
+    // Read as it is, not through findings.mjs: that one syncs to Engram after its commands.
+    ledger: existsSync(join(dir, 'findings.json'))
+      ? JSON.parse(read('findings.json'))
+      : null,
+    plan: read(PLAN),
+    state: readState(dir),
+  };
+}
+
+/** The operation ids sent from a bout, per Engram store (another store has none of them). */
+const readSent = (dir) => {
+  try {
+    const sent = JSON.parse(readFileSync(join(dir, SENT), 'utf8'));
+    return Array.isArray(sent) ? {} : sent;
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * Sends what a bout learned that Engram does not have yet. A 409 is a save Engram already holds
+ * under another payload: it counts as sent. Returns the counts.
+ */
+export async function syncBout(settings, { dir, slug, pr, instance }) {
+  const items = learnedItems({ slug, pr, ...boutFiles(dir) });
+  const byStore = readSent(dir);
+  const sent = new Set(byStore[instance] ?? []);
+  const pending = items
+    .map((item) => ({ item, op: operationId(settings.project, item) }))
+    .filter(({ op }) => !sent.has(op));
+  if (!pending.length) return { items: items.length, saved: 0 };
+  const session = await openSession(settings, `ring:${boutTag(slug, pr)}`);
+  let saved = 0;
+  try {
+    for (const { item, op } of pending) {
+      const { status, json } = await call(settings, '/observations', {
+        method: 'POST',
+        body: {
+          session_id: session,
+          project: settings.project,
+          scope: 'project',
+          tool_name: 'ring',
+          capture_prompt: false,
+          operation_id: op,
+          ...item,
+        },
+      });
+      if (status >= 300 && status !== 409)
+        throw new Error(
+          `engram refused «${item.title}»: ${status} ${json?.error ?? ''}`,
+        );
+      sent.add(op);
+      saved += status === 409 ? 0 : 1;
+    }
+  } finally {
+    writeFileSync(
+      join(dir, SENT),
+      `${JSON.stringify({ ...byStore, [instance]: [...sent] }, null, 2)}\n`,
+    );
+  }
+  return { items: items.length, saved };
+}
+
+/** Engram's compact search, scoped to the project; [] when there is nothing. */
+async function search(settings, query, { type, limit = 12 } = {}) {
+  const params = new URLSearchParams({
+    q: query,
+    project: settings.project,
+    limit: String(limit),
+    match_mode: 'any',
+    response_format: 'compact',
+    ...(type ? { type } : {}),
+  });
+  const { status, json } = await call(settings, `/search?${params}`);
+  return status === 200 ? (json?.results ?? []) : [];
+}
+
+/**
+ * The brief's section of lessons from earlier bouts on the files of the range, or null (Engram
+ * off, not there, or nothing relevant). Never throws: a brief never waits on Engram.
+ */
+export async function recallSection(config, { slug, pr, files }) {
+  const settings = engramSettings(config, slug);
+  const terms = recallTerms(files);
+  if (!settings || !terms.length) return null;
+  try {
+    const lines = learnedLines(
+      await search(settings, terms.join(' '), { limit: 16 }),
+      { exclude: boutTag(slug, pr) },
+    );
+    if (!lines.length) return null;
+    return [
+      '## Learned in earlier bouts of this repo (Engram: context, never a rule; the rules are below)',
+      lines.join('\n'),
+    ].join('\n\n');
+  } catch {
+    return null;
+  }
+}
+
+/** The repo's latest fouls, verdicts and precedents for the referee's summary, or a notice. */
+export async function refereeRecall(config, { slug, pr }) {
+  const settings = engramSettings(config, slug);
+  if (!settings) return null;
+  if (!(await reachable(settings)))
+    return `(Engram is not answering at ${settings.url}: nothing from earlier bouts; the bout goes on without it.)`;
+  const results = [
+    ...(await search(settings, 'Foul', { type: 'learning', limit: 10 })),
+    ...(await search(settings, 'Judge Precedent', { limit: 10 })),
+  ];
+  const lines = learnedLines(results, { exclude: boutTag(slug, pr), max: 12 });
+  return lines.length ? lines.join('\n') : '(nothing learned yet in this repo)';
+}
+
+/**
+ * The bout synced after a command that changed what it learned. Quiet when Engram is off or not
+ * there; one line on stderr when it refused something. Never throws: the command already ran.
+ */
+export async function syncAfter(pr) {
+  try {
+    const slug = repoSlug(projectDir());
+    const dir = boutDir(slug, pr);
+    if (!existsSync(join(dir, 'state.json'))) return;
+    const { config } = loadConfig(projectDir(), {
+      contract: false,
+      venue: readState(dir).venue ?? 'backend',
+    });
+    const settings = engramSettings(config, slug);
+    const instance = await instanceOf(settings);
+    if (!instance) return;
+    await syncBout(settings, { dir, slug, pr, instance });
+  } catch (error) {
+    console.error(`engram: ${error.message} (the bout's files are intact)`);
+  }
+}
+
+function settingsHere() {
+  const slug = repoSlug(projectDir());
+  const { config } = loadConfig(projectDir(), { contract: false });
+  return { slug, settings: engramSettings(config, slug), config };
+}
+
+async function status() {
+  const { settings } = settingsHere();
+  if (!settings) return void console.log('engram: off (engramUrl is null)');
+  const up = await reachable(settings);
+  console.log(
+    `engram: ${up ? 'answering' : 'NOT answering'} at ${settings.url} · project ${settings.project}`,
+  );
+  if (!up) process.exitCode = 2;
+}
+
+async function sync([pr]) {
+  if (!pr) throw new Error('usage: sync <pr> | --all');
+  const { slug, settings } = settingsHere();
+  const instance = await instanceOf(settings);
+  if (!instance)
+    throw new Error(`Engram is not answering at ${settings?.url ?? '(off)'}`);
+  const bouts =
+    pr === '--all'
+      ? repoBouts(slug).map(({ dir, state }) => ({ dir, pr: state.pr }))
+      : [{ dir: boutDir(slug, pr), pr }];
+  for (const bout of bouts) {
+    const { items, saved } = await syncBout(settings, {
+      ...bout,
+      slug,
+      instance,
+    });
+    console.log(
+      `#${bout.pr}: ${saved} sent, ${items - saved} already there (${items} learned)`,
+    );
+  }
+}
+
+async function recall([pr, ...argv]) {
+  const { slug, config } = settingsHere();
+  const at = argv.indexOf('--files');
+  const files =
+    at === -1
+      ? []
+      : String(argv[at + 1] ?? '')
+          .split(',')
+          .filter(Boolean);
+  console.log(
+    files.length
+      ? ((await recallSection(config, { slug, pr, files })) ??
+          '(nothing relevant)')
+      : ((await refereeRecall(config, { slug, pr })) ?? 'engram: off'),
+  );
+}
+
+const COMMANDS = { status, sync, recall };
+
+if (isMain(import.meta.url)) {
+  const [command, ...rest] = process.argv.slice(2);
+  const run = COMMANDS[command];
+  if (!run) {
+    console.error(
+      'Usage: node engram.mjs status | sync <pr>|--all | recall <pr> [--files a,b]',
+    );
+    process.exit(1);
+  }
+  try {
+    await run(rest);
+  } catch (error) {
+    console.error(`engram: ${error.message}`);
+    process.exit(1);
+  }
+}