@nathapp/nax 0.36.0 → 0.36.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.36.0",
+  "version": "0.36.2",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/agents/claude-decompose.ts

@@ -130,7 +130,7 @@ export function parseDecomposeOutput(output: string): DecomposedStory[] {
         : ["Implementation complete"],
       tags: Array.isArray(record.tags) ? record.tags : [],
       dependencies: Array.isArray(record.dependencies) ? record.dependencies : [],
-      complexity: validateComplexity(record.complexity),
+      complexity: coerceComplexity(record.complexity),
       // contextFiles: prefer the new field; fall back to legacy relevantFiles from older LLM responses
       contextFiles: Array.isArray(record.contextFiles)
         ? record.contextFiles
@@ -158,9 +158,9 @@ export function parseDecomposeOutput(output: string): DecomposedStory[] {
 }
 
 /**
- * Validate complexity value from decompose output.
+ * Coerce complexity value from decompose output.
  */
-export function validateComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
+export function coerceComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
   if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
     return value;
   }

package/src/cli/constitution.ts

@@ -4,12 +4,6 @@
  * Generates agent-specific config files from nax/constitution.md.
  */
 
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import chalk from "chalk";
-import { generateAll, generateFor } from "../constitution/generator";
-import type { AgentType } from "../constitution/generators/types";
-
 /** Constitution generate options */
 export interface ConstitutionGenerateOptions {
   /** Path to constitution file (default: nax/constitution.md) */
@@ -21,89 +15,3 @@ export interface ConstitutionGenerateOptions {
   /** Dry run mode (don't write files) */
   dryRun?: boolean;
 }
-
-/**
- * Constitution generate command
- */
-export async function constitutionGenerateCommand(options: ConstitutionGenerateOptions): Promise<void> {
-  const workdir = process.cwd();
-  const constitutionPath = options.constitution
-    ? join(workdir, options.constitution)
-    : join(workdir, "nax/constitution.md");
-  const outputDir = options.output ? join(workdir, options.output) : workdir;
-
-  // Validate constitution file exists
-  if (!existsSync(constitutionPath)) {
-    console.error(chalk.red(`[FAIL] Constitution file not found: ${constitutionPath}`));
-    console.error(chalk.yellow(`Create ${constitutionPath} first or use --constitution to specify a different path.`));
-    process.exit(1);
-  }
-
-  console.log(chalk.blue(`[OK] Loading constitution from ${constitutionPath}`));
-
-  // Validate agent type if specified
-  const validAgents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  if (options.agent && !validAgents.includes(options.agent as AgentType)) {
-    console.error(chalk.red(`[FAIL] Unknown agent type: ${options.agent}`));
-    console.error(chalk.yellow(`Valid agents: ${validAgents.join(", ")}`));
-    process.exit(1);
-  }
-
-  const dryRun = options.dryRun ?? false;
-
-  if (dryRun) {
-    console.log(chalk.yellow("[DRY RUN] No files will be written"));
-  }
-
-  try {
-    // Generate for specific agent or all agents
-    if (options.agent) {
-      const agent = options.agent as AgentType;
-      console.log(chalk.blue(`-> Generating config for ${agent}...`));
-
-      const result = await generateFor(agent, constitutionPath, outputDir, dryRun);
-
-      if (result.error) {
-        console.error(chalk.red(`[FAIL] ${agent}: ${result.error}`));
-        process.exit(1);
-      }
-
-      if (dryRun) {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`));
-      } else {
-        console.log(chalk.green(`[OK] ${agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-      }
-    } else {
-      console.log(chalk.blue("-> Generating configs for all agents..."));
-
-      const results = await generateAll(constitutionPath, outputDir, dryRun);
-
-      let errorCount = 0;
-      for (const result of results) {
-        if (result.error) {
-          console.error(chalk.red(`[FAIL] ${result.agent}: ${result.error}`));
-          errorCount++;
-        } else if (dryRun) {
-          console.log(
-            chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes, dry run)`),
-          );
-        } else {
-          console.log(chalk.green(`[OK] ${result.agent} -> ${result.outputFile} (${result.content.length} bytes)`));
-        }
-      }
-
-      if (errorCount > 0) {
-        console.error(chalk.red(`[FAIL] ${errorCount} generation(s) failed`));
-        process.exit(1);
-      }
-    }
-
-    if (!dryRun) {
-      console.log(chalk.green(`\n[OK] Constitution config(s) generated in ${outputDir}`));
-    }
-  } catch (err) {
-    const error = err instanceof Error ? err.message : String(err);
-    console.error(chalk.red(`[FAIL] Generation failed: ${error}`));
-    process.exit(1);
-  }
-}

package/src/constitution/generator.ts

@@ -156,36 +156,3 @@ export async function generateAll(
 
   return results;
 }
-
-/**
- * Check if constitution file is newer than generated configs
- */
-export function isConstitutionNewer(constitutionPath: string, outputDir: string): boolean {
-  if (!existsSync(constitutionPath)) {
-    return false;
-  }
-
-  const constitutionStat = Bun.file(constitutionPath);
-  const constitutionMtime = constitutionStat.lastModified;
-
-  // Check all generated files
-  const agents: AgentType[] = ["claude", "opencode", "cursor", "windsurf", "aider"];
-  for (const agent of agents) {
-    const outputFile = GENERATORS[agent].outputFile;
-    const outputPath = join(outputDir, outputFile);
-
-    if (!existsSync(outputPath)) {
-      // If any config file is missing, consider constitution newer
-      return true;
-    }
-
-    const outputStat = Bun.file(outputPath);
-    const outputMtime = outputStat.lastModified;
-
-    if (constitutionMtime > outputMtime) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/constitution/index.ts

@@ -7,4 +7,5 @@
  */
 
 export type { ConstitutionConfig, ConstitutionResult } from "./types";
-export { loadConstitution, estimateTokens, truncateToTokens } from "./loader";
+export { loadConstitution, truncateToTokens } from "./loader";
+export { estimateTokens } from "../optimizer/types";

package/src/constitution/loader.ts

@@ -8,21 +8,9 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { validateFilePath } from "../config/path-security";
 import { globalConfigDir } from "../config/paths";
+import { estimateTokens } from "../optimizer/types";
 import type { ConstitutionConfig, ConstitutionResult } from "./types";
 
-/**
- * Estimate token count for text
- *
- * Uses simple heuristic: 1 token ≈ 3 characters (conservative estimate)
- * This is a rough approximation sufficient for quota management.
- *
- * @param text - Text to estimate tokens for
- * @returns Estimated token count
- */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 3);
-}
-
 /**
  * Truncate text to fit within token limit
  *

package/src/context/builder.ts

@@ -7,6 +7,7 @@
 import path from "node:path";
 import type { NaxConfig } from "../config";
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { UserStory } from "../prd";
 import { countStories, getContextFiles } from "../prd";
 import { autoDetectContextFiles } from "./auto-detect";
@@ -18,7 +19,6 @@ import {
   createProgressContext,
   createStoryContext,
   createTestCoverageContext,
-  estimateTokens,
 } from "./elements";
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
@@ -30,7 +30,6 @@ export const _deps = {
 
 // Re-export for backward compatibility
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,

package/src/context/elements.ts

@@ -5,21 +5,10 @@
  */
 
 import { getLogger } from "../logger";
+import { estimateTokens } from "../optimizer/types";
 import type { StructuredFailure, UserStory } from "../prd";
 import type { ContextElement } from "./types";
 
-/**
- * Approximate character-to-token ratio for token estimation.
- * Value of 3 is a middle ground optimized for mixed content (prose + code + markdown).
- * Slightly overestimates tokens, preventing budget overflow.
- */
-const CHARS_PER_TOKEN = 3;
-
-/** Estimate token count for text using character-to-token ratio. */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
-}
-
 /** Create context element from current story */
 export function createStoryContext(story: UserStory, priority: number): ContextElement {
   const content = formatStoryAsText(story);

package/src/context/index.ts

@@ -5,7 +5,6 @@
 export type { ContextElement, ContextBudget, StoryContext, BuiltContext } from "./types";
 
 export {
-  estimateTokens,
   createStoryContext,
   createDependencyContext,
   createErrorContext,
@@ -17,6 +16,8 @@ export {
   formatContextAsMarkdown,
 } from "./builder";
 
+export { estimateTokens } from "../optimizer/types";
+
 export {
   generateTestCoverageSummary,
   scanTestFiles,

package/src/context/test-scanner.ts

@@ -9,7 +9,7 @@
 import path from "node:path";
 import { Glob } from "bun";
 import { getLogger } from "../logger";
-import { estimateTokens } from "./builder";
+import { estimateTokens } from "../optimizer/types";
 
 // ============================================================================
 // Types

package/src/execution/dry-run.ts

@@ -66,7 +66,7 @@ export async function handleDryRun(ctx: DryRunContext): Promise<DryRunResult> {
       storyId: s.id,
       story: s,
       passed: true,
-      durationMs: 0,
+      runElapsedMs: 0,
       cost: 0,
       modelTier: ctx.routing.modelTier,
       testStrategy: ctx.routing.testStrategy,

package/src/execution/escalation/escalation.ts

@@ -22,18 +22,20 @@ import type { TierConfig } from "../../config";
  * ```
  */
 export function escalateTier(currentTier: string, tierOrder: TierConfig[]): string | null {
-  const currentIndex = tierOrder.findIndex((t) => t.tier === currentTier);
+  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
+  const currentIndex = tierOrder.findIndex((t) => getName(t) === currentTier);
   if (currentIndex === -1 || currentIndex === tierOrder.length - 1) {
     return null;
   }
-  return tierOrder[currentIndex + 1].tier;
+  return getName(tierOrder[currentIndex + 1]);
 }
 
 /**
  * Get the tier config for a given tier name.
  */
 export function getTierConfig(tierName: string, tierOrder: TierConfig[]): TierConfig | undefined {
-  return tierOrder.find((t) => t.tier === tierName);
+  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
+  return tierOrder.find((t) => getName(t) === tierName);
 }
 
 /**

package/src/execution/escalation/tier-escalation.ts

@@ -24,6 +24,7 @@ function buildEscalationFailure(
   story: UserStory,
   currentTier: string,
   reviewFindings?: import("../../plugins/types").ReviewFinding[],
+  cost?: number,
 ): StructuredFailure {
   return {
     attempt: (story.attempts ?? 0) + 1,
@@ -31,6 +32,7 @@ function buildEscalationFailure(
     stage: "escalation" as const,
     summary: `Failed with tier ${currentTier}, escalating to next tier`,
     reviewFindings: reviewFindings && reviewFindings.length > 0 ? reviewFindings : undefined,
+    cost: cost ?? 0,
     timestamp: new Date().toISOString(),
   };
 }
@@ -54,6 +56,8 @@ export function resolveMaxAttemptsOutcome(failureCategory?: FailureCategory): "p
     case "verifier-rejected":
     case "greenfield-no-tests":
       return "pause";
+    case "runtime-crash":
+      return "pause";
     case "session-failure":
     case "tests-failing":
       return "fail";
@@ -208,14 +212,38 @@ export interface EscalationHandlerContext {
   feature: string;
   totalCost: number;
   workdir: string;
+  /** Verify result from the pipeline verify stage — used to detect RUNTIME_CRASH (BUG-070) */
+  verifyResult?: { status: string; success: boolean };
+  /** Cost of the failed attempt being escalated (BUG-067: accumulated across escalations) */
+  attemptCost?: number;
 }
 
 export interface EscalationHandlerResult {
-  outcome: "escalated" | "paused" | "failed";
+  outcome: "escalated" | "paused" | "failed" | "retry-same";
   prdDirty: boolean;
   prd: PRD;
 }
 
+/**
+ * Determine if the pipeline should retry the same tier due to a transient runtime crash.
+ *
+ * Returns true when the verify result status is RUNTIME_CRASH — these are Bun
+ * runtime-level failures, not code quality issues, so escalating the model tier
+ * would not help. Instead the same tier should be retried.
+ *
+ * @param verifyResult - Verify result from the pipeline verify stage
+ */
+export function shouldRetrySameTier(verifyResult: { status: string; success: boolean } | undefined): boolean {
+  return verifyResult?.status === "RUNTIME_CRASH";
+}
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _tierEscalationDeps = {
+  savePRD,
+};
+
 /**
  * Handle tier escalation after pipeline escalation action
  *
@@ -223,6 +251,15 @@ export interface EscalationHandlerResult {
  */
 export async function handleTierEscalation(ctx: EscalationHandlerContext): Promise<EscalationHandlerResult> {
   const logger = getSafeLogger();
+
+  // BUG-070: Runtime crashes are transient — retry same tier, do NOT escalate
+  if (shouldRetrySameTier(ctx.verifyResult)) {
+    logger?.warn("escalation", "Runtime crash detected — retrying same tier (transient, not a code issue)", {
+      storyId: ctx.story.id,
+    });
+    return { outcome: "retry-same", prdDirty: false, prd: ctx.prd };
+  }
+
   const nextTier = escalateTier(ctx.routing.modelTier, ctx.config.autoMode.escalation.tierOrder);
   const escalateWholeBatch = ctx.config.autoMode.escalation.escalateEntireBatch ?? true;
   const storiesToEscalate = ctx.isBatchExecution && escalateWholeBatch ? ctx.storiesToExecute : [ctx.story];
@@ -294,8 +331,8 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
       const isChangingTier = currentStoryTier !== nextTier;
       const shouldResetAttempts = isChangingTier || shouldSwitchToTestAfter;
 
-      // Build escalation failure
-      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings);
+      // Build escalation failure (BUG-067: include cost for accumulatedAttemptCost in metrics)
+      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings, ctx.attemptCost);
 
       return {
         ...s,
@@ -307,7 +344,7 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
     }) as PRD["userStories"],
   } as PRD;
 
-  await savePRD(updatedPrd, ctx.prdPath);
+  await _tierEscalationDeps.savePRD(updatedPrd, ctx.prdPath);
 
   // Clear routing cache for all escalated stories to avoid returning old cached decisions
   for (const story of storiesToEscalate) {

package/src/execution/iteration-runner.ts

@@ -60,6 +60,10 @@ export async function runIteration(
 
   const storyStartTime = Date.now();
   const storyGitRef = await captureGitRef(ctx.workdir);
+
+  // BUG-067: Accumulate cost from all prior failed attempts (stored in priorFailures by handleTierEscalation)
+  const accumulatedAttemptCost = (story.priorFailures || []).reduce((sum, f) => sum + (f.cost || 0), 0);
+
   const pipelineContext: PipelineContext = {
     config: ctx.config,
     prd,
@@ -74,6 +78,7 @@ export async function runIteration(
     storyStartTime: new Date().toISOString(),
     storyGitRef: storyGitRef ?? undefined,
     interaction: ctx.interactionChain ?? undefined,
+    accumulatedAttemptCost: accumulatedAttemptCost > 0 ? accumulatedAttemptCost : undefined,
   };
 
   ctx.statusWriter.setPrd(prd);