@nathapp/nax 0.75.6 → 0.77.0

package/flows/nax-finish/steps/git.ts

@@ -58,12 +58,35 @@ async function isDirty(repoRoot: string): Promise<boolean> {
  * A failing commit still throws: the fix is then unreviewable, and continuing
  * would silently reproduce the stale-diff bug this exists to fix.
  */
+/** Current HEAD sha, or null outside a repo / on an unborn branch. */
+async function headSha(repoRoot: string): Promise<string | null> {
+  const res = await _gitDeps.run(["git", "rev-parse", "HEAD"], { cwd: repoRoot });
+  return res.exitCode === 0 ? res.stdout.trim() || null : null;
+}
+
+/**
+ * Repo-root-relative paths touched by a commit.
+ *
+ * `--format=` suppresses the header so the output is just the file list.
+ * Failure yields `[]`, which the gate loop reads as "cannot tell what changed"
+ * and therefore reviews — see `partitionTestFiles`.
+ */
+export async function filesInCommit(repoRoot: string, sha: string): Promise<string[]> {
+  const res = await _gitDeps.run(["git", "show", "--name-only", "--format=", sha], { cwd: repoRoot });
+  if (res.exitCode !== 0) return [];
+  return res.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
 export async function commitFixes(
   repoRoot: string,
   message: string,
   opts: { skipHooks?: boolean } = {},
-): Promise<{ committed: boolean }> {
-  if (!(await isDirty(repoRoot))) return { committed: false };
+): Promise<{ committed: boolean; shaBefore: string | null; shaAfter: string | null }> {
+  const shaBefore = await headSha(repoRoot);
+  if (!(await isDirty(repoRoot))) return { committed: false, shaBefore, shaAfter: shaBefore };
 
   const add = await _gitDeps.run(["git", "add", "-A"], { cwd: repoRoot });
   if (add.exitCode !== 0) {
@@ -82,7 +105,7 @@ export async function commitFixes(
       { stage: "finish-git", repoRoot },
     );
   }
-  return { committed: true };
+  return { committed: true, shaBefore, shaAfter: await headSha(repoRoot) };
 }
 
 /**

package/flows/nax-finish/steps/index.ts

@@ -5,4 +5,5 @@ export * from "./escalate";
 export * from "./forge";
 export * from "./git";
 export * from "./pr";
+export * from "./pr-narrative";
 export * from "./result";

package/flows/nax-finish/steps/pr-body.ts

@@ -0,0 +1,345 @@
+/**
+ * nax-finish PR title and body — pure deterministic builder, plus the loader
+ * that assembles a `FinishPrContext` from finish-audit artifacts on disk.
+ *
+ * The finish flow opens a PR via `openOrPromotePr` and used to ship a
+ * hardcoded `nax-finish: <feature>` title and a one-sentence body, throwing
+ * away every artifact the run produced on the way. This module restores that
+ * context as a deterministic markdown body — the title matches
+ * `src/plugins/builtin/auto-pr/pr-body.ts:buildTitle`, and the body is
+ * assembled by string joins over the fields in `FinishPrContext`. No model
+ * call: every section is reproducible from artifacts that exist before
+ * `open_pr` runs, and so the body stays greppable in PR history.
+ *
+ * Reimplemented here (rather than imported from `src/`) because `flows/`
+ * ships to a different runtime — `acpx flow run` runs it in acpx's own Node
+ * process where nax's `src/` and its `@/*` alias are not available.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { runArgv } from "../exec";
+import { readSpecSummary, resolveNarrative } from "../narrative";
+import { findPrTemplate } from "../pr-template";
+import type { Finding, FinishInput, FinishRound, RunFn } from "../types";
+import type { Forge } from "./forge";
+import { readRounds } from "./result";
+
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+
+/** Six hex + one — the abbreviated form used everywhere in PR bodies and logs. */
+const SHORT_SHA_LEN = 7;
+
+/** One row in the Stories table. */
+export interface FinishPrStory {
+  id: string;
+  title: string;
+  acCount: number;
+}
+
+/** Everything `open_pr` renders, sourced from finish-audit artifacts. */
+export interface FinishPrContext {
+  feature: string;
+  stories: FinishPrStory[];
+  outOfScope: string[];
+  acceptance?: string;
+  regression?: string;
+  gatesRan: string[];
+  diffstat?: string;
+  /** Repository PR/MR template, verbatim. Absent when none resolves. */
+  template?: string;
+  /** Resolved "What changed" prose. Absent when neither source produced text. */
+  narrative?: string;
+  rounds: FinishRound[];
+  run: {
+    durationMs?: number;
+    storiesPassed?: number;
+    storiesTotal?: number;
+  };
+}
+
+export const _prBodyDeps: {
+  run: RunFn;
+  readText: (path: string) => Promise<string | null>;
+  warn: (message: string, details: { path: string; error: unknown }) => void;
+} = {
+  run: runArgv,
+  // ENOENT is the routine case (status.json/prd.json not yet written) and must
+  // stay silent — mirrors `_qualityDeps.readText` in `steps/quality.ts`. Only a
+  // genuine I/O failure (permission denied, corrupted mount) should warn.
+  readText: async (path) => {
+    try {
+      return await readFile(path, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
+  },
+  warn: (message, details) => process.emitWarning(message, { detail: `${details.path}: ${String(details.error)}` }),
+};
+
+interface PrdArtifact {
+  userStories?: { id: string; title: string; acceptanceCriteria?: unknown[] }[];
+  outOfScope?: string[];
+}
+
+interface StatusArtifact {
+  postRun?: { acceptance?: { status?: string }; regression?: { status?: string } };
+  durationMs?: number;
+  progress?: { passed?: number; total?: number };
+}
+
+async function readJson(path: string): Promise<unknown> {
+  let text: string | null;
+  try {
+    text = await _prBodyDeps.readText(path);
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to read PR context artifact", { path, error });
+    return undefined;
+  }
+  if (text === null) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to parse PR context artifact", { path, error });
+    return undefined;
+  }
+}
+
+function storiesFrom(prd: PrdArtifact | undefined): FinishPrStory[] {
+  if (!Array.isArray(prd?.userStories)) return [];
+  // A hand-edited or older-schema PRD can carry a story with a missing/non-string
+  // `id`/`title` — drop only that row rather than letting `escapeTableCell` throw
+  // and take down the entire PR body (caught upstream by `open_pr`'s fallback).
+  return prd.userStories
+    .filter((story) => typeof story.id === "string" && typeof story.title === "string")
+    .map((story) => ({
+      id: story.id,
+      title: story.title,
+      acCount: Array.isArray(story.acceptanceCriteria) ? story.acceptanceCriteria.length : 0,
+    }));
+}
+
+/**
+ * Run `git diff --stat <base>...HEAD` and return its stdout on success.
+ *
+ * Fail-open on every non-happy path — a non-zero exit (no commits, divergent
+ * branch, base missing), a rejected run promise (forks too slow to start), or
+ * any thrown error — returning `undefined`. The PR's Verification block is
+ * optional, and a routine empty-branch finish must not lose `open_pr` to a
+ * throw that the body can simply skip.
+ */
+async function runDiffstat(workdir: string, base: string): Promise<string | undefined> {
+  // An empty `base` would interpolate to `...HEAD`, which git resolves as
+  // `HEAD...HEAD` — exit 0, empty stdout — masking the missing-base case as
+  // "no changes" instead of skipping explicitly.
+  if (!base) return undefined;
+  try {
+    const res = await _prBodyDeps.run(["git", "diff", "--stat", `${base}...HEAD`], { cwd: workdir });
+    if (res.exitCode !== 0) return undefined;
+    return res.stdout;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the repository's PR/MR template, fail-open.
+ *
+ * An absent template is the common case and never warns. A genuine read failure
+ * is swallowed too: the body is useful without this section, and `open_pr` must
+ * not lose a PR to a permissions error on a file most repos do not have.
+ */
+async function loadTemplate(workdir: string, forge: Forge | undefined): Promise<string | undefined> {
+  if (forge === undefined) return undefined;
+  try {
+    return (await findPrTemplate(workdir, forge, { readText: _prBodyDeps.readText })) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadFinishPrContext(
+  input: FinishInput,
+  args: { base: string; gatesRan: string[]; forge?: Forge; specPath?: string; narrative?: string },
+): Promise<FinishPrContext> {
+  const inputPrdPath = input.prdPath || "prd.json";
+  const prdPath = isAbsolute(inputPrdPath) ? inputPrdPath : join(input.workdir, inputPrdPath);
+  // [US-004] The audit trail (`rounds`), the diffstat, and the spec summary
+  // are independent of the PRD/status reads — fetching them in parallel keeps
+  // the loader's wall clock at max(readRounds, readJson×2, diffstat, spec).
+  const [prd, status, rounds, diffstat, template, specSummary] = (await Promise.all([
+    readJson(prdPath),
+    readJson(join(dirname(prdPath), "status.json")),
+    readRounds(input),
+    runDiffstat(input.workdir, args.base),
+    loadTemplate(input.workdir, args.forge),
+    readSpecSummary(args.specPath, _prBodyDeps.readText),
+  ])) as [
+    PrdArtifact | undefined,
+    StatusArtifact | undefined,
+    FinishRound[],
+    string | undefined,
+    string | undefined,
+    string | null,
+  ];
+  return {
+    feature: input.feature,
+    stories: storiesFrom(prd),
+    outOfScope: Array.isArray(prd?.outOfScope) ? prd.outOfScope : [],
+    acceptance: status?.postRun?.acceptance?.status,
+    regression: status?.postRun?.regression?.status,
+    gatesRan: args.gatesRan,
+    rounds,
+    diffstat,
+    template,
+    narrative: resolveNarrative(args.narrative, specSummary),
+    run: {
+      durationMs: status?.durationMs,
+      storiesPassed: status?.progress?.passed,
+      storiesTotal: status?.progress?.total,
+    },
+  };
+}
+
+/**
+ * Conventional-commit title matching `buildTitle` in
+ * `src/plugins/builtin/auto-pr/pr-body.ts`, so finish-opened and
+ * auto-PR-opened PRs read the same in a list view.
+ */
+export function buildFinishTitle(ctx: FinishPrContext): string {
+  return `feat: ${ctx.feature}`;
+}
+
+/**
+ * Escape a string for safe inclusion in a single markdown table cell.
+ *
+ * Mirrors `escapeTableCell` in `src/plugins/builtin/auto-pr/pr-body.ts`,
+ * trimmed to the cases the finish body actually needs: pipes (which break
+ * the column boundary) and newlines (which create new rows). Backslashes are
+ * escaped first so the pipe escape survives a literal backslash in a title.
+ */
+function escapeTableCell(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function formatDuration(durationMs: number): string {
+  // `Math.max(0, NaN)` returns NaN, and `Math.floor(Infinity / 1000)` returns
+  // Infinity — both would render as `"NaNm NaNs"` / `"Infinitym Infinitys"`.
+  // A non-finite duration is a corrupted artifact (status.json is hand-editable),
+  // so fall back to zero rather than let it leak into the PR body verbatim.
+  if (!Number.isFinite(durationMs)) return "0m 00s";
+  const clampedMs = Math.max(0, Math.round(durationMs));
+  const totalSeconds = Math.floor(clampedMs / MS_PER_SECOND);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+
+function buildStoriesSection(stories: FinishPrStory[]): string {
+  const lines: string[] = [];
+  lines.push("## Stories");
+  lines.push("| Story | Title | ACs |");
+  lines.push("|-------|-------|-----|");
+  for (const story of stories) {
+    lines.push(`| ${escapeTableCell(story.id)} | ${escapeTableCell(story.title)} | ${story.acCount} |`);
+  }
+  return lines.join("\n");
+}
+
+function buildVerificationSection(
+  acceptance: string | undefined,
+  regression: string | undefined,
+  gatesRan: string[],
+  diffstat: string | undefined,
+): string | null {
+  const lines: string[] = ["## Verification"];
+  if (acceptance !== undefined) lines.push(`- Acceptance: ${acceptance}`);
+  if (regression !== undefined) lines.push(`- Regression: ${regression}`);
+  if (gatesRan.length > 0) lines.push(`- Gates: ${gatesRan.join(", ")}`);
+  if (diffstat !== undefined && diffstat.length > 0) lines.push(`- Diffstat:\n\n\`\`\`\n${diffstat}\n\`\`\``);
+  if (lines.length === 1) return null;
+  return lines.join("\n");
+}
+
+function buildRoundHeading(round: FinishRound): string {
+  const base = `### ${round.phase} attempt ${round.attempt}`;
+  if (!round.committed || !round.sha) return base;
+  const short = round.sha.slice(0, SHORT_SHA_LEN);
+  return `${base} (${short})`;
+}
+
+function buildRoundBlock(round: FinishRound): string {
+  const lines: string[] = [buildRoundHeading(round)];
+  if (round.findings.length === 0) {
+    lines.push("- _no findings_");
+  } else {
+    for (const finding of round.findings) lines.push(renderFinding(finding));
+  }
+  return lines.join("\n");
+}
+
+function buildRoundsSection(rounds: FinishRound[]): string | null {
+  if (rounds.length === 0) return null;
+  const blocks = rounds.map(buildRoundBlock);
+  return ["## Review rounds", ...blocks].join("\n\n");
+}
+
+function renderFinding(finding: Finding): string {
+  return `- [${finding.severity}] ${finding.title}`;
+}
+
+/**
+ * Heading and text are produced together, so "no text" cannot render a bare
+ * `## What changed` heading — the empty-heading case #1477 forbids.
+ */
+function buildNarrativeSection(narrative: string | undefined): string | null {
+  const text = narrative?.trim();
+  if (!text) return null;
+  return ["## What changed", text].join("\n\n");
+}
+
+function buildOutOfScopeSection(outOfScope: string[]): string | null {
+  if (outOfScope.length === 0) return null;
+  const lines: string[] = ["## Out of scope"];
+  for (const item of outOfScope) lines.push(`- ${item}`);
+  return lines.join("\n");
+}
+
+function buildFooter(run: FinishPrContext["run"]): string | null {
+  const { storiesPassed, storiesTotal, durationMs } = run;
+  if (storiesPassed === undefined && storiesTotal === undefined && durationMs === undefined) return null;
+  const counts =
+    storiesPassed !== undefined && storiesTotal !== undefined ? `${storiesPassed}/${storiesTotal} stories` : null;
+  const timing = durationMs !== undefined ? formatDuration(durationMs) : null;
+  const parts = [counts, timing].filter((p): p is string => p !== null);
+  if (parts.length === 0) return null;
+  return parts.join(" · ");
+}
+
+export function buildFinishBody(ctx: FinishPrContext): string {
+  const sections: string[] = [];
+
+  const narrativeSection = buildNarrativeSection(ctx.narrative);
+  if (narrativeSection !== null) sections.push(narrativeSection);
+
+  if (ctx.stories.length > 0) sections.push(buildStoriesSection(ctx.stories));
+
+  const verification = buildVerificationSection(ctx.acceptance, ctx.regression, ctx.gatesRan, ctx.diffstat);
+  if (verification !== null) sections.push(verification);
+
+  const roundsSection = buildRoundsSection(ctx.rounds);
+  if (roundsSection !== null) sections.push(roundsSection);
+
+  const outOfScopeSection = buildOutOfScopeSection(ctx.outOfScope);
+  if (outOfScopeSection !== null) sections.push(outOfScopeSection);
+
+  const footer = buildFooter(ctx.run);
+  if (footer !== null) sections.push(footer);
+
+  // Appended last and verbatim: `gh` / `glab` suppress the repo's own template
+  // whenever `--body` / `--description` is passed, so it has to be re-embedded.
+  if (ctx.template !== undefined && ctx.template.trim().length > 0) sections.push(ctx.template.trim());
+
+  return sections.join("\n\n");
+}

package/flows/nax-finish/steps/pr-narrative.ts

@@ -0,0 +1,43 @@
+/**
+ * `amend_body` — rewrite the PR body once the narrative node has produced prose.
+ *
+ * Runs *after* the PR is open and its result file written, which is the whole
+ * point: acpx has no error edge, so an acp node placed before `open_pr` could
+ * kill the flow and cost the PR. Here the worst case is a body missing one
+ * section.
+ *
+ * Every failure is warned and swallowed for the same reason — a throw would
+ * fail a flow whose real work already succeeded.
+ */
+import { gateOutputs, inputOf, loadCtxOf, narrativeOf } from "../flow-ctx";
+import { detectForge } from "./forge";
+import { updatePrBody } from "./pr";
+import { _prBodyDeps, buildFinishBody, buildFinishTitle, loadFinishPrContext } from "./pr-body";
+
+export async function amendPrBodyNode(ctx: {
+  input: unknown;
+  outputs: unknown;
+}): Promise<{ route: "done"; amended: boolean }> {
+  const narrative = narrativeOf(ctx);
+  // Nothing to add: the body already in place is correct, and rewriting it
+  // identically would spend a forge call to change nothing.
+  if (!narrative) return { route: "done", amended: false };
+
+  const i = inputOf(ctx);
+  const loadCtx = loadCtxOf(ctx);
+  try {
+    const forge = await detectForge(_prBodyDeps.run, i.workdir, "finish-pr");
+    const prCtx = await loadFinishPrContext(i, {
+      base: loadCtx.base ?? "",
+      gatesRan: gateOutputs(ctx).ran ?? [],
+      forge,
+      specPath: loadCtx.specPath,
+      narrative,
+    });
+    await updatePrBody(forge, i.workdir, i.branch, buildFinishTitle(prCtx), buildFinishBody(prCtx));
+    return { route: "done", amended: true };
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to amend the PR body with the narrative", { path: i.branch, error });
+    return { route: "done", amended: false };
+  }
+}

package/flows/nax-finish/steps/pr.ts

@@ -1,9 +1,19 @@
 import { FinishError } from "../errors";
-import { runArgv } from "../exec";
 import type { RunFn } from "../types";
 import { type Forge, detectForge, extractUrl, viewArgv } from "./forge";
+import { _prBodyDeps, loadFinishPrContext } from "./pr-body";
 
-export const _prDeps: { run: RunFn } = { run: runArgv };
+// `loadFinishPrContext` moved to `./pr-body` (the spec's stated module
+// boundary); re-exported here so consumers importing from `./pr` (or the
+// `steps` barrel, which re-exports `./pr`) keep working.
+export { loadFinishPrContext };
+
+// `_prDeps` is deliberately the *same object* as `./pr-body`'s `_prBodyDeps`,
+// not a copy — this module's `run` calls (forge CLI) and pr-body's
+// `readText`/`warn`/diffstat `run` calls share one injectable seam, so a
+// single test stub controls both. Typed to `{ run: RunFn }` here because
+// that's the only member this module actually calls.
+export const _prDeps: { run: RunFn } = _prBodyDeps;
 
 /**
  * Parse `gh pr view --json isDraft,url` / `glab mr view --output json` stdout.
@@ -33,8 +43,12 @@ export async function openOrPromotePr(
   branch: string,
   title: string,
   body: string,
+  // Optional so a caller whose own `detectForge` threw still gets the previous
+  // behaviour. Passing it in is what stops the body and the create-command from
+  // disagreeing about the forge when both would otherwise detect separately.
+  knownForge?: Forge,
 ): Promise<{ status: "opened" | "promoted" | "already-ready"; url?: string }> {
-  const forge = await detectForge(_prDeps.run, repoRoot, "finish-pr");
+  const forge = knownForge ?? (await detectForge(_prDeps.run, repoRoot, "finish-pr"));
   const view = await _prDeps.run(viewArgv(forge, branch, "isDraft,url"), { cwd: repoRoot });
 
   if (view.exitCode !== 0) {
@@ -64,8 +78,39 @@ export async function openOrPromotePr(
         { stage: "finish-pr", branch },
       );
     }
+    await updatePrBody(forge, repoRoot, branch, title, body);
     return { status: "promoted", url };
   }
 
+  await updatePrBody(forge, repoRoot, branch, title, body);
   return { status: "already-ready", url };
 }
+
+/**
+ * Write the finish title/body onto an already-open PR/MR.
+ *
+ * Non-fatal by design: this runs after the PR exists, so a failed metadata
+ * write must not throw away that state — the caller's returned status/url
+ * stays valid either way. Exported because `amend_body` calls it after the
+ * narrative node produces prose.
+ */
+export async function updatePrBody(
+  forge: Forge,
+  repoRoot: string,
+  branch: string,
+  title: string,
+  body: string,
+): Promise<void> {
+  const editCmd =
+    forge === "github"
+      ? ["gh", "pr", "edit", branch, "--title", title, "--body", body]
+      : ["glab", "mr", "update", branch, "--title", title, "--description", body];
+  try {
+    const res = await _prDeps.run(editCmd, { cwd: repoRoot });
+    if (res.exitCode !== 0) {
+      _prBodyDeps.warn("[finish-pr] Failed to write PR title/body", { path: branch, error: res.stderr.trim() });
+    }
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to write PR title/body", { path: branch, error });
+  }
+}

package/flows/nax-finish/steps/result.ts

@@ -1,23 +1,112 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-import type { FinishResult } from "../types";
+/**
+ * Finish-audit artifacts.
+ *
+ * These live under nax's global per-project output directory —
+ * `~/.nax/<project>/finish-audit/<feature>/` — alongside `prompt-audit/` and
+ * `review-audit/`, not in the user's repo. Two reasons the repo was the wrong
+ * home: the artifact describes a *run*, not the source tree, so committing it
+ * and gitignoring it are both wrong answers; and a per-feature, per-run path
+ * makes the history queryable across runs, which a single overwritten
+ * `.nax/nax-finish-result.json` never was.
+ *
+ * The plugin supplies `auditDir` because it owns nax's path SSOT
+ * (`src/runtime/paths.ts`), which this module may not import — `flows/` is
+ * loaded by acpx, outside nax's own process. Absent, we fall back to a
+ * repo-local directory so a hand-run `acpx flow run` still records something.
+ *
+ * Two files per run:
+ * - `<runId>.jsonl`       — one line per fix round, appended as it happens
+ * - `<runId>.result.json` — the terminal result the plugin reads back
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { FinishInput, FinishResult, FinishRound } from "../types";
 
-export function resultPath(repoRoot: string): string {
-  return `${repoRoot}/.nax/nax-finish-result.json`;
+/** Used when the plugin supplied no run id (e.g. a hand-run `acpx flow run`). */
+const FALLBACK_RUN_ID = "run";
+
+type AuditTarget = Pick<FinishInput, "auditDir" | "workdir" | "feature" | "runId">;
+
+export function resolveAuditDir(input: AuditTarget): string {
+  return input.auditDir ?? join(input.workdir, ".nax", "finish-audit", input.feature);
+}
+
+export function resultPath(input: AuditTarget): string {
+  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.result.json`);
 }
 
-export const _resultDeps: { writeText: (p: string, s: string) => Promise<void> } = {
+export function roundsPath(input: AuditTarget): string {
+  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.jsonl`);
+}
+
+export const _resultDeps: {
+  writeText: (p: string, s: string) => Promise<void>;
+  appendText: (p: string, s: string) => Promise<void>;
+  readText: (p: string) => Promise<string | null>;
+} = {
   // node:fs, not Bun.write — this module runs inside acpx's Node process, where
   // the `Bun` global does not exist (see the header of `../exec.ts`). The mkdir
   // is not redundant: Bun.write creates missing parent directories implicitly,
-  // writeFile does not, and this is the one artifact the plugin needs on disk to
-  // report an outcome at all.
+  // writeFile does not, and the audit directory now lives under `~/.nax/`,
+  // where for a project's first run nothing on the path exists yet.
   writeText: async (p, s) => {
     await mkdir(dirname(p), { recursive: true });
     await writeFile(p, s, "utf8");
   },
+  appendText: async (p, s) => {
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, s, { encoding: "utf8", flag: "a" });
+  },
+  readText: async (p) => {
+    try {
+      return await readFile(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
 };
 
-export async function writeResult(repoRoot: string, result: FinishResult): Promise<void> {
-  await _resultDeps.writeText(resultPath(repoRoot), `${JSON.stringify(result, null, 2)}\n`);
+/**
+ * Append one fix round to the run's audit trail.
+ *
+ * Best-effort: an unwritable audit directory must not take the flow down
+ * mid-loop. The round is a record of work already done — losing the record is
+ * bad, losing the run that did the work is worse.
+ */
+export async function appendRound(input: AuditTarget, round: FinishRound): Promise<void> {
+  try {
+    await _resultDeps.appendText(roundsPath(input), `${JSON.stringify(round)}\n`);
+  } catch {
+    // Intentionally swallowed — see the doc comment above.
+  }
+}
+
+/** Read back every round recorded for this run, so a terminal result can embed them. */
+export async function readRounds(input: AuditTarget): Promise<FinishRound[]> {
+  const raw = await _resultDeps.readText(roundsPath(input));
+  if (!raw) return [];
+  const rounds: FinishRound[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      rounds.push(JSON.parse(line) as FinishRound);
+    } catch {
+      // A torn final line (killed mid-write) must not lose the rounds before it.
+    }
+  }
+  return rounds;
+}
+
+/**
+ * Write the terminal result, embedding every round this run recorded.
+ *
+ * Rounds are attached on *every* status, not just `escalated`: a finish that
+ * succeeded after four rounds is precisely the case worth auditing — it says
+ * the run's own review gates missed four defects — and it was the one case
+ * that previously recorded nothing at all.
+ */
+export async function writeResult(input: AuditTarget, result: FinishResult): Promise<void> {
+  const rounds = await readRounds(input);
+  const withRounds: FinishResult = rounds.length > 0 ? { ...result, rounds } : result;
+  await _resultDeps.writeText(resultPath(input), `${JSON.stringify(withRounds, null, 2)}\n`);
 }