@nathapp/nax 0.76.0 → 0.77.1

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/types.ts

@@ -16,13 +16,21 @@ export interface Finding {
 }
 export interface ReviewVerdict {
   /**
-   * `clean` is not a model-produced route — the review nodes' `parse` rewrites
-   * `proceed` with zero findings to `clean` so the graph can skip the fix node
-   * entirely instead of prompting an agent to "apply fixes" for nothing.
+   * Neither `clean` nor `reprompt` is a model-produced route.
+   *
+   * `clean` — `parse` rewrites `proceed` with zero findings, so the graph can
+   * skip the fix node instead of prompting an agent to "apply fixes" for nothing.
+   *
+   * `reprompt` — `parse` could not read JSON out of the reply at all. Returning
+   * this rather than throwing is deliberate: a throw fails the acp node and kills
+   * the whole flow with no result file, bypassing the `escalate` sink that exists
+   * to report exactly this kind of dead end.
    */
-  route: "proceed" | "escalate" | "clean";
+  route: "proceed" | "escalate" | "clean" | "reprompt";
   findings: Finding[];
   escalationReason?: string;
+  /** Bounded tail of an unparseable reply; set only when `route` is `reprompt`. */
+  raw?: string;
 }
 /** Wall-clock budgets, forwarded from `finish.autoFlow.timeouts` by the plugin. */
 export interface FinishTimeouts {
@@ -53,6 +61,13 @@ export interface FinishRound {
   findings: Finding[];
   /** Gate commands that were red this round (gate phase). */
   failing?: string[];
+  /**
+   * `HEAD` SHA after this round's commit (set only when `committed`); absent
+   * on no-op rounds so a reader can distinguish "no commit" from "record lost".
+   * Lets "Fixed in `<sha>`" be reconstructed from the audit trail alone, rather
+   * than by matching round timestamps against `git log`.
+   */
+  sha?: string;
 }
 
 export interface FinishInput {

package/flows/nax-finish/verdict.ts

@@ -0,0 +1,159 @@
+/**
+ * Turning a reviewer's reply into a deterministic route.
+ *
+ * Lives outside `nax-finish.flow.ts` for two reasons: the flow file sits within
+ * a few lines of the 600-line hard limit, and this is a cohesive unit —
+ * `routeReview` consumes exactly what the parsers produce.
+ *
+ * The central invariant: **no parser here ever throws.** acpx has no node-level
+ * retry and no error edge (`AcpNodeDefinition` offers only `prompt`/`parse`;
+ * `FlowEdge` is only `to` or `switch`), so a throw inside `parse` fails the node
+ * and fails the run — exit 1, no result file, no notification, bypassing the
+ * `escalate` node that exists to report precisely this.
+ */
+import { extractJsonObject } from "acpx/flows";
+import { type OutputsCtx, type StepsCtx, fixAttemptCount } from "./flow-ctx";
+import type { Finding, ReviewVerdict } from "./types";
+
+/**
+ * Cap on fix-and-reverify iterations, per phase, before escalating instead of
+ * looping forever. acpx's flow engine has no built-in cycle guard, so without
+ * this cap a stubborn failure (LLM can't fix it, or fixes something else each
+ * time) hangs `acpx flow run` — and the post-run plugin awaits that subprocess.
+ *
+ * Lives here rather than in the flow file because `routeReview` needs it; the
+ * flow imports it back for the acceptance node and the two `quality_gates` caps.
+ */
+export const MAX_FIX_ATTEMPTS = 3;
+
+/**
+ * Unparseable reviews tolerated per phase before escalating.
+ *
+ * One. A reviewer that ignores the JSON contract twice in a row is not going to
+ * comply on a third ask, and each review is the most expensive node in the flow
+ * (128s and ~4.2M tokens on the run that motivated this).
+ */
+export const MAX_REPROMPT_ATTEMPTS = 1;
+
+/** How much of an unparseable reply to carry forward — it lands in a PR comment and a Telegram message. */
+export const RAW_TAIL_LIMIT = 500;
+
+function tail(text: string): string {
+  const t = text.trim();
+  return t.length <= RAW_TAIL_LIMIT ? t : `…${t.slice(-(RAW_TAIL_LIMIT - 1))}`;
+}
+
+/** Shared happy path: read the object, normalise findings, rewrite empty `proceed` to `clean`. */
+function parseVerdictJson(text: string): ReviewVerdict {
+  const raw = extractJsonObject(text) as Partial<ReviewVerdict>;
+  const findings: Finding[] = Array.isArray(raw.findings) ? raw.findings : [];
+  const route = raw.route === "escalate" ? "escalate" : findings.length === 0 ? "clean" : "proceed";
+  return { route, findings, escalationReason: raw.escalationReason };
+}
+
+/**
+ * Parser for `review_spec` / `review_quality`, whose JSON is load-bearing —
+ * `findingsOf` reads it and the fix loop is driven by it. An unreadable reply
+ * routes to `reprompt` so `routeReview` can ask once more before escalating.
+ */
+export function parseReviewVerdict(text: string): ReviewVerdict {
+  try {
+    return parseVerdictJson(text);
+  } catch {
+    return { route: "reprompt", findings: [], raw: tail(text) };
+  }
+}
+
+/**
+ * Parser for the four `fix_*` nodes, whose parsed value nothing reads —
+ * `findingsOf` only ever looks at `review_spec`/`review_quality`, and
+ * `commitFixNode` decides from git rather than from the model's word.
+ *
+ * Never routes `reprompt`: the fix nodes have unconditional edges
+ * (`fix_spec → commit_spec`), so a reprompt route would have nowhere to go.
+ */
+export function parseFixVerdict(text: string): ReviewVerdict {
+  try {
+    return parseVerdictJson(text);
+  } catch {
+    return { route: "proceed", findings: [] };
+  }
+}
+
+/**
+ * How many times this phase's review already came back unparseable.
+ *
+ * Counts step *outputs*, not step ids: `commit_quality → review_quality` and
+ * `commit_gate → review_quality` are legitimate re-entries in the normal fix
+ * loop, so counting bare `review_<phase>` steps would escalate a healthy run.
+ *
+ * This is observable only because `parseReviewVerdict` returns rather than
+ * throws — a returned verdict makes acpx record the step as successful with
+ * this output. A throw would record it `failed`, with nothing to count.
+ *
+ * SELF-INCLUSIVE, not self-exclusive: acpx's runtime calls
+ * `recordFlowStepOutcome(runDir, state, step)` (acpx/src/flows/runtime.ts:262),
+ * which pushes the just-finished step onto `state.steps`
+ * (acpx/src/flows/runtime.ts:499), BEFORE `resolveNextNode` runs and before the
+ * following node (`route_<phase>`) executes. So by the time `routeReview` reads
+ * `ctx.state.steps` here, the current round's own `review_<phase>` step is
+ * already included. On the very first unparseable reply this already returns
+ * 1, not 0. `routeReview`'s comparison against `MAX_REPROMPT_ATTEMPTS` MUST
+ * stay `<=` (not `<`) for that reason — see routeReview below.
+ */
+export function repromptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
+  return (ctx.state.steps ?? []).filter(
+    (s) => s.nodeId === `review_${phase}` && (s.output as ReviewVerdict | undefined)?.route === "reprompt",
+  ).length;
+}
+
+/**
+ * Turn a reviewer verdict into a deterministic route.
+ *
+ * `clean` (no findings) skips the fix node entirely — prompting an agent to
+ * "apply the recommended fixes" for an empty finding list burns a turn and
+ * invites unrequested edits.
+ *
+ * The `reprompt` branch MUST come first. A reprompt verdict carries zero
+ * findings, so checking `findings.length === 0` ahead of it would route an
+ * unreadable review to `clean`, and the flow would open a PR having reviewed
+ * nothing. That silent false green is worse than the crash this replaces.
+ */
+export function routeReview(
+  ctx: OutputsCtx & StepsCtx,
+  phase: "spec" | "quality",
+): { route: string; escalationReason?: string; findings: Finding[] } {
+  const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
+  const findings = verdict?.findings ?? [];
+  if (verdict?.route === "reprompt") {
+    // `attempts` is self-inclusive (see repromptCount) — it already counts this
+    // round's failure, so `<=` (not `<`) is what makes MAX_REPROMPT_ATTEMPTS=1
+    // tolerate exactly one retry before escalating.
+    const attempts = repromptCount(ctx, phase);
+    if (attempts <= MAX_REPROMPT_ATTEMPTS) return { route: "reprompt", findings };
+    return {
+      route: "escalate",
+      escalationReason:
+        `${phase} reviewer returned unparseable output after ${attempts} attempts. ` +
+        `Last reply: ${verdict.raw ?? "(empty)"}`,
+      findings,
+    };
+  }
+  if (verdict?.route === "escalate") {
+    return {
+      route: "escalate",
+      escalationReason: verdict.escalationReason ?? `${phase} review raised a finding needing human judgment`,
+      findings,
+    };
+  }
+  if (findings.length === 0) return { route: "clean", findings };
+  const attempts = fixAttemptCount(ctx, `fix_${phase}`);
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      escalationReason: `${phase} review still reporting ${findings.length} finding(s) after ${attempts} fix attempts.`,
+      findings,
+    };
+  }
+  return { route: "fix", findings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.76.0",
+  "version": "0.77.1",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {