@nathapp/nax 0.18.1

package/src/execution/sequential-executor.ts

@@ -0,0 +1,388 @@
+/** Sequential Story Executor — main execution loop for story pipeline. */
+
+import type { NaxConfig } from "../config";
+import { type LoadedHooksConfig, fireHook } from "../hooks";
+import type { InteractionChain } from "../interaction/chain";
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+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";
+import { generateHumanHaltSummary, getNextStory, isComplete, isStalled, loadPRD } from "../prd";
+import type { PRD, UserStory } from "../prd/types";
+import { routeTask } from "../routing";
+import { captureGitRef } from "../utils/git";
+import type { StoryBatch } from "./batching";
+import { startHeartbeat, stopHeartbeat, writeExitSummary } from "./crash-recovery";
+import { preIterationTierCheck } from "./escalation";
+import { hookCtx } from "./helpers";
+import {
+  applyCachedRouting,
+  handleDryRun,
+  handlePipelineFailure,
+  handlePipelineSuccess,
+} from "./pipeline-result-handler";
+import type { StatusWriter } from "./status-writer";
+
+export interface SequentialExecutionContext {
+  prdPath: string;
+  workdir: string;
+  config: NaxConfig;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  featureDir?: string;
+  dryRun: boolean;
+  useBatch: boolean;
+  pluginRegistry: PluginRegistry;
+  eventEmitter?: PipelineEventEmitter;
+  statusWriter: StatusWriter;
+  logFilePath?: string;
+  runId: string;
+  startTime: number;
+  batchPlan: StoryBatch[];
+  interactionChain?: InteractionChain | null;
+}
+
+export interface SequentialExecutionResult {
+  prd: PRD;
+  iterations: number;
+  storiesCompleted: number;
+  totalCost: number;
+  allStoryMetrics: StoryMetrics[];
+  timeoutRetryCountMap: Map<string, number>;
+  exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories";
+}
+
+/**
+ * Execute stories sequentially through the pipeline
+ */
+export async function executeSequential(
+  ctx: SequentialExecutionContext,
+  initialPrd: PRD,
+): Promise<SequentialExecutionResult> {
+  const logger = getSafeLogger();
+  let prd = initialPrd;
+  let prdDirty = false;
+  let iterations = 0;
+  let storiesCompleted = 0;
+  let totalCost = 0;
+  const allStoryMetrics: StoryMetrics[] = [];
+  const timeoutRetryCountMap = new Map<string, number>();
+  let currentBatchIndex = 0;
+  let lastStoryId: string | null = null;
+
+  const buildResult = (exitReason: SequentialExecutionResult["exitReason"]): SequentialExecutionResult => ({
+    prd,
+    iterations,
+    storiesCompleted,
+    totalCost,
+    allStoryMetrics,
+    timeoutRetryCountMap,
+    exitReason,
+  });
+
+  startHeartbeat(
+    ctx.statusWriter,
+    () => totalCost,
+    () => iterations,
+    ctx.logFilePath,
+  );
+
+  try {
+    // Main execution loop
+    while (iterations < ctx.config.execution.maxIterations) {
+      iterations++;
+
+      // MEM-1: Check memory usage (warn if > 1GB heap)
+      const memUsage = process.memoryUsage();
+      const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
+      if (heapUsedMB > 1024) {
+        logger?.warn("execution", "High memory usage detected", {
+          heapUsedMB,
+          suggestion: "Consider pausing (echo PAUSE > .queue.txt) if this continues to grow",
+        });
+      }
+
+      // Reload PRD only if dirty (modified since last load)
+      if (prdDirty) {
+        prd = await loadPRD(ctx.prdPath);
+        prdDirty = false;
+      }
+
+      // Check completion
+      if (isComplete(prd)) {
+        logger?.info("execution", "All stories complete!", {
+          feature: ctx.feature,
+          totalCost,
+        });
+        await fireHook(
+          ctx.hooks,
+          "on-complete",
+          hookCtx(ctx.feature, { status: "complete", cost: totalCost }),
+          ctx.workdir,
+        );
+        return buildResult("completed");
+      }
+
+      // Get next story/batch
+      let storiesToExecute: UserStory[];
+      let isBatchExecution: boolean;
+      let story: UserStory;
+      let routing: ReturnType<typeof routeTask>;
+
+      if (ctx.useBatch && currentBatchIndex < ctx.batchPlan.length) {
+        // Get next batch from precomputed plan
+        const batch = ctx.batchPlan[currentBatchIndex];
+        currentBatchIndex++;
+
+        // Filter out already-completed stories
+        storiesToExecute = batch.stories.filter(
+          (s) =>
+            !s.passes &&
+            s.status !== "passed" &&
+            s.status !== "skipped" &&
+            s.status !== "blocked" &&
+            s.status !== "failed" &&
+            s.status !== "paused",
+        );
+        isBatchExecution = batch.isBatch && storiesToExecute.length > 1;
+
+        if (storiesToExecute.length === 0) {
+          // All stories in this batch already completed, move to next batch
+          continue;
+        }
+
+        // Use first story as the primary story for routing/context
+        story = storiesToExecute[0];
+        routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, ctx.config);
+        routing = applyCachedRouting(routing, story, ctx.config);
+      } else {
+        // Fallback to single-story mode (when batching disabled or batch plan exhausted)
+        const nextStory = getNextStory(prd, lastStoryId, ctx.config.execution.rectification?.maxRetries ?? 2);
+        if (!nextStory) {
+          logger?.warn("execution", "No actionable stories (check dependencies)");
+          return buildResult("no-stories");
+        }
+
+        story = nextStory;
+        lastStoryId = story.id;
+        storiesToExecute = [story];
+        isBatchExecution = false;
+
+        routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, ctx.config);
+        routing = applyCachedRouting(routing, story, ctx.config);
+      }
+
+      // Pre-iteration tier escalation check
+      const tierCheckResult = await preIterationTierCheck(
+        story,
+        routing,
+        ctx.config,
+        prd,
+        ctx.prdPath,
+        ctx.featureDir,
+        ctx.hooks,
+        ctx.feature,
+        totalCost,
+        ctx.workdir,
+      );
+
+      if (tierCheckResult.shouldSkipIteration) {
+        prd = tierCheckResult.prd;
+        prdDirty = tierCheckResult.prdDirty;
+        continue;
+      }
+
+      // Check cost limit
+      if (totalCost >= ctx.config.execution.costLimit) {
+        logger?.warn("execution", "Cost limit reached, pausing", {
+          totalCost,
+          costLimit: ctx.config.execution.costLimit,
+        });
+        await fireHook(
+          ctx.hooks,
+          "on-pause",
+          hookCtx(ctx.feature, {
+            storyId: story.id,
+            reason: `Cost limit reached: $${totalCost.toFixed(2)}`,
+            cost: totalCost,
+          }),
+          ctx.workdir,
+        );
+        return buildResult("cost-limit");
+      }
+
+      logger?.info("iteration.start", `Starting iteration ${iterations}`, {
+        iteration: iterations,
+        storyId: story.id,
+        storyTitle: story.title,
+        isBatch: isBatchExecution,
+        batchSize: isBatchExecution ? storiesToExecute.length : 1,
+        modelTier: routing.modelTier,
+        complexity: routing.complexity,
+        ...(isBatchExecution && { batchStoryIds: storiesToExecute.map((s) => s.id) }),
+      });
+
+      // Fire story-start hook
+      await fireHook(
+        ctx.hooks,
+        "on-story-start",
+        hookCtx(ctx.feature, {
+          storyId: story.id,
+          model: routing.modelTier,
+          agent: ctx.config.autoMode.defaultAgent,
+          iteration: iterations,
+        }),
+        ctx.workdir,
+      );
+
+      if (ctx.dryRun) {
+        const dryRunResult = await handleDryRun({
+          prd,
+          prdPath: ctx.prdPath,
+          storiesToExecute,
+          routing,
+          statusWriter: ctx.statusWriter,
+          pluginRegistry: ctx.pluginRegistry,
+          runId: ctx.runId,
+          totalCost,
+          iterations,
+        });
+        storiesCompleted += dryRunResult.storiesCompletedDelta;
+        prdDirty = dryRunResult.prdDirty;
+        continue;
+      }
+
+      // Capture git ref for scoped verification
+      const storyGitRef = await captureGitRef(ctx.workdir);
+
+      // Build pipeline context
+      const storyStartTime = new Date().toISOString();
+      const pipelineContext: PipelineContext = {
+        config: ctx.config,
+        prd,
+        story,
+        stories: storiesToExecute,
+        routing: routing as RoutingResult,
+        workdir: ctx.workdir,
+        featureDir: ctx.featureDir,
+        hooks: ctx.hooks,
+        plugins: ctx.pluginRegistry,
+        storyStartTime,
+        interaction: ctx.interactionChain ?? undefined,
+      };
+
+      // Log agent start
+      logger?.info("agent.start", "Starting agent execution", {
+        storyId: story.id,
+        agent: ctx.config.autoMode.defaultAgent,
+        modelTier: routing.modelTier,
+        testStrategy: routing.testStrategy,
+        isBatch: isBatchExecution,
+      });
+
+      // Update status before execution
+      ctx.statusWriter.setPrd(prd);
+      ctx.statusWriter.setCurrentStory({
+        storyId: story.id,
+        title: story.title,
+        complexity: routing.complexity,
+        tddStrategy: routing.testStrategy,
+        model: routing.modelTier,
+        attempt: (story.attempts ?? 0) + 1,
+        phase: "routing",
+      });
+      await ctx.statusWriter.update(totalCost, iterations);
+
+      // Run pipeline
+      const pipelineResult = await runPipeline(defaultPipeline, pipelineContext, ctx.eventEmitter);
+
+      // Log agent complete
+      logger?.info("agent.complete", "Agent execution completed", {
+        storyId: story.id,
+        success: pipelineResult.success,
+        finalAction: pipelineResult.finalAction,
+        estimatedCost: pipelineResult.context.agentResult?.estimatedCost,
+      });
+
+      // Update PRD reference (pipeline may have modified it)
+      prd = pipelineResult.context.prd;
+
+      // Handle pipeline result
+      const handlerCtx = {
+        config: ctx.config,
+        prd,
+        prdPath: ctx.prdPath,
+        workdir: ctx.workdir,
+        featureDir: ctx.featureDir,
+        hooks: ctx.hooks,
+        feature: ctx.feature,
+        totalCost,
+        startTime: ctx.startTime,
+        runId: ctx.runId,
+        pluginRegistry: ctx.pluginRegistry,
+        story,
+        storiesToExecute,
+        routing,
+        isBatchExecution,
+        allStoryMetrics,
+        timeoutRetryCountMap,
+        storyGitRef,
+        interactionChain: ctx.interactionChain,
+      };
+
+      if (pipelineResult.success) {
+        const successResult = await handlePipelineSuccess(handlerCtx, pipelineResult);
+        totalCost += successResult.costDelta;
+        storiesCompleted += successResult.storiesCompletedDelta;
+        prd = successResult.prd;
+        prdDirty = successResult.prdDirty;
+      } else {
+        const failResult = await handlePipelineFailure(handlerCtx, pipelineResult);
+        prd = failResult.prd;
+        prdDirty = failResult.prdDirty;
+      }
+
+      // Update status after story complete
+      if (prdDirty) {
+        prd = await loadPRD(ctx.prdPath);
+        prdDirty = false;
+      }
+      ctx.statusWriter.setPrd(prd);
+      ctx.statusWriter.setCurrentStory(null);
+      await ctx.statusWriter.update(totalCost, iterations);
+
+      // Stall detection
+      if (isStalled(prd)) {
+        const summary = generateHumanHaltSummary(prd);
+        logger?.error("execution", "Execution stalled", {
+          reason: "All remaining stories blocked or dependent on blocked stories",
+          summary,
+        });
+        await fireHook(
+          ctx.hooks,
+          "on-pause",
+          hookCtx(ctx.feature, {
+            reason: "All remaining stories blocked or dependent on blocked stories",
+            cost: totalCost,
+          }),
+          ctx.workdir,
+        );
+        return buildResult("stalled");
+      }
+
+      // Delay between iterations
+      if (ctx.config.execution.iterationDelayMs > 0) {
+        await Bun.sleep(ctx.config.execution.iterationDelayMs);
+      }
+    }
+
+    return buildResult("max-iterations");
+  } finally {
+    // Stop heartbeat and write exit summary
+    stopHeartbeat();
+    await writeExitSummary(ctx.logFilePath, totalCost, iterations, storiesCompleted, Date.now() - ctx.startTime);
+  }
+}

package/src/execution/status-file.ts

@@ -0,0 +1,264 @@
+/**
+ * Status File — Machine-readable run state for external tooling
+ *
+ * Writes a JSON status file that external tools (CI/CD, orchestrators,
+ * dashboards) can poll to monitor nax runs without parsing logs.
+ *
+ * Atomic writes: write to <path>.tmp then rename to <path>
+ */
+
+import { rename, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { NaxConfig } from "../config";
+import type { PRD, StoryStatus, UserStory } from "../prd";
+
+// ============================================================================
+// NaxStatusFile Interface
+// ============================================================================
+
+/** Machine-readable status file written during nax runs */
+export interface NaxStatusFile {
+  /** Schema version for forward compatibility */
+  version: 1;
+
+  /** Run metadata */
+  run: {
+    /** Run ID (e.g. "run-2026-02-25T10-00-00-000Z") */
+    id: string;
+    /** Feature name */
+    feature: string;
+    /** ISO 8601 start timestamp */
+    startedAt: string;
+    /** Current run status */
+    status: "running" | "completed" | "failed" | "stalled" | "crashed" | "precheck-failed";
+    /** Whether this is a dry run */
+    dryRun: boolean;
+    /** Process ID for crash detection */
+    pid: number;
+    /** ISO 8601 crash timestamp (present when status is "crashed") */
+    crashedAt?: string;
+    /** Signal or exception that caused crash (present when status is "crashed") */
+    crashSignal?: string;
+  };
+
+  /** Aggregate progress counts */
+  progress: {
+    /** Total stories in PRD */
+    total: number;
+    /** Stories that passed */
+    passed: number;
+    /** Stories that failed */
+    failed: number;
+    /** Stories that are paused */
+    paused: number;
+    /** Stories that are blocked */
+    blocked: number;
+    /** Stories not yet processed (total - passed - failed - paused - blocked) */
+    pending: number;
+  };
+
+  /** Cost tracking */
+  cost: {
+    /** Accumulated cost in USD */
+    spent: number;
+    /** Cost limit from config (null if not set) */
+    limit: number | null;
+  };
+
+  /** Current story being processed (null if between stories or at run boundaries) */
+  current: {
+    /** Story ID */
+    storyId: string;
+    /** Story title */
+    title: string;
+    /** Complexity level */
+    complexity: string;
+    /** TDD strategy */
+    tddStrategy: string;
+    /** Resolved model name */
+    model: string;
+    /** Current attempt number (1-based) */
+    attempt: number;
+    /** Current phase */
+    phase: string;
+  } | null;
+
+  /** Number of loop iterations completed */
+  iterations: number;
+
+  /** ISO 8601 last-updated timestamp */
+  updatedAt: string;
+
+  /** Elapsed duration in milliseconds */
+  durationMs: number;
+
+  /** ISO 8601 last heartbeat timestamp (updated every 60s during execution) */
+  lastHeartbeat?: string;
+
+  /** Parallel execution info (present when --parallel is used) */
+  parallel?: {
+    /** Whether parallel mode is enabled */
+    enabled: boolean;
+    /** Max concurrent sessions */
+    maxConcurrency: number;
+    /** Currently executing stories in parallel */
+    activeStories: Array<{
+      storyId: string;
+      worktreePath: string;
+    }>;
+  };
+}
+
+// ============================================================================
+// Progress Counting
+// ============================================================================
+
+/**
+ * Derive progress counts from PRD story statuses.
+ *
+ * Counts each story by its current status. `pending` is computed as
+ * everything not in the four explicit terminal/waiting states.
+ */
+export function countProgress(prd: PRD): NaxStatusFile["progress"] {
+  const stories = prd.userStories;
+  const passed = stories.filter((s) => s.status === "passed").length;
+  const failed = stories.filter((s) => s.status === "failed").length;
+  const paused = stories.filter((s) => s.status === "paused").length;
+  const blocked = stories.filter((s) => s.status === "blocked").length;
+  const total = stories.length;
+  const pending = total - passed - failed - paused - blocked;
+
+  return { total, passed, failed, paused, blocked, pending };
+}
+
+// ============================================================================
+// Run State (for buildStatusSnapshot)
+// ============================================================================
+
+/**
+ * Snapshot of current run state used to build NaxStatusFile.
+ *
+ * This is a value-only snapshot — callers pass in what they have at the
+ * current write point. The runner constructs this inline from local variables.
+ */
+export interface RunStateSnapshot {
+  /** Unique run identifier */
+  runId: string;
+  /** Feature name */
+  feature: string;
+  /** ISO 8601 start timestamp */
+  startedAt: string;
+  /** Current run status */
+  runStatus: NaxStatusFile["run"]["status"];
+  /** Whether this is a dry run */
+  dryRun: boolean;
+  /** Process ID for crash detection */
+  pid: number;
+  /** Loaded PRD (for progress counting) */
+  prd: PRD;
+  /** Accumulated cost in USD */
+  totalCost: number;
+  /** Cost limit from config (or null) */
+  costLimit: number | null;
+  /** Currently-executing story info (null between stories) */
+  currentStory: {
+    storyId: string;
+    title: string;
+    complexity: string;
+    tddStrategy: string;
+    model: string;
+    attempt: number;
+    phase: string;
+  } | null;
+  /** Number of loop iterations */
+  iterations: number;
+  /** Run start time as ms epoch (for computing durationMs) */
+  startTimeMs: number;
+  /** Parallel execution info (optional) */
+  parallel?: NaxStatusFile["parallel"];
+  /** ISO 8601 crash timestamp (present when status is "crashed") */
+  crashedAt?: string;
+  /** Signal or exception that caused crash (present when status is "crashed") */
+  crashSignal?: string;
+  /** ISO 8601 last heartbeat timestamp (updated every 60s during execution) */
+  lastHeartbeat?: string;
+}
+
+// ============================================================================
+// buildStatusSnapshot
+// ============================================================================
+
+/**
+ * Build a NaxStatusFile object from current run state.
+ *
+ * Derives progress from PRD story statuses. Sets updatedAt and durationMs
+ * from the current time. Does not write to disk — call writeStatusFile() for that.
+ */
+export function buildStatusSnapshot(state: RunStateSnapshot): NaxStatusFile {
+  const now = Date.now();
+  const snapshot: NaxStatusFile = {
+    version: 1,
+    run: {
+      id: state.runId,
+      feature: state.feature,
+      startedAt: state.startedAt,
+      status: state.runStatus,
+      dryRun: state.dryRun,
+      pid: state.pid,
+      ...(state.crashedAt && { crashedAt: state.crashedAt }),
+      ...(state.crashSignal && { crashSignal: state.crashSignal }),
+    },
+    progress: countProgress(state.prd),
+    cost: {
+      spent: state.totalCost,
+      limit: state.costLimit,
+    },
+    current: state.currentStory,
+    iterations: state.iterations,
+    updatedAt: new Date(now).toISOString(),
+    durationMs: now - state.startTimeMs,
+    ...(state.lastHeartbeat && { lastHeartbeat: state.lastHeartbeat }),
+  };
+
+  if (state.parallel) {
+    snapshot.parallel = state.parallel;
+  }
+
+  return snapshot;
+}
+
+// ============================================================================
+// Atomic Writer
+// ============================================================================
+
+/**
+ * Atomically write a NaxStatusFile to disk.
+ *
+ * Writes to `<path>.tmp` first, then renames to `<path>` to prevent
+ * consumers from reading partial JSON during the write.
+ *
+ * @param filePath - Destination path for the status file
+ * @param status   - Status file content to write
+ * @throws Error if path traversal is detected
+ */
+export async function writeStatusFile(filePath: string, status: NaxStatusFile): Promise<void> {
+  // SEC-1: Validate path to prevent path traversal attacks
+  const resolvedPath = resolve(filePath);
+
+  // Check for path traversal patterns in the original path
+  if (filePath.includes("../") || filePath.includes("..\\")) {
+    throw new Error("Invalid status file path: path traversal detected");
+  }
+
+  const tmpPath = `${resolvedPath}.tmp`;
+
+  // MEM-1: Clean up stale .tmp file if it exists
+  try {
+    await unlink(tmpPath);
+  } catch {
+    // Ignore error if file doesn't exist
+  }
+
+  await Bun.write(tmpPath, JSON.stringify(status, null, 2));
+  await rename(tmpPath, resolvedPath);
+}