@nathapp/nax 0.38.0 → 0.38.2

package/src/execution/crash-writer.ts

@@ -0,0 +1,154 @@
+/**
+ * Crash data serialization — write logs and event summaries
+ */
+
+import { appendFileSync } from "node:fs";
+import { getSafeLogger } from "../logger";
+import type { StatusWriter } from "./status-writer";
+
+/**
+ * Write fatal log entry to JSONL file
+ */
+export async function writeFatalLog(jsonlFilePath: string | undefined, signal: string, error?: Error): Promise<void> {
+  if (!jsonlFilePath) return;
+
+  try {
+    const fatalEntry = {
+      timestamp: new Date().toISOString(),
+      level: "error",
+      stage: "crash-recovery",
+      message: error ? `Uncaught exception: ${error.message}` : `Process terminated by ${signal}`,
+      data: {
+        signal,
+        ...(error && {
+          stack: error.stack,
+          name: error.name,
+        }),
+      },
+    };
+
+    const line = `${JSON.stringify(fatalEntry)}\n`;
+    appendFileSync(jsonlFilePath, line);
+  } catch (err) {
+    console.error("[crash-recovery] Failed to write fatal log:", err);
+  }
+}
+
+/**
+ * Write run.complete event to JSONL file
+ * Called on SIGTERM to emit final run summary before exit
+ */
+export interface RunCompleteContext {
+  jsonlFilePath?: string;
+  runId?: string;
+  feature?: string;
+  getTotalCost: () => number;
+  getIterations: () => number;
+  getStartTime?: () => number;
+  getTotalStories?: () => number;
+  getStoriesCompleted?: () => number;
+}
+
+export async function writeRunComplete(ctx: RunCompleteContext, exitReason: string): Promise<void> {
+  if (!ctx.jsonlFilePath || !ctx.runId || !ctx.feature) return;
+
+  const logger = getSafeLogger();
+
+  try {
+    const totalCost = ctx.getTotalCost();
+    const iterations = ctx.getIterations();
+    const startTime = ctx.getStartTime?.() ?? Date.now();
+    const durationMs = Date.now() - startTime;
+    const totalStories = ctx.getTotalStories?.() ?? 0;
+    const storiesCompleted = ctx.getStoriesCompleted?.() ?? 0;
+
+    const runCompleteEntry = {
+      timestamp: new Date().toISOString(),
+      level: "info",
+      stage: "run.complete",
+      message: "Feature execution terminated",
+      data: {
+        runId: ctx.runId,
+        feature: ctx.feature,
+        success: false,
+        exitReason,
+        totalCost,
+        iterations,
+        totalStories,
+        storiesCompleted,
+        durationMs,
+      },
+    };
+
+    const line = `${JSON.stringify(runCompleteEntry)}\n`;
+    appendFileSync(ctx.jsonlFilePath, line);
+    logger?.debug("crash-recovery", "run.complete event written", { exitReason });
+  } catch (err) {
+    console.error("[crash-recovery] Failed to write run.complete event:", err);
+  }
+}
+
+/**
+ * Update status.json to "crashed" state (both project-level and feature-level)
+ */
+export async function updateStatusToCrashed(
+  statusWriter: StatusWriter,
+  totalCost: number,
+  iterations: number,
+  signal: string,
+  featureDir?: string,
+): Promise<void> {
+  try {
+    statusWriter.setRunStatus("crashed");
+    await statusWriter.update(totalCost, iterations, {
+      crashedAt: new Date().toISOString(),
+      crashSignal: signal,
+    });
+
+    if (featureDir) {
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations, {
+        crashedAt: new Date().toISOString(),
+        crashSignal: signal,
+      });
+    }
+  } catch (err) {
+    console.error("[crash-recovery] Failed to update status.json:", err);
+  }
+}
+
+/**
+ * Write exit summary entry to JSONL
+ */
+export async function writeExitSummary(
+  jsonlFilePath: string | undefined,
+  totalCost: number,
+  iterations: number,
+  storiesCompleted: number,
+  durationMs: number,
+): Promise<void> {
+  if (!jsonlFilePath) return;
+
+  const logger = getSafeLogger();
+
+  try {
+    const summaryEntry = {
+      timestamp: new Date().toISOString(),
+      level: "info",
+      stage: "exit-summary",
+      message: "Run completed",
+      data: {
+        totalCost,
+        iterations,
+        storiesCompleted,
+        durationMs,
+        exitedCleanly: true,
+      },
+    };
+
+    const line = `${JSON.stringify(summaryEntry)}\n`;
+    appendFileSync(jsonlFilePath, line);
+    logger?.debug("crash-recovery", "Exit summary written");
+  } catch (err) {
+    logger?.warn("crash-recovery", "Failed to write exit summary", { error: (err as Error).message });
+  }
+}

package/src/execution/lifecycle/run-setup.ts

@@ -171,7 +171,13 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     const globalPluginsDir = path.join(os.homedir(), ".nax", "plugins");
     const projectPluginsDir = path.join(workdir, "nax", "plugins");
     const configPlugins = config.plugins || [];
-    const pluginRegistry = await loadPlugins(globalPluginsDir, projectPluginsDir, configPlugins, workdir);
+    const pluginRegistry = await loadPlugins(
+      globalPluginsDir,
+      projectPluginsDir,
+      configPlugins,
+      workdir,
+      config.disabledPlugins,
+    );
 
     // Log plugins loaded
     logger?.info("plugins", `Loaded ${pluginRegistry.plugins.length} plugins`, {

package/src/execution/parallel-coordinator.ts

@@ -0,0 +1,278 @@
+/**
+ * Parallel coordinator — Orchestrates parallel story execution
+ */
+
+import os from "node:os";
+import { join } from "node:path";
+import type { NaxConfig } from "../config";
+import type { LoadedHooksConfig } from "../hooks";
+import { getSafeLogger } from "../logger";
+import type { PipelineEventEmitter } from "../pipeline/events";
+import type { PipelineContext } from "../pipeline/types";
+import type { PluginRegistry } from "../plugins/registry";
+import type { PRD, UserStory } from "../prd";
+import { markStoryFailed, markStoryPassed, savePRD } from "../prd";
+import { errorMessage } from "../utils/errors";
+import { WorktreeManager } from "../worktree/manager";
+import { MergeEngine, type StoryDependencies } from "../worktree/merge";
+import { executeParallelBatch } from "./parallel-worker";
+
+/**
+ * Group stories into dependency batches; stories in each batch can run in parallel.
+ */
+function groupStoriesByDependencies(stories: UserStory[]): UserStory[][] {
+  const batches: UserStory[][] = [];
+  const processed = new Set<string>();
+  const storyMap = new Map(stories.map((s) => [s.id, s]));
+
+  // Keep processing until all stories are batched
+  while (processed.size < stories.length) {
+    const batch: UserStory[] = [];
+
+    for (const story of stories) {
+      if (processed.has(story.id)) continue;
+
+      // Check if all dependencies are satisfied
+      const depsCompleted = story.dependencies.every((dep) => processed.has(dep) || !storyMap.has(dep));
+
+      if (depsCompleted) {
+        batch.push(story);
+      }
+    }
+
+    if (batch.length === 0) {
+      // No stories ready — circular dependency or missing dep
+      const remaining = stories.filter((s) => !processed.has(s.id));
+      const logger = getSafeLogger();
+      logger?.error("parallel", "Cannot resolve story dependencies", {
+        remainingStories: remaining.map((s) => s.id),
+      });
+      throw new Error("Circular dependency or missing dependency detected");
+    }
+
+    // Mark batch stories as processed
+    for (const story of batch) {
+      processed.add(story.id);
+    }
+
+    batches.push(batch);
+  }
+
+  return batches;
+}
+
+/**
+ * Build dependency map for merge engine
+ */
+function buildDependencyMap(stories: UserStory[]): StoryDependencies {
+  const deps: StoryDependencies = {};
+  for (const story of stories) {
+    deps[story.id] = story.dependencies;
+  }
+  return deps;
+}
+
+/**
+ * Determine max concurrency from parallel option
+ * - undefined: sequential mode (should not call this function)
+ * - 0: auto-detect (use CPU count)
+ * - N > 0: use N
+ */
+function resolveMaxConcurrency(parallel: number): number {
+  if (parallel === 0) {
+    return os.cpus().length;
+  }
+  return Math.max(1, parallel);
+}
+
+/**
+ * Execute stories in parallel using worktree pipeline
+ *
+ * High-level flow:
+ * 1. Group stories by dependencies into batches
+ * 2. For each batch:
+ *    a. Create worktrees for all stories
+ *    b. Execute pipeline in parallel (respecting maxConcurrency)
+ *    c. Merge successful branches in topological order
+ *    d. Clean up worktrees on success, preserve on failure
+ * 3. Update PRD with results
+ */
+export async function executeParallel(
+  stories: UserStory[],
+  prdPath: string,
+  projectRoot: string,
+  config: NaxConfig,
+  hooks: LoadedHooksConfig,
+  plugins: PluginRegistry,
+  prd: PRD,
+  featureDir: string | undefined,
+  parallel: number,
+  eventEmitter?: PipelineEventEmitter,
+): Promise<{
+  storiesCompleted: number;
+  totalCost: number;
+  updatedPrd: PRD;
+  mergeConflicts: Array<{ storyId: string; conflictFiles: string[]; originalCost: number }>;
+}> {
+  const logger = getSafeLogger();
+  const maxConcurrency = resolveMaxConcurrency(parallel);
+  const worktreeManager = new WorktreeManager();
+  const mergeEngine = new MergeEngine(worktreeManager);
+
+  logger?.info("parallel", "Starting parallel execution", {
+    totalStories: stories.length,
+    maxConcurrency,
+  });
+
+  // Group stories by dependencies
+  const batches = groupStoriesByDependencies(stories);
+  logger?.info("parallel", "Grouped stories into batches", {
+    batchCount: batches.length,
+    batches: batches.map((b, i) => ({ index: i, storyCount: b.length, storyIds: b.map((s) => s.id) })),
+  });
+
+  let storiesCompleted = 0;
+  let totalCost = 0;
+  const currentPrd = prd;
+  const allMergeConflicts: Array<{ storyId: string; conflictFiles: string[]; originalCost: number }> = [];
+
+  // Execute each batch sequentially (stories within each batch run in parallel)
+  for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+    const batch = batches[batchIndex];
+    logger?.info("parallel", `Executing batch ${batchIndex + 1}/${batches.length}`, {
+      storyCount: batch.length,
+      storyIds: batch.map((s) => s.id),
+    });
+
+    // Build context for this batch (shared across all stories in batch)
+    const baseContext = {
+      config,
+      prd: currentPrd,
+      featureDir,
+      hooks,
+      plugins,
+      storyStartTime: new Date().toISOString(),
+    };
+
+    // Create worktrees for all stories in batch
+    const worktreePaths = new Map<string, string>();
+
+    for (const story of batch) {
+      const worktreePath = join(projectRoot, ".nax-wt", story.id);
+      try {
+        await worktreeManager.create(projectRoot, story.id);
+        worktreePaths.set(story.id, worktreePath);
+
+        logger?.info("parallel", "Created worktree for story", {
+          storyId: story.id,
+          worktreePath,
+        });
+      } catch (error) {
+        markStoryFailed(currentPrd, story.id);
+        logger?.error("parallel", "Failed to create worktree", {
+          storyId: story.id,
+          error: errorMessage(error),
+        });
+      }
+    }
+
+    // Execute batch in parallel
+    const batchResult = await executeParallelBatch(
+      batch,
+      projectRoot,
+      config,
+      baseContext,
+      worktreePaths,
+      maxConcurrency,
+      eventEmitter,
+    );
+
+    totalCost += batchResult.totalCost;
+
+    // Merge successful stories in topological order
+    if (batchResult.pipelinePassed.length > 0) {
+      const successfulIds = batchResult.pipelinePassed.map((s) => s.id);
+      const deps = buildDependencyMap(batch);
+
+      logger?.info("parallel", "Merging successful stories", {
+        storyIds: successfulIds,
+      });
+
+      const mergeResults = await mergeEngine.mergeAll(projectRoot, successfulIds, deps);
+
+      // Process merge results
+      for (const mergeResult of mergeResults) {
+        if (mergeResult.success) {
+          // Update PRD: mark story as passed
+          markStoryPassed(currentPrd, mergeResult.storyId);
+          storiesCompleted++;
+          const mergedStory = batchResult.pipelinePassed.find((s) => s.id === mergeResult.storyId);
+          if (mergedStory) batchResult.merged.push(mergedStory);
+
+          logger?.info("parallel", "Story merged successfully", {
+            storyId: mergeResult.storyId,
+            retryCount: mergeResult.retryCount,
+          });
+        } else {
+          // Merge conflict — mark story as failed
+          markStoryFailed(currentPrd, mergeResult.storyId);
+          batchResult.mergeConflicts.push({
+            storyId: mergeResult.storyId,
+            conflictFiles: mergeResult.conflictFiles || [],
+            originalCost: batchResult.storyCosts.get(mergeResult.storyId) ?? 0,
+          });
+
+          logger?.error("parallel", "Merge conflict", {
+            storyId: mergeResult.storyId,
+            conflictFiles: mergeResult.conflictFiles,
+          });
+
+          // Keep worktree for manual resolution
+          logger?.warn("parallel", "Worktree preserved for manual conflict resolution", {
+            storyId: mergeResult.storyId,
+            worktreePath: join(projectRoot, ".nax-wt", mergeResult.storyId),
+          });
+        }
+      }
+    }
+
+    // Mark failed stories in PRD and clean up their worktrees
+    for (const { story, error } of batchResult.failed) {
+      markStoryFailed(currentPrd, story.id);
+
+      logger?.error("parallel", "Cleaning up failed story worktree", {
+        storyId: story.id,
+        error,
+      });
+
+      try {
+        await worktreeManager.remove(projectRoot, story.id);
+      } catch (cleanupError) {
+        logger?.warn("parallel", "Failed to clean up worktree", {
+          storyId: story.id,
+          error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+        });
+      }
+    }
+
+    // Save PRD after each batch
+    await savePRD(currentPrd, prdPath);
+
+    allMergeConflicts.push(...batchResult.mergeConflicts);
+
+    logger?.info("parallel", `Batch ${batchIndex + 1} complete`, {
+      pipelinePassed: batchResult.pipelinePassed.length,
+      merged: batchResult.merged.length,
+      failed: batchResult.failed.length,
+      mergeConflicts: batchResult.mergeConflicts.length,
+      batchCost: batchResult.totalCost,
+    });
+  }
+
+  logger?.info("parallel", "Parallel execution complete", {
+    storiesCompleted,
+    totalCost,
+  });
+
+  return { storiesCompleted, totalCost, updatedPrd: currentPrd, mergeConflicts: allMergeConflicts };
+}

package/src/execution/parallel-executor-rectification-pass.ts

@@ -0,0 +1,117 @@
+/**
+ * Rectification Pass — Re-run conflicted stories sequentially
+ *
+ * After the initial parallel merge pass, handle any conflicts
+ * by re-running each conflicted story on the updated base (MFX-005).
+ */
+
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+import type { PRD } from "../prd";
+import { markStoryPassed } from "../prd";
+import type { ParallelExecutorOptions } from "./parallel-executor";
+import type {
+  ConflictedStoryInfo,
+  RectificationResult,
+  RectifyConflictedStoryOptions,
+} from "./parallel-executor-rectify";
+
+/** Metrics for stories completed via rectification */
+export interface ParallelStoryMetrics extends StoryMetrics {
+  source: "parallel" | "sequential" | "rectification";
+  rectifiedFromConflict?: boolean;
+  originalCost?: number;
+  rectificationCost?: number;
+}
+
+/**
+ * Run the rectification pass: sequentially re-run each conflicted story on
+ * the updated base (which already includes all clean merges from the first pass).
+ *
+ * Note: rectifyConflictedStory must be passed as a parameter for proper test mocking.
+ */
+export async function runRectificationPass(
+  conflictedStories: ConflictedStoryInfo[],
+  options: ParallelExecutorOptions,
+  prd: PRD,
+  rectifyConflictedStory?: (opts: RectifyConflictedStoryOptions) => Promise<RectificationResult>,
+): Promise<{
+  rectifiedCount: number;
+  stillConflictingCount: number;
+  additionalCost: number;
+  updatedPrd: PRD;
+  rectificationMetrics: ParallelStoryMetrics[];
+}> {
+  const logger = getSafeLogger();
+  const { workdir, config, hooks, pluginRegistry, eventEmitter } = options;
+
+  // Use provided function or import default
+  const rectify =
+    rectifyConflictedStory ||
+    (async (opts: RectifyConflictedStoryOptions) => {
+      const { rectifyConflictedStory: importedRectify } = await import("./parallel-executor-rectify");
+      return importedRectify(opts);
+    });
+
+  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 rectify({
+      ...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 };
+}

package/src/execution/parallel-executor-rectify.ts

@@ -0,0 +1,135 @@
+/**
+ * Conflict Rectification Logic
+ *
+ * Handles re-running a single conflicted story on the updated base branch
+ * so it sees all previously merged stories (MFX-005).
+ */
+
+import path from "node:path";
+import type { NaxConfig } from "../config";
+import type { LoadedHooksConfig } from "../hooks";
+import { getSafeLogger } from "../logger";
+import type { PipelineEventEmitter } from "../pipeline/events";
+import type { PluginRegistry } from "../plugins/registry";
+import type { PRD } from "../prd";
+import { errorMessage } from "../utils/errors";
+
+/** 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
+ */
+export 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: errorMessage(error),
+    });
+    return { success: false, storyId, cost: 0, finalConflict: false, pipelineFailure: true };
+  }
+}