faberun 0.3.0

package/src/campaign/projection.mjs

@@ -0,0 +1,250 @@
+/**
+ * The journal folded into current state: what is open, what is blocked, who is
+ * attached, what was decided.
+ *
+ * A projection is a cache and is always rebuildable -- it is read incrementally
+ * from the last complete journal byte, and a torn write is discarded rather than
+ * half-folded. Nothing in the control path depends on it being present.
+ */
+import { JOURNAL_FILE, JOURNAL_TAIL_BYTES, PROJECTION_ACTIVE_CAP, PROJECTION_FILE, PROJECTION_LIST_CAP } from "./layout.mjs";
+import { closeSync, existsSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { errorCode } from "../util.mjs";
+import { join } from "node:path";
+import { readJournal, validateJournalEntry, withoutLegacyLivenessFields } from "./journal.mjs";
+
+/** @typedef {import("./index.mjs").Campaign} Campaign */
+/** @typedef {import("./index.mjs").JournalEntry} JournalEntry */
+/** @typedef {import("../notify/index.mjs").JsonObject} JsonObject */
+/** @typedef {import("./index.mjs").Projection} Projection */
+/** @typedef {import("./index.mjs").ProjectionRecord} ProjectionRecord */
+
+/**
+ * @param {string} campaignPath
+ * @param {Campaign} campaign
+ * @returns {{state: Projection, cursor: number, byte: number, size: number, changed: boolean}}
+ */
+export function readProjectionState(campaignPath, campaign) {
+  const path = join(campaignPath, PROJECTION_FILE);
+  let stored = null;
+  try {
+    stored = /** @type {unknown} */ (JSON.parse(readFileSync(path, "utf8")));
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
+  }
+  const journalPath = join(campaignPath, JOURNAL_FILE);
+  const journalSize = existsSync(journalPath) ? statSync(journalPath).size : 0;
+  if (validProjectionRecord(stored) && stored.size <= journalSize) {
+    try {
+      const { entries, nextByte } = readJournalDelta(campaignPath, stored.byte);
+      if (!entries.length) return { state: stored.projection, cursor: stored.cursor, byte: nextByte, size: stored.size, changed: false };
+      return {
+        state: foldEntries(stored.projection, entries),
+        cursor: stored.cursor + entries.length,
+        byte: nextByte,
+        size: journalSize,
+        changed: true,
+      };
+    } catch {
+      // A delta that cannot be read means the projection is untrustworthy;
+      // fall back to a full reparse of the append-only journal.
+    }
+  }
+  const journal = readJournal(campaignPath);
+  return {
+    state: projectState(journal),
+    cursor: journal.length,
+    byte: completeJournalByte(campaignPath),
+    size: journalSize,
+    changed: true,
+  };
+}
+/**
+ * @param {unknown} stored
+ * @returns {stored is ProjectionRecord}
+ */
+function validProjectionRecord(stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) return false;
+  const record = /** @type {JsonObject} */ (stored);
+  if (!Number.isInteger(record.cursor) || /** @type {number} */ (record.cursor) < 0) return false;
+  if (!Number.isInteger(record.byte) || /** @type {number} */ (record.byte) < 0) return false;
+  if (!Number.isInteger(record.size) || /** @type {number} */ (record.size) < 0) return false;
+  // A record that claims folded entries but has no complete journal bytes is
+  // the signature of a stale checkpoint written before the tail scan handled
+  // partial lines beyond its window; re-folding from byte 0 would duplicate
+  // list-based state. Treat it as untrustworthy and reparse from the journal.
+  if (record.byte === 0 && /** @type {number} */ (record.cursor) > 0) return false;
+  const state = record.projection;
+  if (!state || typeof state !== "object" || Array.isArray(state)) return false;
+  const projection = /** @type {JsonObject} */ (state);
+  return (
+    typeof projection.decisions === "object" && projection.decisions !== null && !Array.isArray(projection.decisions) &&
+    typeof projection.questions === "object" && projection.questions !== null && !Array.isArray(projection.questions) &&
+    Array.isArray(projection.constraints) &&
+    Array.isArray(projection.intents) &&
+    Array.isArray(projection.outcomes) &&
+    Array.isArray(projection.sessions)
+  );
+}
+/**
+ * @param {string} campaignPath
+ * @param {number} fromByte
+ * @returns {{entries: JournalEntry[], nextByte: number}}
+ */
+function readJournalDelta(campaignPath, fromByte) {
+  const path = join(campaignPath, JOURNAL_FILE);
+  let size;
+  try {
+    size = statSync(path).size;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return { entries: [], nextByte: fromByte };
+    throw error;
+  }
+  if (fromByte >= size) return { entries: [], nextByte: fromByte };
+  const descriptor = openSync(path, "r");
+  try {
+    const buffer = Buffer.alloc(size - fromByte);
+    readSync(descriptor, buffer, 0, buffer.length, fromByte);
+    /** @type {JournalEntry[]} */
+    const entries = [];
+    let start = 0;
+    while (start < buffer.length) {
+      const newline = buffer.indexOf(0x0a, start);
+      if (newline === -1) break;
+      let line = buffer.toString("utf8", start, newline);
+      if (line.endsWith("\r")) line = line.slice(0, -1);
+      if (line.trim()) {
+        const entry = withoutLegacyLivenessFields(/** @type {JournalEntry} */ (JSON.parse(line)));
+        validateJournalEntry(entry);
+        entries.push(entry);
+      }
+      start = newline + 1;
+    }
+    return { entries, nextByte: fromByte + start };
+  } finally {
+    closeSync(descriptor);
+  }
+}
+/**
+ * @param {string} campaignPath
+ * @returns {number}
+ */
+function completeJournalByte(campaignPath) {
+  const path = join(campaignPath, JOURNAL_FILE);
+  let size;
+  try {
+    size = statSync(path).size;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") return 0;
+    throw error;
+  }
+  if (!size) return 0;
+  const descriptor = openSync(path, "r");
+  try {
+    // Scan backward in bounded windows so a partial trailing line longer than
+    // the window cannot hide the boundary of the last complete line.
+    let start = Math.max(0, size - JOURNAL_TAIL_BYTES);
+    while (true) {
+      const length = size - start;
+      const buffer = Buffer.alloc(length);
+      readSync(descriptor, buffer, 0, length, start);
+      if (buffer[buffer.length - 1] === 0x0a) return size;
+      const newline = buffer.lastIndexOf(0x0a);
+      if (newline !== -1) return start + newline + 1;
+      if (start === 0) return 0;
+      start = Math.max(0, start - JOURNAL_TAIL_BYTES);
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}
+/**
+ * @returns {Projection}
+ */
+function emptyProjection() {
+  return {
+    updatedAt: null,
+    decisions: {},
+    questions: {},
+    constraints: [],
+    intents: [],
+    outcomes: [],
+    sessions: [],
+    next: null,
+    evicted: {},
+  };
+}
+/**
+ * @param {JournalEntry[]} journal
+ * @returns {Projection}
+ */
+function projectState(journal) {
+  return foldEntries(emptyProjection(), journal);
+}
+/**
+ * @param {Projection} state
+ * @param {JournalEntry[]} entries
+ * @returns {Projection}
+ */
+function foldEntries(state, entries) {
+  /** @type {Projection} */
+  const next = {
+    updatedAt: state.updatedAt,
+    decisions: { ...state.decisions },
+    questions: { ...state.questions },
+    constraints: [...state.constraints],
+    intents: [...state.intents],
+    outcomes: [...state.outcomes],
+    sessions: [...state.sessions],
+    next: state.next,
+    evicted: { ...state.evicted },
+  };
+  for (const entry of entries) {
+    if (entry.type === "liveness") continue;
+    next.updatedAt = entry.at;
+    if (entry.type === "session.attached") next.sessions = pushCapped(next.sessions, entry, "sessions", next.evicted);
+    else if (entry.type === "intent") next.intents = pushCapped(next.intents, entry, "intents", next.evicted);
+    else if (entry.type === "decision" && entry.decisionId !== undefined) next.decisions = setCapped(next.decisions, entry.decisionId, entry, next.evicted, "decisions");
+    else if (entry.type === "supersede" && entry.supersedes !== undefined) delete next.decisions[entry.supersedes];
+    else if (entry.type === "constraint") next.constraints = pushCapped(next.constraints, entry, "constraints", next.evicted);
+    else if (entry.type === "outcome" || entry.type === "retrospective") next.outcomes = pushCapped(next.outcomes, entry, "outcomes", next.evicted);
+    else if (entry.type === "next") next.next = entry;
+    else if (entry.type === "open-question" && entry.questionId !== undefined) next.questions = setCapped(next.questions, entry.questionId, entry, next.evicted, "questions");
+    else if (entry.type === "question.resolved" && entry.questionId !== undefined) delete next.questions[entry.questionId];
+  }
+  return next;
+}
+/**
+ * @param {JournalEntry[]} list
+ * @param {JournalEntry} entry
+ * @param {string} key
+ * @param {Record<string, number>} evicted
+ * @returns {JournalEntry[]}
+ */
+function pushCapped(list, entry, key, evicted) {
+  const next = [...list, entry];
+  if (next.length > PROJECTION_LIST_CAP) {
+    const dropped = next.length - PROJECTION_LIST_CAP;
+    evicted[key] = (evicted[key] ?? 0) + dropped;
+    return next.slice(dropped);
+  }
+  return next;
+}
+/**
+ * @param {Record<string, JournalEntry>} map
+ * @param {string} key
+ * @param {JournalEntry} entry
+ * @param {Record<string, number>} evicted
+ * @param {string} evictionKey
+ * @returns {Record<string, JournalEntry>}
+ */
+function setCapped(map, key, entry, evicted, evictionKey) {
+  /** @type {Record<string, JournalEntry>} */
+  const next = { ...map, [key]: entry };
+  const keys = Object.keys(next);
+  if (keys.length > PROJECTION_ACTIVE_CAP) {
+    const oldest = keys.reduce((left, right) => (next[left].at <= next[right].at ? left : right));
+    delete next[oldest];
+    evicted[evictionKey] = (evicted[evictionKey] ?? 0) + 1;
+  }
+  return next;
+}

package/src/campaign/record.mjs

@@ -0,0 +1,102 @@
+/**
+ * The `campaign.json` record itself: read it, validate it, and answer what a
+ * campaign's id is.
+ *
+ * `campaignIdOf` falls back to the directory name when the record cannot be
+ * read, because a campaign whose file is corrupt still has to be nameable in an
+ * error message.
+ */
+import { CAMPAIGN_FILE, basenameSafe } from "./layout.mjs";
+import { errorCode } from "../util.mjs";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { assertObject, requireId, requirePacketHash, requireString, requireText, requireTimestamp } from "../contract/assert.mjs";
+
+/** @typedef {import("./index.mjs").Campaign} Campaign */
+/** @typedef {import("../notify/index.mjs").JsonObject} JsonObject */
+
+/**
+ * @param {string} path
+ * @returns {Campaign}
+ */
+export function readCampaign(path) {
+  let campaign;
+  try {
+    campaign = /** @type {unknown} */ (JSON.parse(readFileSync(join(path, CAMPAIGN_FILE), "utf8")));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") throw new Error(`campaign not found: ${path}`);
+    throw error;
+  }
+  validateCampaign(campaign);
+  // A campaign written before the chain fields existed still reads: the
+  // manifest is empty and the landing branch takes the current default. A
+  // campaign written by `initializeCampaign` always carries all three.
+  const record = /** @type {JsonObject} */ (campaign);
+  record.contracts ??= [];
+  record.landBranch ??= `campaign/${String(record.id)}`;
+  record.promotions ??= [];
+  return /** @type {Campaign} */ (campaign);
+}
+/**
+ * @param {string} campaignPath
+ * @returns {string}
+ */
+export function campaignIdOf(campaignPath) {
+  try {
+    return readCampaign(campaignPath).id;
+  } catch {
+    return basenameSafe(campaignPath);
+  }
+}
+/**
+ * @param {unknown} campaign
+ */
+function validateCampaign(campaign) {
+  if (!campaign || typeof campaign !== "object" || Array.isArray(campaign)) {
+    throw new TypeError("campaign.json must be an object");
+  }
+  const record = /** @type {JsonObject} */ (campaign);
+  requireId(record.id, "campaign.id");
+  requireText(record.goal, "campaign.goal");
+  if (record.status !== "active" && record.status !== "closed") {
+    throw new TypeError("campaign.status must be active or closed");
+  }
+  if (!Array.isArray(record.linkedRunIds)) throw new TypeError("campaign.linkedRunIds must be an array");
+  for (const runId of record.linkedRunIds) requireId(runId, "campaign.linkedRunIds[]");
+  // The ordered contract manifest and the landing branch. Each entry carries
+  // the digest of the contract's authored bytes, enough to detect tampering
+  // between authoring and the launch that validates it. The fields are
+  // optional on read so a recorded historical campaign stays readable; a
+  // campaign written by `initializeCampaign` always carries them.
+  if (record.contracts !== undefined) {
+    if (!Array.isArray(record.contracts)) throw new TypeError("campaign.contracts must be an array");
+    for (const [index, entry] of record.contracts.entries()) {
+      assertObject(entry, `campaign.contracts[${index}]`);
+      requireString(/** @type {JsonObject} */ (entry).path, `campaign.contracts[${index}].path`);
+      requirePacketHash(/** @type {JsonObject} */ (entry).digest, `campaign.contracts[${index}].digest`);
+    }
+  }
+  if (record.landBranch !== undefined) requireText(record.landBranch, "campaign.landBranch");
+  // The chain's durable park: the campaign stays active but carries the reason
+  // it stopped, naming the contract, the node and the status when they exist.
+  if (record.attention !== undefined && record.attention !== null) {
+    assertObject(record.attention, "campaign.attention");
+    const attention = /** @type {JsonObject} */ (record.attention);
+    requireString(attention.code, "campaign.attention.code");
+    requireString(attention.message, "campaign.attention.message");
+    requireTimestamp(attention.at, "campaign.attention.at");
+  }
+  if (record.promotions !== undefined) {
+    if (!Array.isArray(record.promotions)) throw new TypeError("campaign.promotions must be an array");
+    for (const [index, entry] of record.promotions.entries()) {
+      assertObject(entry, `campaign.promotions[${index}]`);
+      const promotion = /** @type {JsonObject} */ (entry);
+      requireId(promotion.runId, `campaign.promotions[${index}].runId`);
+      requireString(promotion.branch, `campaign.promotions[${index}].branch`);
+      requireString(promotion.sha, `campaign.promotions[${index}].sha`);
+      if (promotion.previousSha !== null) requireString(promotion.previousSha, `campaign.promotions[${index}].previousSha`);
+      requireTimestamp(promotion.at, `campaign.promotions[${index}].at`);
+      if (promotion.contractPath !== undefined) requireString(promotion.contractPath, `campaign.promotions[${index}].contractPath`);
+    }
+  }
+}

package/src/campaign/unpark.mjs

@@ -0,0 +1,56 @@
+/**
+ * The way back from a parked campaign.
+ *
+ * The chain parks by writing `campaign.attention`, and `parkCampaign` in
+ * `index.mjs` is its only writer. Clearing it needs both the campaign record
+ * (`record.mjs`) and the chain's run classification (`chain.mjs`), and
+ * `chain.mjs` already imports `index.mjs`. Putting the clearing in either would
+ * close a runtime import cycle, so it lives here, where both directions of that
+ * dependency are already acyclic.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomic } from "../run/store.mjs";
+import { requireTimestamp } from "../contract/assert.mjs";
+import { CAMPAIGN_FILE } from "./layout.mjs";
+import { readCampaign } from "./record.mjs";
+import { appendJournal } from "./journal.mjs";
+import { classifyRunProgress } from "./chain.mjs";
+import { runProgress } from "../engine/supervise.mjs";
+
+/** @typedef {import("./index.mjs").Campaign} Campaign */
+/** @typedef {import("./index.mjs").CampaignAttention} CampaignAttention */
+
+/**
+ * Clear a campaign's attention once the run it names is no longer parked, and
+ * append the `campaign.unparked` journal event. A closed campaign and a
+ * campaign without attention are refused before anything is written. A run
+ * that is still parked or canceled is refused unless `force` overrides it;
+ * a run directory that no longer exists has nothing left to resume, so the
+ * attention is cleared.
+ *
+ * @param {string} campaignPath
+ * @param {{runsDir: string, force?: boolean, at?: string, eventId?: string}} options
+ * @returns {{campaign: Campaign, cleared: CampaignAttention}}
+ */
+export function unparkCampaign(campaignPath, { runsDir, force = false, at = new Date().toISOString(), eventId = randomUUID() }) {
+  requireTimestamp(at, "at");
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  const attention = campaign.attention;
+  if (!attention) throw new Error(`campaign is not parked: ${campaign.id}`);
+  const runId = attention.runId;
+  const runDir = typeof runId === "string" && runId ? join(runsDir, runId) : null;
+  if (runDir !== null && existsSync(runDir)) {
+    const state = classifyRunProgress(runProgress(runDir, Date.parse(at)));
+    if (!force && (state === "parked" || state === "canceled")) {
+      throw new Error(`run ${runId} is still ${state}; resume it first or pass --force`);
+    }
+  }
+  const unparked = /** @type {Campaign} */ ({ ...campaign, updatedAt: at });
+  delete unparked.attention;
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), unparked);
+  appendJournal(campaignPath, { type: "campaign.unparked", at, eventId, code: attention.code, runId: runId ?? null });
+  return { campaign: unparked, cleared: attention };
+}

package/src/cli/brand.mjs

@@ -0,0 +1,205 @@
+/**
+ * The command line's visual identity: color capability, the semantic role
+ * palette, glyphs, check tokens, the hornero-nest banner and the usage text.
+ *
+ * It is separate from `cli.mjs` because `DESIGN.md` is the specification and a
+ * renderer that disagrees with it is a defect. Dispatch decides what to print;
+ * this module is the one place a palette value, a glyph or a banner line lives.
+ * `--json` and other machine output call with `level` 0 and receive the text
+ * untouched.
+ */
+
+import { compareVersions, faberunHome, readUpdateCheck } from "../host/home.mjs";
+
+/** @typedef {"brand"|"ok"|"progress"|"warn"|"fail"|"muted"|"text"} Role */
+/** @typedef {"terra"|"argila"|"folha"} ColorName */
+/** @typedef {{color?: ColorName, bold?: boolean, dim?: boolean}} RoleSpec */
+/** @typedef {{version: string, nodeVersion: string, harnessCount: number, level: number, env?: NodeJS.ProcessEnv}} BannerOptions */
+
+/** The palette's terminal encodings, exactly as DESIGN.md's table gives them. */
+/** @type {Record<ColorName, {rgb: string, index: number, ansi16: number}>} */
+const COLORS = {
+  terra: { rgb: "38;2;181;82;42", index: 166, ansi16: 31 },
+  argila: { rgb: "38;2;217;123;79", index: 173, ansi16: 33 },
+  folha: { rgb: "38;2;85;107;63", index: 65, ansi16: 32 },
+};
+
+/** One role per rendered state; a new state picks a row, never a color. */
+/** @type {Record<Role, RoleSpec>} */
+const ROLE_SPECS = {
+  brand: { color: "terra", bold: true },
+  ok: { color: "folha" },
+  progress: { color: "argila" },
+  warn: { color: "argila", bold: true },
+  fail: { color: "terra", bold: true },
+  muted: { dim: true },
+  text: {},
+};
+
+/** The Unicode glyph and ASCII fallback of each glyph-bearing role. */
+/** @type {Record<string, {unicode: string, ascii: string}>} */
+const GLYPHS = {
+  ok: { unicode: "✓", ascii: "+" },
+  progress: { unicode: "·", ascii: "." },
+  warn: { unicode: "!", ascii: "!" },
+  fail: { unicode: "✗", ascii: "x" },
+};
+
+/**
+ * Resolve how much color this process may emit, once, in DESIGN.md's order:
+ * `NO_COLOR` wins, an explicit `FORCE_COLOR` overrides the terminal, and a
+ * non-TTY or `TERM=dumb` stays monochrome.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @param {boolean} isTTY
+ * @returns {0|1|2|3}
+ */
+export function colorLevel(env, isTTY) {
+  if (env.NO_COLOR !== undefined) return 0;
+  if (env.FORCE_COLOR !== undefined) {
+    if (env.FORCE_COLOR === "") return 3;
+    if (env.FORCE_COLOR === "0") return 0;
+    if (env.FORCE_COLOR === "1") return 1;
+    if (env.FORCE_COLOR === "2") return 2;
+    return 3;
+  }
+  if (!isTTY || env.TERM === "dumb") return 0;
+  if (env.COLORTERM === "truecolor" || env.COLORTERM === "24bit") return 3;
+  return 2;
+}
+
+/**
+ * @param {ColorName} name
+ * @param {number} level
+ * @returns {string}
+ */
+function colorCode(name, level) {
+  const color = COLORS[name];
+  if (level === 1) return `\u001b[${color.ansi16}m`;
+  if (level === 2) return `\u001b[38;5;${color.index}m`;
+  return `\u001b[${color.rgb}m`;
+}
+
+/**
+ * @param {string} text
+ * @param {RoleSpec} spec
+ * @param {number} level
+ * @returns {string}
+ */
+function colorize(text, spec, level) {
+  if (level === 0) return text;
+  let open = "";
+  if (spec.bold) open += "\u001b[1m";
+  if (spec.dim) open += "\u001b[2m";
+  if (spec.color) open += colorCode(spec.color, level);
+  return open ? `${open}${text}\u001b[0m` : text;
+}
+
+/**
+ * Paint one short token in its semantic role. At level 0 the text is returned
+ * untouched, which is what every non-TTY test and all `--json` output see.
+ *
+ * @param {string} text
+ * @param {Role} role
+ * @param {number} level
+ * @returns {string}
+ */
+export function paint(text, role, level) {
+  return colorize(text, ROLE_SPECS[role], level);
+}
+
+/**
+ * Whether the locale advertises UTF-8 and the terminal is not dumb.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {boolean}
+ */
+export function useUnicodeGlyphs(env) {
+  if (env.TERM === "dumb") return false;
+  return [env.LANG, env.LC_ALL, env.LC_CTYPE].some((value) => typeof value === "string" && /utf-?8/iu.test(value));
+}
+
+/**
+ * The role's glyph, in Unicode or its ASCII fallback. Roles without a glyph
+ * (brand, muted, text) have none.
+ *
+ * @param {Role} role
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string}
+ */
+export function glyph(role, env) {
+  const entry = GLYPHS[role];
+  if (!entry) return "";
+  return useUnicodeGlyphs(env) ? entry.unicode : entry.ascii;
+}
+
+/**
+ * The bracketed check token in its role color. The bracketed text is the
+ * contract with scripts and tests and never changes; only color is added.
+ *
+ * @param {"ok"|"warn"|"fail"} kind
+ * @param {number} level
+ * @returns {string}
+ */
+export function statusToken(kind, level) {
+  return paint(`[${kind}]`, kind, level);
+}
+
+/**
+ * The five-line hornero-nest banner. The dome is Terra without bold, the inner
+ * opening is muted, the wordmark is the brand role, the tagline is plain text
+ * and the last line is muted and filled from the running process. The last line
+ * gains ` · update available: <latest>` when the cached check names a newer
+ * release; the banner reads only the cache (`update-check.json`) and never
+ * fetches. ASCII apart from the middle-dot separator, so it survives every
+ * monospace font.
+ *
+ * @param {BannerOptions} options
+ * @returns {string}
+ */
+export function renderBanner({ version, nodeVersion, harnessCount, level, env = process.env }) {
+  const cached = readUpdateCheck(faberunHome(env));
+  const latest = cached && compareVersions(cached.latest, version) > 0 ? cached.latest : null;
+  const terra = /** @param {string} text @returns {string} */ (text) => colorize(text, { color: "terra" }, level);
+  const lines = [
+    terra("       .-~~~-."),
+    `${terra("    .-'  ")}${paint(".-.", "muted", level)}${terra("  '-.")}       ${paint("faberun", "brand", level)}`,
+    `${terra("   /    ")}${paint("(   )", "muted", level)}${terra("    \\")}      from intent to running software`,
+    `${terra("   \\     ")}${paint("'-'", "muted", level)}${terra("     /")}`,
+    `${terra("    '-.._____..-'")}       ${paint(`v${version} · node ${nodeVersion} · ${harnessCount} harnesses detected${latest ? ` · update available: ${latest}` : ""}`, "muted", level)}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * One `usage: faberun <verb> ...` line per verb group, keeping the verbs and
+ * flags the CLI dispatches. The same text serves the help path (stdout) and
+ * the usage error (stderr).
+ *
+ * @returns {string}
+ */
+export function renderUsage() {
+  const groups = [
+    "<run|validate> <contract.json> [--base-ref <ref>] [--detach]",
+    "preflight <contract.json> [--static] [--time-verification] [--json]",
+    "<resume|cancel> <run-dir> [--detach]",
+    "supervise <run-dir> [--detach] [--interval <sec>]",
+    "supervise campaign <campaign-id> [--cwd <dir>] [--allow-main]",
+    "<status|report> <run-dir> [--json]",
+    "findings <run-dir>",
+    "doctor [<contract.json>] [--cwd <dir>] [--discover] [--json]",
+    "setup [--yes] [--harnesses <a,b>] [--worker <id>] [--judge <id>] [--json]",
+    "init [--cwd <dir>] [--yes] [--no-skill] [--agentkit] [--greenfield|--stable] [--json]",
+    "update [--check] [--json]",
+    "models [--probe] [--json]",
+    "next [--cwd <dir>] [--json]",
+    "bulk-read --question <text> --paths <a,b,c> [--json]",
+    "contract validate <contract.json>",
+    "metrics <campaign-id> [--cwd <dir>] [--json]",
+    "campaign <init|watch|attach|note|resolve|close|supervise|show|list|sync|ack> ...",
+    "seat <start|attach|status|stop> [<campaign-id>] [--cwd <dir>] ...",
+    "skills list",
+    "skills install [<name>...] [--target <dir>] [--global] [--force]",
+  ];
+  return `${groups.map((group) => `usage: faberun ${group}`).join("\n")}\n`;
+}