@nathapp/nax 0.77.0 → 0.77.1

package/dist/nax.js

@@ -43724,6 +43724,60 @@ var init_operations = __esm(() => {
   init_mutation_check();
 });
 
+// src/findings/cycle-iteration-log.ts
+function recordIteration(cycle, input, ctx, logger) {
+  const iterationNum = cycle.iterations.length + 1;
+  const findingsBeforeCount = input.findingsBefore.length;
+  const findingsAfterCount = input.findingsAfter.length;
+  const findingKeysBefore = input.findingsBefore.map(findingKey);
+  const findingKeysAfter = input.findingsAfter.map(findingKey);
+  const costUsd = input.fixesApplied.reduce((sum, fa) => sum + (fa.costUsd ?? 0), 0);
+  const seenTargetFiles = new Set;
+  const fixTargetFiles = [];
+  for (const fa of input.fixesApplied) {
+    for (const path6 of fa.targetFiles) {
+      if (seenTargetFiles.has(path6))
+        continue;
+      seenTargetFiles.add(path6);
+      fixTargetFiles.push(path6);
+    }
+  }
+  const fixSummaries = input.fixesApplied.map((fa) => fa.summary);
+  const hasFixes = input.fixesApplied.length > 0;
+  const iteration = {
+    iterationNum,
+    findingsBefore: input.findingsBefore,
+    fixesApplied: input.fixesApplied,
+    findingsAfter: input.findingsAfter,
+    outcome: input.outcome,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    findingKeysBefore,
+    findingKeysAfter,
+    ...hasFixes ? { fixTargetFiles, fixSummaries } : {},
+    ...costUsd > 0 ? { costUsd } : {}
+  };
+  cycle.iterations.push(iteration);
+  logger?.info("findings.cycle", "iteration completed", {
+    storyId: ctx.storyId,
+    packageDir: ctx.packageDir,
+    cycleName: ctx.cycleName,
+    iterationNum,
+    strategiesRan: input.fixesApplied.map((fa) => fa.strategyName),
+    outcome: input.outcome,
+    findingsBefore: findingsBeforeCount,
+    findingsAfter: findingsAfterCount,
+    findingKeysBefore,
+    findingKeysAfter,
+    ...hasFixes ? { fixTargetFiles, fixSummaries } : {},
+    ...costUsd > 0 ? { costUsd } : {}
+  });
+  return iteration;
+}
+var init_cycle_iteration_log = __esm(() => {
+  init_types6();
+});
+
 // src/findings/cycle-retirement.ts
 function createDeclineLedger() {
   const declinedByStrategy = new Map;
@@ -43935,15 +43989,14 @@ async function runFixCycle(cycle, ctx, cycleName, _deps = {}) {
       const allGaveUp = unresolvedFas.length === fixesApplied.length;
       if (allGaveUp) {
         const finishedAt2 = now();
-        cycle.iterations.push({
-          iterationNum: cycle.iterations.length + 1,
+        recordIteration(cycle, {
           findingsBefore,
           fixesApplied,
           findingsAfter: cycle.findings,
           outcome: "unchanged",
           startedAt,
           finishedAt: finishedAt2
-        });
+        }, { storyId, packageDir, cycleName }, logger);
         totalCostUsd += fixesApplied.reduce((sum, fa) => sum + (fa.costUsd ?? 0), 0);
         logger?.info("findings.cycle", "cycle exited \u2014 agent gave up", {
           storyId,
@@ -43986,15 +44039,14 @@ async function runFixCycle(cycle, ctx, cycleName, _deps = {}) {
         liteShortCircuited = liteResult.shortCircuited ?? false;
       } catch (err) {
         const finishedAt3 = now();
-        cycle.iterations.push({
-          iterationNum: cycle.iterations.length + 1,
+        recordIteration(cycle, {
           findingsBefore,
           fixesApplied,
           findingsAfter: cycle.findings,
           outcome: "unchanged",
           startedAt,
           finishedAt: finishedAt3
-        });
+        }, { storyId, packageDir, cycleName }, logger);
         logger?.warn("findings.cycle", "lite validate failed on terminal exhausted branch", {
           storyId,
           packageDir,
@@ -44011,15 +44063,14 @@ async function runFixCycle(cycle, ctx, cycleName, _deps = {}) {
       }
       const outcome2 = classifyOutcome(findingsBefore, liteFindingsAfter);
       const finishedAt2 = now();
-      cycle.iterations.push({
-        iterationNum: cycle.iterations.length + 1,
+      recordIteration(cycle, {
         findingsBefore,
         fixesApplied,
         findingsAfter: liteFindingsAfter,
         outcome: outcome2,
         startedAt,
         finishedAt: finishedAt2
-      });
+      }, { storyId, packageDir, cycleName }, logger);
       cycle.findings = liteFindingsAfter;
       if (liteFindingsAfter.length === 0 && !liteShortCircuited) {
         logger?.info("findings.cycle", "cycle exited \u2014 resolved after terminal lite validate", {
@@ -44112,31 +44163,17 @@ async function runFixCycle(cycle, ctx, cycleName, _deps = {}) {
     }
     const outcome = classifyOutcome(findingsBefore, findingsAfter);
     const finishedAt = now();
-    const iterationNum = cycle.iterations.length + 1;
-    const iteration = {
-      iterationNum,
+    recordIteration(cycle, {
       findingsBefore,
       fixesApplied,
       findingsAfter,
       outcome,
       startedAt,
       finishedAt
-    };
-    cycle.iterations.push(iteration);
+    }, { storyId, packageDir, cycleName }, logger);
     cycle.findings = findingsAfter;
     const iterationCostUsd = fixesApplied.reduce((sum, fa) => sum + (fa.costUsd ?? 0), 0);
     totalCostUsd += iterationCostUsd;
-    logger?.info("findings.cycle", "iteration completed", {
-      storyId,
-      packageDir,
-      cycleName,
-      iterationNum,
-      strategiesRan: fixesApplied.map((fa) => fa.strategyName),
-      outcome,
-      findingsBefore: findingsBefore.length,
-      findingsAfter: findingsAfter.length,
-      ...iterationCostUsd > 0 ? { costUsd: iterationCostUsd } : {}
-    });
     if (outcome === "resolved") {
       return { iterations: cycle.iterations, finalFindings: [], exitReason: "resolved", costUsd: totalCostUsd };
     }
@@ -44146,6 +44183,7 @@ var _cycleDeps;
 var init_cycle = __esm(() => {
   init_logger2();
   init_operations();
+  init_cycle_iteration_log();
   init_cycle_retirement();
   init_types6();
   _cycleDeps = {
@@ -44160,6 +44198,7 @@ var init_findings = __esm(() => {
   init_adapters();
   init_path_utils();
   init_cycle();
+  init_cycle_iteration_log();
 });
 
 // src/review/review-iteration-store.ts
@@ -44646,7 +44685,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.77.0",
+    version: "0.77.1",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -44750,8 +44789,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("4c943eec"))
-        return "4c943eec";
+      if (/^[0-9a-f]{6,10}$/.test("a50be624"))
+        return "a50be624";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -59904,7 +59943,7 @@ var init_completion = __esm(() => {
       const logger = getLogger();
       const isBatch = ctx.stories.length > 1;
       const sessionCost = ctx.runtime.costAggregator.byStory()[ctx.story.id]?.totalCostUsd ?? 0;
-      const persistPrd = ctx.skipPrdPersistence !== true;
+      const persistPrd2 = ctx.skipPrdPersistence !== true;
       const prdPath = ctx.prdPath ?? (ctx.featureDir ? `${ctx.featureDir}/prd.json` : `${ctx.workdir}/nax/features/unknown/prd.json`);
       const storyStartTime = ctx.storyStartTime || new Date().toISOString();
       if (isBatch) {
@@ -59929,7 +59968,7 @@ var init_completion = __esm(() => {
         }
       }
       for (const completedStory of ctx.stories) {
-        if (persistPrd) {
+        if (persistPrd2) {
           markStoryPassed(ctx.prd, completedStory.id);
         }
         const costPerStory = sessionCost / ctx.stories.length;
@@ -59963,7 +60002,7 @@ var init_completion = __esm(() => {
           }
         }
       }
-      if (persistPrd) {
+      if (persistPrd2) {
         await _completionDeps.savePRD(ctx.prd, prdPath);
       }
       logHighMemoryCheckpoint(logger, ctx);
@@ -106619,8 +106658,12 @@ function buildPlanComposition(userStageConfig) {
 
 // src/plan/strategies/write-prd.ts
 init_errors();
+init_logger2();
 init_prd();
 
+// src/plan/strategies/persist-prd.ts
+init_operations();
+
 // src/plan/strategies/finalize-routing.ts
 init_agents();
 function finalizePrdRouting(prd, agentRouting, profileName) {
@@ -106642,6 +106685,26 @@ function finalizePrdRouting(prd, agentRouting, profileName) {
   return { ...prd, userStories, routingProfile: profileName ?? "default" };
 }
 
+// src/plan/strategies/persist-prd.ts
+async function finalizeAndWritePrd(args) {
+  const repaired = applyPlanFidelity(args.prd, args.specContent, args.featureName);
+  const finalized = finalizePrdRouting({ ...repaired, project: args.projectName }, args.agentRouting, args.profileName);
+  await args.writeFile(args.outputPath, JSON.stringify(finalized, null, 2));
+  return args.outputPath;
+}
+async function persistPrd(ctx, prd) {
+  return finalizeAndWritePrd({
+    prd,
+    specContent: ctx.specContent,
+    featureName: ctx.options.feature,
+    projectName: ctx.projectName,
+    agentRouting: ctx.config.routing?.agents,
+    profileName: ctx.profileName,
+    outputPath: ctx.outputPath,
+    writeFile: ctx.deps.writeFile
+  });
+}
+
 // src/plan/strategies/write-prd.ts
 async function writeOrRecoverPrd(ctx, prd, err) {
   const tryExtractPrd = (value) => {
@@ -106661,15 +106724,11 @@ async function writeOrRecoverPrd(ctx, prd, err) {
   };
   if (prd !== null) {
     if (Array.isArray(prd.userStories)) {
-      const finalized = finalizePrdRouting({ ...prd, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-      await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(finalized, null, 2));
-      return ctx.outputPath;
+      return { outputPath: await persistPrd(ctx, prd) };
     }
     const normalizedPrd = tryExtractPrd(prd);
     if (normalizedPrd !== null) {
-      const finalized = finalizePrdRouting({ ...normalizedPrd, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-      await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(finalized, null, 2));
-      return ctx.outputPath;
+      return { outputPath: await persistPrd(ctx, normalizedPrd) };
     }
   }
   if (err === undefined) {
@@ -106688,9 +106747,13 @@ async function writeOrRecoverPrd(ctx, prd, err) {
       }
     }
     recoveredPrd = recoveredPrd ?? validatePlanOutput(rawContent, ctx.options.feature, ctx.branchName);
-    const finalized = finalizePrdRouting({ ...recoveredPrd, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-    await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(finalized, null, 2));
-    return ctx.outputPath;
+    const reason = err instanceof Error ? err.message : String(err);
+    getSafeLogger()?.warn("plan", "PRD recovered from disk after a plan failure \u2014 result is degraded", {
+      featureName: ctx.options.feature,
+      outputPath: ctx.outputPath,
+      error: reason
+    });
+    return { outputPath: await persistPrd(ctx, recoveredPrd), degraded: { reason } };
   } catch {
     throw err;
   }
@@ -106747,9 +106810,7 @@ class DebatePlanStrategy {
       });
       if (debateResult.outcome !== "failed" && debateResult.output) {
         const prd2 = validatePlanOutput(debateResult.output, ctx.options.feature, ctx.branchName);
-        const scoped2 = applyPlanFidelity(prd2, ctx.specContent, ctx.options.feature);
-        const withProject2 = { ...scoped2, project: ctx.projectName };
-        return _debatePlanDeps.writeOrRecoverPrd(ctx, withProject2);
+        return _debatePlanDeps.writeOrRecoverPrd(ctx, prd2);
       }
       const prd = await callOp({
         ...callCtx,
@@ -106766,8 +106827,7 @@ class DebatePlanStrategy {
         projectProfile: ctx.config.project
       });
       assertIsValidPrd(prd);
-      const withProject = { ...prd, project: ctx.projectName };
-      return _debatePlanDeps.writeOrRecoverPrd(ctx, withProject);
+      return _debatePlanDeps.writeOrRecoverPrd(ctx, prd);
     } catch (err) {
       return _debatePlanDeps.writeOrRecoverPrd(ctx, null, err);
     } finally {
@@ -106846,10 +106906,7 @@ class PipelinePlanStrategy {
       if (verdict.outcome !== "passed") {
         throw new NaxError(verdict.specDeltasPath ? `Plan pipeline failed; see ${verdict.specDeltasPath}` : "Plan pipeline failed with no spec-deltas path", "PLAN_CRITIC_BLOCKED", { stage: "plan", specDeltasPath: verdict.specDeltasPath });
       }
-      const scoped2 = applyPlanFidelity(verdict.prd, ctx.specContent, ctx.options.feature);
-      const prdToWrite = finalizePrdRouting({ ...scoped2, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-      await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(prdToWrite, null, 2));
-      return ctx.outputPath;
+      return { outputPath: await persistPrd(ctx, verdict.prd) };
     } finally {
       await ctx.runtime.close().catch(() => {});
     }
@@ -106898,6 +106955,7 @@ class RefinePlanStrategy {
 }
 
 // src/plan/strategies/single.ts
+init_logger2();
 init_operations();
 init_prd();
 var _singlePlanDeps = {
@@ -106929,16 +106987,18 @@ class SinglePlanStrategy {
         projectProfile: ctx.config.project
       });
       assertIsValidPrd(prd);
-      const finalized = finalizePrdRouting({ ...prd, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-      await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(finalized, null, 2));
-      return ctx.outputPath;
+      return { outputPath: await persistPrd(ctx, prd) };
     } catch (err) {
       if (ctx.deps.existsSync(ctx.outputPath)) {
         const rawContent = await ctx.deps.readFile(ctx.outputPath);
         const recoveredPrd = validatePlanOutput(rawContent, ctx.options.feature, ctx.branchName);
-        const finalizedRecovered = finalizePrdRouting({ ...recoveredPrd, project: ctx.projectName }, ctx.config.routing?.agents, ctx.profileName);
-        await ctx.deps.writeFile(ctx.outputPath, JSON.stringify(finalizedRecovered, null, 2));
-        return ctx.outputPath;
+        const reason = err instanceof Error ? err.message : String(err);
+        getSafeLogger()?.warn("plan", "PRD recovered from disk after a plan failure \u2014 result is degraded", {
+          featureName: ctx.options.feature,
+          outputPath: ctx.outputPath,
+          error: reason
+        });
+        return { outputPath: await persistPrd(ctx, recoveredPrd), degraded: { reason } };
       }
       throw err;
     } finally {
@@ -118060,6 +118120,14 @@ program2.name("nax").description("AI Coding Agent Orchestrator \u2014 loops unti
 function collectProfile(value, previous) {
   return previous.concat(value);
 }
+function warnIfPlanDegraded(result2) {
+  if (!result2.degraded)
+    return;
+  console.log(source_default.yellow(`
+[WARN] PRD recovered after a plan failure \u2014 this is a degraded result`));
+  console.log(source_default.dim(`   Cause: ${result2.degraded.reason}`));
+  console.log(source_default.dim("   Deterministic spec->PRD repairs were re-applied, but review the PRD before running."));
+}
 async function promptForConfirmation(question) {
   if (!process.stdin.isTTY) {
     return true;
@@ -118381,12 +118449,14 @@ program2.command("run").description("Run the orchestration loop for a feature").
       initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
       console.log(source_default.dim(`   [Plan log: ${planLogPath}]`));
       console.log(source_default.dim("   [Planning phase: generating PRD from spec]"));
-      const generatedPrdPath = await planCommand(workdir, config2, {
+      const planResult = await planCommand(workdir, config2, {
         from: options.from,
         feature: options.feature,
         auto: options.oneShot ?? false,
         branch: undefined
       });
+      const generatedPrdPath = planResult.outputPath;
+      warnIfPlanDegraded(planResult);
       const generatedPrd = await loadPRD(generatedPrdPath);
       await runReplanLoop(workdir, config2, {
         feature: options.feature,
@@ -118805,15 +118875,16 @@ Use: nax plan -f <feature> --from <spec>`));
         console.error(source_default.red("Error: --from <spec-path> is required unless --decompose is used"));
         process.exit(1);
       }
-      const prdPath = await planCommand(workdir, config2, {
+      const planResult = await planCommand(workdir, config2, {
         from: options.from,
         feature: options.feature,
         auto: options.auto || options.oneShot,
         branch: options.branch
       });
+      warnIfPlanDegraded(planResult);
       console.log(source_default.green(`
 [OK] PRD generated`));
-      console.log(source_default.dim(`   PRD: ${prdPath}`));
+      console.log(source_default.dim(`   PRD: ${planResult.outputPath}`));
       console.log(source_default.dim(`   Log: ${planLogPath}`));
       console.log(source_default.dim(`
 Next: nax run -f ${options.feature}`));

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

@@ -54,10 +54,28 @@ export function loadCtxOf(ctx: OutputsCtx): LoadCtxOutput {
  * Absent when the node was skipped by config, died, or produced only
  * whitespace — `amend_body` treats all three identically, so there is one
  * branch downstream rather than three.
+ *
+ * Accepts the bare string the node used to return as well as the
+ * `{ narrative, title }` it returns now: a flow resumed from a run recorded
+ * before the title landed replays the old shape from its journal.
  */
 export function narrativeOf(ctx: OutputsCtx): string | undefined {
   const out = (ctx.outputs as Record<string, unknown>).narrative;
-  return typeof out === "string" && out.trim().length > 0 ? out : undefined;
+  const prose = typeof out === "string" ? out : (out as { narrative?: unknown } | undefined)?.narrative;
+  return typeof prose === "string" && prose.trim().length > 0 ? prose : undefined;
+}
+
+/**
+ * The narrative node's parsed PR title, already sanitised by `parseTitle`.
+ *
+ * Absent whenever the node is — `resolveTitle` then falls back to
+ * `feat: <feature>`, which is what shipped before and what auto-PR opens with.
+ */
+export function prTitleOf(ctx: OutputsCtx): string | undefined {
+  const out = (ctx.outputs as Record<string, unknown>).narrative;
+  if (typeof out !== "object" || out === null) return undefined;
+  const title = (out as { title?: unknown }).title;
+  return typeof title === "string" && title.trim().length > 0 ? title : undefined;
 }
 
 export function gateOutputs(ctx: OutputsCtx): { failing?: string[]; ran?: string[] } {

package/flows/nax-finish/narrative.ts

@@ -12,11 +12,41 @@
  * test can reach it.
  */
 
+import { TITLE_CLOSE_TAG, TITLE_MAX_CHARS, TITLE_OPEN_TAG, parseTitle } from "./pr-title";
+
 /** Longest narrative rendered into a PR body, in characters, including the ellipsis. */
 export const NARRATIVE_MAX_CHARS = 4000;
 
 const TRUNCATION_SUFFIX = "…";
 
+/**
+ * Sentinel wrapping the prose, so `parseNarrative` has an explicit anchor
+ * rather than an inferred one.
+ *
+ * acpx hands `parse` the concatenation of *every* agent message chunk in the
+ * turn — `chunks.join("")` in its `createQuietCaptureOutput`. This node reads
+ * the diff with tools, so the agent's between-tool-call narration ("Now I have
+ * a clear picture. Let me check…") is structurally part of that string. A
+ * prompt asking for "no preamble" cannot prevent it; only a delimiter can.
+ *
+ * A sentinel rather than the JSON contract the sibling nodes use: this payload
+ * is multi-paragraph prose about code, full of backticks, quotes and newlines.
+ * Literal newlines inside a JSON string are invalid JSON, so a JSON contract
+ * would fail on exactly the inputs this node exists to carry.
+ */
+const OPEN_TAG = "<narrative>";
+const CLOSE_TAG = "</narrative>";
+
+/**
+ * Headings the agent emits despite being told not to. Anchors the fallback
+ * strip when the sentinel is absent: everything up to and including the
+ * heading is preamble.
+ */
+const HEADING_RE = /^[\s\S]*?(?:\*\*What changed\*\*|##+\s*What changed)\s*/i;
+
+/** A `<title>…</title>` block, closed or not — removed wholesale from the prose. */
+const TITLE_BLOCK_RE = new RegExp(`${TITLE_OPEN_TAG}[\\s\\S]*?(?:${TITLE_CLOSE_TAG}|$)`, "gi");
+
 /** Headings a spec uses for its lead paragraph, in priority order. */
 const SUMMARY_HEADINGS = ["summary", "overview"] as const;
 
@@ -57,7 +87,18 @@ export function buildNarrativePrompt(args: { base: string }): string {
     "anything a reviewer would otherwise have to reconstruct from the diff by hand.",
     `Hard limit: ${NARRATIVE_MAX_CHARS} characters.`,
     "Do not write a heading — the heading is added for you.",
-    "Return the prose only. No JSON, no code fences, no preamble.",
+    "",
+    "Then write the pull request title: a conventional-commit subject describing",
+    `the change (\`fix: …\`, \`feat: …\`, \`refactor: …\`), at most ${TITLE_MAX_CHARS} characters.`,
+    "Describe what the change does — not the feature's name, which the reader",
+    "can already see on the branch.",
+    "",
+    "Reply with exactly these two blocks, and write nothing after the last one:",
+    `${TITLE_OPEN_TAG}conventional-commit subject${TITLE_CLOSE_TAG}`,
+    `${OPEN_TAG}the prose${CLOSE_TAG}`,
+    "",
+    "Everything outside those tags is discarded, so anything you say while working",
+    "through the diff is safe to leave where it falls.",
   ].join("\n");
 }
 
@@ -66,10 +107,51 @@ export function buildNarrativePrompt(args: { base: string }): string {
  *
  * Never throws. A throw inside `parse` fails the node, and acpx has no error
  * edge — see `verdict.ts`. Here that would mean the flow dying *after* the PR
- * was already opened.
+ * was already opened, so every branch below degrades instead of rejecting.
+ *
+ * Three tiers, strongest anchor first:
+ *   1. Sentinel — the contract the prompt asks for.
+ *   2. Heading — the agent ignored the sentinel but still wrote
+ *      `**What changed**`, which marks where its preamble stopped.
+ *   3. Bare trim — no anchor available; better a narrative with preamble than
+ *      no narrative at all.
  */
 export function parseNarrative(text: string): string {
-  return typeof text === "string" ? text.trim() : "";
+  if (typeof text !== "string") return "";
+
+  // Last opening tag, not the first: if the agent narrates the tag before
+  // emitting it for real ("I'll wrap this in <narrative>"), the real one wins.
+  const open = text.lastIndexOf(OPEN_TAG);
+  if (open !== -1) {
+    const from = open + OPEN_TAG.length;
+    const close = text.indexOf(CLOSE_TAG, from);
+    const inner = (close === -1 ? text.slice(from) : text.slice(from, close)).trim();
+    if (inner) return inner;
+  }
+
+  // Strip tag markers before the heading pass: an empty or malformed sentinel
+  // falls through to here, and leftover `<narrative>` markup in a PR body is
+  // worse than the preamble this function exists to remove. The title block
+  // goes entirely — tags and content — since it is not part of the prose.
+  const untagged = text.replace(TITLE_BLOCK_RE, "").split(OPEN_TAG).join("").split(CLOSE_TAG).join("");
+  return untagged.replace(HEADING_RE, "").trim();
+}
+
+/** What the `narrative` acp node returns: the prose, and the title to rename the PR to. */
+export interface NarrativeNodeResult {
+  narrative: string;
+  title?: string;
+}
+
+/**
+ * `parse` for the narrative acp node.
+ *
+ * Both halves are optional to the flow: a missing title leaves the PR on
+ * `feat: <feature>`, and missing prose leaves the body's mechanical sections
+ * alone. Never throws, for the reason `parseNarrative` documents.
+ */
+export function parseNarrativeNode(text: string): NarrativeNodeResult {
+  return { narrative: parseNarrative(text), title: parseTitle(text) };
 }
 
 function truncate(text: string): string {

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

@@ -44,7 +44,7 @@
 import { defineFlow } from "acpx/flows";
 import { buildFixCommitMessage } from "./commit-message";
 import { findingsOf, fixAttemptCount, gateOutputs, incrementalSince, inputOf, loadCtxOf } from "./flow-ctx";
-import { narrativePrompt, parseNarrative } from "./narrative";
+import { narrativePrompt, parseNarrativeNode } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
@@ -449,7 +449,7 @@ export default defineFlow({
       session: { isolated: true },
       profile: process.env.NAX_FINISH_NARRATIVE_PROFILE || undefined,
       prompt: narrativePrompt,
-      parse: parseNarrative,
+      parse: parseNarrativeNode,
     },
     amend_body: {
       nodeType: "action",

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

@@ -0,0 +1,140 @@
+/**
+ * The PR title — sentinel, sanitiser, and the fallback chain.
+ *
+ * `buildFinishTitle` used to return `feat: <feature>` unconditionally, so every
+ * finish-opened PR was titled with its feature slug: `feat: schema-drift-gate`
+ * describes the run, not the change. The narrative node has already read the
+ * whole diff by the time the body is amended, so a real conventional-commit
+ * subject costs one extra sentinel in a prompt that was being sent anyway.
+ *
+ * No deterministic source can replace it. The spec's H1 is the slug in prose
+ * (`# SPEC: Schema drift gate`), the PRD carries no feature-level title, and
+ * concatenating story titles reads worse than the slug it replaces — which is
+ * why this is the one part of the PR metadata that is model-derived, and why
+ * everything below assumes the model may return junk.
+ *
+ * Lives beside `narrative.ts` rather than in `src/prompts/builders/` for the
+ * same reason that file gives: `flows/` runs in acpx's Node process and imports
+ * nothing from `src/`.
+ */
+
+/** Sentinel wrapping the title. See `narrative.ts` for why a delimiter is required at all. */
+export const TITLE_OPEN_TAG = "<title>";
+export const TITLE_CLOSE_TAG = "</title>";
+
+/**
+ * Longest title rendered onto a PR.
+ *
+ * 72 is the conventional-commit subject norm, and GitHub truncates around this
+ * width in list views.
+ */
+export const TITLE_MAX_CHARS = 72;
+
+/**
+ * Conventional-commit prefix, split into the type-with-scope and the subject.
+ *
+ * Types mirror the list in `.claude/rules/project-conventions.md`, plus
+ * `revert`. Captured rather than merely tested so the two halves can be
+ * rejoined with exactly one space — `feat:no space` and `feat:` both reach
+ * here, and testing alone let the latter become `feat: feat:`.
+ *
+ * A title arriving without any prefix is prefixed rather than rejected: the
+ * prose is usually right even when the model forgets the ceremony.
+ */
+const CONVENTIONAL_PREFIX_RE =
+  /^((?:feat|fix|refactor|perf|docs|test|chore|ci|build|style|revert)(?:\([^)]*\))?!?):\s*([\s\S]*)$/i;
+
+const DEFAULT_TYPE = "feat";
+
+/** Wrapping quotes/backticks the model adds when it treats the title as a quoted string. */
+const WRAPPING_CHARS = new Set(['"', "'", "`", "*", "_"]);
+
+function stripWrapping(text: string): string {
+  let out = text;
+  // Loop: models nest these ("`fix: thing`" arrives quoted *and* fenced).
+  while (out.length >= 2) {
+    const first = out[0];
+    const last = out[out.length - 1];
+    if (first !== undefined && first === last && WRAPPING_CHARS.has(first)) {
+      out = out.slice(1, -1).trim();
+      continue;
+    }
+    break;
+  }
+  return out;
+}
+
+/**
+ * Cut to `TITLE_MAX_CHARS` on a word boundary where one is available.
+ *
+ * A mid-word cut reads as corruption rather than brevity; falling back to a
+ * hard slice only matters for a title with no spaces at all.
+ */
+function clamp(text: string): string {
+  if (text.length <= TITLE_MAX_CHARS) return text;
+  const cut = text.slice(0, TITLE_MAX_CHARS);
+  const lastSpace = cut.lastIndexOf(" ");
+  // Guard against a long type prefix eating the whole budget: only honour a
+  // word boundary that leaves a meaningful subject behind.
+  const MIN_KEEP = 20;
+  return (lastSpace >= MIN_KEEP ? cut.slice(0, lastSpace) : cut).trimEnd();
+}
+
+/**
+ * Normalise a model-supplied title, or `undefined` if nothing usable survives.
+ *
+ * Never throws — this feeds `parse` on an acp node, and the flow's PR is
+ * already open by the time it runs.
+ */
+export function sanitizeTitle(raw: string | undefined): string | undefined {
+  if (typeof raw !== "string") return undefined;
+
+  // First non-empty line: a title is single-line by definition, and a model
+  // that adds a rationale below it must not push that onto the PR.
+  const firstLine = raw.split(/\r?\n/).find((line) => line.trim().length > 0);
+  if (firstLine === undefined) return undefined;
+
+  // Collapse internal runs of whitespace before measuring, so the length cap
+  // reflects what a reader sees.
+  let title = stripWrapping(firstLine.trim()).replace(/\s+/g, " ");
+  // Markdown heading marks, for a model that answers the "write a title" ask
+  // with a heading.
+  title = title.replace(/^#+\s*/, "").trim();
+  title = stripWrapping(title);
+  // Trailing sentence punctuation — conventional-commit subjects carry none.
+  title = title.replace(/[.\s]+$/, "");
+  if (!title) return undefined;
+
+  const match = CONVENTIONAL_PREFIX_RE.exec(title);
+  const type = match?.[1] ?? DEFAULT_TYPE;
+  const subject = (match?.[2] ?? title).trim();
+  // A bare `feat:` carries no subject, and a type alone is not a title.
+  if (!subject) return undefined;
+
+  return clamp(`${type}: ${subject}`);
+}
+
+/**
+ * Extract the title from the narrative node's reply.
+ *
+ * Last opening tag wins, mirroring `parseNarrative` — a model that narrates the
+ * tag before emitting it must not beat the real one.
+ */
+export function parseTitle(text: string): string | undefined {
+  if (typeof text !== "string") return undefined;
+  const open = text.lastIndexOf(TITLE_OPEN_TAG);
+  if (open === -1) return undefined;
+  const from = open + TITLE_OPEN_TAG.length;
+  const close = text.indexOf(TITLE_CLOSE_TAG, from);
+  return sanitizeTitle(close === -1 ? text.slice(from) : text.slice(from, close));
+}
+
+/**
+ * The title to render, best source first.
+ *
+ * `feat: <feature>` remains the floor: it is what shipped before, it is what
+ * the auto-PR plugin opens with, and it is always available.
+ */
+export function resolveTitle(agentTitle: string | undefined, feature: string): string {
+  return sanitizeTitle(agentTitle) ?? `${DEFAULT_TYPE}: ${feature}`;
+}

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

@@ -5,11 +5,14 @@
  * 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.
+ * context as a deterministic markdown body, assembled by string joins over the
+ * fields in `FinishPrContext`. Every *section* is reproducible from artifacts
+ * that exist before `open_pr` runs, so the body stays greppable in PR history.
+ *
+ * Two fields are the exception, and both arrive later, from the narrative node
+ * that runs after the PR is already open: `narrative` and `title`. Each has a
+ * deterministic fallback (`resolveNarrative`, `resolveTitle`) so `open_pr` never
+ * waits on a model — see `steps/pr-narrative.ts`.
  *
  * Reimplemented here (rather than imported from `src/`) because `flows/`
  * ships to a different runtime — `acpx flow run` runs it in acpx's own Node
@@ -20,6 +23,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import { runArgv } from "../exec";
 import { readSpecSummary, resolveNarrative } from "../narrative";
 import { findPrTemplate } from "../pr-template";
+import { resolveTitle } from "../pr-title";
 import type { Finding, FinishInput, FinishRound, RunFn } from "../types";
 import type { Forge } from "./forge";
 import { readRounds } from "./result";
@@ -46,10 +50,20 @@ export interface FinishPrContext {
   regression?: string;
   gatesRan: string[];
   diffstat?: string;
+  /**
+   * `--shortstat` for the nax artifacts held out of `diffstat`. Absent when the
+   * branch touched none, so a repo that gitignores them renders nothing.
+   */
+  artifactSummary?: string;
   /** Repository PR/MR template, verbatim. Absent when none resolves. */
   template?: string;
   /** Resolved "What changed" prose. Absent when neither source produced text. */
   narrative?: string;
+  /**
+   * Resolved conventional-commit PR title. Always set — `resolveTitle` falls
+   * back to `feat: <feature>` when the narrative node produced nothing usable.
+   */
+  title: string;
   rounds: FinishRound[];
   run: {
     durationMs?: number;
@@ -121,7 +135,43 @@ function storiesFrom(prd: PrdArtifact | undefined): FinishPrStory[] {
 }
 
 /**
- * Run `git diff --stat <base>...HEAD` and return its stdout on success.
+ * Pathspec matching nax's own run artifacts, at any depth.
+ *
+ * `**` and the `glob` magic word are both load-bearing. nax writes artifacts
+ * to a repo-root `.nax/` *and* to a per-package `<pkg>/.nax/` — a root-anchored
+ * `:!.nax/**` silently keeps the per-package copy, which is routinely the
+ * largest file in the diff (587 of 2039 insertions on the run that motivated
+ * this). Without `glob`, git's default wildmatch lets `*` cross `/` and the
+ * two forms stop being distinguishable.
+ */
+const NAX_ARTIFACT_PATHSPEC = "**/.nax/**";
+
+/** The two halves of the branch's diff: what is under review, and what was held out. */
+interface DiffstatResult {
+  diffstat?: string;
+  artifactSummary?: string;
+}
+
+/** Run `git diff <...args>` under `workdir`, or `undefined` on any non-happy path. */
+async function runGitDiff(workdir: string, args: string[]): Promise<string | undefined> {
+  try {
+    const res = await _prBodyDeps.run(["git", "diff", ...args], { cwd: workdir });
+    if (res.exitCode !== 0) return undefined;
+    return res.stdout;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Diffstat of the branch, excluding nax's own artifacts.
+ *
+ * The artifacts (`spec.md`, `prd.json`, the generated acceptance test) are
+ * committed and real, but they are the run's exhaust rather than the change
+ * under review, and they dominate the totals — quoting them in the headline
+ * advertises a 2039-line change where 791 lines are reviewable code.
+ * `artifactSummary` keeps them accounted for rather than silently dropped, so
+ * the body still reconciles against `gh pr diff`.
  *
  * 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
@@ -129,18 +179,18 @@ function storiesFrom(prd: PrdArtifact | undefined): FinishPrStory[] {
  * 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> {
+async function runDiffstat(workdir: string, base: string): Promise<DiffstatResult> {
   // 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;
-  }
+  if (!base) return {};
+  const range = `${base}...HEAD`;
+  const [diffstat, artifacts] = await Promise.all([
+    runGitDiff(workdir, ["--stat", range, "--", `:(glob,exclude)${NAX_ARTIFACT_PATHSPEC}`]),
+    runGitDiff(workdir, ["--shortstat", range, "--", `:(glob)${NAX_ARTIFACT_PATHSPEC}`]),
+  ]);
+  const summary = artifacts?.trim();
+  return { diffstat, artifactSummary: summary ? summary : undefined };
 }
 
 /**
@@ -161,14 +211,14 @@ async function loadTemplate(workdir: string, forge: Forge | undefined): Promise<
 
 export async function loadFinishPrContext(
   input: FinishInput,
-  args: { base: string; gatesRan: string[]; forge?: Forge; specPath?: string; narrative?: string },
+  args: { base: string; gatesRan: string[]; forge?: Forge; specPath?: string; narrative?: string; title?: 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([
+  const [prd, status, rounds, stat, template, specSummary] = (await Promise.all([
     readJson(prdPath),
     readJson(join(dirname(prdPath), "status.json")),
     readRounds(input),
@@ -179,7 +229,7 @@ export async function loadFinishPrContext(
     PrdArtifact | undefined,
     StatusArtifact | undefined,
     FinishRound[],
-    string | undefined,
+    DiffstatResult,
     string | undefined,
     string | null,
   ];
@@ -191,9 +241,11 @@ export async function loadFinishPrContext(
     regression: status?.postRun?.regression?.status,
     gatesRan: args.gatesRan,
     rounds,
-    diffstat,
+    diffstat: stat.diffstat,
+    artifactSummary: stat.artifactSummary,
     template,
     narrative: resolveNarrative(args.narrative, specSummary),
+    title: resolveTitle(args.title, input.feature),
     run: {
       durationMs: status?.durationMs,
       storiesPassed: status?.progress?.passed,
@@ -203,12 +255,18 @@ export async function loadFinishPrContext(
 }
 
 /**
- * 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.
+ * The PR title: the narrative node's conventional-commit subject when it
+ * produced one, else `feat: <feature>`.
+ *
+ * That fallback is what this returned unconditionally, and is still what
+ * `buildTitle` in `src/plugins/builtin/auto-pr/pr-body.ts` opens with — so a
+ * finish run that reaches `open_pr` before the narrative node has spoken still
+ * reads identically to an auto-PR-opened one in a list view. The two diverge
+ * only once there is something better to say: `feat: schema-drift-gate` names
+ * the run, not the change.
  */
 export function buildFinishTitle(ctx: FinishPrContext): string {
-  return `feat: ${ctx.feature}`;
+  return ctx.title;
 }
 
 /**
@@ -247,17 +305,24 @@ function buildStoriesSection(stories: FinishPrStory[]): string {
   return lines.join("\n");
 }
 
-function buildVerificationSection(
-  acceptance: string | undefined,
-  regression: string | undefined,
-  gatesRan: string[],
-  diffstat: string | undefined,
-): string | null {
+/**
+ * Takes the whole context rather than the five fields it reads: the section
+ * grew past the three-positional-parameter cap in the coding standards, and
+ * every field it wants is already on `FinishPrContext`.
+ */
+function buildVerificationSection(ctx: FinishPrContext): string | null {
+  const { acceptance, regression, gatesRan, diffstat, artifactSummary } = ctx;
   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\`\`\``);
+  // Stated even though the files are excluded above: a reviewer who diffs the
+  // branch themselves sees more than the diffstat quotes, and an unexplained
+  // mismatch reads as a stale body.
+  if (artifactSummary !== undefined && artifactSummary.length > 0) {
+    lines.push(`- Excluded from diffstat — nax run artifacts: ${artifactSummary}`);
+  }
   if (lines.length === 1) return null;
   return lines.join("\n");
 }
@@ -325,7 +390,7 @@ export function buildFinishBody(ctx: FinishPrContext): string {
 
   if (ctx.stories.length > 0) sections.push(buildStoriesSection(ctx.stories));
 
-  const verification = buildVerificationSection(ctx.acceptance, ctx.regression, ctx.gatesRan, ctx.diffstat);
+  const verification = buildVerificationSection(ctx);
   if (verification !== null) sections.push(verification);
 
   const roundsSection = buildRoundsSection(ctx.rounds);

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

@@ -9,7 +9,7 @@
  * 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 { gateOutputs, inputOf, loadCtxOf, narrativeOf, prTitleOf } from "../flow-ctx";
 import { detectForge } from "./forge";
 import { updatePrBody } from "./pr";
 import { _prBodyDeps, buildFinishBody, buildFinishTitle, loadFinishPrContext } from "./pr-body";
@@ -19,9 +19,11 @@ export async function amendPrBodyNode(ctx: {
   outputs: unknown;
 }): Promise<{ route: "done"; amended: boolean }> {
   const narrative = narrativeOf(ctx);
+  const title = prTitleOf(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 };
+  // identically would spend a forge call to change nothing. A title alone is
+  // still worth the call — it is the part a reviewer reads first.
+  if (!narrative && !title) return { route: "done", amended: false };
 
   const i = inputOf(ctx);
   const loadCtx = loadCtxOf(ctx);
@@ -33,6 +35,7 @@ export async function amendPrBodyNode(ctx: {
       forge,
       specPath: loadCtx.specPath,
       narrative,
+      title,
     });
     await updatePrBody(forge, i.workdir, i.branch, buildFinishTitle(prCtx), buildFinishBody(prCtx));
     return { route: "done", amended: true };

package/package.json

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