@nathapp/nax 0.50.3 → 0.51.0

package/src/execution/batching.ts

@@ -1,157 +0,0 @@
-/**
- * Story batching logic
- *
- * Groups consecutive simple-complexity stories into batches for efficient execution.
- */
-
-import type { UserStory } from "../prd";
-
-/**
- * Default maximum number of stories per batch.
- *
- * Rationale:
- * - Batch size must balance efficiency vs. blast radius
- * - 4 stories is optimal for most simple tasks (e.g., add 4 similar util functions)
- * - Keeps prompts manageable (~1500 tokens per story = ~6000 tokens total context)
- * - If one story in batch fails, only 3 others retry at next tier (acceptable waste)
- * - Larger batches (8+) increase risk of cascading failures and context overload
- *
- * This default can be overridden via config or function parameter.
- */
-const DEFAULT_MAX_BATCH_SIZE = 4;
-
-/**
- * Story batch for grouped execution
- */
-export interface StoryBatch {
-  /** Stories in this batch */
-  stories: UserStory[];
-  /** True if this is a batch of multiple stories, false if single story */
-  isBatch: boolean;
-}
-
-/**
- * Group consecutive simple-complexity stories into batches (max 4 per batch).
- * Non-simple stories execute individually.
- *
- * @param stories - Array of user stories to batch
- * @param maxBatchSize - Maximum stories per batch (default: 4)
- * @returns Array of story batches
- *
- * @example
- * ```typescript
- * const stories = [simpleStory1, simpleStory2, complexStory, simpleStory3];
- * const batches = groupStoriesIntoBatches(stories);
- * // Returns: [
- * //   { stories: [simpleStory1, simpleStory2], isBatch: true },
- * //   { stories: [complexStory], isBatch: false },
- * //   { stories: [simpleStory3], isBatch: false }
- * // ]
- * ```
- */
-export function groupStoriesIntoBatches(stories: UserStory[], maxBatchSize = DEFAULT_MAX_BATCH_SIZE): StoryBatch[] {
-  const batches: StoryBatch[] = [];
-  let currentBatch: UserStory[] = [];
-
-  for (const story of stories) {
-    const isSimple = story.routing?.complexity === "simple";
-
-    if (isSimple && currentBatch.length < maxBatchSize) {
-      // Add to current batch
-      currentBatch.push(story);
-    } else {
-      // Flush current batch if it exists
-      if (currentBatch.length > 0) {
-        batches.push({
-          stories: [...currentBatch],
-          isBatch: currentBatch.length > 1,
-        });
-        currentBatch = [];
-      }
-
-      // Add non-simple story as individual batch
-      if (!isSimple) {
-        batches.push({
-          stories: [story],
-          isBatch: false,
-        });
-      } else {
-        // Start new batch with this simple story
-        currentBatch.push(story);
-      }
-    }
-  }
-
-  // Flush remaining batch
-  if (currentBatch.length > 0) {
-    batches.push({
-      stories: [...currentBatch],
-      isBatch: currentBatch.length > 1,
-    });
-  }
-
-  return batches;
-}
-
-/**
- * Precompute the full batch plan from ready stories.
- * This eliminates O(n²) re-checking by computing all batches upfront.
- * Maintains original story order from PRD.
- *
- * @param stories - Array of ready user stories (already filtered for dependencies)
- * @param maxBatchSize - Maximum stories per batch (default: 4)
- * @returns Array of story batches ready for sequential execution
- *
- * @example
- * ```typescript
- * const readyStories = getAllReadyStories(prd);
- * const batchPlan = precomputeBatchPlan(readyStories);
- * // Iterate through batches sequentially
- * for (const batch of batchPlan) {
- *   await executeBatch(batch);
- * }
- * ```
- */
-export function precomputeBatchPlan(stories: UserStory[], maxBatchSize = DEFAULT_MAX_BATCH_SIZE): StoryBatch[] {
-  const batches: StoryBatch[] = [];
-  let currentBatch: UserStory[] = [];
-
-  for (const story of stories) {
-    const isSimple = story.routing?.complexity === "simple" && story.routing?.testStrategy === "test-after";
-
-    if (isSimple && currentBatch.length < maxBatchSize) {
-      // Add to current batch
-      currentBatch.push(story);
-    } else {
-      // Flush current batch if it exists
-      if (currentBatch.length > 0) {
-        batches.push({
-          stories: [...currentBatch],
-          isBatch: currentBatch.length > 1,
-        });
-        currentBatch = [];
-      }
-
-      // Add non-simple story as individual batch
-      if (!isSimple) {
-        batches.push({
-          stories: [story],
-          isBatch: false,
-        });
-      } else {
-        // Start new batch with this simple story
-        currentBatch.push(story);
-      }
-    }
-  }
-
-  // Flush remaining batch
-  if (currentBatch.length > 0) {
-    batches.push({
-      stories: [...currentBatch],
-      isBatch: currentBatch.length > 1,
-    });
-  }
-
-  return batches;
-}

package/src/execution/crash-heartbeat.ts

@@ -1,77 +0,0 @@
-/**
- * Heartbeat monitoring — periodic health checks during execution
- */
-
-import { appendFileSync } from "node:fs";
-import { getSafeLogger } from "../logger";
-import type { StatusWriter } from "./status-writer";
-
-let heartbeatTimer: Timer | null = null;
-
-/**
- * Start heartbeat timer (60s interval)
- */
-export function startHeartbeat(
-  statusWriter: StatusWriter,
-  getTotalCost: () => number,
-  getIterations: () => number,
-  jsonlFilePath?: string,
-): void {
-  const logger = getSafeLogger();
-
-  stopHeartbeat();
-
-  heartbeatTimer = setInterval(async () => {
-    logger?.debug("crash-recovery", "Heartbeat");
-
-    if (jsonlFilePath) {
-      try {
-        const heartbeatEntry = {
-          timestamp: new Date().toISOString(),
-          level: "debug",
-          stage: "heartbeat",
-          message: "Process alive",
-          data: {
-            pid: process.pid,
-            memoryUsageMB: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
-          },
-        };
-        const line = `${JSON.stringify(heartbeatEntry)}\n`;
-        appendFileSync(jsonlFilePath, line);
-      } catch (err) {
-        logger?.warn("crash-recovery", "Failed to write heartbeat", { error: (err as Error).message });
-      }
-    }
-
-    try {
-      await statusWriter.update(getTotalCost(), getIterations(), {
-        lastHeartbeat: new Date().toISOString(),
-      });
-    } catch (err) {
-      logger?.warn("crash-recovery", "Failed to update status during heartbeat", {
-        error: (err as Error).message,
-      });
-    }
-  }, 60_000);
-
-  logger?.debug("crash-recovery", "Heartbeat started (60s interval)");
-}
-
-/**
- * Stop heartbeat timer
- */
-export function stopHeartbeat(): void {
-  if (heartbeatTimer) {
-    clearInterval(heartbeatTimer);
-    heartbeatTimer = null;
-    getSafeLogger()?.debug("crash-recovery", "Heartbeat stopped");
-  }
-}
-
-/**
- * Returns true if heartbeat timer is currently active.
- * @internal - test use only.
- */
-export function _isHeartbeatActive(): boolean {
-  return heartbeatTimer !== null;
-}

package/src/execution/crash-recovery.ts

@@ -1,79 +0,0 @@
-/**
- * Crash Recovery Orchestrator
- *
- * Implements US-007:
- * - SIGTERM/SIGINT/SIGHUP handlers
- * - Uncaught exception handlers
- * - Fatal log + status.json update to "crashed"
- * - Heartbeat every 60s during agent execution
- * - Exit summary entry on normal exit
- *
- * Re-exports crash detection and writer modules.
- */
-
-import { stopHeartbeat } from "./crash-heartbeat";
-import { installSignalHandlers } from "./crash-signals";
-import type { PidRegistry } from "./pid-registry";
-import type { StatusWriter } from "./status-writer";
-
-// Re-export for backward compatibility
-export {
-  type RunCompleteContext,
-  updateStatusToCrashed,
-  writeFatalLog,
-  writeRunComplete,
-  writeExitSummary,
-} from "./crash-writer";
-
-export { type SignalHandlerContext, installSignalHandlers } from "./crash-signals";
-
-export { startHeartbeat, stopHeartbeat, _isHeartbeatActive } from "./crash-heartbeat";
-
-/**
- * Crash recovery context — dependencies injected at setup
- */
-export interface CrashRecoveryContext {
-  statusWriter: StatusWriter;
-  getTotalCost: () => number;
-  getIterations: () => number;
-  jsonlFilePath?: string;
-  pidRegistry?: PidRegistry;
-  runId?: string;
-  feature?: string;
-  featureDir?: string;
-  getStartTime?: () => number;
-  getTotalStories?: () => number;
-  getStoriesCompleted?: () => number;
-  emitError?: (reason: string) => void;
-  /** Called during graceful shutdown before process.exit — use to close ACP sessions etc. */
-  onShutdown?: () => Promise<void>;
-}
-
-let handlersInstalled = false;
-
-/**
- * Install crash handlers for recovery
- */
-export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
-  if (handlersInstalled) {
-    return () => {};
-  }
-
-  const cleanup = installSignalHandlers(ctx);
-  handlersInstalled = true;
-
-  return () => {
-    cleanup();
-    stopHeartbeat();
-    handlersInstalled = false;
-  };
-}
-
-/**
- * Reset handlers (for testing)
- * @internal
- */
-export function resetCrashHandlers(): void {
-  handlersInstalled = false;
-  stopHeartbeat();
-}

package/src/execution/crash-signals.ts

@@ -1,165 +0,0 @@
-/**
- * Crash detection — Signal and exception handlers
- */
-
-import { getSafeLogger } from "../logger";
-import { type RunCompleteContext, updateStatusToCrashed, writeFatalLog, writeRunComplete } from "./crash-writer";
-import type { PidRegistry } from "./pid-registry";
-import type { StatusWriter } from "./status-writer";
-
-/**
- * Handler context for signal/exception management
- */
-export interface SignalHandlerContext extends RunCompleteContext {
-  statusWriter: StatusWriter;
-  pidRegistry?: PidRegistry;
-  featureDir?: string;
-  emitError?: (reason: string) => void;
-  /** Called during graceful shutdown (signal/exception) before process.exit — use to close ACP sessions etc. */
-  onShutdown?: () => Promise<void>;
-}
-
-/**
- * Get numeric signal number for exit code
- */
-function getSignalNumber(signal: NodeJS.Signals): number {
-  const signalMap: Record<string, number> = {
-    SIGTERM: 15,
-    SIGINT: 2,
-    SIGHUP: 1,
-  };
-  return signalMap[signal] ?? 15;
-}
-
-/**
- * Create signal handler
- */
-function createSignalHandler(ctx: SignalHandlerContext): (signal: NodeJS.Signals) => Promise<void> {
-  return async (signal: NodeJS.Signals) => {
-    const hardDeadline = setTimeout(() => {
-      process.exit(128 + getSignalNumber(signal));
-    }, 10_000);
-    if (hardDeadline.unref) hardDeadline.unref();
-
-    const logger = getSafeLogger();
-    logger?.error("crash-recovery", `Received ${signal}, shutting down...`, { signal });
-
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
-
-    // Close any open ACP sessions before exiting (prevents orphaned acpx processes)
-    if (ctx.onShutdown) {
-      await ctx.onShutdown().catch(() => {});
-    }
-
-    ctx.emitError?.(signal.toLowerCase());
-
-    await writeFatalLog(ctx.jsonlFilePath, signal);
-    await writeRunComplete(ctx, signal.toLowerCase());
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal, ctx.featureDir);
-
-    clearTimeout(hardDeadline);
-    process.exit(128 + getSignalNumber(signal));
-  };
-}
-
-/**
- * Create uncaught exception handler
- */
-function createUncaughtExceptionHandler(ctx: SignalHandlerContext): (error: Error) => Promise<void> {
-  return async (error: Error) => {
-    const logger = getSafeLogger();
-    logger?.error("crash-recovery", "Uncaught exception", {
-      error: error.message,
-      stack: error.stack,
-    });
-
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
-
-    if (ctx.onShutdown) {
-      await ctx.onShutdown().catch(() => {});
-    }
-
-    ctx.emitError?.("uncaughtException");
-    await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
-    await updateStatusToCrashed(
-      ctx.statusWriter,
-      ctx.getTotalCost(),
-      ctx.getIterations(),
-      "uncaughtException",
-      ctx.featureDir,
-    );
-
-    process.exit(1);
-  };
-}
-
-/**
- * Create unhandled promise rejection handler
- */
-function createUnhandledRejectionHandler(ctx: SignalHandlerContext): (reason: unknown) => Promise<void> {
-  return async (reason: unknown) => {
-    const error = reason instanceof Error ? reason : new Error(String(reason));
-    const logger = getSafeLogger();
-    logger?.error("crash-recovery", "Unhandled promise rejection", {
-      error: error.message,
-      stack: error.stack,
-    });
-
-    if (ctx.pidRegistry) {
-      await ctx.pidRegistry.killAll();
-    }
-
-    if (ctx.onShutdown) {
-      await ctx.onShutdown().catch(() => {});
-    }
-
-    ctx.emitError?.("unhandledRejection");
-    await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
-    await updateStatusToCrashed(
-      ctx.statusWriter,
-      ctx.getTotalCost(),
-      ctx.getIterations(),
-      "unhandledRejection",
-      ctx.featureDir,
-    );
-
-    process.exit(1);
-  };
-}
-
-/**
- * Install signal and exception handlers, return cleanup function
- */
-export function installSignalHandlers(ctx: SignalHandlerContext): () => void {
-  const logger = getSafeLogger();
-
-  const signalHandler = createSignalHandler(ctx);
-  const uncaughtExceptionHandler = createUncaughtExceptionHandler(ctx);
-  const unhandledRejectionHandler = createUnhandledRejectionHandler(ctx);
-
-  const sigtermHandler = () => signalHandler("SIGTERM");
-  const sigintHandler = () => signalHandler("SIGINT");
-  const sighupHandler = () => signalHandler("SIGHUP");
-
-  process.on("SIGTERM", sigtermHandler);
-  process.on("SIGINT", sigintHandler);
-  process.on("SIGHUP", sighupHandler);
-  process.on("uncaughtException", uncaughtExceptionHandler);
-  const rejectionWrapper = (reason: unknown) => unhandledRejectionHandler(reason);
-  process.on("unhandledRejection", rejectionWrapper);
-
-  logger?.debug("crash-recovery", "Signal handlers installed");
-
-  return () => {
-    process.removeListener("SIGTERM", sigtermHandler);
-    process.removeListener("SIGINT", sigintHandler);
-    process.removeListener("SIGHUP", sighupHandler);
-    process.removeListener("uncaughtException", uncaughtExceptionHandler);
-    process.removeListener("unhandledRejection", rejectionWrapper);
-    logger?.debug("crash-recovery", "Signal handlers unregistered");
-  };
-}

package/src/execution/crash-writer.ts

@@ -1,154 +0,0 @@
-/**
- * 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 });
-  }
-}