@nathapp/nax 0.48.4 → 0.49.1

package/package.json

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

package/src/acceptance/generator.ts

@@ -94,9 +94,8 @@ ${criteriaList}
 
 ${strategyInstructions}Generate a complete acceptance.test.ts file using bun:test framework. Each AC maps to exactly one test named "AC-N: <description>".
 
-Use this structure:
+Structure example (do NOT wrap in markdown fences — output raw TypeScript only):
 
-\`\`\`typescript
 import { describe, test, expect } from "bun:test";
 
 describe("${options.featureName} - Acceptance Tests", () => {
@@ -104,13 +103,16 @@ describe("${options.featureName} - Acceptance Tests", () => {
     // Test implementation
   });
 });
-\`\`\`
 
-Respond with ONLY the TypeScript test code (no markdown code fences, no explanation).`;
+IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\`\`typescript or \`\`\`). Start directly with the import statement.`;
 
   logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
 
-  const testCode = await _generatorPRDDeps.adapter.complete(prompt, { config: options.config });
+  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, {
+    model: options.modelDef.model,
+    config: options.config,
+  });
+  const testCode = extractTestCode(rawOutput);
 
   const refinedJsonContent = JSON.stringify(
     refinedCriteria.map((c, i) => ({

package/src/agents/acp/adapter.ts

@@ -694,8 +694,13 @@ export class AcpAgentAdapter implements AgentAdapter {
 
       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 });
+        // complete() is one-shot — ephemeral session, no sidecar
+        // Use caller-provided sessionName if available (aids tracing), otherwise timestamp-based
+        session = await client.createSession({
+          agentName: this.name,
+          permissionMode,
+          sessionName: _options?.sessionName,
+        });
 
         // Enforce timeout via Promise.race — session.prompt() can hang indefinitely
         let timeoutId: ReturnType<typeof setTimeout> | undefined;

package/src/agents/acp/parser.ts

@@ -70,7 +70,7 @@ export function parseAcpxJsonOutput(rawOutput: string): {
           }
         }
 
-        // Final result with token breakdown (camelCase from acpx)
+        // Final result with token breakdown
         if (event.id !== undefined && event.result && typeof event.result === "object") {
           const result = event.result as Record<string, unknown>;
 

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

@@ -135,6 +135,8 @@ class SpawnAcpSession implements AcpSession {
       "acpx",
       "--cwd",
       this.cwd,
+      "--format",
+      "json",
       ...(this.permissionMode === "approve-all" ? ["--approve-all"] : []),
       "--model",
       this.model,

package/src/agents/types.ts

@@ -127,6 +127,12 @@ export interface CompleteOptions {
    * Pass when available so complete() honours permissionProfile / dangerouslySkipPermissions.
    */
   config?: NaxConfig;
+  /**
+   * Named session to use for this completion call.
+   * If omitted, a timestamp-based ephemeral session name is generated.
+   * Pass a meaningful name (e.g. "nax-decompose-us-001") to aid debugging.
+   */
+  sessionName?: string;
 }
 
 /**

package/src/cli/plan.ts

@@ -138,7 +138,17 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     const prompt = buildPlanningPrompt(specContent, codebaseContext, undefined, relativePackages, packageDetails);
     const cliAdapter = _deps.getAgent(agentName);
     if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config });
+    let autoModel: string | undefined;
+    try {
+      const planTier = config?.plan?.model ?? "balanced";
+      const { resolveModel } = await import("../config/schema");
+      const models = config?.models as Record<string, unknown> | undefined;
+      const entry = models?.[planTier] ?? models?.balanced;
+      if (entry) autoModel = resolveModel(entry as Parameters<typeof resolveModel>[0]).model;
+    } catch {
+      // fall through — complete() will use its own fallback
+    }
+    rawResponse = await cliAdapter.complete(prompt, { model: autoModel, jsonMode: true, workdir, config });
     // CLI adapter returns {"type":"result","result":"..."} envelope — unwrap it
     try {
       const envelope = JSON.parse(rawResponse) as Record<string, unknown>;

package/src/cli/prompts-main.ts

@@ -97,6 +97,7 @@ export async function promptsCommand(options: PromptsCommandOptions): Promise<st
     // Build initial pipeline context
     const ctx: PipelineContext = {
       config,
+      effectiveConfig: config,
       prd,
       story,
       stories: [story], // Single story, not batch

package/src/config/merge.ts

@@ -1,8 +1,9 @@
 /**
- * Per-Package Config Merge Utility (MW-008)
+ * Per-Package Config Merge Utility (MW-008, v0.49.0 expansion)
  *
- * Only quality.commands is mergeable — routing, plugins, execution,
- * and agents stay root-only.
+ * Merges a package-level partial config override into a root config.
+ * Covers all fields that make sense at the per-package level.
+ * Root-only fields (models, autoMode, routing, agent, etc.) are unchanged.
  */
 
 import type { NaxConfig } from "./schema";
@@ -10,27 +11,72 @@ import type { NaxConfig } from "./schema";
 /**
  * Merge a package-level partial config override into a root config.
  *
- * Only quality.commands keys are merged. All other sections remain
- * unchanged from the root config.
+ * Mergeable sections:
+ * - execution: smartTestRunner, regressionGate (deep), verificationTimeoutSeconds
+ * - review: enabled, checks, commands (deep), pluginMode
+ * - acceptance: enabled, generateTests, testPath
+ * - quality: requireTests, requireTypecheck, requireLint, commands (deep)
+ * - context: testCoverage (deep)
+ *
+ * All other sections (models, autoMode, routing, agent, generate, tdd,
+ * decompose, plan, constitution, interaction) remain root-only.
  *
  * @param root - Full root NaxConfig (already validated)
- * @param packageOverride - Partial package-level override (only quality.commands honored)
+ * @param packageOverride - Partial package-level override
  * @returns New merged NaxConfig (immutable — does not mutate inputs)
  */
 export function mergePackageConfig(root: NaxConfig, packageOverride: Partial<NaxConfig>): NaxConfig {
-  const packageCommands = packageOverride.quality?.commands;
+  const hasAnyMergeableField =
+    packageOverride.execution !== undefined ||
+    packageOverride.review !== undefined ||
+    packageOverride.acceptance !== undefined ||
+    packageOverride.quality !== undefined ||
+    packageOverride.context !== undefined;
 
-  if (!packageCommands) {
+  if (!hasAnyMergeableField) {
     return root;
   }
 
   return {
     ...root,
+    execution: {
+      ...root.execution,
+      ...packageOverride.execution,
+      smartTestRunner: packageOverride.execution?.smartTestRunner ?? root.execution.smartTestRunner,
+      regressionGate: {
+        ...root.execution.regressionGate,
+        ...packageOverride.execution?.regressionGate,
+      },
+      verificationTimeoutSeconds:
+        packageOverride.execution?.verificationTimeoutSeconds ?? root.execution.verificationTimeoutSeconds,
+    },
+    review: {
+      ...root.review,
+      ...packageOverride.review,
+      commands: {
+        ...root.review.commands,
+        ...packageOverride.review?.commands,
+      },
+    },
+    acceptance: {
+      ...root.acceptance,
+      ...packageOverride.acceptance,
+    },
     quality: {
       ...root.quality,
+      requireTests: packageOverride.quality?.requireTests ?? root.quality.requireTests,
+      requireTypecheck: packageOverride.quality?.requireTypecheck ?? root.quality.requireTypecheck,
+      requireLint: packageOverride.quality?.requireLint ?? root.quality.requireLint,
       commands: {
         ...root.quality.commands,
-        ...packageCommands,
+        ...packageOverride.quality?.commands,
+      },
+    },
+    context: {
+      ...root.context,
+      testCoverage: {
+        ...root.context.testCoverage,
+        ...packageOverride.context?.testCoverage,
       },
     },
   };

package/src/execution/iteration-runner.ts

@@ -5,6 +5,8 @@
  * Extracted from sequential-executor.ts to slim it below 120 lines.
  */
 
+import { join } from "node:path";
+import { loadConfigForWorkdir } from "../config/loader";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import { runPipeline } from "../pipeline/runner";
@@ -64,8 +66,14 @@ export async function runIteration(
   // BUG-067: Accumulate cost from all prior failed attempts (stored in priorFailures by handleTierEscalation)
   const accumulatedAttemptCost = (story.priorFailures || []).reduce((sum, f) => sum + (f.cost || 0), 0);
 
+  // PKG-003: Resolve per-package effective config once per story (not per-stage)
+  const effectiveConfig = story.workdir
+    ? await _iterationRunnerDeps.loadConfigForWorkdir(join(ctx.workdir, "nax", "config.json"), story.workdir)
+    : ctx.config;
+
   const pipelineContext: PipelineContext = {
     config: ctx.config,
+    effectiveConfig,
     prd,
     story,
     stories: storiesToExecute,
@@ -140,3 +148,10 @@ export async function runIteration(
     reason: pipelineResult.reason,
   };
 }
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _iterationRunnerDeps = {
+  loadConfigForWorkdir,
+};

package/src/execution/lifecycle/acceptance-loop.ts

@@ -134,6 +134,7 @@ async function executeFixStory(
   );
   const fixContext: PipelineContext = {
     config: ctx.config,
+    effectiveConfig: ctx.config,
     prd,
     story,
     stories: [story],
@@ -177,6 +178,7 @@ export async function runAcceptanceLoop(ctx: AcceptanceLoopContext): Promise<Acc
     const firstStory = prd.userStories[0];
     const acceptanceContext: PipelineContext = {
       config: ctx.config,
+      effectiveConfig: ctx.config,
       prd,
       story: firstStory,
       stories: [firstStory],

package/src/execution/parallel-coordinator.ts

@@ -148,6 +148,7 @@ export async function executeParallel(
     // Build context for this batch (shared across all stories in batch)
     const baseContext = {
       config,
+      effectiveConfig: config,
       prd: currentPrd,
       featureDir,
       hooks,

package/src/execution/parallel-executor-rectify.ts

@@ -90,6 +90,7 @@ export async function rectifyConflictedStory(options: RectifyConflictedStoryOpti
 
     const pipelineContext = {
       config,
+      effectiveConfig: config,
       prd,
       story,
       stories: [story],

package/src/execution/parallel-worker.ts

@@ -28,6 +28,7 @@ export async function executeStoryInWorktree(
   try {
     const pipelineContext: PipelineContext = {
       ...context,
+      effectiveConfig: context.effectiveConfig ?? context.config,
       story,
       stories: [story],
       workdir: worktreePath,

package/src/execution/sequential-executor.ts

@@ -72,6 +72,7 @@ export async function executeSequential(
     logger?.info("execution", "Running pre-run pipeline (acceptance test setup)");
     const preRunCtx: PipelineContext = {
       config: ctx.config,
+      effectiveConfig: ctx.config,
       prd,
       workdir: ctx.workdir,
       featureDir: ctx.featureDir,

package/src/pipeline/stages/acceptance.ts

@@ -92,7 +92,8 @@ export const acceptanceStage: PipelineStage = {
     // Only run when:
     // 1. Acceptance validation is enabled
     // 2. All stories are complete
-    if (!ctx.config.acceptance.enabled) {
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    if (!effectiveConfig.acceptance.enabled) {
       return false;
     }
 
@@ -106,6 +107,9 @@ export const acceptanceStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // PKG-004: use centrally resolved effective config
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+
     logger.info("acceptance", "Running acceptance tests");
 
     // Build path to acceptance test file
@@ -114,7 +118,7 @@ export const acceptanceStage: PipelineStage = {
       return { action: "continue" };
     }
 
-    const testPath = path.join(ctx.featureDir, ctx.config.acceptance.testPath);
+    const testPath = path.join(ctx.featureDir, effectiveConfig.acceptance.testPath);
 
     // Check if test file exists
     const testFile = Bun.file(testPath);

package/src/pipeline/stages/autofix.ts

@@ -19,8 +19,10 @@
  * - `escalate`                 — max attempts exhausted or agent unavailable
  */
 
+import { join } from "node:path";
 import { getAgent } from "../../agents";
 import { resolveModel } from "../../config";
+import { loadConfigForWorkdir } from "../../config/loader";
 import { resolvePermissions } from "../../config/permissions";
 import { getLogger } from "../../logger";
 import type { UserStory } from "../../prd";
@@ -34,7 +36,7 @@ export const autofixStage: PipelineStage = {
   enabled(ctx: PipelineContext): boolean {
     if (!ctx.reviewResult) return false;
     if (ctx.reviewResult.success) return false;
-    const autofixEnabled = ctx.config.quality.autofix?.enabled ?? true;
+    const autofixEnabled = (ctx.effectiveConfig ?? ctx.config).quality.autofix?.enabled ?? true;
     return autofixEnabled;
   },
 
@@ -51,14 +53,19 @@ export const autofixStage: PipelineStage = {
       return { action: "continue" };
     }
 
-    const lintFixCmd = ctx.config.quality.commands.lintFix;
-    const formatFixCmd = ctx.config.quality.commands.formatFix;
+    // PKG-004: use centrally resolved effective config (ctx.effectiveConfig set once per story)
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    const lintFixCmd = effectiveConfig.quality.commands.lintFix;
+    const formatFixCmd = effectiveConfig.quality.commands.formatFix;
+
+    // Effective workdir for running commands (scoped to package if monorepo)
+    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
 
     // Phase 1: Mechanical fix (if commands are configured)
     if (lintFixCmd || formatFixCmd) {
       if (lintFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: lintFixCmd });
-        const lintResult = await _autofixDeps.runCommand(lintFixCmd, ctx.workdir);
+        const lintResult = await _autofixDeps.runCommand(lintFixCmd, effectiveWorkdir);
         logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id });
         if (lintResult.exitCode !== 0) {
           logger.warn("autofix", "lintFix command failed — may not have fixed all issues", {
@@ -70,7 +77,7 @@ export const autofixStage: PipelineStage = {
 
       if (formatFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: formatFixCmd });
-        const fmtResult = await _autofixDeps.runCommand(formatFixCmd, ctx.workdir);
+        const fmtResult = await _autofixDeps.runCommand(formatFixCmd, effectiveWorkdir);
         logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, { storyId: ctx.story.id });
         if (fmtResult.exitCode !== 0) {
           logger.warn("autofix", "formatFix command failed — may not have fixed all issues", {
@@ -155,7 +162,8 @@ Commit your fixes when done.`;
 
 async function runAgentRectification(ctx: PipelineContext): Promise<boolean> {
   const logger = getLogger();
-  const maxAttempts = ctx.config.quality.autofix?.maxAttempts ?? 2;
+  const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+  const maxAttempts = effectiveConfig.quality.autofix?.maxAttempts ?? 2;
   const failedChecks = collectFailedChecks(ctx);
 
   if (failedChecks.length === 0) {
@@ -224,4 +232,4 @@ async function runAgentRectification(ctx: PipelineContext): Promise<boolean> {
 /**
  * Injectable deps for testing.
  */
-export const _autofixDeps = { runCommand, recheckReview, runAgentRectification };
+export const _autofixDeps = { runCommand, recheckReview, runAgentRectification, loadConfigForWorkdir };

package/src/pipeline/stages/execution.ts

@@ -16,6 +16,7 @@
  * - `session-failure`                   → escalate
  * - `tests-failing`                     → escalate
  * - `verifier-rejected`                 → escalate
+ * - `greenfield-no-tests`               → escalate (tier-escalation switches to test-after)
  * - no category / unknown               → pause (backward compatible)
  *
  * @example
@@ -111,6 +112,11 @@ export function routeTddFailure(
     return { action: "escalate" };
   }
 
+  // S5: greenfield-no-tests → escalate so tier-escalation can switch to test-after
+  if (failureCategory === "greenfield-no-tests") {
+    return { action: "escalate" };
+  }
+
   // Default: no category or unknown — backward-compatible pause for human review
   return {
     action: "pause",

package/src/pipeline/stages/prompt.ts

@@ -34,6 +34,9 @@ export const promptStage: PipelineStage = {
     const logger = getLogger();
     const isBatch = ctx.stories.length > 1;
 
+    // PKG-004: use centrally resolved effective config
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+
     let prompt: string;
     if (isBatch) {
       const builder = PromptBuilder.for("batch")
@@ -41,7 +44,7 @@ export const promptStage: PipelineStage = {
         .stories(ctx.stories)
         .context(ctx.contextMarkdown)
         .constitution(ctx.constitution?.content)
-        .testCommand(ctx.config.quality?.commands?.test);
+        .testCommand(effectiveConfig.quality?.commands?.test);
       prompt = await builder.build();
     } else {
       // Both test-after and tdd-simple use the tdd-simple prompt (RED/GREEN/REFACTOR)
@@ -51,7 +54,7 @@ export const promptStage: PipelineStage = {
         .story(ctx.story)
         .context(ctx.contextMarkdown)
         .constitution(ctx.constitution?.content)
-        .testCommand(ctx.config.quality?.commands?.test);
+        .testCommand(effectiveConfig.quality?.commands?.test);
       prompt = await builder.build();
     }
 

package/src/pipeline/stages/rectify.ts

@@ -59,13 +59,15 @@ export const rectifyStage: PipelineStage = {
       testOutput,
     });
 
-    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";
+    // PKG-004: use centrally resolved effective config
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test ?? "bun test";
     const fixed = await _rectifyDeps.runRectificationLoop({
       config: ctx.config,
       workdir: ctx.workdir,
       story: ctx.story,
       testCommand,
-      timeoutSeconds: ctx.config.execution.verificationTimeoutSeconds,
+      timeoutSeconds: effectiveConfig.execution.verificationTimeoutSeconds,
       testOutput,
     });
 

package/src/pipeline/stages/regression.ts

@@ -24,24 +24,28 @@ export const regressionStage: PipelineStage = {
   name: "regression",
 
   enabled(ctx: PipelineContext): boolean {
-    const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    const mode = effectiveConfig.execution.regressionGate?.mode ?? "deferred";
     if (mode !== "per-story") return false;
     // Only run when verify passed (or was skipped/not set)
     if (ctx.verifyResult && !ctx.verifyResult.success) return false;
-    const gateEnabled = ctx.config.execution.regressionGate?.enabled ?? true;
+    const gateEnabled = effectiveConfig.execution.regressionGate?.enabled ?? true;
     return gateEnabled;
   },
 
   skipReason(ctx: PipelineContext): string {
-    const mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    const mode = effectiveConfig.execution.regressionGate?.mode ?? "deferred";
     if (mode !== "per-story") return `not needed (regression mode is '${mode}', not 'per-story')`;
     return "disabled (regression gate not enabled in config)";
   },
 
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
-    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";
-    const timeoutSeconds = ctx.config.execution.regressionGate?.timeoutSeconds ?? 120;
+    // PKG-004: use centrally resolved effective config
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test ?? "bun test";
+    const timeoutSeconds = effectiveConfig.execution.regressionGate?.timeoutSeconds ?? 120;
 
     logger.info("regression", "Running full-suite regression gate", { storyId: ctx.story.id });
 
@@ -50,7 +54,7 @@ export const regressionStage: PipelineStage = {
       testCommand,
       timeoutSeconds,
       storyId: ctx.story.id,
-      acceptOnTimeout: ctx.config.execution.regressionGate?.acceptOnTimeout ?? true,
+      acceptOnTimeout: effectiveConfig.execution.regressionGate?.acceptOnTimeout ?? true,
       config: ctx.config,
     };
 

package/src/pipeline/stages/review.ts

@@ -19,20 +19,23 @@ import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
 export const reviewStage: PipelineStage = {
   name: "review",
-  enabled: (ctx) => ctx.config.review.enabled,
+  enabled: (ctx) => (ctx.effectiveConfig ?? ctx.config).review.enabled,
 
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
+    // PKG-004: use centrally resolved effective config
+    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
+
     logger.info("review", "Running review phase", { storyId: ctx.story.id });
 
     // MW-010: scope review to package directory when story.workdir is set
     const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
 
     const result = await reviewOrchestrator.review(
-      ctx.config.review,
+      effectiveConfig.review,
       effectiveWorkdir,
-      ctx.config.execution,
+      effectiveConfig.execution,
       ctx.plugins,
       ctx.storyGitRef,
       ctx.story.workdir, // MW-010: scope changed-file checks to package
@@ -49,10 +52,10 @@ export const reviewStage: PipelineStage = {
 
       if (result.pluginFailed) {
         // security-review trigger: prompt before permanently failing
-        if (ctx.interaction && isTriggerEnabled("security-review", ctx.config)) {
+        if (ctx.interaction && isTriggerEnabled("security-review", effectiveConfig)) {
           const shouldContinue = await _reviewDeps.checkSecurityReview(
             { featureName: ctx.prd.feature, storyId: ctx.story.id },
-            ctx.config,
+            effectiveConfig,
             ctx.interaction,
           );
           if (!shouldContinue) {
@@ -67,11 +70,12 @@ export const reviewStage: PipelineStage = {
         return { action: "fail", reason: `Review failed: ${result.failureReason}` };
       }
 
-      logger.warn("review", "Review failed (built-in checks) — escalating for retry", {
+      logger.warn("review", "Review failed (built-in checks) — handing off to autofix", {
         reason: result.failureReason,
         storyId: ctx.story.id,
       });
-      return { action: "escalate", reason: `Review failed: ${result.failureReason}` };
+      // ctx.reviewResult is already set with success:false — autofixStage handles it next
+      return { action: "continue" };
     }
 
     logger.info("review", "Review passed", {

package/src/pipeline/stages/routing.ts

@@ -65,9 +65,28 @@ async function runDecompose(
   if (!agent) {
     throw new Error(`[decompose] Agent "${config.autoMode.defaultAgent}" not found — cannot decompose`);
   }
+
+  // Resolve decompose model: config.decompose.model tier → actual model string
+  const decomposeTier = naxDecompose?.model ?? "balanced";
+  let decomposeModel: string | undefined;
+  try {
+    const { resolveModel } = await import("../../config/schema");
+    const models = config.models as Record<string, unknown>;
+    const entry = models[decomposeTier] ?? models.balanced;
+    if (entry) decomposeModel = resolveModel(entry as Parameters<typeof resolveModel>[0]).model;
+  } catch {
+    // resolveModel can throw on malformed entries — fall through to let complete() handle it
+  }
+
+  const storySessionName = `nax-decompose-${story.id.toLowerCase()}`;
   const adapter = {
     async decompose(prompt: string): Promise<string> {
-      return agent.complete(prompt, { jsonMode: true, config });
+      return agent.complete(prompt, {
+        model: decomposeModel,
+        jsonMode: true,
+        config,
+        sessionName: storySessionName,
+      });
     },
   };