faberun 0.3.0

package/src/repo/worktree.mjs

@@ -0,0 +1,352 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+
+/** @typedef {{status: "ready", path: string, branch: string, commit: string|null, baseSha: string}} AttemptWorktree */
+/** @typedef {{sha: string, empty: boolean}} SealedAttempt */
+/** @typedef {{encoding?: "utf8"|"buffer", stdio?: import("node:child_process").StdioOptions, timeoutMs?: number, maxBuffer?: number, cwd?: string, env?: NodeJS.ProcessEnv}} BoundedGitOptions */
+/** @typedef {{status: number|null, signal: NodeJS.Signals|null, stdout: string|Buffer, stderr: string|Buffer, error?: Error & {code?: string}, timedOut: boolean}} BoundedGitResult */
+
+/**
+ * The wall-clock bound on every synchronous git subprocess. A controller that
+ * blocks forever on `git` while another process holds `.git/index.lock` is a
+ * frozen loop; git has no timeout of its own, so the wrapper supplies one.
+ * 30s is far longer than any one of these calls takes at the sizes this runner
+ * uses, and far shorter than an operator waiting on a silent run.
+ */
+export const GIT_SYNC_TIMEOUT_MS = 30_000;
+
+/**
+ * The timeout a call uses: the explicit option, else the operator override
+ * (`FABERUN_GIT_TIMEOUT_MS`, for a slow disk or a test), else the
+ * default. Read at call time so the env is honoured without a restart.
+ *
+ * @param {number|undefined} optionMs
+ * @returns {number}
+ */
+function gitSyncTimeoutMs(optionMs) {
+  if (optionMs !== undefined) return optionMs;
+  const raw = process.env.FABERUN_GIT_TIMEOUT_MS;
+  const parsed = raw === undefined ? Number.NaN : Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : GIT_SYNC_TIMEOUT_MS;
+}
+
+/**
+ * The one place a synchronous `git` process is spawned. `execFileSync`-style
+ * callers (`runGit`) read `stdout`, `spawnSync`-style callers read the result
+ * object, and both are held to the same timeout. A spawn that hits the timeout
+ * carries a named `git_timeout` error instead of hanging.
+ *
+ * @param {string[]} args
+ * @param {BoundedGitOptions} [options]
+ * @returns {BoundedGitResult}
+ */
+export function boundedGitSync(args, options = {}) {
+  const timeoutMs = gitSyncTimeoutMs(options.timeoutMs);
+  const result = spawnSync("git", args, {
+    encoding: options.encoding ?? "utf8",
+    stdio: options.stdio ?? ["ignore", "pipe", "pipe"],
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+    ...(options.maxBuffer !== undefined ? { maxBuffer: options.maxBuffer } : {}),
+    ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+    ...(options.env !== undefined ? { env: options.env } : {}),
+  });
+  const timedOut = result.error !== undefined && /** @type {{code?: string}} */ (result.error).code === "ETIMEDOUT";
+  if (timedOut) {
+    /** @type {Error & {code?: string}} */
+    const error = new Error(`git ${args.join(" ")} timed out after ${timeoutMs}ms`);
+    error.code = "git_timeout";
+    error.cause = result.error;
+    return { ...result, error, timedOut: true };
+  }
+  return { ...result, timedOut: false };
+}
+
+/**
+ * Run git and, when it fails, carry git's own stderr into the error.
+ *
+ * Node's `execFileSync` error says only `Command failed: git -C … commit -qm
+ * …` and drops the reason. That is how an empty-change-set commit exiting 1
+ * was misdiagnosed twice across two campaigns: the surfaced error named the
+ * command, never git's "nothing to commit". Every git call here goes through
+ * this helper so a failure always says why.
+ *
+ * @param {string[]} args @returns {string}
+ */
+function runGit(args) {
+  const result = boundedGitSync(args, { encoding: "utf8" });
+  if (result.error || result.status !== 0) {
+    const error = /** @type {Error & {stderr?: unknown, stdout?: unknown, status?: number|null, signal?: string|null}} */ (result.error ?? new Error(`Command failed: git ${args.join(" ")}`));
+    if (result.error === undefined) {
+      error.stderr = result.stderr;
+      error.stdout = result.stdout;
+      error.status = result.status;
+      error.signal = result.signal;
+    }
+    const reason = gitFailureReason(error);
+    if (reason && !String(error.message).includes(reason)) error.message = `${String(error.message).split("\n")[0]}: ${reason}`;
+    throw error;
+  }
+  return String(result.stdout ?? "").trim();
+}
+
+/** @param {string} runId @returns {string} */
+export function runRefName(runId) {
+  return `refs/faberun/${runId}/run`;
+}
+
+/** @param {string} runId @returns {string} */
+export function candidateRefName(runId) {
+  return `refs/faberun/${runId}/candidate`;
+}
+
+/** @param {string} runDir @param {string} runId @returns {string} */
+function worktreeRoot(runDir, runId) {
+  return join(dirname(runDir), "worktrees", runId);
+}
+
+/** @param {string} runDir @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
+export function attemptWorktreePath(runDir, runId, nodeId, attempt) {
+  return join(worktreeRoot(runDir, runId), `${nodeId}.${attempt}`);
+}
+
+/** @param {string} runId @param {string} nodeId @param {number} attempt @returns {string} */
+function attemptBranchName(runId, nodeId, attempt) {
+  return `faberun/${runId}/${nodeId}/${attempt}`;
+}
+
+/** @param {string} runDir @param {string} runId @returns {string} */
+export function candidateWorktreePath(runDir, runId) {
+  return join(worktreeRoot(runDir, runId), ".candidate");
+}
+
+/** @param {unknown} error @returns {string} */
+function gitFailureReason(error) {
+  const streams = /** @type {{stderr?: unknown, stdout?: unknown}} */ (error ?? {});
+  return [streams.stderr, streams.stdout]
+    .map((stream) => (typeof stream === "string" ? stream : stream ? String(stream) : ""))
+    .map((text) => text.trim())
+    .find(Boolean) ?? "";
+}
+
+/** @param {string} repo @param {string[]} args @returns {string} */
+export function git(repo, args) {
+  return runGit(["-C", repo, ...args]);
+}
+
+/** @param {string} repo @param {string} [ref] @returns {string|null} */
+export function gitHead(repo, ref = "HEAD") {
+  try {
+    return git(repo, ["rev-parse", ref]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The path of the worktree that has `branch` checked out right now, or null.
+ * The operator's own checkout is included: `git worktree list` reports it, so
+ * moving that branch under a live checkout is exactly what this guards.
+ *
+ * @param {string} repo
+ * @param {string} branch
+ * @returns {string|null}
+ */
+export function worktreeCheckedOutAt(repo, branch) {
+  const ref = `refs/heads/${branch}`;
+  let output;
+  try {
+    output = git(repo, ["worktree", "list", "--porcelain"]);
+  } catch {
+    // A repository that cannot list its worktrees cannot prove the branch is
+    // safe to move; the caller treats null as "not checked out".
+    return null;
+  }
+  let path = null;
+  for (const line of output.split("\n")) {
+    if (line.startsWith("worktree ")) path = line.slice("worktree ".length);
+    else if (line.startsWith("branch ") && line.slice("branch ".length) === ref) return path;
+  }
+  return null;
+}
+
+/** @param {string} repo @param {string} runId @param {string|null|undefined} head @returns {string} */
+export function createRunRef(repo, runId, head) {
+  if (!head) throw Object.assign(new Error("an execution repository must have at least one commit"), { code: "git_head_required" });
+  const ref = runRefName(runId);
+  if (gitHead(repo, ref)) throw new Error(`run ref already exists: ${ref}`);
+  runGit(["-C", repo, "update-ref", ref, head]);
+  return ref;
+}
+
+/**
+ * @param {{repo: string, runDir: string, runId: string, nodeId: string, attempt: number, base?: string}} args
+ *   `base` cuts the new branch from a sealed sha instead of the run ref tip —
+ *   the previous attempt's sealed work, when it left one (TECH-SPEC lean
+ *   v0.3 section 3 rule 4). Omitted, it falls back to the run ref tip as
+ *   before.
+ * @returns {AttemptWorktree}
+ */
+export function createAttemptWorktree({ repo, runDir, runId, nodeId, attempt, base }) {
+  const runRefSha = gitHead(repo, runRefName(runId));
+  if (!runRefSha) throw Object.assign(new Error(`integration ref is unavailable for ${runId}`), { code: "run_ref_missing" });
+  const path = attemptWorktreePath(runDir, runId, nodeId, attempt);
+  const branch = attemptBranchName(runId, nodeId, attempt);
+  mkdirSync(dirname(path), { recursive: true });
+  const existingCommit = gitHead(path);
+  const existingBranch = gitHead(repo, branch);
+  if (existingCommit) {
+    if (existingBranch !== existingCommit) throw new Error(`attempt worktree identity does not match ${branch}: ${path}`);
+  } else if (existingBranch) {
+    runGit(["-C", repo, "worktree", "add", path, branch]);
+  } else {
+    runGit(["-C", repo, "worktree", "add", path, "-b", branch, base ?? runRefName(runId)]);
+  }
+  prepareWorktreeEnvironment(repo, path);
+  return { status: "ready", path, branch, commit: gitHead(path), baseSha: base ?? runRefSha };
+}
+
+/**
+ * Give a fresh worktree the environment repository tooling needs: the
+ * installed `node_modules`, linked as a symlink and never copied, so
+ * commitlint through the commit-msg hook and `npm run typecheck` work without
+ * an install. A no-op when the repository has nothing installed, or the
+ * worktree already has an entry at that path.
+ *
+ * Every worktree a run creates goes through here — attempts and the
+ * integration candidate alike. That is the point of the single function: the
+ * candidate re-runs the verification the attempt just passed, so any
+ * environment the attempt had and the candidate lacked turns a correct node
+ * into a failed one, and the failure names the node rather than the missing
+ * install.
+ *
+ * @param {string} repo @param {string} path @returns {void}
+ */
+function prepareWorktreeEnvironment(repo, path) {
+  const source = join(repo, "node_modules");
+  if (!existsSync(source)) return;
+  const target = join(path, "node_modules");
+  if (existsSync(target) || isSymlink(target)) return;
+  symlinkSync(source, target);
+}
+
+/** @param {string} path @returns {boolean} */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{repo: string, path: string, baseSha: string|null, runId: string, nodeId: string, attempt: number}} args
+ * @returns {SealedAttempt}
+ */
+export function sealAttempt({ repo, path, baseSha, runId, nodeId, attempt }) {
+  // The attempt-local `.runs` result sidecar must never enter the attempt
+  // commit. Naming it through an exclude pathspec makes `git add` exit 1 with
+  // advice.addIgnoredFile as soon as the sidecar exists in a repository that
+  // ignores `.runs/` (every real worker writes it), so stage everything and
+  // unstage the sidecar afterwards; that also covers a repository that does
+  // not ignore it.
+  //
+  // The probe below must therefore exclude exactly what the staging step
+  // unstages, `node_modules` included: `node_modules/` in .gitignore does not
+  // match the symlink of the same name, so a re-sealed attempt whose only
+  // entry is that link would look dirty, stage it, unstage it, and commit an
+  // empty change set — which exits 1 and turns every retry of an
+  // already-sealed attempt into a hard failure.
+  const dirty = git(path, ["status", "--porcelain=v1", "--", ".", ":(exclude).runs", ":(exclude)node_modules"]);
+  if (dirty) {
+    runGit(["-C", path, "add", "-A", "--", "."]);
+    // node_modules is linked into the worktree as a symlink, which `node_modules/`
+    // in .gitignore does not match; never let the link into the attempt commit.
+    runGit(["-C", path, "rm", "-r", "-q", "--cached", "--ignore-unmatch", "--", ".runs", "node_modules"]);
+    runGit([
+      "-C", path,
+      "-c", "user.email=runner@example.test",
+      "-c", "user.name=faberun",
+      "-c", "commit.gpgSign=false",
+      // The seal is bookkeeping, not a contribution: it checkpoints one
+      // attempt's worktree onto a throwaway `faberun/<run>/<node>/<attempt>` branch
+      // so the next attempt can build on it, and nothing here is ever pushed.
+      // Running the target repository's hooks on it is wrong twice over.
+      // Measured 2026-09-13 against a repository with a plain failing
+      // `.git/hooks/pre-commit`: every seal failed, and because the commit
+      // message never varies between attempts, every node of every run failed
+      // the same way with no way out. A lint or test hook is also work the
+      // controller already does deliberately through `verification`, on a
+      // schedule it chose. The identity and signing overrides above are the
+      // same argument: this commit answers to the factory, not to the repo's
+      // conventions for human commits.
+      "commit", "--no-verify", "-qm", `faberun ${runId} ${nodeId} attempt ${attempt}`,
+    ]);
+  }
+  const sha = gitHead(path);
+  if (!sha) throw new Error(`attempt worktree has no commit: ${path}`);
+  const empty = Boolean(baseSha && gitDiffEmpty(path, baseSha, sha));
+  return { sha, empty };
+}
+
+/** @param {string} repo @param {string} base @param {string} head @returns {boolean} */
+export function gitDiffEmpty(repo, base, head) {
+  try {
+    runGit(["-C", repo, "diff", "--quiet", base, head]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @param {string} repo @param {string} ref @param {string} next @param {string} previous @returns {void} */
+export function updateRefConditional(repo, ref, next, previous) {
+  runGit(["-C", repo, "update-ref", ref, next, previous]);
+}
+
+/** @param {string} repo @param {string} ref @returns {void} */
+export function deleteRef(repo, ref) {
+  try {
+    runGit(["-C", repo, "update-ref", "-d", ref]);
+  } catch {
+    // Deleting an already absent cleanup ref is idempotent.
+  }
+}
+
+/**
+ * @param {{repo: string, runDir: string, runId: string, ref?: string}} args
+ * @returns {string}
+ */
+export function createCandidateWorktree({ repo, runDir, runId, ref = candidateRefName(runId) }) {
+  const path = candidateWorktreePath(runDir, runId);
+  mkdirSync(dirname(path), { recursive: true });
+  runGit(["-C", repo, "worktree", "add", "--detach", path, ref]);
+  prepareWorktreeEnvironment(repo, path);
+  return path;
+}
+
+/** @param {string} repo @param {string|null|undefined} path @returns {void} */
+export function removeWorktree(repo, path) {
+  if (!path) return;
+  try {
+    runGit(["-C", repo, "worktree", "remove", "--force", path]);
+  } catch (error) {
+    if (existsSync(path)) rmSync(path, { recursive: true, force: true });
+    else if (/** @type {{status?: number}} */ (error)?.status !== 128) throw error;
+  }
+}
+
+/** @param {string} repo @param {string} runDir @param {string} runId @returns {void} */
+export function cleanupCandidate(repo, runDir, runId) {
+  removeWorktree(repo, candidateWorktreePath(runDir, runId));
+  deleteRef(repo, candidateRefName(runId));
+}
+
+/** @param {NodeSnapshot|undefined} state @returns {string|null} */
+export function attemptWorkspace(state) {
+  const path = state?.worktree?.path;
+  return path && state?.worktree?.status !== "removed" && existsSync(path) ? path : null;
+}

package/src/report/final.mjs

@@ -0,0 +1,200 @@
+/**
+ * The run's closing artifacts: the final status table, the report, and
+ * `findings.json`. Written once when the controller settles, from the persisted
+ * node snapshots alone.
+ *
+ * This is presentation. It lived inside the engine only because that is where
+ * the loop happened to end; nothing in the control path reads what it writes.
+ */
+import { compactCost, compactTokens, errorCode } from "../util.mjs";
+import { basename, join } from "node:path";
+import { readJson, writeJsonAtomic, writeTextAtomic } from "../run/store.mjs";
+import { scopeFindingsNote } from "../contract/scope-findings.mjs";
+import { MARK, fit, roleCosts, statusNote, writeStatusArtifacts } from "./render.mjs";
+import { unlinkSync } from "node:fs";
+
+/** @typedef {ReturnType<typeof import("../run/lock.mjs").acquire>} LockHandle */
+/** @typedef {import("../contract/index.mjs").NodeSnapshot} NodeSnapshot */
+/** @typedef {import("../contract/index.mjs").ValidatedContract} ValidatedContract */
+
+/**
+ * @param {string} runDir
+ * @param {string} runsDir
+ * @param {ValidatedContract} contract
+ * @param {Map<string, NodeSnapshot>} states
+ * @param {LockHandle|null} [lock]
+ */
+export function render(runDir, runsDir, contract, states, lock = null) {
+  lock?.assert();
+  writeTextAtomic(join(runDir, "STATUS.md"), renderFinalStatus(runDir, contract, states));
+  writeStatusArtifacts(runDir, runsDir, contract, states);
+}
+/**
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {Map<string, NodeSnapshot>} states
+ * @returns {string}
+ */
+function renderFinalStatus(runDir, contract, states) {
+  const nodes = /** @type {NodeSnapshot[]} */ (contract.nodes.map((node) => states.get(node.id)).filter((node) => node !== undefined));
+  const runMetadata = /** @type {{identityWarnings?: string[]}} */ (readJson(join(runDir, "run.json")) ?? {});
+  const identityWarnings = runMetadata.identityWarnings ?? [];
+  const counts = new Map();
+  for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
+  const summary = [...counts].map(([status, count]) => `${count} ${status}`).join(" · ");
+  // The note carries every advisory marker a node earned (scope finding,
+  // review verdict, gate summary), so the cell holds the composed note whole.
+  const widths = [3, 24, 9, 28, 7, 64];
+  /** @param {unknown[]} cells */
+  const row = (cells) => cells.map((cell, index) => fit(String(cell ?? ""), widths[index])).join(" ");
+  const lines = [
+    `# run ${basename(runDir)}`,
+    "",
+    contract.goal,
+    "",
+    `${nodes.length} nodes · ${summary}`,
+    "",
+    "```",
+    row(["", "NODE", "STATE", "RUNTIME", "TRY", "NOTE"]),
+    row(widths.map((width) => "-".repeat(width))),
+  ];
+  for (const node of nodes) {
+    const runtime = node.runtime ? `${node.runtime.harness}/${node.runtime.model}` : "-";
+    const planNode = contract.nodes.find((candidate) => candidate.id === node.id);
+    const detail = statusNote(node) ?? "-";
+    // A scope finding leads the note and drops the phase boilerplate: the
+    // operator has to see it, and the fixed cell cannot hold both.
+    const note = scopeFindingsNote(node.scopeFindings)
+      ? detail
+      : `${detail} · phase ${planNode?.phase ?? "-"} · ${node.invocations?.at(-1)?.continuationMode ?? "fresh"}`;
+    lines.push(row([MARK[node.status] ?? "[?]", node.id, node.status, runtime, node.attempt ?? 0, note]));
+  }
+  lines.push("```", "", "## Needs you", "");
+  const attention = nodes.filter((node) => !["pending", "running", "done"].includes(node.status));
+  if (!attention.length && !identityWarnings.length) lines.push("Nothing needs you right now.");
+  for (const warning of identityWarnings) lines.push(`- [~] ${warning}`);
+  for (const node of attention) lines.push(`- ${MARK[node.status] ?? "[?]"} ${node.id}: ${node.gate?.summary ?? node.error?.message ?? node.status}`);
+  return `${lines.join("\n")}\n`;
+}
+/**
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {Map<string, NodeSnapshot>} states
+ * @returns {string}
+ */
+export function renderFinalReport(runDir, contract, states) {
+  const nodes = /** @type {NodeSnapshot[]} */ (contract.nodes.map((node) => states.get(node.id)).filter((node) => node !== undefined));
+  const counts = new Map();
+  for (const node of nodes) counts.set(node.status, (counts.get(node.status) ?? 0) + 1);
+  const summary = [...counts].map(([status, count]) => `${count} ${status}`).join(" · ");
+  const widths = [3, 24, 9, 7, 7, 28, 10, 10, 10, 12, 64];
+  /** @param {unknown[]} cells */
+  const row = (cells) => cells.map((cell, index) => fit(String(cell ?? ""), widths[index])).join(" ");
+  const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0 };
+  let totalCostUsd = null;
+  const lines = [
+    `# run ${basename(runDir)}`,
+    "",
+    `${nodes.length} nodes · ${summary}`,
+    "",
+    "```",
+    row(["", "NODE", "STATE", "TRY", "REV", "RUNTIME", "IN", "OUT", "CACHE", "COST", "NOTE"]),
+    row(widths.map((width) => "-".repeat(width))),
+  ];
+  for (const node of nodes) {
+    const usage = node.usage ?? { inputTokens: null, outputTokens: null, cacheReadInputTokens: null };
+    totals.inputTokens += usage.inputTokens ?? 0;
+    totals.outputTokens += usage.outputTokens ?? 0;
+    totals.cacheReadInputTokens += usage.cacheReadInputTokens ?? 0;
+    if (typeof node.costUsd === "number" && Number.isFinite(node.costUsd)) totalCostUsd = (totalCostUsd ?? 0) + node.costUsd;
+    const runtime = node.runtime ? `${node.runtime.harness}/${node.runtime.model}` : "-";
+    const planNode = contract.nodes.find((candidate) => candidate.id === node.id);
+    const detail = node.gate?.summary ?? node.error?.message ?? (node.blockedBy?.length ? node.blockedBy.join(", ") : null) ?? (typeof node.result === "string" && node.result.trim() ? node.result.trim() : node.phase ?? "-");
+    // The advisory scope finding leads the note, as it does in STATUS.md.
+    const note = scopeFindingsNote(node.scopeFindings)
+      ? `${scopeFindingsNote(node.scopeFindings)} · ${detail}`
+      : `${detail} · phase ${planNode?.phase ?? "-"} · ${node.invocations?.at(-1)?.continuationMode ?? "fresh"}`;
+    lines.push(row([
+      MARK[node.status] ?? "[?]",
+      node.id,
+      node.status,
+      node.attempt ?? 0,
+      node.revisions ?? 0,
+      runtime,
+      compactTokens(usage.inputTokens),
+      compactTokens(usage.outputTokens),
+      compactTokens(usage.cacheReadInputTokens),
+      compactCost(node.costUsd),
+      note,
+    ]));
+  }
+  const roles = roleCosts(nodes);
+  lines.push("```", "", `totals · in ${compactTokens(totals.inputTokens)} · out ${compactTokens(totals.outputTokens)} · cache ${compactTokens(totals.cacheReadInputTokens)} · worker ${compactCost(roles.worker)} · judge ${compactCost(roles.judge)} · cost ${compactCost(totalCostUsd)}`);
+  return `${lines.join("\n")}\n`;
+}
+/**
+ * Consolidated terminal-state handoff: one bounded JSON snapshot in the run
+ * dir so a triage session never loads full run state. Nodes stay the source
+ * of truth; this file is a snapshot of the moment the run finished. Written
+ * when any node ended non-done; removed when a later resume drives the run
+ * fully done, so a stale snapshot cannot outlive the state it described.
+ *
+ * @param {string} runDir
+ * @param {ValidatedContract} contract
+ * @param {Map<string, NodeSnapshot>} states
+ */
+export function writeFindingsArtifact(runDir, contract, states) {
+  const failing = [...states.values()].filter((state) => state.status !== "done");
+  const path = join(runDir, "findings.json");
+  if (!failing.length) {
+    try { unlinkSync(path); } catch (error) {
+      if (errorCode(error) !== "ENOENT") throw error;
+    }
+    return;
+  }
+  const counts = new Map();
+  for (const state of states.values()) counts.set(state.status, (counts.get(state.status) ?? 0) + 1);
+  writeJsonAtomic(path, {
+    schemaVersion: 1,
+    run: contract.id,
+    goal: contract.goal,
+    summary: [...counts].map(([status, count]) => `${count} ${status}`).join(" · "),
+    nodes: failing.map((state) => ({
+      id: state.id,
+      status: state.status,
+      attempt: state.attempt,
+      revisions: state.revisions,
+      error: state.error,
+      gate: state.gate,
+      ...(state.blockedBy?.length ? { blockedBy: state.blockedBy } : {}),
+      ...missingContextOf(state),
+      ...unexpectedPathsOf(state),
+    })),
+  });
+}
+/**
+ * @param {NodeSnapshot} state
+ * @returns {{missingContext?: string[]}}
+ */
+function missingContextOf(state) {
+  const result = /** @type {{missingContext?: unknown}|null} */ (state.result);
+  if (result && Array.isArray(result.missingContext) && result.missingContext.length) {
+    return { missingContext: result.missingContext.map(String) };
+  }
+  return {};
+}
+/**
+ * An `unexpected_write` failure is only actionable with the offending paths,
+ * and the bounded error message truncates them. Carry a bounded list into the
+ * artifact so triage never has to open the node file.
+ *
+ * @param {NodeSnapshot} state
+ * @returns {{unexpectedPaths?: string[]}}
+ */
+function unexpectedPathsOf(state) {
+  const scope = /** @type {{unexpectedPaths?: unknown}|null|undefined} */ (state.scope);
+  if (scope && Array.isArray(scope.unexpectedPaths) && scope.unexpectedPaths.length) {
+    return { unexpectedPaths: scope.unexpectedPaths.slice(0, 16).map(String) };
+  }
+  return {};
+}

package/src/report/metrics-report.mjs

@@ -0,0 +1,99 @@
+/**
+ * Presentation of a metrics projection (TECH-SPEC lean section 6).
+ *
+ * `metrics.mjs` measures a campaign; this module is the only place that
+ * decides how a measurement is printed. Both forms render the whole indicator
+ * set and nothing else.
+ *
+ * The report is bounded by construction — one header line plus one line per
+ * indicator, with grouped values elided past `MAX_GROUPS` — so a campaign with
+ * many lanes or runtimes prints in the same space as one with few. The
+ * dependency runs one way: the projector imports the renderers, and nothing
+ * here reads a filesystem path or a projection's inputs.
+ */
+
+/** @typedef {import("../campaign/metrics.mjs").CampaignMetrics} CampaignMetrics */
+/** @typedef {import("../campaign/metrics.mjs").MetricsSources} MetricsSources */
+
+/** Schema of the `--json` form; bumped when a consumer would have to change. */
+const METRICS_SCHEMA_VERSION = 2;
+/** Indicators whose value is a duration in seconds; the rest are ratios, counts or tokens. */
+const SECONDS_INDICATORS = new Set(["wallClockSec"]);
+/** Groups printed per grouped indicator before the line is elided; the report stays bounded. */
+const MAX_GROUPS = 6;
+/** The runtime-by-kind breakdown doubles the key length of every other grouped indicator, so it elides sooner. */
+/** @type {Record<string, number>} */
+const MAX_GROUPS_BY_INDICATOR = { usageTokensByKindByRuntime: 2 };
+/** Large token counts compact to a short suffix in the two token indicators; every other grouped value prints as-is. */
+const COMPACT_TOKEN_INDICATORS = new Set(["usageTokensByKind", "usageTokensByKindByRuntime"]);
+const NAME_WIDTH = 28;
+const SECONDS_PER_HOUR = 3600;
+/** Hours print at the four decimals the projector rounds its own values to. */
+const HOURS_PRECISION = 10_000;
+
+/**
+ * The bounded human report: one line per indicator, always the full set.
+ *
+ * @param {MetricsSources} sources
+ * @param {CampaignMetrics} metrics
+ * @returns {string}
+ */
+export function renderMetricsReport(sources, metrics) {
+  const lines = [
+    `[metrics] ${sources.campaignId} · ${sources.runIds.length} runs · ${sources.events.length} events · ${Object.keys(metrics).length} indicators`,
+  ];
+  for (const [name, indicator] of Object.entries(metrics)) {
+    const records = indicator.count === 1 ? "1 record" : `${indicator.count} records`;
+    const unknown = typeof (/** @type {{unknownCount?: number}} */ (indicator).unknownCount) === "number"
+      ? ` · ${(/** @type {{unknownCount: number}} */ (indicator)).unknownCount} unknown`
+      : "";
+    lines.push(`${name.padEnd(NAME_WIDTH)} ${indicator.direction.padEnd(11)} ${formatValue(name, indicator.value).padEnd(24)} · ${records}${unknown}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The machine-readable form, one JSON line like `preflight --json`.
+ *
+ * @param {MetricsSources} sources
+ * @param {CampaignMetrics} metrics
+ * @returns {string}
+ */
+export function renderMetricsJson(sources, metrics) {
+  return `${JSON.stringify({
+    schemaVersion: METRICS_SCHEMA_VERSION,
+    campaignId: sources.campaignId,
+    runs: sources.runIds.length,
+    events: sources.events.length,
+    indicators: metrics,
+  })}\n`;
+}
+
+/**
+ * @param {string} name
+ * @param {number|Record<string, number>|null} value
+ * @returns {string}
+ */
+function formatValue(name, value) {
+  if (value === null) return "no record";
+  if (typeof value === "number") return SECONDS_INDICATORS.has(name) ? formatSeconds(value) : String(value);
+  const maxGroups = MAX_GROUPS_BY_INDICATOR[name] ?? MAX_GROUPS;
+  const compact = COMPACT_TOKEN_INDICATORS.has(name);
+  const groups = Object.entries(value);
+  const shown = groups.slice(0, maxGroups).map(([group, measurement]) => `${group}=${compact ? compactCount(measurement) : measurement}`);
+  if (groups.length > shown.length) shown.push(`+${groups.length - shown.length} more`);
+  return shown.join(" ");
+}
+
+/** @param {number} value @returns {string} */
+function compactCount(value) {
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (value >= 1_000) return `${Math.round(value / 1_000)}k`;
+  return String(value);
+}
+
+/** @param {number} seconds @returns {string} */
+function formatSeconds(seconds) {
+  const hours = seconds / SECONDS_PER_HOUR;
+  return hours >= 1 ? `${seconds}s (${Math.round(hours * HOURS_PRECISION) / HOURS_PRECISION}h)` : `${seconds}s`;
+}