@nathapp/nax 0.77.3 → 0.79.0

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

@@ -17,6 +17,7 @@
  *   *outcome*, so the currently-executing node is never in this list — which is
  *   what lets `incrementalSince` find the *previous* review rather than itself.
  */
+import type { AcceptanceStatus } from "./steps/context";
 import type { AcceptanceGroup, Finding, FinishInput, FinishPhase, ReviewVerdict } from "./types";
 
 /** Minimal shapes so each reader takes only the part of the context it reads. */
@@ -34,11 +35,13 @@ export interface LoadCtxOutput {
   base?: string;
   specPath?: string;
   groups?: AcceptanceGroup[];
-  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
-  acceptanceStatus?: string;
+  /** `nax features resolve`'s acceptance status, narrowed at `resolveFeature`. */
+  acceptanceStatus?: AcceptanceStatus;
   /** Test-file regex sources from `nax features resolve`; empty = cannot classify. */
   testFileRegex?: string[];
   route?: string;
+  /** Set only when `route` is `escalate` — see `preflight`. */
+  reason?: string;
 }
 
 export function fixAttemptCount(ctx: StepsCtx, fixNodeId: string): number {
@@ -111,15 +114,32 @@ export function findingsOf(ctx: OutputsCtx, phase: FinishPhase): Finding[] {
  * would have discarded the earlier `shaBefore` and silently under-scoped the
  * review.
  *
+ * Only commit steps that actually **committed** anchor the window. A fix node
+ * that edited nothing still records a `commit_*` step, and its `shaBefore` is
+ * the current HEAD — so scoping to it asks the reviewer for `HEAD..HEAD`, an
+ * empty diff, while the prompt tells it the prior findings "have since been
+ * fixed and committed". It returns clean, `route_*` sends the flow onward, and
+ * the findings ship unfixed. That leaves the loop through the green door, so
+ * `MAX_FIX_ATTEMPTS` never catches it. A no-op round therefore either yields
+ * the window to a later real commit, or falls back to a full review.
+ *
+ * Rounds journalled before `committed` existed carry no such field; `!== false`
+ * keeps replaying them on the previous behaviour rather than widening every
+ * resumed review to the whole branch.
+ *
  * Returns null — a full review — when there is no prior review of this phase
- * (round 1), no commit since it (nothing new to look at), or the commit step
- * recorded no `shaBefore`.
+ * (round 1), no commit landed since it (nothing new to look at), or the commit
+ * step recorded no `shaBefore`.
  */
 export function incrementalSince(ctx: OutputsCtx & StepsCtx, phase: "spec" | "quality"): string | null {
   const steps = ctx.state.steps ?? [];
   const lastReview = steps.map((s) => s.nodeId).lastIndexOf(`review_${phase}`);
   if (lastReview < 0) return null;
-  const firstCommit = steps.slice(lastReview + 1).find((s) => s.nodeId.startsWith("commit_"));
+  const firstCommit = steps
+    .slice(lastReview + 1)
+    .find(
+      (s) => s.nodeId.startsWith("commit_") && (s.output as { committed?: boolean } | undefined)?.committed !== false,
+    );
   if (!firstCommit) return null;
   return (firstCommit.output as { shaBefore?: string | null } | undefined)?.shaBefore ?? null;
 }

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

@@ -31,11 +31,17 @@
  *   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.
- * - `commit_gate` re-enters `review_quality` when its fix touched non-test code
- *   — the gate loop was previously the one editing loop whose output only ever
- *   faced mechanical checks. A test-only fix skips the re-review by explicit
- *   cost tradeoff; see `gateCommitRoute` for why that is a known hole. The skip
- *   records `review-skipped`, so it is visible in the audit.
+ * - `commit_gate` re-enters `review_quality` whenever its fix committed — the
+ *   gate loop was otherwise the one editing loop whose output faced only
+ *   mechanical checks, which a fix that degrades the tests it repairs will
+ *   satisfy. A test-only fix used to skip the re-review as a cost tradeoff;
+ *   #1510 closed that hole. See `gateCommitRoute`.
+ * - `load_ctx` and `open_pr` both route to `escalate` rather than throwing on
+ *   their own failures. acpx has no error edge, so a throw ends the run with no
+ *   result file for the plugin to read or notify from — the one outcome that
+ *   must always be reported is "a human is needed" (#1399). `open_pr` matters
+ *   most: it is reached only after every gate is green, so a failed push or
+ *   forge call there discards a completed, verified run.
  * - Every `commit_*` node appends its round to the finish-audit trail as it
  *   happens, rather than a terminal node reconstructing them from
  *   `ctx.state.steps`. Appending live is what makes the trail survive a flow
@@ -49,6 +55,7 @@ import { narrativePrompt, parseNarrativeNode } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
+  acceptanceGateNode,
   amendPrBodyNode,
   appendRound,
   buildCommitRound,
@@ -59,21 +66,19 @@ import {
   detectForge,
   filesInCommit,
   loadFinishPrContext,
-  loadQualityCommands,
   openOrPromotePr,
   partitionTestFiles,
   postEscalation,
   preflight,
+  qualityGatesNode,
   resolveFeature,
   routeReviewAndRecord,
-  runAcceptanceGate,
-  runQualityGates,
   writeResult,
 } from "./steps";
 import type { Forge } from "./steps/forge";
 import { _prBodyDeps, buildFinishBody, buildFinishTitle } from "./steps/pr-body";
 import type { FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
-import { MAX_FIX_ATTEMPTS, parseFixVerdict, parseReviewVerdict, repromptCount } from "./verdict";
+import { parseFixVerdict, parseReviewVerdict, repromptCount } from "./verdict";
 
 /**
  * Disabled only on an explicit "0". An unset variable means enabled, so a flow
@@ -93,72 +98,28 @@ export const _openPrDeps = {
   buildFinishBody,
 };
 
-/**
- * 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 = [], 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) {
-    // 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 {
-      route: "escalate",
-      reason: `Acceptance tests still failing after ${attempts} fix attempts.`,
-      output: r.output,
-    };
-  }
-  return { route: "fix", output: r.output };
-}
-
 /**
  * Route for `commit_gate`, whose successor depends on what the fix touched.
  *
  * - `unchanged` — nothing committed; no new diff, so nothing to review.
  * - `tests-only` — every touched path matched the repo's test-file patterns.
- *   Skipped by explicit choice: the re-review is the flow's most expensive node
- *   and a gate fix is usually a mechanical test repair. **This is a real hole.**
- *   The defect that motivated the re-entry (rs-stock `b6fb66dd`) was itself
- *   test-only — 8 copy-pasted stubs across 3 test files — so this route would
- *   not have caught it. Widen it here if test-quality regressions start
- *   shipping — the audit's `review-skipped` rounds are the evidence.
  * - `changed` — production code was touched, or the paths could not be
  *   classified at all. "Cannot classify" reviews rather than skips.
+ *
+ * `tests-only` and `changed` both re-enter `review_quality` (#1510). They used
+ * to diverge: `tests-only` skipped the re-review as a cost tradeoff, on the
+ * reasoning that a gate fix is usually a mechanical test repair. That was a
+ * real hole — the defect that motivated the re-entry was itself test-only, 8
+ * copy-pasted stubs across 3 test files, so the skip would not have caught the
+ * very thing it was built for. A gate fix can turn a red suite green by
+ * degrading the tests it repairs, and `quality_gates` is satisfied by exactly
+ * that; nothing else read that diff. The audit settled the cost side: across
+ * every finish recorded, exactly one `gate` round has ever fired, so the skip
+ * was saving a review that almost never runs.
+ *
+ * The classification is kept even though both routes now review. It is what a
+ * cheaper test-quality-scoped reviewer would key off if gate rounds ever become
+ * frequent enough for the full re-review to hurt.
  */
 async function gateCommitRoute(
   i: FinishInput,
@@ -260,6 +221,7 @@ export default defineFlow({
           testFileRegex: resolution.testFileRegex,
           commitsAhead: pf.commitsAhead,
           route: pf.route,
+          ...(pf.reason ? { reason: pf.reason } : {}),
         };
       },
     },
@@ -333,75 +295,7 @@ export default defineFlow({
     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 };
-        // Nothing configured is not a pass — escalate immediately rather than
-        // open a "ready" PR having verified nothing. An LLM fix node cannot
-        // invent the repo's build/test commands.
-        if (r.ran.length === 0) {
-          return {
-            route: "escalate",
-            reason: "No quality.commands configured in .nax/config.json — nax-finish verified nothing.",
-            ran: r.ran,
-            failing: r.failing,
-            output: r.output,
-          };
-        }
-        const attempts = fixAttemptCount(ctx, "fix_gate");
-        if (attempts >= MAX_FIX_ATTEMPTS) {
-          return {
-            route: "escalate",
-            reason: `Quality gates still failing after ${attempts} fix attempts (${r.failing.join(", ")}).`,
-            ran: r.ran,
-            failing: r.failing,
-            output: r.output,
-          };
-        }
-        return { route: "fix", ran: r.ran, failing: r.failing, output: r.output };
-      },
+      run: qualityGatesNode,
     },
     open_pr: {
       nodeType: "action",
@@ -414,7 +308,24 @@ export default defineFlow({
         }
         // Every fix node edited the working tree; without this the PR would be
         // opened from a remote branch missing all of them.
-        const sync = await commitAndPush(i.workdir, i.branch, `fix(${i.feature}): nax-finish automated fixes`);
+        //
+        // Routed, not thrown. acpx has no error edge, so a throw here kills the
+        // flow — and this is the last node on the happy path, reached only once
+        // every gate is green and every fix has landed. It died before
+        // `writeResult`, so the plugin found no result file and notified
+        // nobody: the #1399 failure mode the `escalate` node was hardened
+        // against and this one was not. A protected branch, an expired token or
+        // a non-fast-forward push is exactly the kind of dead end `escalate`
+        // exists to report.
+        let sync: { committed: boolean };
+        try {
+          sync = await commitAndPush(i.workdir, i.branch, `fix(${i.feature}): nax-finish automated fixes`);
+        } catch (error) {
+          return {
+            route: "escalate",
+            reason: `nax-finish could not push "${i.branch}", so no PR was opened: ${String(error)}`,
+          };
+        }
 
         const fallbackTitle = `nax-finish: ${i.feature}`;
         const fallbackBody = `Automated finish of \`${i.feature}\`.`;
@@ -441,7 +352,18 @@ export default defineFlow({
           body = fallbackBody;
         }
 
-        const r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
+        // Same reasoning as the push above: a forge that refuses to create or
+        // promote (rate limit, revoked token, unrecognised remote) must reach a
+        // human through `escalate`, not take the flow down silently.
+        let r: { status: "opened" | "promoted" | "already-ready"; url?: string };
+        try {
+          r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
+        } catch (error) {
+          return {
+            route: "escalate",
+            reason: `nax-finish could not open or promote the PR for "${i.branch}": ${String(error)}`,
+          };
+        }
         await writeResult(i, { feature: i.feature, status: r.status, url: r.url });
         // The PR now exists with the mechanical narrative already in place.
         // Anything the narrative node does from here is an improvement on a
@@ -478,12 +400,14 @@ export default defineFlow({
             : routed.route_quality?.route === "escalate"
               ? routed.route_quality
               : undefined;
-        const loopExhausted =
-          outs.acceptance?.route === "escalate"
-            ? outs.acceptance
-            : outs.quality_gates?.route === "escalate"
-              ? outs.quality_gates
-              : undefined;
+        // Ordered by how far down the graph the node sits, so the *last* thing
+        // that gave up names the reason. `load_ctx` and `open_pr` are here
+        // because both can now route here rather than throw — a base ref that
+        // does not resolve, and a push or forge call that failed after every
+        // gate was green.
+        const loopExhausted = [outs.open_pr, outs.quality_gates, outs.acceptance, outs.load_ctx].find(
+          (o) => o?.route === "escalate",
+        );
         const reason =
           verdict?.escalationReason ?? loopExhausted?.reason ?? "nax-finish could not reach a green, shippable state";
 
@@ -531,7 +455,15 @@ export default defineFlow({
     },
   },
   edges: [
-    { from: "load_ctx", switch: { on: "$.route", cases: { proceed: "acceptance", "nothing-to-finish": "open_pr" } } },
+    {
+      from: "load_ctx",
+      switch: {
+        on: "$.route",
+        // `escalate`: the branch could not be measured against its base at all,
+        // so neither "proceed" nor "nothing-to-finish" would be a true claim.
+        cases: { proceed: "acceptance", "nothing-to-finish": "open_pr", escalate: "escalate" },
+      },
+    },
     {
       from: "acceptance",
       switch: { on: "$.route", cases: { proceed: "review_spec", fix: "fix_acceptance", escalate: "escalate" } },
@@ -586,12 +518,15 @@ export default defineFlow({
       from: "commit_gate",
       switch: {
         on: "$.route",
-        cases: { changed: "review_quality", "tests-only": "quality_gates", unchanged: "quality_gates" },
+        cases: { changed: "review_quality", "tests-only": "review_quality", unchanged: "quality_gates" },
       },
     },
     // The narrative runs only once the PR exists. acpx has no error edge, so an
     // acp node before `open_pr` would be able to fail the flow and cost the PR.
-    { from: "open_pr", switch: { on: "$.route", cases: { narrate: "narrative", done: "finish_done" } } },
+    {
+      from: "open_pr",
+      switch: { on: "$.route", cases: { narrate: "narrative", done: "finish_done", escalate: "escalate" } },
+    },
     { from: "narrative", to: "amend_body" },
   ],
 });

package/flows/nax-finish/review-prompts.ts

@@ -334,9 +334,12 @@ const RETRY_NOTICE = [
  * available — it is told to open whatever the fix touches — it just is not asked
  * to re-derive a verdict on unchanged code.
  *
- * `since` is only ever supplied when exactly one commit separates the two
- * reviews (see `incrementalSince`), so `since..HEAD` provably contains every
- * change made since the previous verdict.
+ * `since` is the parent of the *first* commit that landed after the previous
+ * verdict, not of the latest one (see `incrementalSince`) — the acceptance loop
+ * can commit between a spec fix and its re-review, and the window has to span
+ * both. So `since..HEAD` provably contains every change made since that
+ * verdict, however many commits that took, and it is never supplied at all when
+ * no commit landed.
  */
 export function buildReviewPrompt(
   phase: "spec" | "quality",

package/flows/nax-finish/steps/commit-round.ts

@@ -16,16 +16,15 @@ const REVIEWED_PHASES: FinishPhase[] = ["spec", "quality"];
 /**
  * What produced this round, given the successor the commit routed to.
  *
- * The `route` argument is why this is computed after the commit rather than
- * alongside it: `tests-only` is only known once the committed paths have been
- * classified, and it is the difference between "no reviewer exists for this
- * phase" and "a reviewer exists, was owed a look, and was skipped".
+ * `route` no longer changes the answer, and that is the point: since #1510
+ * every committed gate fix re-enters `review_quality`, so no route can skip an
+ * owed re-review. The parameter stays because the round is still keyed on the
+ * successor conceptually, and a future route that *does* bypass a reviewer
+ * would need to be reflected here rather than silently inheriting
+ * `no-reviewer`.
  */
-export function commitRoundOutcome(phase: FinishPhase, route: string): FinishRoundOutcome {
+export function commitRoundOutcome(phase: FinishPhase, _route: string): FinishRoundOutcome {
   if (REVIEWED_PHASES.includes(phase)) return "fixed";
-  // Only `gate` can skip an owed re-review; `acceptance` has no reviewer to
-  // skip, so its `tests-only`-shaped routes (it has none today) stay honest.
-  if (phase === "gate" && route === "tests-only") return "review-skipped";
   return "no-reviewer";
 }
 
@@ -58,6 +57,7 @@ export function buildCommitRound(i: CommitRoundInput): FinishRound {
     committed: i.committed,
     outcome: commitRoundOutcome(i.phase, i.route),
     findings: i.findings,
+    route: i.route,
     ...(i.failing ? { failing: i.failing } : {}),
     ...(i.committed && i.shaAfter ? { sha: i.shaAfter } : {}),
   };

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

@@ -12,10 +12,35 @@ export async function detectBaseBranch(workdir: string): Promise<string> {
   return main.exitCode === 0 ? "origin/main" : "origin/master";
 }
 
+/**
+ * The acceptance resolutions this flow knows how to route on, as emitted by
+ * `resolveFeatureAcceptance` (`src/cli/features-acceptance.ts`).
+ *
+ * A closed set, not `string`: `steps/gates.ts` branches on all three by literal
+ * — `disabled` decides whether the acceptance gate runs at all — and a typo in
+ * any of those comparisons against a `string` compiles cleanly and silently
+ * stops a gate from firing.
+ */
+export type AcceptanceStatus = "ok" | "no-prd" | "disabled";
+
+const ACCEPTANCE_STATUSES: readonly AcceptanceStatus[] = ["ok", "no-prd", "disabled"];
+
+/**
+ * Narrow the resolver's status, degrading anything unrecognised to `no-prd`.
+ *
+ * A status this flow cannot interpret is not a licence to proceed: it is
+ * neither the explicit opt-out nor a resolution to trust. `no-prd` routes to
+ * `escalate`, which is the honest answer and matches the existing default for
+ * a status that is missing entirely.
+ */
+export function toAcceptanceStatus(raw: unknown): AcceptanceStatus {
+  return ACCEPTANCE_STATUSES.find((s) => s === raw) ?? "no-prd";
+}
+
 export interface FeatureResolution {
   specPath: string;
   specKind: "markdown" | "prd";
-  acceptanceStatus: string;
+  acceptanceStatus: AcceptanceStatus;
   groups: AcceptanceGroup[];
   /**
    * Test-file classification regexes, as sources, from `nax features resolve`
@@ -57,7 +82,7 @@ export async function resolveFeature(feature: string, workdir: string): Promise<
   return {
     specPath: parsed.specSource.path,
     specKind: parsed.specSource.kind,
-    acceptanceStatus: parsed.acceptance?.status ?? "no-prd",
+    acceptanceStatus: toAcceptanceStatus(parsed.acceptance?.status),
     groups: parsed.acceptance?.groups ?? [],
     testFileRegex: parsed.testPatterns?.regex ?? [],
   };
@@ -92,11 +117,42 @@ export function partitionTestFiles(paths: string[], regexSources: string[]): { t
   return { test, nonTest };
 }
 
-export async function preflight(
-  workdir: string,
-  base: string,
-): Promise<{ commitsAhead: number; route: "proceed" | "nothing-to-finish" }> {
+export interface PreflightOutcome {
+  commitsAhead: number;
+  route: "proceed" | "nothing-to-finish" | "escalate";
+  /** Set only on `escalate` — why the count could not be trusted. */
+  reason?: string;
+}
+
+/**
+ * How far ahead of the base branch this branch is.
+ *
+ * A failed count must never be reported as zero. `base` reaches here from
+ * `detectBaseBranch`, whose last-resort `origin/master` is returned without
+ * being verified — so a repo whose base ref is not fetched locally makes
+ * `rev-list` exit non-zero with empty stdout. `Number.parseInt("") || 0` turned
+ * that into `0`, indistinguishable from "this branch has no new commits", and
+ * the flow reported `nothing-to-finish` having reviewed, verified and pushed
+ * nothing. Both the non-zero exit and unreadable output escalate instead: a
+ * human can fetch the base, and no fix node can.
+ */
+export async function preflight(workdir: string, base: string): Promise<PreflightOutcome> {
   const res = await _contextDeps.run(["git", "rev-list", "--count", `${base}..HEAD`], { cwd: workdir });
-  const commitsAhead = Number.parseInt(res.stdout.trim(), 10) || 0;
+  if (res.exitCode !== 0) {
+    const detail = res.stderr.trim() || res.stdout.trim() || `exit ${res.exitCode}`;
+    return {
+      commitsAhead: 0,
+      route: "escalate",
+      reason: `Could not count commits against "${base}" — git rev-list failed: ${detail}. The base branch may not exist locally; nax-finish will not treat that as "nothing to finish".`,
+    };
+  }
+  const commitsAhead = Number.parseInt(res.stdout.trim(), 10);
+  if (!Number.isFinite(commitsAhead)) {
+    return {
+      commitsAhead: 0,
+      route: "escalate",
+      reason: `git rev-list --count ${base}..HEAD exited 0 but printed no readable count: "${res.stdout.trim()}".`,
+    };
+  }
   return { commitsAhead, route: commitsAhead > 0 ? "proceed" : "nothing-to-finish" };
 }