@nathapp/nax 0.36.1 → 0.36.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.36.1",
+  "version": "0.36.2",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/execution/dry-run.ts

@@ -66,7 +66,7 @@ export async function handleDryRun(ctx: DryRunContext): Promise<DryRunResult> {
       storyId: s.id,
       story: s,
       passed: true,
-      durationMs: 0,
+      runElapsedMs: 0,
       cost: 0,
       modelTier: ctx.routing.modelTier,
       testStrategy: ctx.routing.testStrategy,

package/src/execution/escalation/escalation.ts

@@ -22,18 +22,20 @@ import type { TierConfig } from "../../config";
  * ```
  */
 export function escalateTier(currentTier: string, tierOrder: TierConfig[]): string | null {
-  const currentIndex = tierOrder.findIndex((t) => t.tier === currentTier);
+  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
+  const currentIndex = tierOrder.findIndex((t) => getName(t) === currentTier);
   if (currentIndex === -1 || currentIndex === tierOrder.length - 1) {
     return null;
   }
-  return tierOrder[currentIndex + 1].tier;
+  return getName(tierOrder[currentIndex + 1]);
 }
 
 /**
  * Get the tier config for a given tier name.
  */
 export function getTierConfig(tierName: string, tierOrder: TierConfig[]): TierConfig | undefined {
-  return tierOrder.find((t) => t.tier === tierName);
+  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
+  return tierOrder.find((t) => getName(t) === tierName);
 }
 
 /**

package/src/execution/escalation/tier-escalation.ts

@@ -24,6 +24,7 @@ function buildEscalationFailure(
   story: UserStory,
   currentTier: string,
   reviewFindings?: import("../../plugins/types").ReviewFinding[],
+  cost?: number,
 ): StructuredFailure {
   return {
     attempt: (story.attempts ?? 0) + 1,
@@ -31,6 +32,7 @@ function buildEscalationFailure(
     stage: "escalation" as const,
     summary: `Failed with tier ${currentTier}, escalating to next tier`,
     reviewFindings: reviewFindings && reviewFindings.length > 0 ? reviewFindings : undefined,
+    cost: cost ?? 0,
     timestamp: new Date().toISOString(),
   };
 }
@@ -54,6 +56,8 @@ export function resolveMaxAttemptsOutcome(failureCategory?: FailureCategory): "p
     case "verifier-rejected":
     case "greenfield-no-tests":
       return "pause";
+    case "runtime-crash":
+      return "pause";
     case "session-failure":
     case "tests-failing":
       return "fail";
@@ -208,14 +212,38 @@ export interface EscalationHandlerContext {
   feature: string;
   totalCost: number;
   workdir: string;
+  /** Verify result from the pipeline verify stage — used to detect RUNTIME_CRASH (BUG-070) */
+  verifyResult?: { status: string; success: boolean };
+  /** Cost of the failed attempt being escalated (BUG-067: accumulated across escalations) */
+  attemptCost?: number;
 }
 
 export interface EscalationHandlerResult {
-  outcome: "escalated" | "paused" | "failed";
+  outcome: "escalated" | "paused" | "failed" | "retry-same";
   prdDirty: boolean;
   prd: PRD;
 }
 
+/**
+ * Determine if the pipeline should retry the same tier due to a transient runtime crash.
+ *
+ * Returns true when the verify result status is RUNTIME_CRASH — these are Bun
+ * runtime-level failures, not code quality issues, so escalating the model tier
+ * would not help. Instead the same tier should be retried.
+ *
+ * @param verifyResult - Verify result from the pipeline verify stage
+ */
+export function shouldRetrySameTier(verifyResult: { status: string; success: boolean } | undefined): boolean {
+  return verifyResult?.status === "RUNTIME_CRASH";
+}
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _tierEscalationDeps = {
+  savePRD,
+};
+
 /**
  * Handle tier escalation after pipeline escalation action
  *
@@ -223,6 +251,15 @@ export interface EscalationHandlerResult {
  */
 export async function handleTierEscalation(ctx: EscalationHandlerContext): Promise<EscalationHandlerResult> {
   const logger = getSafeLogger();
+
+  // BUG-070: Runtime crashes are transient — retry same tier, do NOT escalate
+  if (shouldRetrySameTier(ctx.verifyResult)) {
+    logger?.warn("escalation", "Runtime crash detected — retrying same tier (transient, not a code issue)", {
+      storyId: ctx.story.id,
+    });
+    return { outcome: "retry-same", prdDirty: false, prd: ctx.prd };
+  }
+
   const nextTier = escalateTier(ctx.routing.modelTier, ctx.config.autoMode.escalation.tierOrder);
   const escalateWholeBatch = ctx.config.autoMode.escalation.escalateEntireBatch ?? true;
   const storiesToEscalate = ctx.isBatchExecution && escalateWholeBatch ? ctx.storiesToExecute : [ctx.story];
@@ -294,8 +331,8 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
       const isChangingTier = currentStoryTier !== nextTier;
       const shouldResetAttempts = isChangingTier || shouldSwitchToTestAfter;
 
-      // Build escalation failure
-      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings);
+      // Build escalation failure (BUG-067: include cost for accumulatedAttemptCost in metrics)
+      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings, ctx.attemptCost);
 
       return {
         ...s,
@@ -307,7 +344,7 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
     }) as PRD["userStories"],
   } as PRD;
 
-  await savePRD(updatedPrd, ctx.prdPath);
+  await _tierEscalationDeps.savePRD(updatedPrd, ctx.prdPath);
 
   // Clear routing cache for all escalated stories to avoid returning old cached decisions
   for (const story of storiesToEscalate) {

package/src/execution/iteration-runner.ts

@@ -60,6 +60,10 @@ export async function runIteration(
 
   const storyStartTime = Date.now();
   const storyGitRef = await captureGitRef(ctx.workdir);
+
+  // BUG-067: Accumulate cost from all prior failed attempts (stored in priorFailures by handleTierEscalation)
+  const accumulatedAttemptCost = (story.priorFailures || []).reduce((sum, f) => sum + (f.cost || 0), 0);
+
   const pipelineContext: PipelineContext = {
     config: ctx.config,
     prd,
@@ -74,6 +78,7 @@ export async function runIteration(
     storyStartTime: new Date().toISOString(),
     storyGitRef: storyGitRef ?? undefined,
     interaction: ctx.interactionChain ?? undefined,
+    accumulatedAttemptCost: accumulatedAttemptCost > 0 ? accumulatedAttemptCost : undefined,
   };
 
   ctx.statusWriter.setPrd(prd);

package/src/execution/parallel-executor.ts

@@ -4,6 +4,8 @@
  * Handles the full parallel execution flow:
  * - Status updates with parallel info
  * - Execute parallel stories
+ * - Rectify merge conflicts (MFX-005): re-run conflicted stories sequentially
+ *   on the updated base branch so each sees all previously merged stories
  * - Handle completion or continue to sequential
  */
 
@@ -17,17 +19,147 @@ import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
 import type { PluginRegistry } from "../plugins/registry";
 import type { PRD } from "../prd";
-import { countStories, isComplete } from "../prd";
+import { countStories, isComplete, markStoryPassed } from "../prd";
 import { getAllReadyStories, hookCtx } from "./helpers";
 import { executeParallel } from "./parallel";
 import type { StatusWriter } from "./status-writer";
 
+/** StoryMetrics extended with execution-path source */
+export type ParallelStoryMetrics = StoryMetrics & {
+  source: "parallel" | "sequential" | "rectification";
+  rectifiedFromConflict?: boolean;
+  originalCost?: number;
+  rectificationCost?: number;
+};
+
+/** A story that conflicted during the initial parallel merge pass */
+export interface ConflictedStoryInfo {
+  storyId: string;
+  conflictFiles: string[];
+  originalCost: number;
+}
+
+/** Result from attempting to rectify a single conflicted story */
+export type RectificationResult =
+  | { success: true; storyId: string; cost: number }
+  | {
+      success: false;
+      storyId: string;
+      cost: number;
+      finalConflict: boolean;
+      pipelineFailure?: boolean;
+      conflictFiles?: string[];
+    };
+
+/** Options passed to rectifyConflictedStory */
+export interface RectifyConflictedStoryOptions extends ConflictedStoryInfo {
+  workdir: string;
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  pluginRegistry: PluginRegistry;
+  prd: PRD;
+  eventEmitter?: PipelineEventEmitter;
+}
+
+/**
+ * Actual implementation of rectifyConflictedStory.
+ *
+ * Steps:
+ * 1. Remove the old worktree
+ * 2. Create a fresh worktree from current HEAD (post-merge state)
+ * 3. Re-run the full story pipeline
+ * 4. Attempt merge on the updated base
+ * 5. Return success/finalConflict
+ */
+async function rectifyConflictedStory(options: RectifyConflictedStoryOptions): Promise<RectificationResult> {
+  const { storyId, workdir, config, hooks, pluginRegistry, prd, eventEmitter } = options;
+  const logger = getSafeLogger();
+
+  logger?.info("parallel", "Rectifying story on updated base", { storyId, attempt: "rectification" });
+
+  try {
+    const { WorktreeManager } = await import("../worktree/manager");
+    const { MergeEngine } = await import("../worktree/merge");
+    const { runPipeline } = await import("../pipeline/runner");
+    const { defaultPipeline } = await import("../pipeline/stages");
+    const { routeTask } = await import("../routing");
+
+    const worktreeManager = new WorktreeManager();
+    const mergeEngine = new MergeEngine(worktreeManager);
+
+    // Step 1: Remove old worktree
+    try {
+      await worktreeManager.remove(workdir, storyId);
+    } catch {
+      // Ignore — worktree may have already been removed
+    }
+
+    // Step 2: Create fresh worktree from current HEAD
+    await worktreeManager.create(workdir, storyId);
+    const worktreePath = path.join(workdir, ".nax-wt", storyId);
+
+    // Step 3: Re-run the story pipeline
+    const story = prd.userStories.find((s) => s.id === storyId);
+    if (!story) {
+      return { success: false, storyId, cost: 0, finalConflict: false, pipelineFailure: true };
+    }
+
+    const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config);
+
+    const pipelineContext = {
+      config,
+      prd,
+      story,
+      stories: [story],
+      workdir: worktreePath,
+      featureDir: undefined,
+      hooks,
+      plugins: pluginRegistry,
+      storyStartTime: new Date().toISOString(),
+      routing: routing as import("../pipeline/types").RoutingResult,
+    };
+
+    const pipelineResult = await runPipeline(defaultPipeline, pipelineContext, eventEmitter);
+    const cost = pipelineResult.context.agentResult?.estimatedCost ?? 0;
+
+    if (!pipelineResult.success) {
+      logger?.info("parallel", "Rectification failed - preserving worktree", { storyId });
+      return { success: false, storyId, cost, finalConflict: false, pipelineFailure: true };
+    }
+
+    // Step 4: Attempt merge on updated base
+    const mergeResults = await mergeEngine.mergeAll(workdir, [storyId], { [storyId]: [] });
+    const mergeResult = mergeResults[0];
+
+    if (!mergeResult || !mergeResult.success) {
+      const conflictFiles = mergeResult?.conflictFiles ?? [];
+      logger?.info("parallel", "Rectification failed - preserving worktree", { storyId });
+      return { success: false, storyId, cost, finalConflict: true, conflictFiles };
+    }
+
+    logger?.info("parallel", "Rectification succeeded - story merged", {
+      storyId,
+      originalCost: options.originalCost,
+      rectificationCost: cost,
+    });
+    return { success: true, storyId, cost };
+  } catch (error) {
+    logger?.error("parallel", "Rectification failed - preserving worktree", {
+      storyId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return { success: false, storyId, cost: 0, finalConflict: false, pipelineFailure: true };
+  }
+}
+
 /**
  * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
  * @internal - test use only.
  */
 export const _parallelExecutorDeps = {
   fireHook,
+  executeParallel,
+  rectifyConflictedStory,
 };
 
 export interface ParallelExecutorOptions {
@@ -52,12 +184,101 @@ export interface ParallelExecutorOptions {
   headless: boolean;
 }
 
+export interface RectificationStats {
+  rectified: number;
+  stillConflicting: number;
+}
+
 export interface ParallelExecutorResult {
   prd: PRD;
   totalCost: number;
   storiesCompleted: number;
   completed: boolean;
   durationMs?: number;
+  /** Per-story metrics for stories completed via the parallel path */
+  storyMetrics: ParallelStoryMetrics[];
+  /** Stats from the merge-conflict rectification pass (MFX-005) */
+  rectificationStats: RectificationStats;
+}
+
+/**
+ * Run the rectification pass: sequentially re-run each conflicted story on
+ * the updated base (which already includes all clean merges from the first pass).
+ */
+async function runRectificationPass(
+  conflictedStories: ConflictedStoryInfo[],
+  options: ParallelExecutorOptions,
+  prd: PRD,
+): Promise<{
+  rectifiedCount: number;
+  stillConflictingCount: number;
+  additionalCost: number;
+  updatedPrd: PRD;
+  rectificationMetrics: ParallelStoryMetrics[];
+}> {
+  const logger = getSafeLogger();
+  const { workdir, config, hooks, pluginRegistry, eventEmitter } = options;
+  const rectificationMetrics: ParallelStoryMetrics[] = [];
+  let rectifiedCount = 0;
+  let stillConflictingCount = 0;
+  let additionalCost = 0;
+
+  logger?.info("parallel", "Starting merge conflict rectification", {
+    stories: conflictedStories.map((s) => s.storyId),
+    totalConflicts: conflictedStories.length,
+  });
+
+  // Sequential — each story sees all previously rectified stories in the base
+  for (const conflictInfo of conflictedStories) {
+    const result = await _parallelExecutorDeps.rectifyConflictedStory({
+      ...conflictInfo,
+      workdir,
+      config,
+      hooks,
+      pluginRegistry,
+      prd,
+      eventEmitter,
+    });
+
+    additionalCost += result.cost;
+
+    if (result.success) {
+      markStoryPassed(prd, result.storyId);
+      rectifiedCount++;
+
+      rectificationMetrics.push({
+        storyId: result.storyId,
+        complexity: "unknown",
+        modelTier: "parallel",
+        modelUsed: "parallel",
+        attempts: 1,
+        finalTier: "parallel",
+        success: true,
+        cost: result.cost,
+        durationMs: 0,
+        firstPassSuccess: false,
+        startedAt: new Date().toISOString(),
+        completedAt: new Date().toISOString(),
+        source: "rectification" as const,
+        rectifiedFromConflict: true,
+        originalCost: conflictInfo.originalCost,
+        rectificationCost: result.cost,
+      });
+    } else {
+      const isFinalConflict = result.finalConflict === true;
+      if (isFinalConflict) {
+        stillConflictingCount++;
+      }
+      // pipelineFailure — not counted as structural conflict, story remains failed
+    }
+  }
+
+  logger?.info("parallel", "Rectification complete", {
+    rectified: rectifiedCount,
+    stillConflicting: stillConflictingCount,
+  });
+
+  return { rectifiedCount, stillConflictingCount, additionalCost, updatedPrd: prd, rectificationMetrics };
 }
 
 /**
@@ -92,7 +313,14 @@ export async function runParallelExecution(
   const readyStories = getAllReadyStories(prd);
   if (readyStories.length === 0) {
     logger?.info("parallel", "No stories ready for parallel execution");
-    return { prd, totalCost, storiesCompleted, completed: false };
+    return {
+      prd,
+      totalCost,
+      storiesCompleted,
+      completed: false,
+      storyMetrics: [],
+      rectificationStats: { rectified: 0, stillConflicting: 0 },
+    };
   }
 
   const maxConcurrency = parallelCount === 0 ? os.cpus().length : Math.max(1, parallelCount);
@@ -115,8 +343,16 @@ export async function runParallelExecution(
     },
   });
 
+  // Track which stories were already passed before this batch
+  const initialPassedIds = new Set(initialPrd.userStories.filter((s) => s.status === "passed").map((s) => s.id));
+  const batchStartedAt = new Date().toISOString();
+  const batchStartMs = Date.now();
+  const batchStoryMetrics: ParallelStoryMetrics[] = [];
+
+  let conflictedStories: ConflictedStoryInfo[] = [];
+
   try {
-    const parallelResult = await executeParallel(
+    const parallelResult = await _parallelExecutorDeps.executeParallel(
       readyStories,
       prdPath,
       workdir,
@@ -129,14 +365,44 @@ export async function runParallelExecution(
       eventEmitter,
     );
 
+    const batchDurationMs = Date.now() - batchStartMs;
+    const batchCompletedAt = new Date().toISOString();
+
     prd = parallelResult.updatedPrd;
     storiesCompleted += parallelResult.storiesCompleted;
     totalCost += parallelResult.totalCost;
+    conflictedStories = parallelResult.mergeConflicts ?? [];
 
-    logger?.info("parallel", "Parallel execution complete", {
-      storiesCompleted: parallelResult.storiesCompleted,
-      totalCost: parallelResult.totalCost,
-    });
+    // BUG-066: Build per-story metrics for stories newly completed by this parallel batch
+    const newlyPassedStories = prd.userStories.filter((s) => s.status === "passed" && !initialPassedIds.has(s.id));
+    const costPerStory = newlyPassedStories.length > 0 ? parallelResult.totalCost / newlyPassedStories.length : 0;
+    for (const story of newlyPassedStories) {
+      batchStoryMetrics.push({
+        storyId: story.id,
+        complexity: "unknown",
+        modelTier: "parallel",
+        modelUsed: "parallel",
+        attempts: 1,
+        finalTier: "parallel",
+        success: true,
+        cost: costPerStory,
+        durationMs: batchDurationMs,
+        firstPassSuccess: true,
+        startedAt: batchStartedAt,
+        completedAt: batchCompletedAt,
+        source: "parallel" as const,
+      });
+    }
+
+    allStoryMetrics.push(...batchStoryMetrics);
+
+    // Log each conflict before scheduling rectification
+    for (const conflict of conflictedStories) {
+      logger?.info("parallel", "Merge conflict detected - scheduling for rectification", {
+        storyId: conflict.storyId,
+        conflictFiles: conflict.conflictFiles,
+      });
+    }
 
     // Clear parallel status
     statusWriter.setPrd(prd);
@@ -160,7 +426,23 @@ export async function runParallelExecution(
     throw error;
   }
 
-  // Check if all stories are complete after parallel execution
+  // ── MFX-005: Rectification pass ────────────────────────────────────────────
+  let rectificationStats: RectificationStats = { rectified: 0, stillConflicting: 0 };
+
+  if (conflictedStories.length > 0) {
+    const rectResult = await runRectificationPass(conflictedStories, options, prd);
+    prd = rectResult.updatedPrd;
+    storiesCompleted += rectResult.rectifiedCount;
+    totalCost += rectResult.additionalCost;
+    rectificationStats = {
+      rectified: rectResult.rectifiedCount,
+      stillConflicting: rectResult.stillConflictingCount,
+    };
+    batchStoryMetrics.push(...rectResult.rectificationMetrics);
+    allStoryMetrics.push(...rectResult.rectificationMetrics);
+  }
+
+  // Check if all stories are complete after parallel execution + rectification
   if (isComplete(prd)) {
     logger?.info("execution", "All stories complete!", {
       feature,
@@ -228,8 +510,10 @@ export async function runParallelExecution(
       storiesCompleted,
       completed: true,
       durationMs,
+      storyMetrics: batchStoryMetrics,
+      rectificationStats,
     };
   }
 
-  return { prd, totalCost, storiesCompleted, completed: false };
+  return { prd, totalCost, storiesCompleted, completed: false, storyMetrics: batchStoryMetrics, rectificationStats };
 }