@nathapp/nax 0.42.0 → 0.42.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 William Khoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/nax.ts

@@ -277,6 +277,7 @@ program
   .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)
@@ -329,8 +330,8 @@ program
       formatterMode = "quiet";
     }
 
-    const config = await loadConfig();
     const naxDir = findProjectDir(workdir);
+    const config = await loadConfig(naxDir ?? undefined);
 
     if (!naxDir) {
       console.error(chalk.red("nax not initialized. Run: nax init"));
@@ -347,7 +348,7 @@ program
         const generatedPrdPath = await planCommand(workdir, config, {
           from: options.from,
           feature: options.feature,
-          auto: true, // AC-1: --auto mode for one-shot planning
+          auto: options.oneShot ?? false, // interactive by default; --one-shot skips Q&A
           branch: undefined,
         });
 
@@ -625,7 +626,8 @@ program
   .description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')")
   .requiredOption("--from <spec-path>", "Path to spec file (required)")
   .requiredOption("-f, --feature <name>", "Feature name (required)")
-  .option("--auto", "Run in auto (one-shot LLM) mode", false)
+  .option("--auto", "Run in one-shot LLM mode (alias: --one-shot)", false)
+  .option("--one-shot", "Run in one-shot LLM mode (alias: --auto)", false)
   .option("-b, --branch <branch>", "Override default branch name")
   .option("-d, --dir <path>", "Project directory", process.cwd())
   .action(async (description, options) => {
@@ -658,7 +660,7 @@ program
       const prdPath = await planCommand(workdir, config, {
         from: options.from,
         feature: options.feature,
-        auto: options.auto,
+        auto: options.auto || options.oneShot, // --auto and --one-shot are aliases
         branch: options.branch,
       });
 

package/dist/nax.js

@@ -17804,7 +17804,7 @@ var init_schemas3 = __esm(() => {
   });
   AgentConfigSchema = exports_external.object({
     protocol: exports_external.enum(["acp", "cli"]).default("acp"),
-    acpPermissionMode: exports_external.string().optional()
+    maxInteractionTurns: exports_external.number().int().min(1).max(100).default(10)
   });
   PrecheckConfigSchema = exports_external.object({
     storySizeGate: StorySizeGateConfigSchema
@@ -17928,7 +17928,6 @@ var init_defaults = __esm(() => {
       detectOpenHandles: true,
       detectOpenHandlesRetries: 1,
       gracePeriodMs: 5000,
-      dangerouslySkipPermissions: true,
       drainTimeoutMs: 2000,
       shell: "/bin/sh",
       stripEnvVars: [
@@ -19057,7 +19056,7 @@ class SpawnAcpClient {
   async start() {}
   async createSession(opts) {
     const sessionName = opts.sessionName || `nax-${Date.now()}`;
-    const cmd = ["acpx", opts.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, opts.agentName, "sessions", "ensure", "--name", sessionName];
     getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
@@ -19076,7 +19075,7 @@ class SpawnAcpClient {
     });
   }
   async loadSession(sessionName) {
-    const cmd = ["acpx", this.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, this.agentName, "sessions", "ensure", "--name", sessionName];
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
@@ -19360,7 +19359,7 @@ class AcpAgentAdapter {
       sessionName = await readAcpSession(options.workdir, options.featureName, options.storyId) ?? undefined;
     }
     sessionName ??= buildSessionName(options.workdir, options.featureName, options.storyId, options.sessionRole);
-    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "default";
+    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "approve-reads";
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
     if (options.featureName && options.storyId) {
       await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName);
@@ -19371,7 +19370,7 @@ class AcpAgentAdapter {
     try {
       let currentPrompt = options.prompt;
       let turnCount = 0;
-      const MAX_TURNS = options.interactionBridge ? 10 : 1;
+      const MAX_TURNS = options.interactionBridge ? options.maxInteractionTurns ?? 10 : 1;
       while (turnCount < MAX_TURNS) {
         turnCount++;
         getSafeLogger()?.debug("acp-adapter", `Session turn ${turnCount}/${MAX_TURNS}`, { sessionName });
@@ -19439,32 +19438,74 @@ class AcpAgentAdapter {
   }
   async complete(prompt, _options) {
     const model = _options?.model ?? "default";
-    const cmdStr = `acpx --model ${model} ${this.name}`;
-    const client = _acpAdapterDeps.createClient(cmdStr);
-    await client.start();
+    const timeoutMs = _options?.timeoutMs ?? 120000;
     const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
-    let session = null;
-    try {
-      session = await client.createSession({ agentName: this.name, permissionMode });
-      const response = await session.prompt(prompt);
-      if (response.stopReason === "error") {
-        throw new CompleteError("complete() failed: stop reason is error");
-      }
-      const text = response.messages.filter((m) => m.role === "assistant").map((m) => m.content).join(`
+    let lastError;
+    for (let attempt = 0;attempt < MAX_RATE_LIMIT_RETRIES; attempt++) {
+      const cmdStr = `acpx --model ${model} ${this.name}`;
+      const client = _acpAdapterDeps.createClient(cmdStr);
+      await client.start();
+      let session = null;
+      try {
+        session = await client.createSession({ agentName: this.name, permissionMode });
+        let timeoutId;
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`complete() timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        timeoutPromise.catch(() => {});
+        const promptPromise = session.prompt(prompt);
+        let response;
+        try {
+          response = await Promise.race([promptPromise, timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutId);
+        }
+        if (response.stopReason === "error") {
+          throw new CompleteError("complete() failed: stop reason is error");
+        }
+        const text = response.messages.filter((m) => m.role === "assistant").map((m) => m.content).join(`
 `).trim();
-      if (!text) {
-        throw new CompleteError("complete() returned empty output");
-      }
-      return text;
-    } finally {
-      if (session) {
-        await session.close().catch(() => {});
+        let unwrapped = text;
+        try {
+          const envelope = JSON.parse(text);
+          if (envelope?.type === "result" && typeof envelope?.result === "string") {
+            unwrapped = envelope.result;
+          }
+        } catch {}
+        if (!unwrapped) {
+          throw new CompleteError("complete() returned empty output");
+        }
+        return unwrapped;
+      } catch (err) {
+        const error48 = err instanceof Error ? err : new Error(String(err));
+        lastError = error48;
+        const shouldRetry = isRateLimitError(error48) && attempt < MAX_RATE_LIMIT_RETRIES - 1;
+        if (!shouldRetry)
+          throw error48;
+        const backoffMs = 2 ** (attempt + 1) * 1000;
+        getSafeLogger()?.warn("acp-adapter", "complete() rate limited, retrying", {
+          backoffSeconds: backoffMs / 1000,
+          attempt: attempt + 1
+        });
+        await _acpAdapterDeps.sleep(backoffMs);
+      } finally {
+        if (session) {
+          await session.close().catch(() => {});
+        }
+        await client.close().catch(() => {});
       }
-      await client.close().catch(() => {});
     }
+    throw lastError ?? new CompleteError("complete() failed with unknown error");
   }
   async plan(options) {
-    const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
+    let modelDef = options.modelDef;
+    if (!modelDef && options.config?.models) {
+      const { resolveBalancedModelDef: resolveBalancedModelDef2 } = await Promise.resolve().then(() => (init_model_resolution(), exports_model_resolution));
+      try {
+        modelDef = resolveBalancedModelDef2(options.config);
+      } catch {}
+    }
+    modelDef ??= { provider: "anthropic", model: "claude-sonnet-4-5-20250514" };
     const timeoutSeconds = options.timeoutSeconds ?? options.config?.execution?.sessionTimeoutSeconds ?? 600;
     const result = await this.run({
       prompt: options.prompt,
@@ -19474,6 +19515,7 @@ class AcpAgentAdapter {
       timeoutSeconds,
       dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
       interactionBridge: options.interactionBridge,
+      maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
       storyId: options.storyId,
       sessionRole: options.sessionRole
@@ -21807,7 +21849,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.42.0",
+    version: "0.42.2",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -21861,7 +21903,15 @@ var init_package = __esm(() => {
       "bin/",
       "README.md",
       "CHANGELOG.md"
-    ]
+    ],
+    repository: {
+      type: "git",
+      url: "https://github.com/nathapp-io/nax.git"
+    },
+    homepage: "https://github.com/nathapp-io/nax",
+    bugs: {
+      url: "https://github.com/nathapp-io/nax/issues"
+    }
   };
 });
 
@@ -21872,8 +21922,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("a59af3a"))
-        return "a59af3a";
+      if (/^[0-9a-f]{6,10}$/.test("9c1f716"))
+        return "9c1f716";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -23550,11 +23600,23 @@ ${stderr}`;
         logger.info("acceptance", "All acceptance tests passed");
         return { action: "continue" };
       }
-      if (actualFailures.length === 0 && exitCode !== 0) {
-        logger.warn("acceptance", "Tests failed but no specific AC failures detected", {
+      if (failedACs.length > 0 && actualFailures.length === 0) {
+        logger.info("acceptance", "All failed ACs are overridden \u2014 treating as pass");
+        return { action: "continue" };
+      }
+      if (failedACs.length === 0 && exitCode !== 0) {
+        logger.error("acceptance", "Tests errored with no AC failures parsed", {
+          exitCode,
           output
         });
-        return { action: "continue" };
+        ctx.acceptanceFailures = {
+          failedACs: ["AC-ERROR"],
+          testOutput: output
+        };
+        return {
+          action: "fail",
+          reason: `Acceptance tests errored (exit code ${exitCode}): syntax error, import failure, or unhandled exception`
+        };
       }
       if (actualFailures.length > 0) {
         const overriddenFailures = failedACs.filter((acId) => overrides[acId]);
@@ -26182,6 +26244,7 @@ async function runRectificationLoop(story, config2, workdir, agent, implementerT
       modelDef: resolveModel(config2.models[implementerTier]),
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config2.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
       sessionRole: "implementer"
@@ -26789,6 +26852,7 @@ async function runTddSession(role, agent, story, config2, workdir, modelTier, be
     modelDef: resolveModel(config2.models[modelTier]),
     timeoutSeconds: config2.execution.sessionTimeoutSeconds,
     dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+    maxInteractionTurns: config2.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
     sessionRole: role
@@ -27538,6 +27602,7 @@ Category: ${tddResult.failureCategory ?? "unknown"}`,
         modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
         timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
         dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+        maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
         pidRegistry: ctx.pidRegistry,
         featureName: ctx.prd.feature,
         storyId: ctx.story.id,
@@ -28086,7 +28151,8 @@ ${rectificationPrompt}`;
       modelTier,
       modelDef,
       timeoutSeconds: config2.execution.sessionTimeoutSeconds,
-      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions
+      dangerouslySkipPermissions: config2.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config2.agent?.maxInteractionTurns
     });
     if (agentResult.success) {
       logger?.info("rectification", `Agent ${label} session complete`, {
@@ -28588,6 +28654,9 @@ function buildScopedCommand(testFiles, baseCommand, testScopedTemplate) {
   }
   return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
 }
+function isMonorepoOrchestratorCommand(command) {
+  return /\bturbo\b/.test(command) || /\bnx\b/.test(command);
+}
 
 class ScopedStrategy {
   name = "scoped";
@@ -28595,9 +28664,10 @@ class ScopedStrategy {
     const logger = getLogger();
     const smartCfg = coerceSmartRunner(ctx.smartRunnerConfig);
     const regressionMode = ctx.regressionMode ?? "deferred";
+    const isMonorepoOrchestrator = isMonorepoOrchestratorCommand(ctx.testCommand);
     let effectiveCommand = ctx.testCommand;
     let isFullSuite = true;
-    if (smartCfg.enabled && ctx.storyGitRef) {
+    if (smartCfg.enabled && ctx.storyGitRef && !isMonorepoOrchestrator) {
       const sourceFiles = await _scopedDeps.getChangedSourceFiles(ctx.workdir, ctx.storyGitRef);
       const pass1Files = await _scopedDeps.mapSourceToTests(sourceFiles, ctx.workdir);
       if (pass1Files.length > 0) {
@@ -28617,14 +28687,19 @@ class ScopedStrategy {
         }
       }
     }
-    if (isFullSuite && regressionMode === "deferred") {
+    if (isFullSuite && regressionMode === "deferred" && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests \u2014 deferring to run-end (mode: deferred)", {
         storyId: ctx.storyId
       });
       return makeSkippedResult(ctx.storyId, "scoped");
     }
-    if (isFullSuite) {
+    if (isFullSuite && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests \u2014 falling back to full suite", { storyId: ctx.storyId });
+    } else if (isMonorepoOrchestrator) {
+      logger.info("verify[scoped]", "Monorepo orchestrator detected \u2014 delegating scoping to tool", {
+        storyId: ctx.storyId,
+        command: effectiveCommand
+      });
     }
     const start = Date.now();
     const result = await _scopedDeps.regression({
@@ -65505,6 +65580,7 @@ async function generateAcceptanceTestsForFeature(specContent, featureName, featu
 init_registry();
 import { existsSync as existsSync9 } from "fs";
 import { join as join10 } from "path";
+import { createInterface } from "readline";
 init_logger2();
 
 // src/prd/schema.ts
@@ -65584,7 +65660,9 @@ function validateStory(raw, index, allIds) {
     throw new Error(`[schema] story[${index}].routing.complexity "${rawComplexity}" is invalid. Valid values: ${VALID_COMPLEXITY.join(", ")}`);
   }
   const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
-  const testStrategy = rawTestStrategy !== undefined && VALID_TEST_STRATEGIES.includes(rawTestStrategy) ? rawTestStrategy : "tdd-simple";
+  const STRATEGY_ALIASES = { "tdd-lite": "three-session-tdd-lite" };
+  const normalizedStrategy = typeof rawTestStrategy === "string" ? STRATEGY_ALIASES[rawTestStrategy] ?? rawTestStrategy : rawTestStrategy;
+  const testStrategy = normalizedStrategy !== undefined && VALID_TEST_STRATEGIES.includes(normalizedStrategy) ? normalizedStrategy : "tdd-simple";
   const rawDeps = s.dependencies;
   const dependencies = Array.isArray(rawDeps) ? rawDeps : [];
   for (const dep of dependencies) {
@@ -65659,7 +65737,7 @@ var _deps2 = {
   readFile: (path) => Bun.file(path).text(),
   writeFile: (path, content) => Bun.write(path, content).then(() => {}),
   scanCodebase: (workdir) => scanCodebase(workdir),
-  getAgent: (name) => getAgent(name),
+  getAgent: (name, cfg) => cfg ? createAgentRegistry(cfg).getAgent(name) : getAgent(name),
   readPackageJson: (workdir) => Bun.file(join10(workdir, "package.json")).json().catch(() => null),
   spawnSync: (cmd, opts) => {
     const result = Bun.spawnSync(cmd, opts ? { cwd: opts.cwd } : {});
@@ -65683,15 +65761,23 @@ async function planCommand(workdir, config2, options) {
   const branchName = options.branch ?? `feat/${options.feature}`;
   const prompt = buildPlanningPrompt(specContent, codebaseContext);
   const agentName = config2?.autoMode?.defaultAgent ?? "claude";
-  const adapter = _deps2.getAgent(agentName);
-  if (!adapter) {
-    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-  }
   const timeoutSeconds = config2?.execution?.sessionTimeoutSeconds ?? 600;
   let rawResponse;
   if (options.auto) {
-    rawResponse = await adapter.complete(prompt, { jsonMode: true });
+    const cliAdapter = _deps2.getAgent(agentName);
+    if (!cliAdapter)
+      throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true });
+    try {
+      const envelope = JSON.parse(rawResponse);
+      if (envelope?.type === "result" && typeof envelope?.result === "string") {
+        rawResponse = envelope.result;
+      }
+    } catch {}
   } else {
+    const adapter = _deps2.getAgent(agentName, config2);
+    if (!adapter)
+      throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
     try {
@@ -65700,7 +65786,11 @@ async function planCommand(workdir, config2, options) {
         workdir,
         interactive: true,
         timeoutSeconds,
-        interactionBridge
+        interactionBridge,
+        config: config2,
+        modelTier: "balanced",
+        dangerouslySkipPermissions: config2?.execution?.dangerouslySkipPermissions ?? false,
+        maxInteractionTurns: config2?.agent?.maxInteractionTurns
       });
       rawResponse = result.specContent;
     } finally {
@@ -65722,7 +65812,20 @@ function createCliInteractionBridge() {
       return text.includes("?");
     },
     async onQuestionDetected(text) {
-      return text;
+      if (!process.stdin.isTTY) {
+        return "";
+      }
+      process.stdout.write(`
+\uD83E\uDD16 Agent: ${text}
+You: `);
+      return new Promise((resolve6) => {
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        rl.once("line", (line) => {
+          rl.close();
+          resolve6(line.trim());
+        });
+        rl.once("close", () => resolve6(""));
+      });
     }
   };
 }
@@ -65798,7 +65901,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-lite | three-session-tdd",
+        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
         "reasoning": "string \u2014 brief classification rationale"
       },
       "escalations": [],
@@ -65810,15 +65913,16 @@ Generate a JSON object with this exact structure (no markdown, no explanation \u
 ## Complexity Classification Guide
 
 - simple: \u226450 LOC, single-file change, purely additive, no new dependencies \u2192 test-after
-- medium: 50\u2013200 LOC, 2\u20135 files, standard patterns, clear requirements \u2192 tdd-lite
+- medium: 50\u2013200 LOC, 2\u20135 files, standard patterns, clear requirements \u2192 tdd-simple
 - complex: 200\u2013500 LOC, multiple modules, new abstractions or integrations \u2192 three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk \u2192 three-session-tdd
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk \u2192 three-session-tdd-lite
 
 ## Test Strategy Guide
 
 - test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-lite: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex/expert. Full TDD cycle with separate sessions for tests and implementation.
+- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
+- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
 Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
 }
@@ -67791,7 +67895,10 @@ var FIELD_DESCRIPTIONS = {
   "decompose.maxSubstories": "Max number of substories to generate (default: 5)",
   "decompose.maxSubstoryComplexity": "Max complexity for any generated substory (default: 'medium')",
   "decompose.maxRetries": "Max retries on decomposition validation failure (default: 2)",
-  "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')"
+  "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')",
+  agent: "Agent protocol configuration (ACP-003)",
+  "agent.protocol": "Protocol for agent communication: 'acp' | 'cli' (default: 'acp')",
+  "agent.maxInteractionTurns": "Max turns in multi-turn interaction loop when interactionBridge is active (default: 10)"
 };
 
 // src/cli/config-diff.ts
@@ -76508,7 +76615,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("--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("--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);
@@ -76543,8 +76650,8 @@ program2.command("run").description("Run the orchestration loop for a feature").
   } else if (options.quiet || options.silent) {
     formatterMode = "quiet";
   }
-  const config2 = await loadConfig();
   const naxDir = findProjectDir(workdir);
+  const config2 = await loadConfig(naxDir ?? undefined);
   if (!naxDir) {
     console.error(source_default.red("nax not initialized. Run: nax init"));
     process.exit(1);
@@ -76557,7 +76664,7 @@ program2.command("run").description("Run the orchestration loop for a feature").
       const generatedPrdPath = await planCommand(workdir, config2, {
         from: options.from,
         feature: options.feature,
-        auto: true,
+        auto: options.oneShot ?? false,
         branch: undefined
       });
       const generatedPrd = await loadPRD(generatedPrdPath);
@@ -76774,7 +76881,7 @@ Features:
   }
   console.log();
 });
-program2.command("plan [description]").description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')").requiredOption("--from <spec-path>", "Path to spec file (required)").requiredOption("-f, --feature <name>", "Feature name (required)").option("--auto", "Run in auto (one-shot LLM) mode", false).option("-b, --branch <branch>", "Override default branch name").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (description, options) => {
+program2.command("plan [description]").description("Generate prd.json from a spec file via LLM one-shot call (replaces deprecated 'nax analyze')").requiredOption("--from <spec-path>", "Path to spec file (required)").requiredOption("-f, --feature <name>", "Feature name (required)").option("--auto", "Run in one-shot LLM mode (alias: --one-shot)", false).option("--one-shot", "Run in one-shot LLM mode (alias: --auto)", false).option("-b, --branch <branch>", "Override default branch name").option("-d, --dir <path>", "Project directory", process.cwd()).action(async (description, options) => {
   if (description) {
     console.error(source_default.red(`Error: Positional args removed in plan v2.
 
@@ -76798,7 +76905,7 @@ Use: nax plan -f <feature> --from <spec>`));
     const prdPath = await planCommand(workdir, config2, {
       from: options.from,
       feature: options.feature,
-      auto: options.auto,
+      auto: options.auto || options.oneShot,
       branch: options.branch
     });
     console.log(source_default.green(`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.42.0",
-  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "version": "0.42.2",
+  "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
     "nax": "./dist/nax.js"
@@ -54,5 +54,13 @@
     "bin/",
     "README.md",
     "CHANGELOG.md"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nathapp-io/nax.git"
+  },
+  "homepage": "https://github.com/nathapp-io/nax",
+  "bugs": {
+    "url": "https://github.com/nathapp-io/nax/issues"
+  }
 }

package/src/agents/acp/adapter.ts

@@ -442,8 +442,8 @@ export class AcpAgentAdapter implements AgentAdapter {
     }
     sessionName ??= buildSessionName(options.workdir, options.featureName, options.storyId, options.sessionRole);
 
-    // 2. Permission mode follows dangerouslySkipPermissions
-    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "default";
+    // 2. Permission mode follows dangerouslySkipPermissions, default is "approve-reads". or should --deny-all be the default?
+    const permissionMode = options.dangerouslySkipPermissions ? "approve-all" : "approve-reads";
 
     // 3. Ensure session (resume existing or create new)
     const session = await ensureAcpSession(client, sessionName, this.name, permissionMode);
@@ -461,7 +461,7 @@ export class AcpAgentAdapter implements AgentAdapter {
       // 5. Multi-turn loop
       let currentPrompt = options.prompt;
       let turnCount = 0;
-      const MAX_TURNS = options.interactionBridge ? 10 : 1;
+      const MAX_TURNS = options.interactionBridge ? (options.maxInteractionTurns ?? 10) : 1;
 
       while (turnCount < MAX_TURNS) {
         turnCount++;
@@ -552,43 +552,101 @@ export class AcpAgentAdapter implements AgentAdapter {
 
   async complete(prompt: string, _options?: CompleteOptions): Promise<string> {
     const model = _options?.model ?? "default";
-    const cmdStr = `acpx --model ${model} ${this.name}`;
-    const client = _acpAdapterDeps.createClient(cmdStr);
-    await client.start();
-
-    // complete() is one-shot — ephemeral session, no session name, no sidecar
+    const timeoutMs = _options?.timeoutMs ?? 120_000; // 2-min safety net by default
     const permissionMode = _options?.dangerouslySkipPermissions ? "approve-all" : "default";
 
-    let session: AcpSession | null = null;
-    try {
-      session = await client.createSession({ agentName: this.name, permissionMode });
-      const response = await session.prompt(prompt);
+    let lastError: Error | undefined;
 
-      if (response.stopReason === "error") {
-        throw new CompleteError("complete() failed: stop reason is error");
-      }
+    for (let attempt = 0; attempt < MAX_RATE_LIMIT_RETRIES; attempt++) {
+      const cmdStr = `acpx --model ${model} ${this.name}`;
+      const client = _acpAdapterDeps.createClient(cmdStr);
+      await client.start();
 
-      const text = response.messages
-        .filter((m) => m.role === "assistant")
-        .map((m) => m.content)
-        .join("\n")
-        .trim();
+      let session: AcpSession | null = null;
+      try {
+        // complete() is one-shot — ephemeral session, no session name, no sidecar
+        session = await client.createSession({ agentName: this.name, permissionMode });
 
-      if (!text) {
-        throw new CompleteError("complete() returned empty output");
-      }
+        // Enforce timeout via Promise.race — session.prompt() can hang indefinitely
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`complete() timed out after ${timeoutMs}ms`)), timeoutMs);
+        });
+        timeoutPromise.catch(() => {}); // prevent unhandled rejection if promptPromise wins
 
-      return text;
-    } finally {
-      if (session) {
-        await session.close().catch(() => {});
+        const promptPromise = session.prompt(prompt);
+
+        let response: AcpSessionResponse;
+        try {
+          response = await Promise.race([promptPromise, timeoutPromise]);
+        } finally {
+          clearTimeout(timeoutId);
+        }
+
+        if (response.stopReason === "error") {
+          throw new CompleteError("complete() failed: stop reason is error");
+        }
+
+        const text = response.messages
+          .filter((m) => m.role === "assistant")
+          .map((m) => m.content)
+          .join("\n")
+          .trim();
+
+        // ACP one-shot sessions wrap the response in a result envelope:
+        // {"type":"result","subtype":"success","result":"<actual output>"}
+        // Unwrap to return the actual content.
+        let unwrapped = text;
+        try {
+          const envelope = JSON.parse(text) as Record<string, unknown>;
+          if (envelope?.type === "result" && typeof envelope?.result === "string") {
+            unwrapped = envelope.result;
+          }
+        } catch {
+          // Not an envelope — use text as-is
+        }
+
+        if (!unwrapped) {
+          throw new CompleteError("complete() returned empty output");
+        }
+
+        return unwrapped;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        lastError = error;
+
+        const shouldRetry = isRateLimitError(error) && attempt < MAX_RATE_LIMIT_RETRIES - 1;
+        if (!shouldRetry) throw error;
+
+        const backoffMs = 2 ** (attempt + 1) * 1000;
+        getSafeLogger()?.warn("acp-adapter", "complete() rate limited, retrying", {
+          backoffSeconds: backoffMs / 1000,
+          attempt: attempt + 1,
+        });
+        await _acpAdapterDeps.sleep(backoffMs);
+      } finally {
+        if (session) {
+          await session.close().catch(() => {});
+        }
+        await client.close().catch(() => {});
       }
-      await client.close().catch(() => {});
     }
+
+    throw lastError ?? new CompleteError("complete() failed with unknown error");
   }
 
   async plan(options: PlanOptions): Promise<PlanResult> {
-    const modelDef = options.modelDef ?? { provider: "anthropic", model: "default" };
+    // Resolve model: explicit > config.models.balanced > fallback
+    let modelDef = options.modelDef;
+    if (!modelDef && options.config?.models) {
+      const { resolveBalancedModelDef } = await import("../model-resolution");
+      try {
+        modelDef = resolveBalancedModelDef(options.config as import("../../config").NaxConfig);
+      } catch {
+        // resolveBalancedModelDef can throw if models.balanced missing
+      }
+    }
+    modelDef ??= { provider: "anthropic", model: "claude-sonnet-4-5-20250514" };
     // Timeout: from options, or config, or fallback to 600s
     const timeoutSeconds =
       options.timeoutSeconds ?? (options.config?.execution?.sessionTimeoutSeconds as number | undefined) ?? 600;
@@ -601,6 +659,7 @@ export class AcpAgentAdapter implements AgentAdapter {
       timeoutSeconds,
       dangerouslySkipPermissions: options.dangerouslySkipPermissions ?? false,
       interactionBridge: options.interactionBridge,
+      maxInteractionTurns: options.maxInteractionTurns,
       featureName: options.featureName,
       storyId: options.storyId,
       sessionRole: options.sessionRole,

package/src/agents/acp/spawn-client.ts

@@ -247,7 +247,7 @@ export class SpawnAcpClient implements AcpClient {
     const sessionName = opts.sessionName || `nax-${Date.now()}`;
 
     // Ensure session exists via CLI
-    const cmd = ["acpx", opts.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, opts.agentName, "sessions", "ensure", "--name", sessionName];
     getSafeLogger()?.debug("acp-adapter", `Ensuring session: ${sessionName}`);
 
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
@@ -271,7 +271,7 @@ export class SpawnAcpClient implements AcpClient {
 
   async loadSession(sessionName: string): Promise<AcpSession | null> {
     // Try to ensure session exists — if it does, acpx returns success
-    const cmd = ["acpx", this.agentName, "sessions", "ensure", "--name", sessionName];
+    const cmd = ["acpx", "--cwd", this.cwd, this.agentName, "sessions", "ensure", "--name", sessionName];
 
     const proc = _spawnClientDeps.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
     const exitCode = await proc.exited;

package/src/agents/types-extended.ts

@@ -48,6 +48,8 @@ export interface PlanOptions {
   timeoutSeconds?: number;
   /** Whether to skip permission prompts (maps to permissionMode in ACP) */
   dangerouslySkipPermissions?: boolean;
+  /** Max interaction turns when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
   /**
    * Callback invoked with the ACP session name after the session is created.
    * Used to persist the name to status.json for plan→run session continuity.

package/src/agents/types.ts

@@ -74,6 +74,8 @@ export interface AgentRunOptions {
   storyId?: string;
   /** Session role for TDD isolation (e.g. "test-writer" | "implementer" | "verifier") */
   sessionRole?: string;
+  /** Max turns in multi-turn interaction loop when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
 }
 
 /**
@@ -100,6 +102,12 @@ export interface CompleteOptions {
   model?: string;
   /** Whether to skip permission prompts (maps to permissionMode in ACP) */
   dangerouslySkipPermissions?: boolean;
+  /**
+   * Timeout for the completion call in milliseconds.
+   * Adapters that support it (e.g. ACP) will enforce this as a hard deadline.
+   * Callers may also wrap complete() in their own Promise.race for shorter timeouts.
+   */
+  timeoutMs?: number;
 }
 
 /**

package/src/cli/config-descriptions.ts

@@ -203,4 +203,10 @@ export const FIELD_DESCRIPTIONS: Record<string, string> = {
   "decompose.maxSubstoryComplexity": "Max complexity for any generated substory (default: 'medium')",
   "decompose.maxRetries": "Max retries on decomposition validation failure (default: 2)",
   "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')",
+
+  // Agent protocol
+  agent: "Agent protocol configuration (ACP-003)",
+  "agent.protocol": "Protocol for agent communication: 'acp' | 'cli' (default: 'acp')",
+  "agent.maxInteractionTurns":
+    "Max turns in multi-turn interaction loop when interactionBridge is active (default: 10)",
 };

package/src/cli/init-detect.ts

@@ -26,6 +26,7 @@ interface PackageJson {
   devDependencies?: Record<string, string>;
   peerDependencies?: Record<string, string>;
   bin?: Record<string, string> | string;
+  workspaces?: string[] | { packages: string[] };
 }
 
 function readPackageJson(projectRoot: string): PackageJson | undefined {
@@ -80,7 +81,7 @@ export type Language = "typescript" | "python" | "rust" | "go" | "unknown";
 export type Linter = "biome" | "eslint" | "ruff" | "clippy" | "golangci-lint" | "unknown";
 
 /** Detected monorepo tooling */
-export type Monorepo = "turborepo" | "none";
+export type Monorepo = "turborepo" | "nx" | "pnpm-workspaces" | "bun-workspaces" | "none";
 
 /** Full detected project stack */
 export interface ProjectStack {
@@ -137,6 +138,11 @@ function detectLinter(projectRoot: string): Linter {
 
 function detectMonorepo(projectRoot: string): Monorepo {
   if (existsSync(join(projectRoot, "turbo.json"))) return "turborepo";
+  if (existsSync(join(projectRoot, "nx.json"))) return "nx";
+  if (existsSync(join(projectRoot, "pnpm-workspace.yaml"))) return "pnpm-workspaces";
+  // Bun/npm/yarn workspaces: package.json with "workspaces" field
+  const pkg = readPackageJson(projectRoot);
+  if (pkg?.workspaces) return "bun-workspaces";
   return "none";
 }
 
@@ -158,10 +164,52 @@ function resolveLintCommand(stack: ProjectStack, fallback: string): string {
   return fallback;
 }
 
+/**
+ * Build quality.commands for monorepo orchestrators.
+ *
+ * Turborepo and Nx support change-aware filtering natively — delegate
+ * scoping to the tool rather than nax's smart test runner.
+ * pnpm/bun workspaces have no built-in affected detection, so nax's
+ * smart runner still applies; commands run across all packages.
+ */
+function buildMonorepoQualityCommands(stack: ProjectStack): QualityCommands | null {
+  if (stack.monorepo === "turborepo") {
+    return {
+      typecheck: "turbo run typecheck --filter=...[HEAD~1]",
+      lint: "turbo run lint --filter=...[HEAD~1]",
+      test: "turbo run test --filter=...[HEAD~1]",
+    };
+  }
+  if (stack.monorepo === "nx") {
+    return {
+      typecheck: "nx affected --target=typecheck",
+      lint: "nx affected --target=lint",
+      test: "nx affected --target=test",
+    };
+  }
+  if (stack.monorepo === "pnpm-workspaces") {
+    return {
+      lint: resolveLintCommand(stack, "pnpm run --recursive lint"),
+      test: "pnpm run --recursive test",
+    };
+  }
+  if (stack.monorepo === "bun-workspaces") {
+    return {
+      lint: resolveLintCommand(stack, "bun run lint"),
+      test: "bun run --filter '*' test",
+    };
+  }
+  return null;
+}
+
 /**
  * Build quality.commands from a detected project stack.
  */
 export function buildQualityCommands(stack: ProjectStack): QualityCommands {
+  // Monorepo orchestrators: delegate to the tool's own scoping
+  const monorepoCommands = buildMonorepoQualityCommands(stack);
+  if (monorepoCommands) return monorepoCommands;
+
   if (stack.runtime === "bun" && stack.language === "typescript") {
     return {
       typecheck: "bun run tsc --noEmit",

package/src/cli/init.ts

@@ -103,11 +103,21 @@ function buildConstitution(stack: ProjectStack): string {
     sections.push("- Use type annotations for variables where non-obvious\n");
   }
 
-  if (stack.monorepo === "turborepo") {
+  if (stack.monorepo !== "none") {
     sections.push("## Monorepo Conventions");
     sections.push("- Respect package boundaries — do not import across packages without explicit dependency");
     sections.push("- Each package should be independently buildable and testable");
-    sections.push("- Shared utilities go in a dedicated `packages/shared` (or equivalent) package\n");
+    sections.push("- Shared utilities go in a dedicated `packages/shared` (or equivalent) package");
+    if (stack.monorepo === "turborepo") {
+      sections.push("- Use `turbo run <task> --filter=<package>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "nx") {
+      sections.push("- Use `nx run <package>:<task>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "pnpm-workspaces") {
+      sections.push("- Use `pnpm --filter <package> run <task>` to run tasks scoped to a single package");
+    } else if (stack.monorepo === "bun-workspaces") {
+      sections.push("- Use `bun run --filter <package> <task>` to run tasks scoped to a single package");
+    }
+    sections.push("");
   }
 
   sections.push("## Preferences");

package/src/cli/plan.ts

@@ -4,12 +4,13 @@
  * Reads a spec file (--from), builds a planning prompt with codebase context,
  * calls adapter.complete(), validates the JSON response, and writes prd.json.
  *
- * Interactive mode is not yet implemented (PLN-002).
+ * Interactive mode: uses ACP session + stdin bridge for Q&A.
  */
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { getAgent } from "../agents/registry";
+import { createInterface } from "node:readline";
+import { createAgentRegistry, getAgent } from "../agents/registry";
 import type { AgentAdapter } from "../agents/types";
 import { scanCodebase } from "../analyze/scanner";
 import type { CodebaseScan } from "../analyze/types";
@@ -25,7 +26,8 @@ export const _deps = {
   readFile: (path: string): Promise<string> => Bun.file(path).text(),
   writeFile: (path: string, content: string): Promise<void> => Bun.write(path, content).then(() => {}),
   scanCodebase: (workdir: string): Promise<CodebaseScan> => scanCodebase(workdir),
-  getAgent: (name: string): AgentAdapter | undefined => getAgent(name),
+  getAgent: (name: string, cfg?: NaxConfig): AgentAdapter | undefined =>
+    cfg ? createAgentRegistry(cfg).getAgent(name) : getAgent(name),
   readPackageJson: (workdir: string): Promise<Record<string, unknown> | null> =>
     Bun.file(join(workdir, "package.json"))
       .json()
@@ -90,12 +92,7 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   const branchName = options.branch ?? `feat/${options.feature}`;
   const prompt = buildPlanningPrompt(specContent, codebaseContext);
 
-  // Get agent adapter
   const agentName = config?.autoMode?.defaultAgent ?? "claude";
-  const adapter = _deps.getAgent(agentName);
-  if (!adapter) {
-    throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-  }
 
   // Timeout: from config, or default to 600 seconds (10 min)
   const timeoutSeconds = config?.execution?.sessionTimeoutSeconds ?? 600;
@@ -103,8 +100,23 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
   // Route to auto (one-shot) or interactive (multi-turn) mode
   let rawResponse: string;
   if (options.auto) {
-    rawResponse = await adapter.complete(prompt, { jsonMode: true });
+    // One-shot: use CLI adapter directly — simple completion doesn't need ACP session overhead
+    const cliAdapter = _deps.getAgent(agentName);
+    if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
+    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true });
+    // CLI adapter returns {"type":"result","result":"..."} envelope — unwrap it
+    try {
+      const envelope = JSON.parse(rawResponse) as Record<string, unknown>;
+      if (envelope?.type === "result" && typeof envelope?.result === "string") {
+        rawResponse = envelope.result;
+      }
+    } catch {
+      // Not an envelope — use rawResponse as-is
+    }
   } else {
+    // Interactive: use protocol-aware adapter (ACP when configured)
+    const adapter = _deps.getAgent(agentName, config);
+    if (!adapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
     const interactionBridge = createCliInteractionBridge();
     logger?.info("plan", "Starting interactive planning session...", { agent: agentName });
     try {
@@ -114,6 +126,10 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
         interactive: true,
         timeoutSeconds,
         interactionBridge,
+        config,
+        modelTier: "balanced",
+        dangerouslySkipPermissions: config?.execution?.dangerouslySkipPermissions ?? false,
+        maxInteractionTurns: config?.agent?.maxInteractionTurns,
       });
       rawResponse = result.specContent;
     } finally {
@@ -153,15 +169,26 @@ function createCliInteractionBridge(): {
 } {
   return {
     async detectQuestion(text: string): Promise<boolean> {
-      // Simple heuristic: detect if text contains a question mark
       return text.includes("?");
     },
 
     async onQuestionDetected(text: string): Promise<string> {
-      // For now, return the question text as-is to be used as follow-up prompt
-      // In a real CLI, this would read from stdin
-      // TODO: Implement stdin reading for actual CLI interaction
-      return text;
+      // In non-TTY mode (headless/pipes), skip interaction and continue
+      if (!process.stdin.isTTY) {
+        return "";
+      }
+
+      // Print agent question and read one line from stdin
+      process.stdout.write(`\n🤖 Agent: ${text}\nYou: `);
+
+      return new Promise<string>((resolve) => {
+        const rl = createInterface({ input: process.stdin, terminal: false });
+        rl.once("line", (line) => {
+          rl.close();
+          resolve(line.trim());
+        });
+        rl.once("close", () => resolve(""));
+      });
     },
   };
 }
@@ -262,7 +289,7 @@ Generate a JSON object with this exact structure (no markdown, no explanation
       "passes": false,
       "routing": {
         "complexity": "simple | medium | complex | expert",
-        "testStrategy": "test-after | tdd-lite | three-session-tdd",
+        "testStrategy": "test-after | tdd-simple | three-session-tdd | three-session-tdd-lite",
         "reasoning": "string — brief classification rationale"
       },
       "escalations": [],
@@ -274,15 +301,16 @@ Generate a JSON object with this exact structure (no markdown, no explanation
 ## Complexity Classification Guide
 
 - simple: ≤50 LOC, single-file change, purely additive, no new dependencies → test-after
-- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-lite
+- medium: 50–200 LOC, 2–5 files, standard patterns, clear requirements → tdd-simple
 - complex: 200–500 LOC, multiple modules, new abstractions or integrations → three-session-tdd
-- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd
+- expert: 500+ LOC, architectural changes, cross-cutting concerns, high risk → three-session-tdd-lite
 
 ## Test Strategy Guide
 
 - test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-lite: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex/expert. Full TDD cycle with separate sessions for tests and implementation.
+- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
+- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
+- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.
 
 Output ONLY the JSON object. Do not wrap in markdown code blocks.`;
 }

package/src/config/defaults.ts

@@ -81,7 +81,6 @@ export const DEFAULT_CONFIG: NaxConfig = {
     detectOpenHandles: true,
     detectOpenHandlesRetries: 1,
     gracePeriodMs: 5000,
-    dangerouslySkipPermissions: true,
     drainTimeoutMs: 2000,
     shell: "/bin/sh",
     stripEnvVars: [

package/src/config/runtime-types.ts

@@ -141,8 +141,6 @@ export interface QualityConfig {
   detectOpenHandlesRetries: number;
   /** Grace period in ms after SIGTERM before sending SIGKILL (default: 5000) */
   gracePeriodMs: number;
-  /** Use --dangerously-skip-permissions for agent sessions (default: false) */
-  dangerouslySkipPermissions: boolean;
   /** Deadline in ms to drain stdout/stderr after killing process (Bun stream workaround, default: 2000) */
   drainTimeoutMs: number;
   /** Shell to use for running verification commands (default: /bin/sh) */
@@ -473,6 +471,6 @@ export interface NaxConfig {
 export interface AgentConfig {
   /** Protocol to use for agent communication (default: 'acp') */
   protocol?: "acp" | "cli";
-  /** ACP permission mode (default: 'approve-all') */
-  acpPermissionMode?: string;
+  /** Max interaction turns when interactionBridge is active (default: 10) */
+  maxInteractionTurns?: number;
 }

package/src/config/schemas.ts

@@ -328,7 +328,7 @@ const StorySizeGateConfigSchema = z.object({
 
 const AgentConfigSchema = z.object({
   protocol: z.enum(["acp", "cli"]).default("acp"),
-  acpPermissionMode: z.string().optional(),
+  maxInteractionTurns: z.number().int().min(1).max(100).default(10),
 });
 
 const PrecheckConfigSchema = z.object({

package/src/pipeline/stages/acceptance.ts

@@ -149,19 +149,34 @@ export const acceptanceStage: PipelineStage = {
     const overrides = ctx.prd.acceptanceOverrides || {};
     const actualFailures = failedACs.filter((acId) => !overrides[acId]);
 
-    // If all failed ACs are overridden, treat as success
+    // If all tests passed cleanly
     if (actualFailures.length === 0 && exitCode === 0) {
       logger.info("acceptance", "All acceptance tests passed");
       return { action: "continue" };
     }
 
-    if (actualFailures.length === 0 && exitCode !== 0) {
-      // Tests failed but we couldn't parse which ACs
-      // This might be a setup/teardown error
-      logger.warn("acceptance", "Tests failed but no specific AC failures detected", {
+    // All parsed AC failures are overridden — treat as success even with non-zero exit
+    if (failedACs.length > 0 && actualFailures.length === 0) {
+      logger.info("acceptance", "All failed ACs are overridden — treating as pass");
+      return { action: "continue" };
+    }
+
+    // Non-zero exit but no AC failures parsed at all — test crashed (syntax error, import failure, etc.)
+    if (failedACs.length === 0 && exitCode !== 0) {
+      logger.error("acceptance", "Tests errored with no AC failures parsed", {
+        exitCode,
         output,
       });
-      return { action: "continue" }; // Don't block on unparseable failures
+
+      ctx.acceptanceFailures = {
+        failedACs: ["AC-ERROR"],
+        testOutput: output,
+      };
+
+      return {
+        action: "fail",
+        reason: `Acceptance tests errored (exit code ${exitCode}): syntax error, import failure, or unhandled exception`,
+      };
     }
 
     // If we have actual failures, report them

package/src/pipeline/stages/execution.ts

@@ -218,6 +218,7 @@ export const executionStage: PipelineStage = {
       modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
       timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: ctx.config.agent?.maxInteractionTurns,
       pidRegistry: ctx.pidRegistry,
       featureName: ctx.prd.feature,
       storyId: ctx.story.id,

package/src/prd/schema.ts

@@ -140,10 +140,14 @@ function validateStory(raw: unknown, index: number, allIds: Set<string>): UserSt
   }
 
   // testStrategy — accept from routing.testStrategy or top-level testStrategy
+  // Also map legacy/LLM-hallucinated aliases: tdd-lite → tdd-simple
   const rawTestStrategy = routing.testStrategy ?? s.testStrategy;
+  const STRATEGY_ALIASES: Record<string, TestStrategy> = { "tdd-lite": "three-session-tdd-lite" };
+  const normalizedStrategy =
+    typeof rawTestStrategy === "string" ? (STRATEGY_ALIASES[rawTestStrategy] ?? rawTestStrategy) : rawTestStrategy;
   const testStrategy: TestStrategy =
-    rawTestStrategy !== undefined && (VALID_TEST_STRATEGIES as unknown[]).includes(rawTestStrategy)
-      ? (rawTestStrategy as TestStrategy)
+    normalizedStrategy !== undefined && (VALID_TEST_STRATEGIES as unknown[]).includes(normalizedStrategy)
+      ? (normalizedStrategy as TestStrategy)
       : "tdd-simple";
 
   // dependencies

package/src/tdd/rectification-gate.ts

@@ -159,6 +159,7 @@ async function runRectificationLoop(
       modelDef: resolveModel(config.models[implementerTier]),
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config.agent?.maxInteractionTurns,
       featureName,
       storyId: story.id,
       sessionRole: "implementer",

package/src/tdd/session-runner.ts

@@ -140,6 +140,7 @@ export async function runTddSession(
     modelDef: resolveModel(config.models[modelTier]),
     timeoutSeconds: config.execution.sessionTimeoutSeconds,
     dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+    maxInteractionTurns: config.agent?.maxInteractionTurns,
     featureName,
     storyId: story.id,
     sessionRole: role,

package/src/verification/rectification-loop.ts

@@ -74,6 +74,7 @@ export async function runRectificationLoop(opts: RectificationLoopOptions): Prom
       modelDef,
       timeoutSeconds: config.execution.sessionTimeoutSeconds,
       dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+      maxInteractionTurns: config.agent?.maxInteractionTurns,
     });
 
     if (agentResult.success) {

package/src/verification/strategies/scoped.ts

@@ -36,6 +36,18 @@ function buildScopedCommand(testFiles: string[], baseCommand: string, testScoped
   return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
 }
 
+/**
+ * Returns true when the test command delegates to a monorepo orchestrator
+ * (Turborepo, Nx) that handles change-aware scoping natively.
+ *
+ * These tools use their own filter syntax (e.g. `--filter=...[HEAD~1]`,
+ * `nx affected`) — nax's smart test runner must not attempt to append
+ * file paths to such commands, as it would produce invalid syntax.
+ */
+export function isMonorepoOrchestratorCommand(command: string): boolean {
+  return /\bturbo\b/.test(command) || /\bnx\b/.test(command);
+}
+
 export class ScopedStrategy implements IVerificationStrategy {
   readonly name = "scoped" as const;
 
@@ -44,10 +56,16 @@ export class ScopedStrategy implements IVerificationStrategy {
     const smartCfg = coerceSmartRunner(ctx.smartRunnerConfig);
     const regressionMode = ctx.regressionMode ?? "deferred";
 
+    // Monorepo orchestrators (turbo, nx) handle change-aware scoping themselves.
+    // Skip nax's smart runner — appending file paths would produce invalid syntax.
+    // Also bypass deferred mode: run per-story so the orchestrator's own filter
+    // (e.g. --filter=...[HEAD~1]) can pick up the story's changes immediately.
+    const isMonorepoOrchestrator = isMonorepoOrchestratorCommand(ctx.testCommand);
+
     let effectiveCommand = ctx.testCommand;
     let isFullSuite = true;
 
-    if (smartCfg.enabled && ctx.storyGitRef) {
+    if (smartCfg.enabled && ctx.storyGitRef && !isMonorepoOrchestrator) {
       const sourceFiles = await _scopedDeps.getChangedSourceFiles(ctx.workdir, ctx.storyGitRef);
 
       const pass1Files = await _scopedDeps.mapSourceToTests(sourceFiles, ctx.workdir);
@@ -69,16 +87,22 @@ export class ScopedStrategy implements IVerificationStrategy {
       }
     }
 
-    // Defer to regression gate when no scoped tests found and mode is deferred
-    if (isFullSuite && regressionMode === "deferred") {
+    // Defer to regression gate when no scoped tests found and mode is deferred.
+    // Exception: monorepo orchestrators run per-story (they carry their own change filter).
+    if (isFullSuite && regressionMode === "deferred" && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests — deferring to run-end (mode: deferred)", {
         storyId: ctx.storyId,
       });
       return makeSkippedResult(ctx.storyId, "scoped");
     }
 
-    if (isFullSuite) {
+    if (isFullSuite && !isMonorepoOrchestrator) {
       logger.info("verify[scoped]", "No mapped tests — falling back to full suite", { storyId: ctx.storyId });
+    } else if (isMonorepoOrchestrator) {
+      logger.info("verify[scoped]", "Monorepo orchestrator detected — delegating scoping to tool", {
+        storyId: ctx.storyId,
+        command: effectiveCommand,
+      });
     }
 
     const start = Date.now();