@nathapp/nax 0.46.0 → 0.46.2

package/src/agents/cost/parse.ts

@@ -0,0 +1,97 @@
+/**
+ * Token usage parsing from raw agent output strings.
+ */
+
+import type { TokenUsageWithConfidence } from "./types";
+
+/**
+ * Parse Claude Code output for token usage.
+ *
+ * Supports multiple formats with varying confidence levels:
+ * - JSON structured output → "exact" confidence
+ * - Markdown/plain text patterns → "estimated" confidence
+ *
+ * Uses specific regex patterns to reduce false positives.
+ *
+ * @param output - Agent stdout + stderr combined
+ * @returns Token usage with confidence indicator, or null if tokens cannot be parsed
+ *
+ * @example
+ * ```ts
+ * // JSON format (exact)
+ * const usage1 = parseTokenUsage('{"usage": {"input_tokens": 1234, "output_tokens": 5678}}');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'exact' }
+ *
+ * // Markdown format (estimated)
+ * const usage2 = parseTokenUsage('Input tokens: 1234\nOutput tokens: 5678');
+ * // { inputTokens: 1234, outputTokens: 5678, confidence: 'estimated' }
+ *
+ * // Unparseable
+ * const usage3 = parseTokenUsage('No token data here');
+ * // null
+ * ```
+ */
+export function parseTokenUsage(output: string): TokenUsageWithConfidence | null {
+  // Try JSON format first (most reliable) - confidence: exact
+  try {
+    const jsonMatch = output.match(
+      /\{[^}]*"usage"\s*:\s*\{[^}]*"input_tokens"\s*:\s*(\d+)[^}]*"output_tokens"\s*:\s*(\d+)[^}]*\}[^}]*\}/,
+    );
+    if (jsonMatch) {
+      return {
+        inputTokens: Number.parseInt(jsonMatch[1], 10),
+        outputTokens: Number.parseInt(jsonMatch[2], 10),
+        confidence: "exact",
+      };
+    }
+
+    // Try parsing as full JSON object
+    const lines = output.split("\n");
+    for (const line of lines) {
+      if (line.trim().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(line);
+          if (parsed.usage?.input_tokens && parsed.usage?.output_tokens) {
+            return {
+              inputTokens: parsed.usage.input_tokens,
+              outputTokens: parsed.usage.output_tokens,
+              confidence: "exact",
+            };
+          }
+        } catch {
+          // Not valid JSON, continue
+        }
+      }
+    }
+  } catch {
+    // JSON parsing failed, try regex patterns
+  }
+
+  // Try specific markdown-style patterns (more specific to reduce false positives)
+  // Match "Input tokens: 1234" or "input_tokens: 1234" or "INPUT TOKENS: 1234"
+  // Use word boundary at start, require colon or space after keyword, then digits
+  // confidence: estimated (regex-based)
+  const inputMatch = output.match(/\b(?:input|input_tokens)\s*:\s*(\d{2,})|(?:input)\s+(?:tokens?)\s*:\s*(\d{2,})/i);
+  const outputMatch = output.match(
+    /\b(?:output|output_tokens)\s*:\s*(\d{2,})|(?:output)\s+(?:tokens?)\s*:\s*(\d{2,})/i,
+  );
+
+  if (inputMatch && outputMatch) {
+    // Extract token counts (may be in capture group 1 or 2)
+    const inputTokens = Number.parseInt(inputMatch[1] || inputMatch[2], 10);
+    const outputTokens = Number.parseInt(outputMatch[1] || outputMatch[2], 10);
+
+    // Sanity check: reject if tokens seem unreasonably large (> 1M each)
+    if (inputTokens > 1_000_000 || outputTokens > 1_000_000) {
+      return null;
+    }
+
+    return {
+      inputTokens,
+      outputTokens,
+      confidence: "estimated",
+    };
+  }
+
+  return null;
+}

package/src/agents/cost/pricing.ts

@@ -0,0 +1,59 @@
+/**
+ * Cost rate tables for all supported model tiers and specific models.
+ */
+
+import type { ModelTier } from "../../config/schema";
+import type { ModelCostRates } from "./types";
+
+/** Model tier cost rates (as of 2025-01) */
+export const COST_RATES: Record<ModelTier, ModelCostRates> = {
+  fast: {
+    // Haiku 4.5
+    inputPer1M: 0.8,
+    outputPer1M: 4.0,
+  },
+  balanced: {
+    // Sonnet 4.5
+    inputPer1M: 3.0,
+    outputPer1M: 15.0,
+  },
+  powerful: {
+    // Opus 4
+    inputPer1M: 15.0,
+    outputPer1M: 75.0,
+  },
+};
+
+/** Per-model pricing in $/1M tokens: { input, output } */
+export const MODEL_PRICING: Record<
+  string,
+  { input: number; output: number; cacheRead?: number; cacheCreation?: number }
+> = {
+  // Anthropic Claude models (short aliases)
+  sonnet: { input: 3, output: 15 },
+  haiku: { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  opus: { input: 15, output: 75 },
+
+  // Anthropic Claude models (full names)
+  "claude-sonnet-4": { input: 3, output: 15 },
+  "claude-sonnet-4-5": { input: 3, output: 15 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-haiku": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-haiku-4-5": { input: 0.8, output: 4.0, cacheRead: 0.1, cacheCreation: 1.0 },
+  "claude-opus": { input: 15, output: 75 },
+  "claude-opus-4": { input: 15, output: 75 },
+  "claude-opus-4-6": { input: 15, output: 75 },
+
+  // OpenAI models
+  "gpt-4.1": { input: 10, output: 30 },
+  "gpt-4": { input: 30, output: 60 },
+  "gpt-3.5-turbo": { input: 0.5, output: 1.5 },
+
+  // Google Gemini
+  "gemini-2.5-pro": { input: 0.075, output: 0.3 },
+  "gemini-2-pro": { input: 0.075, output: 0.3 },
+
+  // OpenAI Codex
+  codex: { input: 0.02, output: 0.06 },
+  "code-davinci-002": { input: 0.02, output: 0.06 },
+};

package/src/agents/cost/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Cost tracking types — shared across all agent adapters.
+ */
+
+import type { ModelTier } from "../../config/schema";
+
+export type { ModelTier };
+
+/** Cost rates per 1M tokens (USD) */
+export interface ModelCostRates {
+  inputPer1M: number;
+  outputPer1M: number;
+}
+
+/** Token usage data (camelCase — nax-internal representation) */
+export interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/** Cost estimate with confidence indicator */
+export interface CostEstimate {
+  cost: number;
+  confidence: "exact" | "estimated" | "fallback";
+}
+
+/** Token usage with confidence indicator */
+export interface TokenUsageWithConfidence {
+  inputTokens: number;
+  outputTokens: number;
+  confidence: "exact" | "estimated";
+}
+
+/**
+ * Token usage from an ACP session's cumulative_token_usage field.
+ * Uses snake_case to match the ACP wire format.
+ */
+export interface SessionTokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  /** Cache read tokens — billed at a reduced rate */
+  cache_read_input_tokens?: number;
+  /** Cache creation tokens — billed at a higher creation rate */
+  cache_creation_input_tokens?: number;
+}

package/src/agents/index.ts

@@ -2,15 +2,17 @@ export type { AgentAdapter, AgentCapabilities, AgentResult, AgentRunOptions, Com
 export { CompleteError } from "./types";
 export { ClaudeCodeAdapter } from "./claude";
 export { getAllAgentNames, getAgent, getInstalledAgents, checkAgentHealth } from "./registry";
-export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence } from "./claude/cost";
+export type { ModelCostRates, TokenUsage, CostEstimate, TokenUsageWithConfidence, SessionTokenUsage } from "./cost";
 export {
   COST_RATES,
+  MODEL_PRICING,
   parseTokenUsage,
   estimateCost,
   estimateCostFromOutput,
   estimateCostByDuration,
   formatCostWithConfidence,
-} from "./claude/cost";
+  estimateCostFromTokenUsage,
+} from "./cost";
 export { validateAgentForTier, validateAgentFeature, describeAgentCapabilities } from "./shared/validation";
 export type { AgentVersionInfo } from "./shared/version-detection";
 export { getAgentVersion, getAgentVersions } from "./shared/version-detection";

package/src/agents/types.ts

@@ -8,6 +8,7 @@
 
 import type { NaxConfig } from "../config";
 import type { ModelDef, ModelTier } from "../config/schema";
+import type { TokenUsage } from "./cost";
 
 // Re-export extended types for backward compatibility
 export type {
@@ -38,6 +39,8 @@ export interface AgentResult {
   durationMs: number;
   /** Estimated cost for this run (USD) */
   estimatedCost: number;
+  /** Token usage for this run (when available) */
+  tokenUsage?: TokenUsage;
   /** Process ID of the spawned agent (for cleanup on failure) */
   pid?: number;
 }

package/src/cli/init.ts

@@ -33,7 +33,21 @@ export interface InitProjectOptions {
 /**
  * Gitignore entries added by nax init
  */
-const NAX_GITIGNORE_ENTRIES = [".nax-verifier-verdict.json", "nax.lock", "nax/**/runs/", "nax/metrics.json"];
+const NAX_GITIGNORE_ENTRIES = [
+  ".nax-verifier-verdict.json",
+  "nax.lock",
+  "nax/**/runs/",
+  "nax/metrics.json",
+  "nax/features/*/status.json",
+  "nax/features/*/plan/",
+  "nax/features/*/acp-sessions.json",
+  "nax/features/*/interactions/",
+  "nax/features/*/progress.txt",
+  "nax/features/*/acceptance-refined.json",
+  ".nax-pids",
+  ".nax-wt/",
+  "~/",
+];
 
 /**
  * Add nax-specific entries to .gitignore if not already present.

package/src/pipeline/stages/acceptance-setup.ts

@@ -106,6 +106,7 @@ export const acceptanceSetupStage: PipelineStage = {
       const result = await _acceptanceSetupDeps.generate(ctx.prd.userStories, refinedCriteria, {
         featureName: ctx.prd.feature,
         workdir: ctx.workdir,
+        featureDir: ctx.featureDir,
         codebaseContext: "",
         modelTier: ctx.config.acceptance.model ?? "fast",
         modelDef: resolveModel(ctx.config.models[ctx.config.acceptance.model ?? "fast"]),

package/src/pipeline/stages/autofix.ts

@@ -3,7 +3,11 @@
  * Autofix Stage (ADR-005, Phase 2)
  *
  * Runs after a failed review stage. Attempts to fix quality issues
- * automatically (lint, format) before escalating.
+ * automatically before escalating:
+ *
+ * Phase 1 — Mechanical fix: runs lintFix / formatFix commands (if configured)
+ * Phase 2 — Agent rectification: spawns an agent session with the review error
+ *            output as context (reuses the pattern from rectification-loop.ts)
  *
  * Language-agnostic: uses quality.commands.lintFix / formatFix from config.
  * No hardcoded tool names.
@@ -12,10 +16,15 @@
  *
  * Returns:
  * - `retry` fromStage:"review" — autofix resolved the failures
- * - `escalate`                 — max attempts exhausted or no fix commands
+ * - `escalate`                 — max attempts exhausted or agent unavailable
  */
 
+import { getAgent } from "../../agents";
+import { resolveModel } from "../../config";
+import { resolvePermissions } from "../../config/permissions";
 import { getLogger } from "../../logger";
+import type { UserStory } from "../../prd";
+import type { ReviewCheckResult } from "../../review/types";
 import { pipelineEventBus } from "../event-bus";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
@@ -45,18 +54,8 @@ export const autofixStage: PipelineStage = {
     const lintFixCmd = ctx.config.quality.commands.lintFix;
     const formatFixCmd = ctx.config.quality.commands.formatFix;
 
-    if (!lintFixCmd && !formatFixCmd) {
-      logger.debug("autofix", "No fix commands configured — skipping autofix", { storyId: ctx.story.id });
-      return { action: "escalate", reason: "Review failed and no autofix commands configured" };
-    }
-
-    const maxAttempts = ctx.config.quality.autofix?.maxAttempts ?? 2;
-    let fixed = false;
-
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      logger.info("autofix", `Autofix attempt ${attempt}/${maxAttempts}`, { storyId: ctx.story.id });
-
-      // Step 1: lint fix
+    // Phase 1: Mechanical fix (if commands are configured)
+    if (lintFixCmd || formatFixCmd) {
       if (lintFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: lintFixCmd });
         const lintResult = await _autofixDeps.runCommand(lintFixCmd, ctx.workdir);
@@ -69,7 +68,6 @@ export const autofixStage: PipelineStage = {
         }
       }
 
-      // Step 2: format fix
       if (formatFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: formatFixCmd });
         const fmtResult = await _autofixDeps.runCommand(formatFixCmd, ctx.workdir);
@@ -82,22 +80,21 @@ export const autofixStage: PipelineStage = {
         }
       }
 
-      // Re-run review to check if fixed
       const recheckPassed = await _autofixDeps.recheckReview(ctx);
       pipelineEventBus.emit({ type: "autofix:completed", storyId: ctx.story.id, fixed: recheckPassed });
 
       if (recheckPassed) {
-        // Update ctx.reviewResult so downstream stages see the corrected state
-        if (ctx.reviewResult) {
-          ctx.reviewResult = { ...ctx.reviewResult, success: true };
-        }
-        fixed = true;
-        break;
+        if (ctx.reviewResult) ctx.reviewResult = { ...ctx.reviewResult, success: true };
+        logger.info("autofix", "Mechanical autofix succeeded — retrying review", { storyId: ctx.story.id });
+        return { action: "retry", fromStage: "review" };
       }
     }
 
-    if (fixed) {
-      logger.info("autofix", "Autofix succeeded — retrying review", { storyId: ctx.story.id });
+    // Phase 2: Agent rectification — spawn agent with review error context
+    const agentFixed = await _autofixDeps.runAgentRectification(ctx);
+    if (agentFixed) {
+      if (ctx.reviewResult) ctx.reviewResult = { ...ctx.reviewResult, success: true };
+      logger.info("autofix", "Agent rectification succeeded — retrying review", { storyId: ctx.story.id });
       return { action: "retry", fromStage: "review" };
     }
 
@@ -134,7 +131,97 @@ async function recheckReview(ctx: PipelineContext): Promise<boolean> {
   return result.action === "continue";
 }
 
+function collectFailedChecks(ctx: PipelineContext): ReviewCheckResult[] {
+  return (ctx.reviewResult?.checks ?? []).filter((c) => !c.success);
+}
+
+export function buildReviewRectificationPrompt(failedChecks: ReviewCheckResult[], story: UserStory): string {
+  const errors = failedChecks
+    .map((c) => `## ${c.check} errors (exit code ${c.exitCode})\n\`\`\`\n${c.output}\n\`\`\``)
+    .join("\n\n");
+
+  return `You are fixing lint/typecheck errors from a code review.
+
+Story: ${story.title} (${story.id})
+
+The following quality checks failed after implementation:
+
+${errors}
+
+Fix ALL errors listed above. Do NOT change test files or test behavior.
+Do NOT add new features — only fix the quality check errors.
+Commit your fixes when done.`;
+}
+
+async function runAgentRectification(ctx: PipelineContext): Promise<boolean> {
+  const logger = getLogger();
+  const maxAttempts = ctx.config.quality.autofix?.maxAttempts ?? 2;
+  const failedChecks = collectFailedChecks(ctx);
+
+  if (failedChecks.length === 0) {
+    logger.debug("autofix", "No failed checks found — skipping agent rectification", { storyId: ctx.story.id });
+    return false;
+  }
+
+  logger.info("autofix", "Starting agent rectification for review failures", {
+    storyId: ctx.story.id,
+    failedChecks: failedChecks.map((c) => c.check),
+    maxAttempts,
+  });
+
+  const agentGetFn = ctx.agentGetFn ?? getAgent;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    logger.info("autofix", `Agent rectification attempt ${attempt}/${maxAttempts}`, { storyId: ctx.story.id });
+
+    const agent = agentGetFn(ctx.config.autoMode.defaultAgent);
+    if (!agent) {
+      logger.error("autofix", "Agent not found — cannot run agent rectification", { storyId: ctx.story.id });
+      return false;
+    }
+
+    const prompt = buildReviewRectificationPrompt(failedChecks, ctx.story);
+    const modelTier = ctx.story.routing?.modelTier ?? ctx.config.autoMode.escalation.tierOrder[0]?.tier ?? "balanced";
+    const modelDef = resolveModel(ctx.config.models[modelTier]);
+
+    await agent.run({
+      prompt,
+      workdir: ctx.workdir,
+      modelTier,
+      modelDef,
+      timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
+      dangerouslySkipPermissions: resolvePermissions(ctx.config, "rectification").skipPermissions,
+      pipelineStage: "rectification",
+      config: ctx.config,
+      maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
+      storyId: ctx.story.id,
+      sessionRole: "implementer",
+    });
+
+    const passed = await _autofixDeps.recheckReview(ctx);
+    if (passed) {
+      logger.info("autofix", `[OK] Agent rectification succeeded on attempt ${attempt}`, {
+        storyId: ctx.story.id,
+      });
+      return true;
+    }
+
+    // Refresh failed checks for next attempt
+    const updatedFailed = collectFailedChecks(ctx);
+    if (updatedFailed.length > 0) {
+      failedChecks.splice(0, failedChecks.length, ...updatedFailed);
+    }
+
+    logger.warn("autofix", `Agent rectification still failing after attempt ${attempt}`, {
+      storyId: ctx.story.id,
+    });
+  }
+
+  logger.warn("autofix", "Agent rectification exhausted", { storyId: ctx.story.id });
+  return false;
+}
+
 /**
  * Injectable deps for testing.
  */
-export const _autofixDeps = { runCommand, recheckReview };
+export const _autofixDeps = { runCommand, recheckReview, runAgentRectification };

package/src/precheck/checks-git.ts

@@ -32,6 +32,25 @@ export async function checkGitRepoExists(workdir: string): Promise<Check> {
   };
 }
 
+/**
+ * nax runtime files that are allowed to be dirty without blocking the precheck.
+ * These are written during nax execution and should be gitignored by `nax init`.
+ */
+const NAX_RUNTIME_PATTERNS = [
+  /^.{2} nax\.lock$/,
+  /^.{2} nax\/metrics\.json$/,
+  /^.{2} nax\/features\/[^/]+\/status\.json$/,
+  /^.{2} nax\/features\/[^/]+\/runs\//,
+  /^.{2} nax\/features\/[^/]+\/plan\//,
+  /^.{2} nax\/features\/[^/]+\/acp-sessions\.json$/,
+  /^.{2} nax\/features\/[^/]+\/interactions\//,
+  /^.{2} nax\/features\/[^/]+\/progress\.txt$/,
+  /^.{2} nax\/features\/[^/]+\/acceptance-refined\.json$/,
+  /^.{2} \.nax-verifier-verdict\.json$/,
+  /^.{2} \.nax-pids$/,
+  /^.{2} \.nax-wt\//,
+];
+
 /** Check if working tree is clean. Uses: git status --porcelain */
 export async function checkWorkingTreeClean(workdir: string): Promise<Check> {
   const proc = Bun.spawn(["git", "status", "--porcelain"], {
@@ -42,13 +61,20 @@ export async function checkWorkingTreeClean(workdir: string): Promise<Check> {
 
   const output = await new Response(proc.stdout).text();
   const exitCode = await proc.exited;
-  const passed = exitCode === 0 && output.trim() === "";
+
+  // Split without trimming the full output — porcelain lines start with status chars
+  // including leading spaces (e.g. " M file.ts"). trim() would corrupt the first line.
+  const lines = output.trim() === "" ? [] : output.split("\n").filter(Boolean);
+  const nonNaxDirtyFiles = lines.filter((line) => !NAX_RUNTIME_PATTERNS.some((pattern) => pattern.test(line)));
+  const passed = exitCode === 0 && nonNaxDirtyFiles.length === 0;
 
   return {
     name: "working-tree-clean",
     tier: "blocker",
     passed,
-    message: passed ? "Working tree is clean" : "Uncommitted changes detected",
+    message: passed
+      ? "Working tree is clean"
+      : `Uncommitted changes detected: ${nonNaxDirtyFiles.map((l) => l.slice(3)).join(", ")}`,
   };
 }
 

package/src/precheck/checks-warnings.ts

@@ -6,6 +6,7 @@
  */
 
 import { existsSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import type { NaxConfig } from "../config";
 import type { PRD } from "../prd/types";
 import type { Check } from "./types";
@@ -126,7 +127,7 @@ async function hasPackageScript(workdir: string, name: string): Promise<boolean>
 
 /**
  * Check if .gitignore covers nax runtime files.
- * Patterns: nax.lock, runs/, test/tmp/
+ * Patterns: nax.lock, runs/, status.json, .nax-pids, .nax-wt/
  */
 export async function checkGitignoreCoversNax(workdir: string): Promise<Check> {
   const gitignorePath = `${workdir}/.gitignore`;
@@ -143,7 +144,14 @@ export async function checkGitignoreCoversNax(workdir: string): Promise<Check> {
 
   const file = Bun.file(gitignorePath);
   const content = await file.text();
-  const patterns = ["nax.lock", "runs/", "test/tmp/"];
+  const patterns = [
+    "nax.lock",
+    "nax/**/runs/",
+    "nax/metrics.json",
+    "nax/features/*/status.json",
+    ".nax-pids",
+    ".nax-wt/",
+  ];
   const missing = patterns.filter((pattern) => !content.includes(pattern));
   const passed = missing.length === 0;
 
@@ -191,3 +199,23 @@ export async function checkPromptOverrideFiles(config: NaxConfig, workdir: strin
 
   return checks;
 }
+
+/**
+ * Check if HOME env is set and is an absolute path.
+ * An unexpanded "~" in HOME causes agent spawns to create a literal ~/
+ * directory inside the repo cwd instead of resolving to the user home dir.
+ */
+export async function checkHomeEnvValid(): Promise<Check> {
+  const home = process.env.HOME ?? "";
+  const passed = home !== "" && isAbsolute(home);
+  return {
+    name: "home-env-valid",
+    tier: "warning",
+    passed,
+    message: passed
+      ? `HOME env is valid: ${home}`
+      : home === ""
+        ? "HOME env is not set — agent may write files to unexpected locations"
+        : `HOME env is not an absolute path ("${home}") — may cause literal "~" directories in repo`,
+  };
+}

package/src/precheck/checks.ts

@@ -28,6 +28,7 @@ export {
   checkPendingStories,
   checkOptionalCommands,
   checkGitignoreCoversNax,
+  checkHomeEnvValid,
   checkPromptOverrideFiles,
 } from "./checks-warnings";
 

package/src/precheck/index.ts

@@ -20,6 +20,7 @@ import {
   checkGitRepoExists,
   checkGitUserConfigured,
   checkGitignoreCoversNax,
+  checkHomeEnvValid,
   checkLintCommand,
   checkMultiAgentHealth,
   checkOptionalCommands,
@@ -126,6 +127,7 @@ function getEnvironmentWarnings(config: NaxConfig, workdir: string): CheckFn[] {
     () => checkDiskSpace(),
     () => checkOptionalCommands(config, workdir),
     () => checkGitignoreCoversNax(workdir),
+    () => checkHomeEnvValid(),
     () => checkPromptOverrideFiles(config, workdir),
     () => checkMultiAgentHealth(),
   ];