@nathapp/nax 0.75.2 → 0.75.4

package/flows/nax-finish/exec.ts

@@ -14,7 +14,20 @@
  *
  * Both cap wall-clock time: an unbounded gate would hang `acpx flow run`, and
  * the post-run plugin awaits that subprocess.
+ *
+ * ## Why `node:child_process` and not `Bun.spawn`
+ *
+ * The rest of nax is Bun-native (see `.claude/rules/project-conventions.md`),
+ * but this module is **not** loaded by nax. `acpx flow run` loads it, in acpx's
+ * own process, and the published `acpx` binary is a Node program
+ * (`#!/usr/bin/env node`). Under Node the `Bun` global does not exist, so
+ * `Bun.spawn` threw `ReferenceError: Bun is not defined` on the flow's very
+ * first git call — aborting the flow before any node completed and before the
+ * result file was written. Everything under `flows/` must therefore stay on
+ * Node built-ins; `Bun.*` is banned here and only here, enforced by
+ * `scripts/check-flows-no-bun.ts`.
  */
+import { spawn } from "node:child_process";
 import type { RunResult } from "./types";
 
 /** Fallbacks used when the plugin passes no explicit budget in the flow input. */
@@ -28,35 +41,71 @@ export interface ExecOptions {
   timeoutMs?: number;
 }
 
-async function spawnCapture(cmd: string[], opts: ExecOptions): Promise<RunResult> {
-  const proc = Bun.spawn(cmd, { cwd: opts.cwd, stdout: "pipe", stderr: "pipe" });
-  let timedOut = false;
-  // setTimeout (not Bun.sleep) because the handle must be cancellable the moment
-  // the process exits — the documented exception in forbidden-patterns.md.
-  const timer =
-    opts.timeoutMs && opts.timeoutMs > 0
-      ? setTimeout(() => {
-          timedOut = true;
-          proc.kill();
-        }, opts.timeoutMs)
-      : undefined;
-  try {
-    const [exitCode, stdout, stderr] = await Promise.all([
-      proc.exited,
-      new Response(proc.stdout).text(),
-      new Response(proc.stderr).text(),
-    ]);
-    return timedOut
-      ? {
-          exitCode: exitCode === 0 ? 124 : exitCode,
-          stdout,
-          stderr: `${stderr}\n[nax-finish] killed after ${opts.timeoutMs}ms timeout`,
-          timedOut: true,
-        }
-      : { exitCode, stdout, stderr };
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
+/** Exit code reported when the wall-clock cap kills the process, matching `timeout(1)`. */
+const TIMEOUT_EXIT_CODE = 124;
+/** Exit code reported when the binary is missing, matching a shell's "command not found". */
+const NOT_FOUND_EXIT_CODE = 127;
+
+function spawnCapture(cmd: string[], opts: ExecOptions): Promise<RunResult> {
+  return new Promise<RunResult>((resolve) => {
+    const [file, ...args] = cmd;
+    const proc = spawn(file as string, args, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let settled = false;
+
+    proc.stdout.setEncoding("utf8");
+    proc.stderr.setEncoding("utf8");
+    proc.stdout.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    proc.stderr.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+
+    // setTimeout (not a sleep) because the handle must be cancellable the moment
+    // the process exits — the documented exception in forbidden-patterns.md.
+    const timer =
+      opts.timeoutMs && opts.timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            proc.kill();
+          }, opts.timeoutMs)
+        : undefined;
+
+    const settle = (result: RunResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+
+    // A missing binary (`gh`/`glab` not installed) surfaces as an `error` event
+    // under Node, where `Bun.spawn` used to throw. Resolving with 127 instead of
+    // rejecting keeps it a readable gate failure the flow can route on, rather
+    // than an exception that kills `acpx flow run` with no result file.
+    proc.on("error", (err: Error) => {
+      settle({ exitCode: NOT_FOUND_EXIT_CODE, stdout, stderr: `${stderr}${err.message}`, timedOut });
+    });
+
+    // `close` (not `exit`) so both pipes are fully drained before we read them.
+    // `code` is null when the process died from a signal — including our own
+    // timeout kill — so it maps to a non-zero code rather than a false green.
+    proc.on("close", (code: number | null) => {
+      const exitCode = code ?? (timedOut ? TIMEOUT_EXIT_CODE : 1);
+      settle(
+        timedOut
+          ? {
+              exitCode: exitCode === 0 ? TIMEOUT_EXIT_CODE : exitCode,
+              stdout,
+              stderr: `${stderr}\n[nax-finish] killed after ${opts.timeoutMs}ms timeout`,
+              timedOut: true,
+            }
+          : { exitCode, stdout, stderr },
+      );
+    });
+  });
 }
 
 /** Spawn an argv array directly — no shell. For flow-constructed commands. */

package/flows/nax-finish/nax-finish.flow.ts

@@ -17,11 +17,20 @@
  * - `load_ctx` is an `action`, not a `compute`: it shells git + `nax features
  *   resolve` once, and its output feeds both the review prompts (specPath) and
  *   the acceptance gate (groups), so nothing resolves the feature twice.
- * - Review fixes loop: `review_* → route_* → fix_* → (re-run acceptance |
- *   re-review) → review_*` until the reviewer comes back clean or the fix cap
- *   trips. A single-shot fix left the fixed diff unverified.
+ * - Review fixes loop: `review_* → route_* → fix_* → commit_* → (re-run
+ *   acceptance | re-review) → review_*` until the reviewer comes back clean or
+ *   the fix cap trips. A single-shot fix left the fixed diff unverified.
+ * - Every `fix_*` node is followed by a `commit_*` node. The reviewers read
+ *   `git diff <base>...HEAD`, so an uncommitted fix is invisible to the
+ *   re-review: the loop re-reported findings that were already fixed and always
+ *   escalated at the cap (issue #1397).
  * - `route_*` compute nodes hold the escalate/clean/fix decision so the cap is
  *   enforced deterministically rather than trusting the model's own route.
+ * - `quality_gates` re-runs the feature's acceptance tests before the repo's
+ *   own commands. The quality-review and gate fix loops both edit code after
+ *   the `acceptance` node last passed, and the repo-root `test` command does
+ *   not cover per-feature acceptance tests — so without this a fix could break
+ *   the contract the first gate proved and still ship.
  */
 import { defineFlow, extractJsonObject } from "acpx/flows";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
@@ -29,6 +38,7 @@ import {
   _contextDeps,
   buildEscalationComment,
   commitAndPush,
+  commitFixes,
   detectBaseBranch,
   loadQualityCommands,
   openOrPromotePr,
@@ -39,7 +49,7 @@ import {
   runQualityGates,
   writeResult,
 } from "./steps";
-import type { AcceptanceGroup, FinishInput, ReviewVerdict } from "./types";
+import type { AcceptanceGroup, FinishInput, FinishResult, ReviewVerdict } from "./types";
 
 const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
 
@@ -55,6 +65,8 @@ interface LoadCtxOutput {
   base?: string;
   specPath?: string;
   groups?: AcceptanceGroup[];
+  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
+  acceptanceStatus?: string;
   route?: string;
 }
 
@@ -66,16 +78,48 @@ function loadCtxOf(ctx: { outputs: unknown }): LoadCtxOutput {
   return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
 }
 
-/** Re-run the acceptance gate, routing on the shared fix-cap rules. */
+/**
+ * Re-run the acceptance gate, routing on the shared fix-cap rules.
+ *
+ * "Nothing ran" is not a pass — the same rule `quality_gates` applies to an
+ * unconfigured repo. `nax features resolve` reports `groups: []` for BOTH
+ * `no-prd` and `disabled`, and reports `exists: false` for a group whose test
+ * was expected at its canonical path but never generated. Treating all of those
+ * as green let the flow open a ready PR having verified nothing about the
+ * feature's own contract (#1398). Only `disabled` — the repo's explicit opt-out
+ * — skips cleanly.
+ */
 async function acceptanceGateNode(ctx: {
   input: unknown;
   outputs: unknown;
   state: { steps: { nodeId: string }[] };
 }): Promise<{ route: string; reason?: string; output: string }> {
   const i = inputOf(ctx);
-  const groups = loadCtxOf(ctx).groups ?? [];
+  const { groups = [], acceptanceStatus } = loadCtxOf(ctx);
+  if (acceptanceStatus === "disabled") {
+    return { route: "proceed", output: "[acceptance] disabled in .nax/config.json — skipping" };
+  }
+  if (acceptanceStatus === "no-prd") {
+    return {
+      route: "escalate",
+      reason: `Acceptance targets could not be computed (status: no-prd) — nothing was verified for "${i.feature}".`,
+      output: "[acceptance] no prd.json resolved — acceptance targets unknown",
+    };
+  }
+
   const r = await runAcceptanceGate(i.workdir, groups, { timeoutMs: i.timeouts?.acceptanceMs });
-  if (r.passed) return { route: "proceed", output: r.output };
+  if (r.passed) {
+    // A real failure below routes to the fix loop, which is more actionable;
+    // the coverage hole is only reported once the runnable groups are green.
+    if (r.missing.length > 0) {
+      return {
+        route: "escalate",
+        reason: `Acceptance test never generated for: ${r.missing.join(", ")} — that package's contract is unverified.`,
+        output: r.output,
+      };
+    }
+    return { route: "proceed", output: r.output };
+  }
   const attempts = fixAttemptCount(ctx, "fix_acceptance");
   if (attempts >= MAX_FIX_ATTEMPTS) {
     return {
@@ -119,6 +163,26 @@ function routeReview(
   return { route: "fix", findings };
 }
 
+/**
+ * Build the `commit_<phase>` node that follows `fix_<phase>`.
+ *
+ * One node per phase rather than a single shared one because each returns to a
+ * different successor, and acpx routes on the node id — a shared node would
+ * need a switch reconstructing which fix ran from the step history.
+ */
+function commitFixNode(phase: "acceptance" | "spec" | "quality" | "gate") {
+  return {
+    nodeType: "action" as const,
+    async run(ctx: { input: unknown }): Promise<{ committed: boolean }> {
+      const i = inputOf(ctx);
+      // skipHooks: an intermediate checkpoint must not be rejected by a repo's
+      // pre-commit hook — quality_gates runs the repo's real gates before any
+      // PR opens, and a hook failure here would kill the flow mid-loop.
+      return commitFixes(i.workdir, `fix(${i.feature}): nax-finish ${phase} fixes`, { skipHooks: true });
+    },
+  };
+}
+
 /** Normalise a reviewer's JSON, rewriting a findings-free `proceed` to `clean`. */
 function parseVerdict(text: string): ReviewVerdict {
   const raw = extractJsonObject(text) as Partial<ReviewVerdict>;
@@ -162,6 +226,7 @@ export default defineFlow({
       prompt: (ctx) => fixPrompt("acceptance", ctx),
       parse: parseVerdict,
     },
+    commit_acceptance: commitFixNode("acceptance"),
     review_spec: {
       nodeType: "acp",
       session: { isolated: true },
@@ -181,6 +246,7 @@ export default defineFlow({
       prompt: (ctx) => fixPrompt("spec", ctx),
       parse: parseVerdict,
     },
+    commit_spec: commitFixNode("spec"),
     review_quality: {
       nodeType: "acp",
       session: { isolated: true },
@@ -200,15 +266,57 @@ export default defineFlow({
       prompt: (ctx) => fixPrompt("quality", ctx),
       parse: parseVerdict,
     },
+    commit_quality: commitFixNode("quality"),
     fix_gate: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("gate", ctx),
       parse: parseVerdict,
     },
+    commit_gate: commitFixNode("gate"),
     quality_gates: {
       nodeType: "action",
       async run(ctx) {
         const i = inputOf(ctx);
+
+        // Acceptance is gate zero here, not just at the `acceptance` node.
+        // Both fix loops that run after it — quality review and this gate —
+        // edit code, and the repo-root `test` command does not cover the
+        // feature's acceptance tests: they live under `<pkg>/.nax/features/<f>/`
+        // and usually need their own runner config. Re-running them here is what
+        // makes "nothing reaches open_pr without the feature's own contract
+        // passing against the tree as it will ship" true on every path (#1398).
+        //
+        // Unconditional, though the common green path re-runs a gate that
+        // already passed: acceptance is the cheapest gate in the pipeline, and a
+        // conditional skip derived from step history would be a check that can
+        // be *wrong* — a silent false green, the failure mode this exists to
+        // prevent.
+        //
+        // `missing` is deliberately ignored: groups are resolved once at
+        // load_ctx, so a coverage hole was already escalated by the acceptance
+        // node and cannot appear here.
+        const acc = await runAcceptanceGate(i.workdir, loadCtxOf(ctx).groups ?? [], {
+          timeoutMs: i.timeouts?.acceptanceMs,
+        });
+        if (!acc.passed) {
+          // Short-circuit: the repo gates are re-run next round anyway, and
+          // skipping them keeps this out of the "nothing configured" branch
+          // below, which would otherwise misreport configured-but-skipped
+          // commands as absent.
+          const accAttempts = fixAttemptCount(ctx, "fix_gate");
+          const failing = ["acceptance"];
+          if (accAttempts >= MAX_FIX_ATTEMPTS) {
+            return {
+              route: "escalate",
+              reason: `A later fix broke the feature's own contract: acceptance still failing after ${accAttempts} fix attempts.`,
+              ran: [],
+              failing,
+              output: acc.output,
+            };
+          }
+          return { route: "fix", ran: [], failing, output: acc.output };
+        }
+
         const cmds = await loadQualityCommands(i.workdir);
         const r = await runQualityGates(i.workdir, cmds, { timeoutMs: i.timeouts?.gateMs });
         if (r.passed) return { route: "green", ran: r.ran, failing: r.failing, output: r.output };
@@ -289,12 +397,36 @@ export default defineFlow({
           syncNote = `\n\n> Note: nax-finish could not push its partial fixes — ${String(err)}`;
         }
 
+        // Write the result BEFORE attempting delivery. Delivery touches the
+        // network and the forge — a rate limit, an expired token, a locked PR
+        // or an unrecognised remote used to throw here, killing the node before
+        // any result existed. The plugin then had nothing to report and, on the
+        // Telegram channel, nothing to notify from: the one path whose job is
+        // to say "a human is needed" was the one path with no fallback (#1399).
+        const result: FinishResult = {
+          feature: i.feature,
+          status: "escalated",
+          escalationReason: reason,
+          findings: verdict?.findings ?? [],
+        };
+        await writeResult(i.workdir, result);
+
         const comment = buildEscalationComment(i.feature, reason, verdict?.findings ?? []) + syncNote;
-        const { url, channel } = await postEscalation(i.workdir, i.branch, comment, {
-          preferTelegram: i.escalateTelegram,
-        });
-        await writeResult(i.workdir, { feature: i.feature, status: "escalated", url, escalationReason: reason });
-        return { route: "done", url, channel, escalationReason: reason };
+        let url: string | undefined;
+        let channel: string | undefined;
+        let deliveryError: string | undefined;
+        try {
+          const posted = await postEscalation(i.workdir, i.branch, comment, {
+            preferTelegram: i.escalateTelegram,
+          });
+          url = posted.url;
+          channel = posted.channel;
+        } catch (err) {
+          deliveryError = String(err);
+        }
+        await writeResult(i.workdir, { ...result, url, deliveryError });
+
+        return { route: "done", url, channel, deliveryError, escalationReason: reason };
       },
     },
   },
@@ -304,7 +436,11 @@ export default defineFlow({
       from: "acceptance",
       switch: { on: "$.route", cases: { proceed: "review_spec", fix: "fix_acceptance", escalate: "escalate" } },
     },
-    { from: "fix_acceptance", to: "acceptance" },
+    // Each fix commits before anything re-reads the diff: the reviewers see
+    // `git diff <base>...HEAD` only, so an uncommitted fix would be re-reported
+    // verbatim until the cap escalated it (#1397).
+    { from: "fix_acceptance", to: "commit_acceptance" },
+    { from: "commit_acceptance", to: "acceptance" },
     { from: "review_spec", to: "route_spec" },
     {
       from: "route_spec",
@@ -312,7 +448,8 @@ export default defineFlow({
     },
     // Spec fixes re-run the acceptance gate first (they can break it), and the
     // acceptance node's `proceed` edge leads back into review_spec for re-review.
-    { from: "fix_spec", to: "acceptance" },
+    { from: "fix_spec", to: "commit_spec" },
+    { from: "commit_spec", to: "acceptance" },
     { from: "review_quality", to: "route_quality" },
     {
       from: "route_quality",
@@ -320,11 +457,13 @@ export default defineFlow({
     },
     // Quality fixes are re-reviewed by the same lens; the repo-root gates that
     // follow catch anything the fix broke mechanically.
-    { from: "fix_quality", to: "review_quality" },
+    { from: "fix_quality", to: "commit_quality" },
+    { from: "commit_quality", to: "review_quality" },
     {
       from: "quality_gates",
       switch: { on: "$.route", cases: { green: "open_pr", fix: "fix_gate", escalate: "escalate" } },
     },
-    { from: "fix_gate", to: "quality_gates" },
+    { from: "fix_gate", to: "commit_gate" },
+    { from: "commit_gate", to: "quality_gates" },
   ],
 });

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

@@ -21,24 +21,47 @@ export function buildAcceptanceCommand(repoRoot: string, group: AcceptanceGroup)
   return template.replace(/\{\{FILE\}\}|\{\{file\}\}|\{\{files\}\}/g, absFile);
 }
 
+export interface AcceptanceGateOutcome {
+  /** Every group that ran exited 0. Says nothing about groups that could not run. */
+  passed: boolean;
+  ran: number;
+  /**
+   * Package names whose acceptance test the resolver expected at its canonical
+   * path but which is absent on disk — never generated, or generation failed.
+   * The caller must treat a non-empty list as a coverage hole rather than a
+   * pass: skipping these silently is how a feature reached a "ready" PR with
+   * nothing verified.
+   */
+  missing: string[];
+  output: string;
+}
+
 export async function runAcceptanceGate(
   repoRoot: string,
   groups: AcceptanceGroup[],
   opts: { timeoutMs?: number } = {},
-): Promise<{ passed: boolean; ran: number; output: string }> {
+): Promise<AcceptanceGateOutcome> {
   const chunks: string[] = [];
   const timeoutMs = opts.timeoutMs ?? DEFAULT_ACCEPTANCE_TIMEOUT_MS;
+  const missing: string[] = [];
   let ran = 0;
   for (const g of groups) {
-    if (!g.exists) continue;
+    const name = g.packageDir || "root";
+    if (!g.exists) {
+      missing.push(name);
+      continue;
+    }
     const cwd = g.packageDir ? `${repoRoot}/${g.packageDir}` : repoRoot;
     ran += 1;
     const res = await _acceptanceDeps.runShell(buildAcceptanceCommand(repoRoot, g), { cwd, timeoutMs });
-    chunks.push(`[${g.packageDir || "root"}] exit=${res.exitCode}\n${res.stdout}\n${res.stderr}`);
-    if (res.exitCode !== 0) return { passed: false, ran, output: chunks.join("\n\n") };
+    chunks.push(`[${name}] exit=${res.exitCode}\n${res.stdout}\n${res.stderr}`);
+    if (res.exitCode !== 0) return { passed: false, ran, missing, output: chunks.join("\n\n") };
+  }
+  if (missing.length > 0) {
+    chunks.push(`[acceptance] no acceptance test file on disk for: ${missing.join(", ")}`);
   }
   if (ran === 0) chunks.push("[acceptance] no acceptance test files present — nothing to run");
-  return { passed: true, ran, output: chunks.join("\n\n") };
+  return { passed: true, ran, missing, output: chunks.join("\n\n") };
 }
 
 function languageRunner(language: string): string {

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

@@ -12,15 +12,64 @@ const URL_REGEX = /https?:\/\/\S+/;
 
 export type Forge = "github" | "gitlab";
 
+/**
+ * Host of a git remote, for both URL forms git accepts:
+ * `git@host:path` (scp-like) and `scheme://[user@]host[:port]/path`.
+ */
+export function remoteHost(remoteUrl: string): string {
+  const scp = remoteUrl.match(/^[^/]*@([^:/]+):/);
+  if (scp?.[1]) return scp[1].toLowerCase();
+  const url = remoteUrl.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^:/]+)/i);
+  return url?.[1]?.toLowerCase() ?? "";
+}
+
+/**
+ * Classify by host name.
+ *
+ * Matching the host (not a substring of the whole URL) is what makes
+ * self-hosted instances work: `"gitlab.mycorp.com".includes("gitlab.com")` is
+ * false, so the previous check rejected every self-hosted forge. GitHub is
+ * tested first purely for determinism on an absurd host naming both.
+ */
+function forgeFromHost(host: string): Forge | null {
+  if (host.includes("github")) return "github";
+  if (host.includes("gitlab")) return "gitlab";
+  return null;
+}
+
+/**
+ * Last resort for an enterprise host that names neither forge (`git.corp.com`):
+ * ask which CLI is installed. Only decisive when exactly one is — with both or
+ * neither present a guess would send `gh` at a GitLab remote.
+ */
+async function forgeFromCli(run: RunFn, repoRoot: string): Promise<Forge | null> {
+  const [gh, glab] = await Promise.all([
+    run(["gh", "--version"], { cwd: repoRoot }),
+    run(["glab", "--version"], { cwd: repoRoot }),
+  ]);
+  const hasGh = gh.exitCode === 0;
+  const hasGlab = glab.exitCode === 0;
+  if (hasGh && !hasGlab) return "github";
+  if (hasGlab && !hasGh) return "gitlab";
+  return null;
+}
+
 export async function detectForge(run: RunFn, repoRoot: string, stage: string): Promise<Forge> {
   const remote = await run(["git", "remote", "get-url", "origin"], { cwd: repoRoot });
   const remoteUrl = remote.stdout.trim();
-  if (remoteUrl.includes("github.com")) return "github";
-  if (remoteUrl.includes("gitlab.com")) return "gitlab";
-  throw new FinishError(`Unable to determine forge from remote URL "${remoteUrl}"`, "FINISH_UNKNOWN_FORGE", {
-    stage,
-    remoteUrl,
-  });
+  const host = remoteHost(remoteUrl);
+
+  const byHost = forgeFromHost(host);
+  if (byHost) return byHost;
+
+  const byCli = await forgeFromCli(run, repoRoot);
+  if (byCli) return byCli;
+
+  throw new FinishError(
+    `Unable to determine forge for remote host "${host || remoteUrl}" — its name matches neither github nor gitlab, and the gh/glab probe was inconclusive`,
+    "FINISH_UNKNOWN_FORGE",
+    { stage, remoteUrl, host },
+  );
 }
 
 /** Best-effort URL extraction: try `{url}` JSON first, fall back to a raw URL regex. */

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

@@ -1,11 +1,17 @@
 /**
  * Branch synchronisation for the nax-finish flow.
  *
- * Every fix node edits the working tree in place. Without this step those edits
- * stay local and uncommitted: `gh pr create --head <branch>` then opens a PR
- * from the *remote* branch, which is missing every fix the flow just made (and
- * an escalation comment would describe state nobody else can see). Both
- * terminal nodes call `commitAndPush` before touching the forge.
+ * Every fix node edits the working tree in place, which two different consumers
+ * would otherwise miss:
+ *
+ * - The **reviewers** read `git diff <base>...HEAD` — committed history only.
+ *   With the fixes uncommitted, every re-review re-read the pre-fix code and
+ *   re-reported findings the fix node had already resolved, so the loop could
+ *   never converge and always escalated at the fix cap (issue #1397). Each
+ *   `commit_*` node calls `commitFixes` for this reason.
+ * - The **forge**: `gh pr create --head <branch>` opens a PR from the *remote*
+ *   branch, and an escalation comment would describe state nobody else can see.
+ *   Both terminal nodes call `commitAndPush` before touching the forge.
  */
 import { FinishError } from "../errors";
 import { runArgv } from "../exec";
@@ -32,34 +38,62 @@ async function isDirty(repoRoot: string): Promise<boolean> {
   return status.stdout.trim().length > 0;
 }
 
+/**
+ * Commit the working tree, if it has anything in it, without pushing.
+ *
+ * Called by the `commit_*` nodes after every fix node so the next reviewer's
+ * `git diff <base>...HEAD` contains the fix. `git add -A` (not `-u`) because a
+ * fix routinely adds a *new* test file, and an untracked file is invisible to
+ * that diff — which is also why committing beats widening the reviewer's diff
+ * to include the working tree.
+ *
+ * `skipHooks` (used by every mid-loop `commit_*` node) adds `--no-verify`. Those
+ * commits are internal checkpoints, not shipped history: a repo whose
+ * pre-commit hook runs lint or typecheck would otherwise reject an intermediate
+ * state — a lint error the gate loop was about to fix — and take the whole flow
+ * down with it, with no result file. Nothing is lost by skipping them, because
+ * `quality_gates` runs the repo's own build/typecheck/lint/test and no PR opens
+ * unless they are green. The terminal `commitAndPush` leaves hooks enabled.
+ *
+ * A failing commit still throws: the fix is then unreviewable, and continuing
+ * would silently reproduce the stale-diff bug this exists to fix.
+ */
+export async function commitFixes(
+  repoRoot: string,
+  message: string,
+  opts: { skipHooks?: boolean } = {},
+): Promise<{ committed: boolean }> {
+  if (!(await isDirty(repoRoot))) return { committed: false };
+
+  const add = await _gitDeps.run(["git", "add", "-A"], { cwd: repoRoot });
+  if (add.exitCode !== 0) {
+    throw new FinishError(
+      `git add failed in "${repoRoot}": ${add.stderr.trim() || `exit ${add.exitCode}`}`,
+      "FINISH_GIT_ADD_FAILED",
+      { stage: "finish-git", repoRoot },
+    );
+  }
+  const commitArgv = ["git", "commit", "-m", message, ...(opts.skipHooks ? ["--no-verify"] : [])];
+  const commit = await _gitDeps.run(commitArgv, { cwd: repoRoot });
+  if (commit.exitCode !== 0) {
+    throw new FinishError(
+      `git commit failed in "${repoRoot}": ${commit.stderr.trim() || commit.stdout.trim() || `exit ${commit.exitCode}`}`,
+      "FINISH_GIT_COMMIT_FAILED",
+      { stage: "finish-git", repoRoot },
+    );
+  }
+  return { committed: true };
+}
+
 /**
  * Commit any outstanding fixes and push the branch to `origin`.
  *
  * The push is unconditional — even with nothing new to commit the local branch
- * may be ahead of its remote (nax's own run commits, or a previous partial
- * finish), and the PR must reflect HEAD.
+ * may be ahead of its remote (nax's own run commits, or the `commit_*` nodes'
+ * per-round commits), and the PR must reflect HEAD.
  */
 export async function commitAndPush(repoRoot: string, branch: string, message: string): Promise<SyncOutcome> {
-  let committed = false;
-  if (await isDirty(repoRoot)) {
-    const add = await _gitDeps.run(["git", "add", "-A"], { cwd: repoRoot });
-    if (add.exitCode !== 0) {
-      throw new FinishError(
-        `git add failed in "${repoRoot}": ${add.stderr.trim() || `exit ${add.exitCode}`}`,
-        "FINISH_GIT_ADD_FAILED",
-        { stage: "finish-git", repoRoot },
-      );
-    }
-    const commit = await _gitDeps.run(["git", "commit", "-m", message], { cwd: repoRoot });
-    if (commit.exitCode !== 0) {
-      throw new FinishError(
-        `git commit failed in "${repoRoot}": ${commit.stderr.trim() || commit.stdout.trim() || `exit ${commit.exitCode}`}`,
-        "FINISH_GIT_COMMIT_FAILED",
-        { stage: "finish-git", repoRoot, branch },
-      );
-    }
-    committed = true;
-  }
+  const { committed } = await commitFixes(repoRoot, message);
 
   const push = await _gitDeps.run(["git", "push", "--set-upstream", "origin", branch], { cwd: repoRoot });
   if (push.exitCode !== 0) {

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

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { FinishError } from "../errors";
 import { DEFAULT_GATE_TIMEOUT_MS, runShell } from "../exec";
 import type { ShellRunFn } from "../types";
@@ -12,9 +13,17 @@ export interface QualityCommands {
 
 export const _qualityDeps: { runShell: ShellRunFn; readText: (path: string) => Promise<string | null> } = {
   runShell,
+  // node:fs, not Bun.file — this module runs inside acpx's Node process, where
+  // the `Bun` global does not exist (see the header of `../exec.ts`). A single
+  // read that treats ENOENT as "absent" also avoids the exists()-then-read race
+  // the Bun version had.
   readText: async (path) => {
-    const file = Bun.file(path);
-    return (await file.exists()) ? await file.text() : null;
+    try {
+      return await readFile(path, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
   },
 };