@nathapp/nax 0.18.1

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

@@ -0,0 +1,204 @@
+/**
+ * Run Setup — Initial Setup Logic
+ *
+ * Handles the initial setup phase before the main execution loop:
+ * - Status writer initialization
+ * - PID registry cleanup
+ * - Crash handler installation
+ * - Lock acquisition
+ * - Plugin loading
+ * - PRD loading
+ * - Precheck validation
+ * - Run initialization
+ */
+
+import * as os from "node:os";
+import path from "node:path";
+import type { NaxConfig } from "../../config";
+import { LockAcquisitionError } from "../../errors";
+import type { LoadedHooksConfig } from "../../hooks";
+import { fireHook } from "../../hooks";
+import type { InteractionChain } from "../../interaction";
+import { initInteractionChain } from "../../interaction";
+import { getSafeLogger } from "../../logger";
+import { loadPlugins } from "../../plugins/loader";
+import type { PluginRegistry } from "../../plugins/registry";
+import type { PRD } from "../../prd";
+import { loadPRD } from "../../prd";
+import { installCrashHandlers } from "../crash-recovery";
+import { acquireLock, hookCtx } from "../helpers";
+import { PidRegistry } from "../pid-registry";
+import { StatusWriter } from "../status-writer";
+
+export interface RunSetupOptions {
+  prdPath: string;
+  workdir: string;
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  dryRun: boolean;
+  statusFile?: string;
+  logFilePath?: string;
+  runId: string;
+  startedAt: string;
+  startTime: number;
+  skipPrecheck: boolean;
+  headless: boolean;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+  getTotalCost: () => number;
+  getIterations: () => number;
+  // BUG-017: Additional getters for run.complete event on SIGTERM
+  getStoriesCompleted: () => number;
+  getTotalStories: () => number;
+}
+
+export interface RunSetupResult {
+  statusWriter: StatusWriter;
+  pidRegistry: PidRegistry;
+  cleanupCrashHandlers: () => void;
+  pluginRegistry: PluginRegistry;
+  prd: PRD;
+  storyCounts: {
+    total: number;
+    passed: number;
+    pending: number;
+    failed: number;
+  };
+  interactionChain: InteractionChain | null;
+}
+
+/**
+ * Execute initial setup phase
+ */
+export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult> {
+  const logger = getSafeLogger();
+  const {
+    prdPath,
+    workdir,
+    config,
+    hooks,
+    feature,
+    dryRun,
+    statusFile,
+    logFilePath,
+    runId,
+    startedAt,
+    startTime,
+    skipPrecheck,
+    headless,
+    formatterMode,
+    getTotalCost,
+    getIterations,
+  } = options;
+
+  // ── Status writer (encapsulates status file state and write logic) ───────
+  const statusWriter = new StatusWriter(statusFile, config, {
+    runId,
+    feature,
+    startedAt,
+    dryRun,
+    startTimeMs: startTime,
+    pid: process.pid,
+  });
+
+  // ── PID registry for orphan process cleanup (BUG-002) ───────
+  const pidRegistry = new PidRegistry(workdir);
+
+  // Cleanup stale PIDs from previous crashed runs
+  await pidRegistry.cleanupStale();
+
+  // Install crash handlers for signal recovery (US-007, BUG-1+MEM-1 fix: pass getters, cleanup in finally)
+  const cleanupCrashHandlers = installCrashHandlers({
+    statusWriter,
+    getTotalCost,
+    getIterations,
+    jsonlFilePath: logFilePath,
+    pidRegistry,
+    // BUG-017: Pass context for run.complete event on SIGTERM
+    runId: options.runId,
+    feature: options.feature,
+    getStartTime: () => options.startTime,
+    getTotalStories: options.getTotalStories,
+    getStoriesCompleted: options.getStoriesCompleted,
+  });
+
+  // Acquire lock to prevent concurrent execution
+  const lockAcquired = await acquireLock(workdir);
+  if (!lockAcquired) {
+    logger?.error("execution", "Another nax process is already running in this directory");
+    logger?.error("execution", "If you believe this is an error, remove nax.lock manually");
+    throw new LockAcquisitionError(workdir);
+  }
+
+  // Load plugins (before try block so it's accessible in finally)
+  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);
+
+  // Load PRD (before try block so it's accessible in finally for onRunEnd)
+  let prd = await loadPRD(prdPath);
+
+  // Initialize interaction chain (US-008) — do this BEFORE precheck so story size prompts can use it
+  const interactionChain = await initInteractionChain(config, headless);
+
+  // ── Prime StatusWriter with PRD so precheck-failed can be recorded ─────────
+  statusWriter.setPrd(prd);
+
+  // ── Run precheck validations (unless --skip-precheck) ──────────────────────
+  if (!skipPrecheck) {
+    const { runPrecheckValidation } = await import("./precheck-runner");
+    await runPrecheckValidation({
+      config,
+      prd,
+      workdir,
+      logFilePath,
+      statusWriter,
+      headless,
+      formatterMode,
+      interactionChain,
+      featureName: feature,
+    });
+  } else {
+    logger?.warn("precheck", "Precheck validations skipped (--skip-precheck)");
+  }
+
+  // Log plugins loaded
+  logger?.info("plugins", `Loaded ${pluginRegistry.plugins.length} plugins`, {
+    plugins: pluginRegistry.plugins.map((p) => ({ name: p.name, version: p.version, provides: p.provides })),
+  });
+
+  // Log run start
+  const routingMode = config.routing.llm?.mode ?? "hybrid";
+  logger?.info("run.start", `Starting feature: ${feature}`, {
+    runId,
+    feature,
+    workdir,
+    dryRun,
+    routingMode,
+  });
+
+  // Fire on-start hook
+  await fireHook(hooks, "on-start", hookCtx(feature), workdir);
+
+  // Initialize run: check agent, reconcile state, validate limits
+  const { initializeRun } = await import("./run-initialization");
+  const initResult = await initializeRun({
+    config,
+    prdPath,
+    workdir,
+    dryRun,
+  });
+  prd = initResult.prd;
+  const counts = initResult.storyCounts;
+
+  return {
+    statusWriter,
+    pidRegistry,
+    cleanupCrashHandlers,
+    pluginRegistry,
+    prd,
+    storyCounts: counts,
+    interactionChain,
+  };
+}

package/src/execution/lifecycle/story-hooks.ts

@@ -0,0 +1,38 @@
+/**
+ * Story Lifecycle Hooks
+ *
+ * Centralizes reporter notification boilerplate for story lifecycle events:
+ * - onStoryComplete (completed/paused/skipped/failed)
+ */
+
+import { getSafeLogger } from "../../logger";
+import type { IReporter } from "../../plugins/types";
+
+export interface StoryCompleteEvent {
+  runId: string;
+  storyId: string;
+  status: "completed" | "paused" | "skipped" | "failed";
+  durationMs: number;
+  cost: number;
+  tier: string;
+  testStrategy: string;
+}
+
+/**
+ * Emit onStoryComplete event to all reporters
+ *
+ * Handles error recovery for individual reporter failures.
+ */
+export async function emitStoryComplete(reporters: IReporter[], event: StoryCompleteEvent): Promise<void> {
+  const logger = getSafeLogger();
+
+  for (const reporter of reporters) {
+    if (reporter.onStoryComplete) {
+      try {
+        await reporter.onStoryComplete(event);
+      } catch (error) {
+        logger?.warn("plugins", `Reporter '${reporter.name}' onStoryComplete failed`, { error });
+      }
+    }
+  }
+}

package/src/execution/lifecycle/story-size-prompts.ts

@@ -0,0 +1,123 @@
+/**
+ * Story Size Prompts (v0.16.0)
+ *
+ * Post-precheck interaction prompts for flagged stories.
+ * Asks user to confirm (Approve/Skip/Abort) for each large story.
+ * Integrates with interaction chain.
+ */
+
+import type { InteractionChain } from "../../interaction/chain";
+import type { InteractionResponse } from "../../interaction/types";
+import { getSafeLogger } from "../../logger";
+import type { PRD } from "../../prd/types";
+import type { FlaggedStory } from "../../precheck/story-size-gate";
+
+/** Prompt result for a single story */
+export interface StoryPromptResult {
+  storyId: string;
+  action: "approve" | "skip" | "abort";
+}
+
+/** Summary of story size prompt results */
+export interface StorySizePromptSummary {
+  approved: string[];
+  skipped: string[];
+  aborted: boolean;
+}
+
+/**
+ * Prompt user for each flagged story
+ *
+ * @param flaggedStories - Stories that exceeded size thresholds
+ * @param prd - PRD instance (mutated: skips stories if user selects Skip)
+ * @param chain - Interaction chain
+ * @param featureName - Feature name for context
+ * @returns Summary of user decisions
+ */
+export async function promptForFlaggedStories(
+  flaggedStories: FlaggedStory[],
+  prd: PRD,
+  chain: InteractionChain,
+  featureName: string,
+): Promise<StorySizePromptSummary> {
+  const logger = getSafeLogger();
+  const summary: StorySizePromptSummary = {
+    approved: [],
+    skipped: [],
+    aborted: false,
+  };
+
+  for (const flagged of flaggedStories) {
+    logger?.info("precheck", `Story size gate: prompting for ${flagged.storyId}`, {
+      recommendation: flagged.recommendation,
+    });
+
+    const story = prd.userStories.find((s) => s.id === flagged.storyId);
+    if (!story) {
+      logger?.warn("precheck", `Story ${flagged.storyId} not found in PRD, skipping prompt`);
+      continue;
+    }
+
+    // Build detail message with signal breakdown
+    const signalDetails = [
+      `- Acceptance Criteria: ${flagged.signals.acCount.value} (threshold: ${flagged.signals.acCount.threshold}) ${flagged.signals.acCount.flagged ? "⚠" : "✓"}`,
+      `- Description Length: ${flagged.signals.descriptionLength.value} chars (threshold: ${flagged.signals.descriptionLength.threshold}) ${flagged.signals.descriptionLength.flagged ? "⚠" : "✓"}`,
+      `- Bullet Points: ${flagged.signals.bulletPoints.value} (threshold: ${flagged.signals.bulletPoints.threshold}) ${flagged.signals.bulletPoints.flagged ? "⚠" : "✓"}`,
+    ];
+
+    const detail = `${flagged.recommendation}\n\nSignal breakdown:\n${signalDetails.join("\n")}\n\nStory: ${story.title}`;
+
+    // Send interaction request
+    const requestId = `ix-${flagged.storyId}-size-gate`;
+    const response: InteractionResponse = await chain.prompt({
+      id: requestId,
+      type: "choose",
+      featureName,
+      storyId: flagged.storyId,
+      stage: "pre-flight",
+      summary: `Story ${flagged.storyId} exceeds size thresholds — proceed?`,
+      detail,
+      options: [
+        { key: "approve", label: "Approve", description: "Continue with this story despite size warnings" },
+        { key: "skip", label: "Skip", description: "Skip this story and continue with others" },
+        { key: "abort", label: "Abort", description: "Abort the entire run" },
+      ],
+      timeout: 600000, // 10 minutes
+      fallback: "escalate",
+      createdAt: Date.now(),
+    });
+
+    // Process response
+    switch (response.action) {
+      case "approve": {
+        summary.approved.push(flagged.storyId);
+        logger?.info("precheck", `User approved ${flagged.storyId} despite size warnings`);
+        break;
+      }
+      case "skip": {
+        summary.skipped.push(flagged.storyId);
+        story.status = "skipped";
+        logger?.info("precheck", `User skipped ${flagged.storyId} due to size warnings`);
+        break;
+      }
+      case "abort": {
+        summary.aborted = true;
+        logger?.warn("precheck", `User aborted run due to ${flagged.storyId} size warnings`);
+        throw new Error(`Run aborted by user: story ${flagged.storyId} exceeds size thresholds`);
+      }
+      default: {
+        logger?.warn("precheck", `Unknown action ${response.action} for ${flagged.storyId}, aborting`);
+        summary.aborted = true;
+        throw new Error(`Run aborted: unknown action ${response.action}`);
+      }
+    }
+  }
+
+  logger?.info("precheck", "Story size gate prompts complete", {
+    approved: summary.approved.length,
+    skipped: summary.skipped.length,
+    aborted: summary.aborted,
+  });
+
+  return summary;
+}

package/src/execution/lock.ts

@@ -0,0 +1,115 @@
+/**
+ * Lock File Management
+ *
+ * Extracted from helpers.ts: execution lock acquisition and release.
+ * Prevents concurrent runs in the same directory.
+ */
+
+import path from "node:path";
+import { getLogger } from "../logger";
+
+/** Safely get logger instance, returns null if not initialized */
+function getSafeLogger() {
+  try {
+    return getLogger();
+  } catch {
+    return null;
+  }
+}
+
+/** Check if a process with given PID is still alive */
+function isProcessAlive(pid: number): boolean {
+  try {
+    // kill(pid, 0) checks if process exists without actually sending a signal
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Acquire execution lock to prevent concurrent runs in same directory.
+ * Creates nax.lock file with PID and timestamp.
+ * Returns true if lock acquired, false if another process holds it.
+ *
+ * Handles stale locks from crashed/OOM-killed processes:
+ * - Reads PID from existing lock file
+ * - Checks if process is still alive using kill(pid, 0)
+ * - Removes stale lock if process is dead
+ * - Re-acquires lock after removal
+ */
+export async function acquireLock(workdir: string): Promise<boolean> {
+  const lockPath = path.join(workdir, "nax.lock");
+  const lockFile = Bun.file(lockPath);
+
+  try {
+    // BUG-2 fix: First check for stale lock before attempting atomic create
+    const exists = await lockFile.exists();
+    if (exists) {
+      // Read lock data
+      const lockContent = await lockFile.text();
+      const lockData = JSON.parse(lockContent);
+      const lockPid = lockData.pid;
+
+      // Check if the process is still alive
+      if (isProcessAlive(lockPid)) {
+        // Process is alive, lock is valid
+        return false;
+      }
+
+      // Process is dead, remove stale lock
+      const logger = getSafeLogger();
+      logger?.warn("execution", "Removing stale lock", {
+        pid: lockPid,
+      });
+      const fs = await import("node:fs/promises");
+      await fs.unlink(lockPath).catch(() => {});
+    }
+
+    // Create lock file atomically using exclusive create (O_CREAT | O_EXCL)
+    const lockData = {
+      pid: process.pid,
+      timestamp: Date.now(),
+    };
+    const fs = await import("node:fs");
+    const fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o644);
+    fs.writeSync(fd, JSON.stringify(lockData));
+    fs.closeSync(fd);
+    return true;
+  } catch (error) {
+    // EEXIST means another process won the race
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      return false;
+    }
+    const logger = getSafeLogger();
+    logger?.warn("execution", "Failed to acquire lock", {
+      error: (error as Error).message,
+    });
+    return false;
+  }
+}
+
+/**
+ * Release execution lock by deleting nax.lock file.
+ *
+ * @param workdir - Working directory to unlock
+ */
+export async function releaseLock(workdir: string): Promise<void> {
+  const lockPath = path.join(workdir, "nax.lock");
+  try {
+    const file = Bun.file(lockPath);
+    const exists = await file.exists();
+    if (exists) {
+      const proc = Bun.spawn(["rm", lockPath], { stdout: "pipe" });
+      await proc.exited;
+      // Wait a bit for filesystem to sync (prevents race in tests)
+      await Bun.sleep(10);
+    }
+  } catch (error) {
+    const logger = getSafeLogger();
+    logger?.warn("execution", "Failed to release lock", {
+      error: (error as Error).message,
+    });
+  }
+}

package/src/execution/parallel-executor.ts

@@ -0,0 +1,216 @@
+/**
+ * Parallel Execution Wrapper
+ *
+ * Handles the full parallel execution flow:
+ * - Status updates with parallel info
+ * - Execute parallel stories
+ * - Handle completion or continue to sequential
+ */
+
+import * as os from "node:os";
+import path from "node:path";
+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 type { PRD } from "../prd";
+import { countStories, isComplete } from "../prd";
+import { getAllReadyStories, hookCtx } from "./helpers";
+import { executeParallel } from "./parallel";
+import type { StatusWriter } from "./status-writer";
+
+export interface ParallelExecutorOptions {
+  prdPath: string;
+  workdir: string;
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  featureDir?: string;
+  parallelCount: number;
+  eventEmitter?: PipelineEventEmitter;
+  statusWriter: StatusWriter;
+  runId: string;
+  startedAt: string;
+  startTime: number;
+  totalCost: number;
+  iterations: number;
+  storiesCompleted: number;
+  allStoryMetrics: StoryMetrics[];
+  pluginRegistry: PluginRegistry;
+  formatterMode: "quiet" | "normal" | "verbose" | "json";
+  headless: boolean;
+}
+
+export interface ParallelExecutorResult {
+  prd: PRD;
+  totalCost: number;
+  storiesCompleted: number;
+  completed: boolean;
+  durationMs?: number;
+}
+
+/**
+ * Execute parallel stories if --parallel is set
+ */
+export async function runParallelExecution(
+  options: ParallelExecutorOptions,
+  initialPrd: PRD,
+): Promise<ParallelExecutorResult> {
+  const logger = getSafeLogger();
+  const {
+    prdPath,
+    workdir,
+    config,
+    hooks,
+    feature,
+    featureDir,
+    parallelCount,
+    eventEmitter,
+    statusWriter,
+    runId,
+    startedAt,
+    startTime,
+    pluginRegistry,
+    formatterMode,
+    headless,
+  } = options;
+
+  let { totalCost, iterations, storiesCompleted, allStoryMetrics } = options;
+  let prd = initialPrd;
+
+  const readyStories = getAllReadyStories(prd);
+  if (readyStories.length === 0) {
+    logger?.info("parallel", "No stories ready for parallel execution");
+    return { prd, totalCost, storiesCompleted, completed: false };
+  }
+
+  const maxConcurrency = parallelCount === 0 ? os.cpus().length : Math.max(1, parallelCount);
+
+  logger?.info("parallel", "Starting parallel execution mode", {
+    totalStories: readyStories.length,
+    maxConcurrency,
+  });
+
+  // Update status with parallel info
+  statusWriter.setPrd(prd);
+  await statusWriter.update(totalCost, iterations, {
+    parallel: {
+      enabled: true,
+      maxConcurrency,
+      activeStories: readyStories.map((s) => ({
+        storyId: s.id,
+        worktreePath: path.join(workdir, ".nax-wt", s.id),
+      })),
+    },
+  });
+
+  try {
+    const parallelResult = await executeParallel(
+      readyStories,
+      prdPath,
+      workdir,
+      config,
+      hooks,
+      pluginRegistry,
+      prd,
+      featureDir,
+      parallelCount,
+      eventEmitter,
+    );
+
+    prd = parallelResult.updatedPrd;
+    storiesCompleted += parallelResult.storiesCompleted;
+    totalCost += parallelResult.totalCost;
+
+    logger?.info("parallel", "Parallel execution complete", {
+      storiesCompleted: parallelResult.storiesCompleted,
+      totalCost: parallelResult.totalCost,
+    });
+
+    // Clear parallel status
+    statusWriter.setPrd(prd);
+    await statusWriter.update(totalCost, iterations, {
+      parallel: {
+        enabled: true,
+        maxConcurrency,
+        activeStories: [],
+      },
+    });
+  } catch (error) {
+    logger?.error("parallel", "Parallel execution failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    // Clear parallel status on error
+    await statusWriter.update(totalCost, iterations, {
+      parallel: undefined,
+    });
+
+    throw error;
+  }
+
+  // Check if all stories are complete after parallel execution
+  if (isComplete(prd)) {
+    logger?.info("execution", "All stories complete!", {
+      feature,
+      totalCost,
+    });
+    await fireHook(hooks, "on-complete", hookCtx(feature, { status: "complete", cost: totalCost }), workdir);
+
+    // Skip to metrics and cleanup
+    const durationMs = Date.now() - startTime;
+    const runCompletedAt = new Date().toISOString();
+
+    const { handleParallelCompletion } = await import("./lifecycle/parallel-lifecycle");
+    await handleParallelCompletion({
+      runId,
+      feature,
+      startedAt,
+      completedAt: runCompletedAt,
+      prd,
+      allStoryMetrics,
+      totalCost,
+      storiesCompleted,
+      durationMs,
+      workdir,
+      pluginRegistry,
+    });
+
+    const finalCounts = countStories(prd);
+    statusWriter.setPrd(prd);
+    statusWriter.setCurrentStory(null);
+    statusWriter.setRunStatus("completed");
+    await statusWriter.update(totalCost, iterations);
+
+    // ── Output run footer in headless mode (parallel path) ──────────────
+    if (headless && 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,
+        startedAt,
+        completedAt: runCompletedAt,
+        formatterMode,
+      });
+    }
+
+    return {
+      prd,
+      totalCost,
+      storiesCompleted,
+      completed: true,
+      durationMs,
+    };
+  }
+
+  return { prd, totalCost, storiesCompleted, completed: false };
+}