@nathapp/nax 0.38.0 → 0.38.2

package/src/execution/parallel.ts

@@ -1,412 +1,13 @@
 /**
- * Parallel Execution — Worktree-based concurrent story execution
+ * Parallel Execution — Hub file
  *
  * Orchestrates parallel story execution using git worktrees: groups stories
  * by dependencies, creates worktrees, dispatches concurrent pipelines,
  * merges in dependency order, and cleans up worktrees.
- */
-
-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 { runPipeline } from "../pipeline/runner";
-import { defaultPipeline } from "../pipeline/stages";
-import type { PipelineContext, RoutingResult } from "../pipeline/types";
-import type { PluginRegistry } from "../plugins/registry";
-import type { PRD, UserStory } from "../prd";
-import { markStoryFailed, markStoryPassed, savePRD } from "../prd";
-import { routeTask, tryLlmBatchRoute } from "../routing";
-import { WorktreeManager } from "../worktree/manager";
-import { MergeEngine, type StoryDependencies } from "../worktree/merge";
-
-/**
- * Result from parallel execution of a batch of stories
- */
-export interface ParallelBatchResult {
-  /** Stories that passed the TDD pipeline (pre-merge) */
-  pipelinePassed: UserStory[];
-  /** Stories that were actually merged to the base branch */
-  merged: UserStory[];
-  /** Stories that failed the pipeline */
-  failed: Array<{ story: UserStory; error: string }>;
-  /** Total cost accumulated */
-  totalCost: number;
-  /** Stories with merge conflicts (includes per-story original cost for rectification) */
-  mergeConflicts: Array<{ storyId: string; conflictFiles: string[]; originalCost: number }>;
-  /** Per-story execution costs for successful stories */
-  storyCosts: Map<string, number>;
-}
-
-/**
- * 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;
-}
-
-/**
- * Execute a single story in its worktree
- */
-async function executeStoryInWorktree(
-  story: UserStory,
-  worktreePath: string,
-  context: Omit<PipelineContext, "story" | "stories" | "workdir" | "routing">,
-  routing: RoutingResult,
-  eventEmitter?: PipelineEventEmitter,
-): Promise<{ success: boolean; cost: number; error?: string }> {
-  const logger = getSafeLogger();
-
-  try {
-    const pipelineContext: PipelineContext = {
-      ...context,
-      story,
-      stories: [story],
-      workdir: worktreePath,
-      routing,
-    };
-
-    logger?.debug("parallel", "Executing story in worktree", {
-      storyId: story.id,
-      worktreePath,
-    });
-
-    const result = await runPipeline(defaultPipeline, pipelineContext, eventEmitter);
-
-    return {
-      success: result.success,
-      cost: result.context.agentResult?.estimatedCost || 0,
-      error: result.success ? undefined : result.reason,
-    };
-  } catch (error) {
-    return {
-      success: false,
-      cost: 0,
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-/**
- * Execute a batch of independent stories in parallel
- */
-async function executeParallelBatch(
-  stories: UserStory[],
-  projectRoot: string,
-  config: NaxConfig,
-  prd: PRD,
-  context: Omit<PipelineContext, "story" | "stories" | "workdir" | "routing">,
-  maxConcurrency: number,
-  eventEmitter?: PipelineEventEmitter,
-): Promise<ParallelBatchResult> {
-  const logger = getSafeLogger();
-  const worktreeManager = new WorktreeManager();
-  const results: ParallelBatchResult = {
-    pipelinePassed: [],
-    merged: [],
-    failed: [],
-    totalCost: 0,
-    mergeConflicts: [],
-    storyCosts: new Map(),
-  };
-
-  // Create worktrees for all stories in batch
-  const worktreeSetup: Array<{ story: UserStory; worktreePath: string }> = [];
-
-  for (const story of stories) {
-    const worktreePath = join(projectRoot, ".nax-wt", story.id);
-    try {
-      await worktreeManager.create(projectRoot, story.id);
-      worktreeSetup.push({ story, worktreePath });
-
-      logger?.info("parallel", "Created worktree for story", {
-        storyId: story.id,
-        worktreePath,
-      });
-    } catch (error) {
-      results.failed.push({
-        story,
-        error: `Failed to create worktree: ${error instanceof Error ? error.message : String(error)}`,
-      });
-      logger?.error("parallel", "Failed to create worktree", {
-        storyId: story.id,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  // Execute stories in parallel with concurrency limit
-  const executing = new Set<Promise<void>>();
-
-  for (const { story, worktreePath } of worktreeSetup) {
-    const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config);
-
-    const executePromise = executeStoryInWorktree(story, worktreePath, context, routing as RoutingResult, eventEmitter)
-      .then((result) => {
-        results.totalCost += result.cost;
-        results.storyCosts.set(story.id, result.cost);
-
-        if (result.success) {
-          results.pipelinePassed.push(story);
-          logger?.info("parallel", "Story execution succeeded", {
-            storyId: story.id,
-            cost: result.cost,
-          });
-        } else {
-          results.failed.push({ story, error: result.error || "Unknown error" });
-          logger?.error("parallel", "Story execution failed", {
-            storyId: story.id,
-            error: result.error,
-          });
-        }
-      })
-      .finally(() => {
-        executing.delete(executePromise);
-      });
-
-    executing.add(executePromise);
-
-    // Wait if we've hit the concurrency limit
-    if (executing.size >= maxConcurrency) {
-      await Promise.race(executing);
-    }
-  }
-
-  // Wait for all remaining executions
-  await Promise.all(executing);
-
-  return results;
-}
-
-/**
- * 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
+ * Re-exports coordinator and worker modules for backward compatibility.
  */
-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(),
-    };
-
-    // Execute batch in parallel
-    const batchResult = await executeParallelBatch(
-      batch,
-      projectRoot,
-      config,
-      currentPrd,
-      baseContext,
-      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 };
-}
+// Re-export for backward compatibility
+export { executeParallel } from "./parallel-coordinator";
+export type { ParallelBatchResult } from "./parallel-worker";

package/src/execution/pid-registry.ts

@@ -10,6 +10,7 @@
  */
 
 import { existsSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
 import { getSafeLogger } from "../logger";
 
 /**
@@ -77,15 +78,9 @@ export class PidRegistry {
     };
 
     try {
-      // Read existing content or create empty file
-      let existingContent = "";
-      if (existsSync(this.pidsFilePath)) {
-        existingContent = await Bun.file(this.pidsFilePath).text();
-      }
-
-      // Append to .nax-pids file (one JSON entry per line)
+      // Atomically append to .nax-pids file (one JSON entry per line)
       const line = `${JSON.stringify(entry)}\n`;
-      await Bun.write(this.pidsFilePath, existingContent + line);
+      await appendFile(this.pidsFilePath, line);
       logger?.debug("pid-registry", `Registered PID ${pid}`, { pid });
     } catch (err) {
       logger?.warn("pid-registry", `Failed to write PID ${pid} to registry`, {

package/src/execution/runner-completion.ts

@@ -0,0 +1,160 @@
+/**
+ * Runner Completion Phase
+ *
+ * Handles post-execution steps: acceptance loop, hooks, metrics, and cleanup.
+ * Extracted from runner.ts for better code organization.
+ */
+
+import type { NaxConfig } from "../config";
+import type { LoadedHooksConfig } from "../hooks";
+import { fireHook } from "../hooks";
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+import type { PipelineEventEmitter } from "../pipeline/events";
+import type { PluginRegistry } from "../plugins/registry";
+import { isComplete } from "../prd";
+import type { PRD } from "../prd";
+import { stopHeartbeat, writeExitSummary } from "./crash-recovery";
+import { hookCtx } from "./story-context";
+
+/**
+ * Options for the completion phase.
+ */
+export interface RunnerCompletionOptions {
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  workdir: string;
+  statusFile: string;
+  logFilePath?: string;
+  runId: string;
+  startedAt: string;
+  startTime: number;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+  headless: boolean;
+  featureDir?: string;
+  prd: PRD;
+  allStoryMetrics: StoryMetrics[];
+  totalCost: number;
+  storiesCompleted: number;
+  iterations: number;
+  // biome-ignore lint/suspicious/noExplicitAny: StatusWriter interface varies by platform
+  statusWriter: any;
+  pluginRegistry: PluginRegistry;
+  eventEmitter?: PipelineEventEmitter;
+}
+
+/**
+ * Result from the completion phase.
+ */
+export interface RunnerCompletionResult {
+  durationMs: number;
+  runCompletedAt: string;
+}
+
+/**
+ * Execute the completion phase of the run.
+ *
+ * @param options - Completion options
+ * @returns Completion result
+ */
+export async function runCompletionPhase(options: RunnerCompletionOptions): Promise<RunnerCompletionResult> {
+  const logger = getSafeLogger();
+
+  // Check if we need acceptance retry loop
+  if (options.config.acceptance.enabled && isComplete(options.prd)) {
+    const { runAcceptanceLoop } = await import("./lifecycle/acceptance-loop");
+    const acceptanceResult = await runAcceptanceLoop({
+      config: options.config,
+      prd: options.prd,
+      prdPath: "", // Not needed for this extraction
+      workdir: options.workdir,
+      featureDir: options.featureDir,
+      hooks: options.hooks,
+      feature: options.feature,
+      totalCost: options.totalCost,
+      iterations: options.iterations,
+      storiesCompleted: options.storiesCompleted,
+      allStoryMetrics: options.allStoryMetrics,
+      pluginRegistry: options.pluginRegistry,
+      eventEmitter: options.eventEmitter,
+      statusWriter: options.statusWriter,
+    });
+
+    Object.assign(options, {
+      prd: acceptanceResult.prd,
+      totalCost: acceptanceResult.totalCost,
+      iterations: acceptanceResult.iterations,
+      storiesCompleted: acceptanceResult.storiesCompleted,
+    });
+  }
+
+  // Fire on-all-stories-complete before regression gate (RL-001)
+  if (isComplete(options.prd)) {
+    await fireHook(
+      options.hooks,
+      "on-all-stories-complete",
+      hookCtx(options.feature, { status: "passed", cost: options.totalCost }),
+      options.workdir,
+    );
+  }
+
+  // Handle run completion: save metrics, log summary, update status
+  const { handleRunCompletion } = await import("./lifecycle/run-completion");
+  const completionResult = await handleRunCompletion({
+    runId: options.runId,
+    feature: options.feature,
+    startedAt: options.startedAt,
+    prd: options.prd,
+    allStoryMetrics: options.allStoryMetrics,
+    totalCost: options.totalCost,
+    storiesCompleted: options.storiesCompleted,
+    iterations: options.iterations,
+    startTime: options.startTime,
+    workdir: options.workdir,
+    statusWriter: options.statusWriter,
+    config: options.config,
+  });
+
+  const { durationMs, runCompletedAt, finalCounts } = completionResult;
+
+  // Write feature-level status (SFC-002)
+  if (options.featureDir) {
+    const finalStatus = isComplete(options.prd) ? "completed" : "failed";
+    options.statusWriter.setRunStatus(finalStatus);
+    await options.statusWriter.writeFeatureStatus(options.featureDir, options.totalCost, options.iterations);
+  }
+
+  // Output run footer in headless mode
+  if (options.headless && options.formatterMode !== "json") {
+    const { outputRunFooter } = await import("./lifecycle/headless-formatter");
+    outputRunFooter({
+      finalCounts: {
+        total: finalCounts.total,
+        passed: finalCounts.passed,
+        failed: finalCounts.failed,
+        skipped: finalCounts.skipped,
+      },
+      durationMs,
+      totalCost: options.totalCost,
+      startedAt: options.startedAt,
+      completedAt: runCompletedAt,
+      formatterMode: options.formatterMode,
+    });
+  }
+
+  // Stop heartbeat and write exit summary (US-007)
+  stopHeartbeat();
+  await writeExitSummary(
+    options.logFilePath,
+    options.totalCost,
+    options.iterations,
+    options.storiesCompleted,
+    durationMs,
+  );
+
+  return {
+    durationMs,
+    runCompletedAt,
+  };
+}