@nathapp/nax 0.43.0 → 0.44.0

package/bin/nax.ts

@@ -69,7 +69,7 @@ import { unlockCommand } from "../src/commands/unlock";
 import { DEFAULT_CONFIG, findProjectDir, loadConfig, validateDirectory } from "../src/config";
 import { run } from "../src/execution";
 import { loadHooksConfig } from "../src/hooks";
-import { type LogLevel, initLogger } from "../src/logger";
+import { type LogLevel, initLogger, resetLogger } from "../src/logger";
 import { countStories, loadPRD } from "../src/prd";
 import { PipelineEventEmitter, type StoryDisplayState, renderTui } from "../src/tui";
 import { NAX_VERSION } from "../src/version";
@@ -278,6 +278,7 @@ program
   .option("--plan", "Run plan phase first before execution", false)
   .option("--from <spec-path>", "Path to spec file (required when --plan is used)")
   .option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false)
+  .option("--force", "Force overwrite existing prd.json when using --plan", false)
   .option("--headless", "Force headless mode (disable TUI, use pipe mode)", false)
   .option("--verbose", "Enable verbose logging (debug level)", false)
   .option("--quiet", "Quiet mode (warnings and errors only)", false)
@@ -343,7 +344,35 @@ program
 
     // Run plan phase if --plan flag is set (AC-4: runs plan then execute)
     if (options.plan && options.from) {
+      // Guard: block overwrite of existing prd.json unless --force
+      if (existsSync(prdPath) && !options.force) {
+        console.error(chalk.red(`Error: prd.json already exists for feature "${options.feature}".`));
+        console.error(chalk.dim("   Use --force to overwrite, or run without --plan to use the existing PRD."));
+        process.exit(1);
+      }
+
+      // Run environment precheck before plan — catch blockers early (before expensive LLM calls)
+      if (!options.skipPrecheck) {
+        const { runEnvironmentPrecheck } = await import("../src/precheck");
+        console.log(chalk.dim("\n   [Pre-plan environment check]"));
+        const envResult = await runEnvironmentPrecheck(config, workdir);
+        if (!envResult.passed) {
+          console.error(chalk.red("\n❌ Environment precheck failed — cannot proceed with planning."));
+          for (const b of envResult.blockers) {
+            console.error(chalk.red(`   ${b.name}: ${b.message}`));
+          }
+          process.exit(1);
+        }
+      }
+
       try {
+        // Initialize plan logger before calling planCommand — writes to features/<feature>/plan-<ts>.jsonl
+        mkdirSync(featureDir, { recursive: true });
+        const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
+        const planLogPath = join(featureDir, `plan-${planLogId}.jsonl`);
+        initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
+        console.log(chalk.dim(`   [Plan log: ${planLogPath}]`));
+
         console.log(chalk.dim("   [Planning phase: generating PRD from spec]"));
         const generatedPrdPath = await planCommand(workdir, config, {
           from: options.from,
@@ -391,6 +420,9 @@ program
       process.exit(1);
     }
 
+    // Reset plan logger (if plan phase ran) so the run logger can be initialized fresh
+    resetLogger();
+
     // Create run directory and JSONL log file path
     const runsDir = join(featureDir, "runs");
     mkdirSync(runsDir, { recursive: true });

package/dist/nax.js

@@ -19233,6 +19233,20 @@ var init_cost2 = __esm(() => {
 });
 
 // src/agents/acp/adapter.ts
+var exports_adapter = {};
+__export(exports_adapter, {
+  sweepStaleFeatureSessions: () => sweepStaleFeatureSessions,
+  sweepFeatureSessions: () => sweepFeatureSessions,
+  saveAcpSession: () => saveAcpSession,
+  runSessionPrompt: () => runSessionPrompt,
+  readAcpSession: () => readAcpSession,
+  ensureAcpSession: () => ensureAcpSession,
+  closeAcpSession: () => closeAcpSession,
+  clearAcpSession: () => clearAcpSession,
+  buildSessionName: () => buildSessionName,
+  _acpAdapterDeps: () => _acpAdapterDeps,
+  AcpAgentAdapter: () => AcpAgentAdapter
+});
 import { createHash } from "crypto";
 import { join as join3 } from "path";
 function resolveRegistryEntry(agentName) {
@@ -19336,6 +19350,59 @@ async function readAcpSession(workdir, featureName, storyId) {
     return null;
   }
 }
+async function sweepFeatureSessions(workdir, featureName) {
+  const path = acpSessionsPath(workdir, featureName);
+  let sessions;
+  try {
+    const text = await Bun.file(path).text();
+    sessions = JSON.parse(text);
+  } catch {
+    return;
+  }
+  const entries = Object.entries(sessions);
+  if (entries.length === 0)
+    return;
+  const logger = getSafeLogger();
+  logger?.info("acp-adapter", `[sweep] Closing ${entries.length} open sessions for feature: ${featureName}`);
+  const cmdStr = "acpx claude";
+  const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+  try {
+    await client.start();
+    for (const [, sessionName] of entries) {
+      try {
+        if (client.loadSession) {
+          const session = await client.loadSession(sessionName, "claude", "approve-reads");
+          if (session) {
+            await session.close().catch(() => {});
+          }
+        }
+      } catch (err) {
+        logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
+      }
+    }
+  } finally {
+    await client.close().catch(() => {});
+  }
+  try {
+    await Bun.write(path, JSON.stringify({}, null, 2));
+  } catch (err) {
+    logger?.warn("acp-adapter", "[sweep] Failed to clear sidecar after sweep", { error: String(err) });
+  }
+}
+async function sweepStaleFeatureSessions(workdir, featureName, maxAgeMs = MAX_SESSION_AGE_MS) {
+  const path = acpSessionsPath(workdir, featureName);
+  const file2 = Bun.file(path);
+  if (!await file2.exists())
+    return;
+  const ageMs = Date.now() - file2.lastModified;
+  if (ageMs < maxAgeMs)
+    return;
+  getSafeLogger()?.info("acp-adapter", `[sweep] Sidecar is ${Math.round(ageMs / 60000)}m old \u2014 sweeping stale sessions`, {
+    featureName,
+    ageMs
+  });
+  await sweepFeatureSessions(workdir, featureName);
+}
 function extractOutput(response) {
   if (!response)
     return "";
@@ -19459,6 +19526,7 @@ class AcpAgentAdapter {
     }
     let lastResponse = null;
     let timedOut = false;
+    const runState = { succeeded: false };
     const totalTokenUsage = { input_tokens: 0, output_tokens: 0 };
     try {
       let currentPrompt = options.prompt;
@@ -19499,12 +19567,17 @@ class AcpAgentAdapter {
       if (turnCount >= MAX_TURNS && options.interactionBridge) {
         getSafeLogger()?.warn("acp-adapter", "Reached max turns limit", { sessionName, maxTurns: MAX_TURNS });
       }
+      runState.succeeded = !timedOut && lastResponse?.stopReason === "end_turn";
     } finally {
-      await closeAcpSession(session);
-      await client.close().catch(() => {});
-      if (options.featureName && options.storyId) {
-        await clearAcpSession(options.workdir, options.featureName, options.storyId);
+      if (runState.succeeded) {
+        await closeAcpSession(session);
+        if (options.featureName && options.storyId) {
+          await clearAcpSession(options.workdir, options.featureName, options.storyId);
+        }
+      } else {
+        getSafeLogger()?.info("acp-adapter", "Keeping session open for retry", { sessionName });
       }
+      await client.close().catch(() => {});
     }
     const durationMs = Date.now() - startTime;
     if (timedOut) {
@@ -19654,7 +19727,7 @@ class AcpAgentAdapter {
     return { stories };
   }
 }
-var MAX_AGENT_OUTPUT_CHARS2 = 5000, MAX_RATE_LIMIT_RETRIES = 3, INTERACTION_TIMEOUT_MS, AGENT_REGISTRY, DEFAULT_ENTRY, _acpAdapterDeps;
+var MAX_AGENT_OUTPUT_CHARS2 = 5000, MAX_RATE_LIMIT_RETRIES = 3, INTERACTION_TIMEOUT_MS, AGENT_REGISTRY, DEFAULT_ENTRY, _acpAdapterDeps, MAX_SESSION_AGE_MS;
 var init_adapter = __esm(() => {
   init_logger2();
   init_spawn_client();
@@ -19698,6 +19771,7 @@ var init_adapter = __esm(() => {
       return createSpawnAcpClient(cmdStr, cwd, timeoutSeconds, pidRegistry);
     }
   };
+  MAX_SESSION_AGE_MS = 2 * 60 * 60 * 1000;
 });
 
 // src/agents/adapters/aider.ts
@@ -21968,7 +22042,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.43.0",
+    version: "0.44.0",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22041,8 +22115,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("d725ea0"))
-        return "d725ea0";
+      if (/^[0-9a-f]{6,10}$/.test("05b2442"))
+        return "05b2442";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -28235,7 +28309,7 @@ var init_test_output_parser = () => {};
 
 // src/verification/rectification-loop.ts
 async function runRectificationLoop2(opts) {
-  const { config: config2, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix } = opts;
+  const { config: config2, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix, featureName } = opts;
   const logger = getSafeLogger();
   const rectificationConfig = config2.execution.rectification;
   const testSummary = parseBunTestOutput(testOutput);
@@ -28261,7 +28335,7 @@ async function runRectificationLoop2(opts) {
       rectificationPrompt = `${promptPrefix}
 
 ${rectificationPrompt}`;
-    const agent = getAgent(config2.autoMode.defaultAgent);
+    const agent = _rectificationDeps.getAgent(config2.autoMode.defaultAgent);
     if (!agent) {
       logger?.error("rectification", "Agent not found, cannot retry");
       break;
@@ -28277,7 +28351,10 @@ ${rectificationPrompt}`;
       dangerouslySkipPermissions: resolvePermissions(config2, "rectification").skipPermissions,
       pipelineStage: "rectification",
       config: config2,
-      maxInteractionTurns: config2.agent?.maxInteractionTurns
+      maxInteractionTurns: config2.agent?.maxInteractionTurns,
+      featureName,
+      storyId: story.id,
+      sessionRole: "implementer"
     });
     if (agentResult.success) {
       logger?.info("rectification", `Agent ${label} session complete`, {
@@ -28292,7 +28369,7 @@ ${rectificationPrompt}`;
         exitCode: agentResult.exitCode
       });
     }
-    const retryVerification = await fullSuite({
+    const retryVerification = await _rectificationDeps.runVerification({
       workdir,
       expectedFiles: getExpectedFiles(story),
       command: testCommand,
@@ -28342,6 +28419,7 @@ ${rectificationPrompt}`;
   }
   return false;
 }
+var _rectificationDeps;
 var init_rectification_loop = __esm(() => {
   init_agents();
   init_config();
@@ -28350,6 +28428,10 @@ var init_rectification_loop = __esm(() => {
   init_prd();
   init_rectification();
   init_runners();
+  _rectificationDeps = {
+    getAgent,
+    runVerification: fullSuite
+  };
 });
 
 // src/pipeline/stages/rectify.ts
@@ -30451,8 +30533,85 @@ async function checkStorySizeGate(config2, prd) {
 var exports_precheck = {};
 __export(exports_precheck, {
   runPrecheck: () => runPrecheck,
+  runEnvironmentPrecheck: () => runEnvironmentPrecheck,
   EXIT_CODES: () => EXIT_CODES
 });
+function getEarlyEnvironmentBlockers(workdir) {
+  return [() => checkGitRepoExists(workdir), () => checkWorkingTreeClean(workdir), () => checkStaleLock(workdir)];
+}
+function getLateEnvironmentBlockers(config2, workdir) {
+  return [
+    () => checkAgentCLI(config2),
+    () => checkDependenciesInstalled(workdir),
+    () => checkTestCommand(config2),
+    () => checkLintCommand(config2),
+    () => checkTypecheckCommand(config2),
+    () => checkGitUserConfigured(workdir)
+  ];
+}
+function getEnvironmentBlockers(config2, workdir) {
+  return [...getEarlyEnvironmentBlockers(workdir), ...getLateEnvironmentBlockers(config2, workdir)];
+}
+function getEnvironmentWarnings(config2, workdir) {
+  return [
+    () => checkClaudeMdExists(workdir),
+    () => checkDiskSpace(),
+    () => checkOptionalCommands(config2, workdir),
+    () => checkGitignoreCoversNax(workdir),
+    () => checkPromptOverrideFiles(config2, workdir),
+    () => checkMultiAgentHealth()
+  ];
+}
+function getProjectBlockers(prd) {
+  return [() => checkPRDValid(prd)];
+}
+function getProjectWarnings(prd) {
+  return [() => checkPendingStories(prd)];
+}
+function normalizeChecks(result) {
+  return Array.isArray(result) ? result : [result];
+}
+async function runEnvironmentPrecheck(config2, workdir, options) {
+  const format = options?.format ?? "human";
+  const silent = options?.silent ?? false;
+  const passed = [];
+  const blockers = [];
+  const warnings = [];
+  for (const checkFn of getEnvironmentBlockers(config2, workdir)) {
+    const checks3 = normalizeChecks(await checkFn());
+    let blocked = false;
+    for (const check2 of checks3) {
+      if (!silent && format === "human")
+        printCheckResult(check2);
+      if (check2.passed) {
+        passed.push(check2);
+      } else {
+        blockers.push(check2);
+        blocked = true;
+        break;
+      }
+    }
+    if (blocked)
+      break;
+  }
+  if (blockers.length === 0) {
+    for (const checkFn of getEnvironmentWarnings(config2, workdir)) {
+      for (const check2 of normalizeChecks(await checkFn())) {
+        if (!silent && format === "human")
+          printCheckResult(check2);
+        if (check2.passed) {
+          passed.push(check2);
+        } else {
+          warnings.push(check2);
+        }
+      }
+    }
+  }
+  if (!silent && format === "json") {
+    console.log(JSON.stringify({ passed: blockers.length === 0, blockers, warnings }, null, 2));
+  }
+  return { passed: blockers.length === 0, blockers, warnings };
+}
 async function runPrecheck(config2, prd, options) {
   const workdir = options?.workdir || process.cwd();
   const format = options?.format || "human";
@@ -30461,47 +30620,33 @@ async function runPrecheck(config2, prd, options) {
   const blockers = [];
   const warnings = [];
   const tier1Checks = [
-    () => checkGitRepoExists(workdir),
-    () => checkWorkingTreeClean(workdir),
-    () => checkStaleLock(workdir),
-    () => checkPRDValid(prd),
-    () => checkAgentCLI(config2),
-    () => checkDependenciesInstalled(workdir),
-    () => checkTestCommand(config2),
-    () => checkLintCommand(config2),
-    () => checkTypecheckCommand(config2),
-    () => checkGitUserConfigured(workdir)
+    ...getEarlyEnvironmentBlockers(workdir),
+    ...getProjectBlockers(prd),
+    ...getLateEnvironmentBlockers(config2, workdir)
   ];
+  let tier1Blocked = false;
   for (const checkFn of tier1Checks) {
-    const result = await checkFn();
-    if (format === "human") {
-      printCheckResult(result);
+    for (const check2 of normalizeChecks(await checkFn())) {
+      if (format === "human")
+        printCheckResult(check2);
+      if (check2.passed) {
+        passed.push(check2);
+      } else {
+        blockers.push(check2);
+        tier1Blocked = true;
+        break;
+      }
     }
-    if (result.passed) {
-      passed.push(result);
-    } else {
-      blockers.push(result);
+    if (tier1Blocked)
       break;
-    }
   }
   let flaggedStories = [];
   if (blockers.length === 0) {
-    const tier2Checks = [
-      () => checkClaudeMdExists(workdir),
-      () => checkDiskSpace(),
-      () => checkPendingStories(prd),
-      () => checkOptionalCommands(config2, workdir),
-      () => checkGitignoreCoversNax(workdir),
-      () => checkPromptOverrideFiles(config2, workdir),
-      () => checkMultiAgentHealth()
-    ];
+    const tier2Checks = [...getEnvironmentWarnings(config2, workdir), ...getProjectWarnings(prd)];
     for (const checkFn of tier2Checks) {
-      const result = await checkFn();
-      const checksToProcess = Array.isArray(result) ? result : [result];
-      for (const check2 of checksToProcess) {
-        if (format === "human") {
+      for (const check2 of normalizeChecks(await checkFn())) {
+        if (format === "human")
           printCheckResult(check2);
-        }
         if (check2.passed) {
           passed.push(check2);
         } else {
@@ -34258,6 +34403,8 @@ async function setupRun(options) {
   } else {
     logger?.warn("precheck", "Precheck validations skipped (--skip-precheck)");
   }
+  const { sweepStaleFeatureSessions: sweepStaleFeatureSessions2 } = await Promise.resolve().then(() => (init_adapter(), exports_adapter));
+  await sweepStaleFeatureSessions2(workdir, feature).catch(() => {});
   const lockAcquired = await acquireLock(workdir);
   if (!lockAcquired) {
     logger?.error("execution", "Another nax process is already running in this directory");
@@ -66342,6 +66489,15 @@ async function loadProjectStatusFile(projectDir) {
 }
 async function getFeatureSummary(featureName, featureDir) {
   const prdPath = join13(featureDir, "prd.json");
+  if (!existsSync11(prdPath)) {
+    return {
+      name: featureName,
+      done: 0,
+      failed: 0,
+      pending: 0,
+      total: 0
+    };
+  }
   const prd = await loadPRD(prdPath);
   const counts = countStories(prd);
   const summary = {
@@ -66454,6 +66610,13 @@ async function displayAllFeatures(projectDir) {
 }
 async function displayFeatureDetails(featureName, featureDir) {
   const prdPath = join13(featureDir, "prd.json");
+  if (!existsSync11(prdPath)) {
+    console.log(source_default.bold(`
+\uD83D\uDCCA ${featureName}
+`));
+    console.log(source_default.dim(`No prd.json found. Run: nax plan -f ${featureName} --from <spec>`));
+    return;
+  }
   const prd = await loadPRD(prdPath);
   const counts = countStories(prd);
   const status = await loadStatusFile(featureDir);
@@ -68888,6 +69051,7 @@ async function unlockCommand(options) {
 init_config();
 
 // src/execution/runner.ts
+init_adapter();
 init_registry();
 init_hooks();
 init_logger2();
@@ -69301,6 +69465,7 @@ async function run(options) {
   } finally {
     stopHeartbeat();
     cleanupCrashHandlers();
+    await sweepFeatureSessions(workdir, feature).catch(() => {});
     const { cleanupRun: cleanupRun2 } = await Promise.resolve().then(() => (init_run_cleanup(), exports_run_cleanup));
     await cleanupRun2({
       runId,
@@ -76762,7 +76927,7 @@ Run \`nax generate\` to regenerate agent config files (CLAUDE.md, AGENTS.md, .cu
   console.log(source_default.dim(`
 Next: nax features create <name>`));
 });
-program2.command("run").description("Run the orchestration loop for a feature").requiredOption("-f, --feature <name>", "Feature name").option("-a, --agent <name>", "Force a specific agent").option("-m, --max-iterations <n>", "Max iterations", "20").option("--dry-run", "Show plan without executing", false).option("--no-context", "Disable context builder (skip file context in prompts)").option("--no-batch", "Disable story batching (execute all stories individually)").option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)").option("--plan", "Run plan phase first before execution", false).option("--from <spec-path>", "Path to spec file (required when --plan is used)").option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false).option("--headless", "Force headless mode (disable TUI, use pipe mode)", false).option("--verbose", "Enable verbose logging (debug level)", false).option("--quiet", "Quiet mode (warnings and errors only)", false).option("--silent", "Silent mode (errors only)", false).option("--json", "JSON mode (raw JSONL output to stdout)", false).option("-d, --dir <path>", "Working directory", process.cwd()).option("--skip-precheck", "Skip precheck validations (advanced users only)", false).action(async (options) => {
+program2.command("run").description("Run the orchestration loop for a feature").requiredOption("-f, --feature <name>", "Feature name").option("-a, --agent <name>", "Force a specific agent").option("-m, --max-iterations <n>", "Max iterations", "20").option("--dry-run", "Show plan without executing", false).option("--no-context", "Disable context builder (skip file context in prompts)").option("--no-batch", "Disable story batching (execute all stories individually)").option("--parallel <n>", "Max parallel sessions (0=auto, omit=sequential)").option("--plan", "Run plan phase first before execution", false).option("--from <spec-path>", "Path to spec file (required when --plan is used)").option("--one-shot", "Skip interactive planning Q&A, use single LLM call (ACP only)", false).option("--force", "Force overwrite existing prd.json when using --plan", false).option("--headless", "Force headless mode (disable TUI, use pipe mode)", false).option("--verbose", "Enable verbose logging (debug level)", false).option("--quiet", "Quiet mode (warnings and errors only)", false).option("--silent", "Silent mode (errors only)", false).option("--json", "JSON mode (raw JSONL output to stdout)", false).option("-d, --dir <path>", "Working directory", process.cwd()).option("--skip-precheck", "Skip precheck validations (advanced users only)", false).action(async (options) => {
   let workdir;
   try {
     workdir = validateDirectory(options.dir);
@@ -76806,7 +76971,31 @@ program2.command("run").description("Run the orchestration loop for a feature").
   const featureDir = join43(naxDir, "features", options.feature);
   const prdPath = join43(featureDir, "prd.json");
   if (options.plan && options.from) {
+    if (existsSync32(prdPath) && !options.force) {
+      console.error(source_default.red(`Error: prd.json already exists for feature "${options.feature}".`));
+      console.error(source_default.dim("   Use --force to overwrite, or run without --plan to use the existing PRD."));
+      process.exit(1);
+    }
+    if (!options.skipPrecheck) {
+      const { runEnvironmentPrecheck: runEnvironmentPrecheck2 } = await Promise.resolve().then(() => (init_precheck(), exports_precheck));
+      console.log(source_default.dim(`
+   [Pre-plan environment check]`));
+      const envResult = await runEnvironmentPrecheck2(config2, workdir);
+      if (!envResult.passed) {
+        console.error(source_default.red(`
+\u274C Environment precheck failed \u2014 cannot proceed with planning.`));
+        for (const b of envResult.blockers) {
+          console.error(source_default.red(`   ${b.name}: ${b.message}`));
+        }
+        process.exit(1);
+      }
+    }
     try {
+      mkdirSync6(featureDir, { recursive: true });
+      const planLogId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");
+      const planLogPath = join43(featureDir, `plan-${planLogId}.jsonl`);
+      initLogger({ level: "info", filePath: planLogPath, useChalk: false, headless: true });
+      console.log(source_default.dim(`   [Plan log: ${planLogPath}]`));
       console.log(source_default.dim("   [Planning phase: generating PRD from spec]"));
       const generatedPrdPath = await planCommand(workdir, config2, {
         from: options.from,
@@ -76841,6 +77030,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
     console.error(source_default.red(`Feature "${options.feature}" not found or missing prd.json`));
     process.exit(1);
   }
+  resetLogger();
   const runsDir = join43(featureDir, "runs");
   mkdirSync6(runsDir, { recursive: true });
   const runId = new Date().toISOString().replace(/:/g, "-").replace(/\..+/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {

package/src/agents/acp/adapter.ts

@@ -307,6 +307,88 @@ export async function readAcpSession(workdir: string, featureName: string, story
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Session sweep — close open sessions at run boundaries
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MAX_SESSION_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+/**
+ * Close all open sessions tracked in the sidecar file for a feature.
+ * Called at run-end to ensure no sessions leak past the run boundary.
+ */
+export async function sweepFeatureSessions(workdir: string, featureName: string): Promise<void> {
+  const path = acpSessionsPath(workdir, featureName);
+  let sessions: Record<string, string>;
+  try {
+    const text = await Bun.file(path).text();
+    sessions = JSON.parse(text) as Record<string, string>;
+  } catch {
+    return; // No sidecar — nothing to sweep
+  }
+
+  const entries = Object.entries(sessions);
+  if (entries.length === 0) return;
+
+  const logger = getSafeLogger();
+  logger?.info("acp-adapter", `[sweep] Closing ${entries.length} open sessions for feature: ${featureName}`);
+
+  const cmdStr = "acpx claude";
+  const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+  try {
+    await client.start();
+    for (const [, sessionName] of entries) {
+      try {
+        if (client.loadSession) {
+          const session = await client.loadSession(sessionName, "claude", "approve-reads");
+          if (session) {
+            await session.close().catch(() => {});
+          }
+        }
+      } catch (err) {
+        logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
+      }
+    }
+  } finally {
+    await client.close().catch(() => {});
+  }
+
+  // Clear sidecar after sweep
+  try {
+    await Bun.write(path, JSON.stringify({}, null, 2));
+  } catch (err) {
+    logger?.warn("acp-adapter", "[sweep] Failed to clear sidecar after sweep", { error: String(err) });
+  }
+}
+
+/**
+ * Sweep stale sessions if the sidecar file is older than maxAgeMs.
+ * Called at startup as a safety net for sessions orphaned by crashes.
+ */
+export async function sweepStaleFeatureSessions(
+  workdir: string,
+  featureName: string,
+  maxAgeMs = MAX_SESSION_AGE_MS,
+): Promise<void> {
+  const path = acpSessionsPath(workdir, featureName);
+  const file = Bun.file(path);
+  if (!(await file.exists())) return;
+
+  const ageMs = Date.now() - file.lastModified;
+  if (ageMs < maxAgeMs) return; // Recent sidecar — skip
+
+  getSafeLogger()?.info(
+    "acp-adapter",
+    `[sweep] Sidecar is ${Math.round(ageMs / 60000)}m old — sweeping stale sessions`,
+    {
+      featureName,
+      ageMs,
+    },
+  );
+
+  await sweepFeatureSessions(workdir, featureName);
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Output helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -470,6 +552,9 @@ export class AcpAgentAdapter implements AgentAdapter {
 
     let lastResponse: AcpSessionResponse | null = null;
     let timedOut = false;
+    // Tracks whether the run completed successfully — used by finally to decide
+    // whether to close the session (success) or keep it open for retry (failure).
+    const runState = { succeeded: false };
     const totalTokenUsage = { input_tokens: 0, output_tokens: 0 };
 
     try {
@@ -525,13 +610,21 @@ export class AcpAgentAdapter implements AgentAdapter {
       if (turnCount >= MAX_TURNS && options.interactionBridge) {
         getSafeLogger()?.warn("acp-adapter", "Reached max turns limit", { sessionName, maxTurns: MAX_TURNS });
       }
+
+      // Compute success here so finally can use it for conditional close.
+      runState.succeeded = !timedOut && lastResponse?.stopReason === "end_turn";
     } finally {
-      // 6. Cleanup — always close session and client, then clear sidecar
-      await closeAcpSession(session);
-      await client.close().catch(() => {});
-      if (options.featureName && options.storyId) {
-        await clearAcpSession(options.workdir, options.featureName, options.storyId);
+      // 6. Cleanup — close session and clear sidecar only on success.
+      // On failure, keep session open so retry can resume with full context.
+      if (runState.succeeded) {
+        await closeAcpSession(session);
+        if (options.featureName && options.storyId) {
+          await clearAcpSession(options.workdir, options.featureName, options.storyId);
+        }
+      } else {
+        getSafeLogger()?.info("acp-adapter", "Keeping session open for retry", { sessionName });
       }
+      await client.close().catch(() => {});
     }
 
     const durationMs = Date.now() - startTime;

package/src/cli/status-features.ts

@@ -85,6 +85,17 @@ async function loadProjectStatusFile(projectDir: string): Promise<NaxStatusFile
 async function getFeatureSummary(featureName: string, featureDir: string): Promise<FeatureSummary> {
   const prdPath = join(featureDir, "prd.json");
 
+  // Guard: prd.json may not exist (e.g. plan failed before writing it)
+  if (!existsSync(prdPath)) {
+    return {
+      name: featureName,
+      done: 0,
+      failed: 0,
+      pending: 0,
+      total: 0,
+    };
+  }
+
   // Load PRD for story counts
   const prd = await loadPRD(prdPath);
   const counts = countStories(prd);
@@ -240,6 +251,14 @@ async function displayAllFeatures(projectDir: string): Promise<void> {
 /** Display single feature details */
 async function displayFeatureDetails(featureName: string, featureDir: string): Promise<void> {
   const prdPath = join(featureDir, "prd.json");
+
+  // Guard: prd.json may not exist (e.g. plan failed or feature just created)
+  if (!existsSync(prdPath)) {
+    console.log(chalk.bold(`\n📊 ${featureName}\n`));
+    console.log(chalk.dim(`No prd.json found. Run: nax plan -f ${featureName} --from <spec>`));
+    return;
+  }
+
   const prd = await loadPRD(prdPath);
   const counts = countStories(prd);
 

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

@@ -159,6 +159,10 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     logger?.warn("precheck", "Precheck validations skipped (--skip-precheck)");
   }
 
+  // Sweep stale ACP sessions from previous crashed runs (safety net)
+  const { sweepStaleFeatureSessions } = await import("../../agents/acp/adapter");
+  await sweepStaleFeatureSessions(workdir, feature).catch(() => {});
+
   // Acquire lock to prevent concurrent execution
   const lockAcquired = await acquireLock(workdir);
   if (!lockAcquired) {

package/src/execution/runner.ts

@@ -13,6 +13,7 @@
  * - runner-completion.ts: Acceptance loop, hooks, metrics
  */
 
+import { sweepFeatureSessions } from "../agents/acp/adapter";
 import { createAgentRegistry } from "../agents/registry";
 import type { NaxConfig } from "../config";
 import type { LoadedHooksConfig } from "../hooks";
@@ -241,6 +242,9 @@ export async function run(options: RunOptions): Promise<RunResult> {
     // Cleanup crash handlers (MEM-1 fix)
     cleanupCrashHandlers();
 
+    // Sweep any remaining open ACP sessions for this feature
+    await sweepFeatureSessions(workdir, feature).catch(() => {});
+
     // Execute cleanup operations
     const { cleanupRun } = await import("./lifecycle/run-cleanup");
     await cleanupRun({

package/src/precheck/index.ts

@@ -4,6 +4,10 @@
  * Runs all prechecks with formatted output. Stops on first Tier 1 blocker (fail-fast).
  * Collects all Tier 2 warnings. Formats human-readable output with emoji indicators.
  * Supports --json flag for machine-readable output.
+ *
+ * Check categories:
+ * - **Environment checks** — no PRD needed (git, deps, agent CLI, stale lock)
+ * - **Project checks** — require PRD (validation, story counts, story size gate)
  */
 
 import type { NaxConfig } from "../config";
@@ -80,8 +84,136 @@ export interface PrecheckResultWithCode {
   flaggedStories?: import("./story-size-gate").FlaggedStory[];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Check list definitions — shared between runEnvironmentPrecheck and runPrecheck
+// ─────────────────────────────────────────────────────────────────────────────
+
+type CheckFn = () => Promise<Check | Check[]>;
+
+/**
+ * Early environment checks — git repo, clean tree, stale lock.
+ * Fast checks that run first in both runEnvironmentPrecheck and runPrecheck.
+ * In runPrecheck, PRD validation is inserted after these (original order preserved).
+ */
+function getEarlyEnvironmentBlockers(workdir: string): CheckFn[] {
+  return [() => checkGitRepoExists(workdir), () => checkWorkingTreeClean(workdir), () => checkStaleLock(workdir)];
+}
+
+/**
+ * Late environment checks — agent CLI, deps, commands, git user.
+ * Run after PRD validation in runPrecheck; all included in runEnvironmentPrecheck.
+ */
+function getLateEnvironmentBlockers(config: NaxConfig, workdir: string): CheckFn[] {
+  return [
+    () => checkAgentCLI(config),
+    () => checkDependenciesInstalled(workdir),
+    () => checkTestCommand(config),
+    () => checkLintCommand(config),
+    () => checkTypecheckCommand(config),
+    () => checkGitUserConfigured(workdir),
+  ];
+}
+
+/** All environment checks — no PRD needed. Used by runEnvironmentPrecheck. */
+function getEnvironmentBlockers(config: NaxConfig, workdir: string): CheckFn[] {
+  return [...getEarlyEnvironmentBlockers(workdir), ...getLateEnvironmentBlockers(config, workdir)];
+}
+
+/** Environment warnings — no PRD needed. */
+function getEnvironmentWarnings(config: NaxConfig, workdir: string): CheckFn[] {
+  return [
+    () => checkClaudeMdExists(workdir),
+    () => checkDiskSpace(),
+    () => checkOptionalCommands(config, workdir),
+    () => checkGitignoreCoversNax(workdir),
+    () => checkPromptOverrideFiles(config, workdir),
+    () => checkMultiAgentHealth(),
+  ];
+}
+
+/** Project checks — require PRD. */
+function getProjectBlockers(prd: PRD): CheckFn[] {
+  return [() => checkPRDValid(prd)];
+}
+
+/** Project warnings — require PRD. */
+function getProjectWarnings(prd: PRD): CheckFn[] {
+  return [() => checkPendingStories(prd)];
+}
+
+/** Normalize check result to array (some checks return Check[]) */
+function normalizeChecks(result: Check | Check[]): Check[] {
+  return Array.isArray(result) ? result : [result];
+}
+
+/** Result from environment-only precheck */
+export interface EnvironmentPrecheckResult {
+  /** Whether all environment checks passed (no blockers) */
+  passed: boolean;
+  /** Blocker check results */
+  blockers: Check[];
+  /** Warning check results */
+  warnings: Check[];
+}
+
+/**
+ * Run environment-only prechecks (no PRD needed).
+ *
+ * Use before plan phase to catch environment issues early,
+ * before expensive LLM calls are made.
+ */
+export async function runEnvironmentPrecheck(
+  config: NaxConfig,
+  workdir: string,
+  options?: { format?: "human" | "json"; silent?: boolean },
+): Promise<EnvironmentPrecheckResult> {
+  const format = options?.format ?? "human";
+  const silent = options?.silent ?? false;
+
+  const passed: Check[] = [];
+  const blockers: Check[] = [];
+  const warnings: Check[] = [];
+
+  // Environment blockers — fail-fast
+  for (const checkFn of getEnvironmentBlockers(config, workdir)) {
+    const checks = normalizeChecks(await checkFn());
+    let blocked = false;
+    for (const check of checks) {
+      if (!silent && format === "human") printCheckResult(check);
+      if (check.passed) {
+        passed.push(check);
+      } else {
+        blockers.push(check);
+        blocked = true;
+        break;
+      }
+    }
+    if (blocked) break;
+  }
+
+  // Environment warnings — only if no blockers
+  if (blockers.length === 0) {
+    for (const checkFn of getEnvironmentWarnings(config, workdir)) {
+      for (const check of normalizeChecks(await checkFn())) {
+        if (!silent && format === "human") printCheckResult(check);
+        if (check.passed) {
+          passed.push(check);
+        } else {
+          warnings.push(check);
+        }
+      }
+    }
+  }
+
+  if (!silent && format === "json") {
+    console.log(JSON.stringify({ passed: blockers.length === 0, blockers, warnings }, null, 2));
+  }
+
+  return { passed: blockers.length === 0, blockers, warnings };
+}
+
 /**
- * Run all precheck validations.
+ * Run all precheck validations (environment + project).
  * Returns result, exit code, and formatted output.
  */
 export async function runPrecheck(
@@ -98,67 +230,46 @@ export async function runPrecheck(
   const warnings: Check[] = [];
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // Tier 1 Blockers - fail-fast on first failure
+  // Tier 1 Blockers — environment + project, fail-fast on first failure
   // ─────────────────────────────────────────────────────────────────────────────
 
+  // Original order preserved: early env → PRD valid → late env
+  // checkPRDValid at position 4 ensures test environments that lack agent CLI
+  // still get EXIT_CODES.INVALID_PRD (2) rather than a generic blocker (1)
   const tier1Checks = [
-    () => checkGitRepoExists(workdir),
-    () => checkWorkingTreeClean(workdir),
-    () => checkStaleLock(workdir),
-    () => checkPRDValid(prd),
-    () => checkAgentCLI(config),
-    () => checkDependenciesInstalled(workdir),
-    () => checkTestCommand(config),
-    () => checkLintCommand(config),
-    () => checkTypecheckCommand(config),
-    () => checkGitUserConfigured(workdir),
+    ...getEarlyEnvironmentBlockers(workdir),
+    ...getProjectBlockers(prd),
+    ...getLateEnvironmentBlockers(config, workdir),
   ];
 
+  let tier1Blocked = false;
   for (const checkFn of tier1Checks) {
-    const result = await checkFn();
-
-    if (format === "human") {
-      printCheckResult(result);
-    }
-
-    if (result.passed) {
-      passed.push(result);
-    } else {
-      blockers.push(result);
-      // Fail-fast: stop on first blocker
-      break;
+    for (const check of normalizeChecks(await checkFn())) {
+      if (format === "human") printCheckResult(check);
+      if (check.passed) {
+        passed.push(check);
+      } else {
+        blockers.push(check);
+        tier1Blocked = true;
+        break;
+      }
     }
+    if (tier1Blocked) break;
   }
 
   // ─────────────────────────────────────────────────────────────────────────────
-  // Tier 2 Warnings - run all regardless of failures
+  // Tier 2 Warnings — environment + project, run all regardless of failures
   // ─────────────────────────────────────────────────────────────────────────────
 
   let flaggedStories: import("./story-size-gate").FlaggedStory[] = [];
 
   // Only run Tier 2 if no blockers
   if (blockers.length === 0) {
-    const tier2Checks = [
-      () => checkClaudeMdExists(workdir),
-      () => checkDiskSpace(),
-      () => checkPendingStories(prd),
-      () => checkOptionalCommands(config, workdir),
-      () => checkGitignoreCoversNax(workdir),
-      () => checkPromptOverrideFiles(config, workdir),
-      () => checkMultiAgentHealth(),
-    ];
+    const tier2Checks = [...getEnvironmentWarnings(config, workdir), ...getProjectWarnings(prd)];
 
     for (const checkFn of tier2Checks) {
-      const result = await checkFn();
-
-      // Handle both single checks and arrays of checks
-      const checksToProcess = Array.isArray(result) ? result : [result];
-
-      for (const check of checksToProcess) {
-        if (format === "human") {
-          printCheckResult(check);
-        }
-
+      for (const check of normalizeChecks(await checkFn())) {
+        if (format === "human") printCheckResult(check);
         if (check.passed) {
           passed.push(check);
         } else {

package/src/verification/rectification-loop.ts

@@ -7,7 +7,7 @@
  * Used by: src/pipeline/stages/rectify.ts, src/execution/lifecycle/run-regression.ts
  */
 
-import { getAgent } from "../agents";
+import { getAgent as _getAgent } from "../agents";
 import type { NaxConfig } from "../config";
 import { resolveModel } from "../config";
 import { resolvePermissions } from "../config/permissions";
@@ -16,7 +16,7 @@ import { getSafeLogger } from "../logger";
 import type { UserStory } from "../prd";
 import { getExpectedFiles } from "../prd";
 import { type RectificationState, createRectificationPrompt, shouldRetryRectification } from "./rectification";
-import { fullSuite as runVerification } from "./runners";
+import { fullSuite as _fullSuite } from "./runners";
 
 export interface RectificationLoopOptions {
   config: NaxConfig;
@@ -26,11 +26,21 @@ export interface RectificationLoopOptions {
   timeoutSeconds: number;
   testOutput: string;
   promptPrefix?: string;
+  featureName?: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Injectable dependencies
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const _rectificationDeps = {
+  getAgent: _getAgent as (name: string) => import("../agents/types").AgentAdapter | undefined,
+  runVerification: _fullSuite as typeof _fullSuite,
+};
+
 /** Run the rectification retry loop. Returns true if all failures were fixed. */
 export async function runRectificationLoop(opts: RectificationLoopOptions): Promise<boolean> {
-  const { config, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix } = opts;
+  const { config, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix, featureName } = opts;
   const logger = getSafeLogger();
   const rectificationConfig = config.execution.rectification;
   const testSummary = parseBunTestOutput(testOutput);
@@ -59,7 +69,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
     let rectificationPrompt = createRectificationPrompt(testSummary.failures, story, rectificationConfig);
     if (promptPrefix) rectificationPrompt = `${promptPrefix}\n\n${rectificationPrompt}`;
 
-    const agent = getAgent(config.autoMode.defaultAgent);
+    const agent = _rectificationDeps.getAgent(config.autoMode.defaultAgent);
     if (!agent) {
       logger?.error("rectification", "Agent not found, cannot retry");
       break;
@@ -78,6 +88,9 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       pipelineStage: "rectification",
       config,
       maxInteractionTurns: config.agent?.maxInteractionTurns,
+      featureName,
+      storyId: story.id,
+      sessionRole: "implementer",
     });
 
     if (agentResult.success) {
@@ -94,7 +107,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       });
     }
 
-    const retryVerification = await runVerification({
+    const retryVerification = await _rectificationDeps.runVerification({
       workdir,
       expectedFiles: getExpectedFiles(story),
       command: testCommand,