@nathapp/nax 0.49.3 → 0.49.6

package/src/agents/acp/adapter.ts

@@ -261,23 +261,37 @@ function acpSessionsPath(workdir: string, featureName: string): string {
   return join(workdir, "nax", "features", featureName, "acp-sessions.json");
 }
 
+/** Sidecar entry — session name + agent name for correct sweep/close. */
+type SidecarEntry = string | { sessionName: string; agentName: string };
+
+/** Extract sessionName from a sidecar entry (handles legacy string format). */
+function sidecarSessionName(entry: SidecarEntry): string {
+  return typeof entry === "string" ? entry : entry.sessionName;
+}
+
+/** Extract agentName from a sidecar entry (defaults to "claude" for legacy entries). */
+function sidecarAgentName(entry: SidecarEntry): string {
+  return typeof entry === "string" ? "claude" : entry.agentName;
+}
+
 /** Persist a session name to the sidecar file. Best-effort — errors are swallowed. */
 export async function saveAcpSession(
   workdir: string,
   featureName: string,
   storyId: string,
   sessionName: string,
+  agentName = "claude",
 ): Promise<void> {
   try {
     const path = acpSessionsPath(workdir, featureName);
-    let data: Record<string, string> = {};
+    let data: Record<string, SidecarEntry> = {};
     try {
       const existing = await Bun.file(path).text();
       data = JSON.parse(existing);
     } catch {
       // File doesn't exist yet — start fresh
     }
-    data[storyId] = sessionName;
+    data[storyId] = { sessionName, agentName };
     await Bun.write(path, JSON.stringify(data, null, 2));
   } catch (err) {
     getSafeLogger()?.warn("acp-adapter", "Failed to save session to sidecar", { error: String(err) });
@@ -307,8 +321,9 @@ export async function readAcpSession(workdir: string, featureName: string, story
   try {
     const path = acpSessionsPath(workdir, featureName);
     const existing = await Bun.file(path).text();
-    const data: Record<string, string> = JSON.parse(existing);
-    return data[storyId] ?? null;
+    const data: Record<string, SidecarEntry> = JSON.parse(existing);
+    const entry = data[storyId];
+    return entry ? sidecarSessionName(entry) : null;
   } catch {
     return null;
   }
@@ -326,10 +341,10 @@ const MAX_SESSION_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
  */
 export async function sweepFeatureSessions(workdir: string, featureName: string): Promise<void> {
   const path = acpSessionsPath(workdir, featureName);
-  let sessions: Record<string, string>;
+  let sessions: Record<string, SidecarEntry>;
   try {
     const text = await Bun.file(path).text();
-    sessions = JSON.parse(text) as Record<string, string>;
+    sessions = JSON.parse(text) as Record<string, SidecarEntry>;
   } catch {
     return; // No sidecar — nothing to sweep
   }
@@ -340,24 +355,35 @@ export async function sweepFeatureSessions(workdir: string, featureName: string)
   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(() => {});
+  // Group sessions by agent name so we create one client per agent
+  const byAgent = new Map<string, string[]>();
+  for (const [, entry] of entries) {
+    const agent = sidecarAgentName(entry);
+    const name = sidecarSessionName(entry);
+    if (!byAgent.has(agent)) byAgent.set(agent, []);
+    byAgent.get(agent)?.push(name);
+  }
+
+  for (const [agentName, sessionNames] of byAgent) {
+    const cmdStr = `acpx ${agentName}`;
+    const client = _acpAdapterDeps.createClient(cmdStr, workdir);
+    try {
+      await client.start();
+      for (const sessionName of sessionNames) {
+        try {
+          if (client.loadSession) {
+            const session = await client.loadSession(sessionName, agentName, "approve-reads");
+            if (session) {
+              await session.close().catch(() => {});
+            }
           }
+        } catch (err) {
+          logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
         }
-      } catch (err) {
-        logger?.warn("acp-adapter", `[sweep] Failed to close session ${sessionName}`, { error: String(err) });
       }
+    } finally {
+      await client.close().catch(() => {});
     }
-  } finally {
-    await client.close().catch(() => {});
   }
 
   // Clear sidecar after sweep
@@ -554,7 +580,7 @@ export class AcpAgentAdapter implements AgentAdapter {
 
     // 4. Persist for plan→run continuity
     if (options.featureName && options.storyId) {
-      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName);
+      await saveAcpSession(options.workdir, options.featureName, options.storyId, sessionName, this.name);
     }
 
     let lastResponse: AcpSessionResponse | null = null;
@@ -635,13 +661,17 @@ export class AcpAgentAdapter implements AgentAdapter {
     } finally {
       // 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) {
+      // When keepSessionOpen=true (e.g. rectification loop), skip close even on success
+      // so all attempts share the same conversation context.
+      if (runState.succeeded && !options.keepSessionOpen) {
         await closeAcpSession(session);
         if (options.featureName && options.storyId) {
           await clearAcpSession(options.workdir, options.featureName, options.storyId);
         }
-      } else {
+      } else if (!runState.succeeded) {
         getSafeLogger()?.info("acp-adapter", "Keeping session open for retry", { sessionName });
+      } else {
+        getSafeLogger()?.debug("acp-adapter", "Keeping session open (keepSessionOpen=true)", { sessionName });
       }
       await client.close().catch(() => {});
     }

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

@@ -272,7 +272,6 @@ export class SpawnAcpClient implements AcpClient {
   private readonly model: string;
   private readonly cwd: string;
   private readonly timeoutSeconds: number;
-  private readonly permissionMode: string;
   private readonly env: Record<string, string | undefined>;
   private readonly pidRegistry?: PidRegistry;
 
@@ -289,7 +288,6 @@ export class SpawnAcpClient implements AcpClient {
     this.agentName = lastToken;
     this.cwd = cwd || process.cwd();
     this.timeoutSeconds = timeoutSeconds || 1800;
-    this.permissionMode = "approve-reads";
     this.env = buildAllowedEnv();
     this.pidRegistry = pidRegistry;
   }

package/src/agents/claude/execution.ts

@@ -126,6 +126,20 @@ export async function executeOnce(
   const cmd = _runOnceDeps.buildCmd(binary, options);
   const startTime = Date.now();
 
+  // Log session-related options for traceability. CLI adapter doesn't use sessions,
+  // but the pipeline passes these uniformly. Logged so future CLI session support
+  // can verify they're threaded correctly.
+  if (options.sessionRole || options.acpSessionName || options.keepSessionOpen) {
+    const logger = getLogger();
+    logger.debug("agent", "CLI mode: session options received (unused)", {
+      sessionRole: options.sessionRole,
+      acpSessionName: options.acpSessionName,
+      keepSessionOpen: options.keepSessionOpen,
+      featureName: options.featureName,
+      storyId: options.storyId,
+    });
+  }
+
   const proc = Bun.spawn(cmd, {
     cwd: options.workdir,
     stdout: "pipe",

package/src/agents/types.ts

@@ -84,6 +84,13 @@ export interface AgentRunOptions {
   pipelineStage?: import("../config/permissions").PipelineStage;
   /** Full nax config — passed through so adapters can call resolvePermissions() */
   config?: NaxConfig;
+  /**
+   * When true, the adapter will NOT close the session after a successful run.
+   * Use this for rectification loops where the same session must persist across
+   * multiple attempts so the agent retains full conversation context.
+   * The caller is responsible for closing the session when the loop is done.
+   */
+  keepSessionOpen?: boolean;
 }
 
 /**

package/src/cli/prompts-main.ts

@@ -13,7 +13,11 @@ import type { PipelineContext } from "../pipeline";
 import { constitutionStage, contextStage, promptStage, routingStage } from "../pipeline/stages";
 import type { UserStory } from "../prd";
 import { loadPRD } from "../prd";
+// buildFrontmatter lives in prompts-shared to avoid circular import with prompts-tdd.
+// Import for local use + re-export to preserve the public API via prompts.ts.
+import { buildFrontmatter } from "./prompts-shared";
 import { handleThreeSessionTddPrompts } from "./prompts-tdd";
+export { buildFrontmatter };
 
 export interface PromptsCommandOptions {
   /** Feature name */
@@ -177,62 +181,3 @@ export async function promptsCommand(options: PromptsCommandOptions): Promise<st
 
   return processedStories;
 }
-
-/**
- * Build YAML frontmatter for a story prompt.
- *
- * Uses actual token counts from BuiltContext elements (computed by context builder
- * using CHARS_PER_TOKEN=3) rather than re-estimating independently.
- *
- * @param story - User story
- * @param ctx - Pipeline context after running prompt assembly
- * @param role - Optional role for three-session TDD (test-writer, implementer, verifier)
- * @returns YAML frontmatter string (without delimiters)
- */
-export function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string): string {
-  const lines: string[] = [];
-
-  lines.push(`storyId: ${story.id}`);
-  lines.push(`title: "${story.title}"`);
-  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
-  lines.push(`modelTier: ${ctx.routing.modelTier}`);
-
-  if (role) {
-    lines.push(`role: ${role}`);
-  }
-
-  // Use actual token counts from BuiltContext if available
-  const builtContext = ctx.builtContext;
-  const contextTokens = builtContext?.totalTokens ?? 0;
-  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
-
-  lines.push(`contextTokens: ${contextTokens}`);
-  lines.push(`promptTokens: ${promptTokens}`);
-
-  // Dependencies
-  if (story.dependencies && story.dependencies.length > 0) {
-    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
-  }
-
-  // Context elements breakdown from actual BuiltContext
-  lines.push("contextElements:");
-
-  if (builtContext) {
-    for (const element of builtContext.elements) {
-      lines.push(`  - type: ${element.type}`);
-      if (element.storyId) {
-        lines.push(`    storyId: ${element.storyId}`);
-      }
-      if (element.filePath) {
-        lines.push(`    filePath: ${element.filePath}`);
-      }
-      lines.push(`    tokens: ${element.tokens}`);
-    }
-  }
-
-  if (builtContext?.truncated) {
-    lines.push("truncated: true");
-  }
-
-  return `${lines.join("\n")}\n`;
-}

package/src/cli/prompts-shared.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared Prompts Utilities
+ *
+ * Functions shared between prompts-main and prompts-tdd to avoid circular imports.
+ * Both modules need buildFrontmatter; keeping it here breaks the cycle:
+ *   prompts-main → prompts-tdd (was circular)
+ *   now both → prompts-shared
+ */
+
+import type { PipelineContext } from "../pipeline";
+import type { UserStory } from "../prd";
+
+/**
+ * Build YAML frontmatter for a prompt file.
+ *
+ * Token counts use actual BuiltContext values (computed during pipeline execution,
+ * using CHARS_PER_TOKEN=3) rather than re-estimating independently.
+ *
+ * @param story - User story
+ * @param ctx - Pipeline context after running prompt assembly
+ * @param role - Optional role for three-session TDD (test-writer, implementer, verifier)
+ * @returns YAML frontmatter string (without delimiters)
+ */
+export function buildFrontmatter(story: UserStory, ctx: PipelineContext, role?: string): string {
+  const lines: string[] = [];
+
+  lines.push(`storyId: ${story.id}`);
+  lines.push(`title: "${story.title}"`);
+  lines.push(`testStrategy: ${ctx.routing.testStrategy}`);
+  lines.push(`modelTier: ${ctx.routing.modelTier}`);
+
+  if (role) {
+    lines.push(`role: ${role}`);
+  }
+
+  // Use actual token counts from BuiltContext if available
+  const builtContext = ctx.builtContext;
+  const contextTokens = builtContext?.totalTokens ?? 0;
+  const promptTokens = ctx.prompt ? Math.ceil(ctx.prompt.length / 3) : 0;
+
+  lines.push(`contextTokens: ${contextTokens}`);
+  lines.push(`promptTokens: ${promptTokens}`);
+
+  // Dependencies
+  if (story.dependencies && story.dependencies.length > 0) {
+    lines.push(`dependencies: [${story.dependencies.join(", ")}]`);
+  }
+
+  // Context elements breakdown from actual BuiltContext
+  lines.push("contextElements:");
+
+  if (builtContext) {
+    for (const element of builtContext.elements) {
+      lines.push(`  - type: ${element.type}`);
+      if (element.storyId) {
+        lines.push(`    storyId: ${element.storyId}`);
+      }
+      if (element.filePath) {
+        lines.push(`    filePath: ${element.filePath}`);
+      }
+      lines.push(`    tokens: ${element.tokens}`);
+    }
+  }
+
+  if (builtContext?.truncated) {
+    lines.push("truncated: true");
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/cli/prompts-tdd.ts

@@ -9,7 +9,7 @@ import type { getLogger } from "../logger";
 import type { PipelineContext } from "../pipeline";
 import type { UserStory } from "../prd";
 import { PromptBuilder } from "../prompts";
-import { buildFrontmatter } from "./prompts-main";
+import { buildFrontmatter } from "./prompts-shared";
 
 /**
  * Handle three-session TDD prompts by building separate prompts for each role.

package/src/config/merge.ts

@@ -55,6 +55,24 @@ export function mergePackageConfig(root: NaxConfig, packageOverride: Partial<Nax
       ...packageOverride.review,
       commands: {
         ...root.review.commands,
+        // PKG-006: Bridge quality.commands → review.commands for per-package overrides.
+        // Users naturally put per-package commands in quality.commands (the intuitive
+        // place), but the review runner reads review.commands. Bridge them here so
+        // packages don't need to define the same commands in two places.
+        // Explicit review.commands still take precedence (applied after).
+        ...(packageOverride.quality?.commands?.lint !== undefined && {
+          lint: packageOverride.quality.commands.lint,
+        }),
+        ...(packageOverride.quality?.commands?.lintFix !== undefined && {
+          lintFix: packageOverride.quality.commands.lintFix,
+        }),
+        ...(packageOverride.quality?.commands?.typecheck !== undefined && {
+          typecheck: packageOverride.quality.commands.typecheck,
+        }),
+        ...(packageOverride.quality?.commands?.test !== undefined && {
+          test: packageOverride.quality.commands.test,
+        }),
+        // Explicit review.commands override bridged quality values
         ...packageOverride.review?.commands,
       },
     },

package/src/interaction/plugins/webhook.ts

@@ -11,8 +11,8 @@ import { z } from "zod";
 import type { InteractionPlugin, InteractionRequest, InteractionResponse } from "../types";
 
 /**
- * Injectable sleep for WebhookInteractionPlugin.receive() polling loop.
- * Replace in tests to avoid real backoff delays.
+ * Injectable sleep — kept for backward compat with existing tests that override it.
+ * No longer used internally by receive() (replaced by event-driven delivery).
  * @internal
  */
 export const _webhookPluginDeps = {
@@ -56,7 +56,10 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
   private config: WebhookConfig = {};
   private server: Server | null = null;
   private serverStartPromise: Promise<void> | null = null;
+  /** Legacy map for responses that arrive before receive() is called */
   private pendingResponses = new Map<string, InteractionResponse>();
+  /** Event-driven callbacks: requestId → resolve fn (set by receive(), called by handleRequest) */
+  private receiveCallbacks = new Map<string, (response: InteractionResponse) => void>();
 
   async init(config: Record<string, unknown>): Promise<void> {
     const cfg = WebhookConfigSchema.parse(config);
@@ -117,33 +120,49 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
     // Start HTTP server to receive callback
     await this.startServer();
 
-    const startTime = Date.now();
-    let backoffMs = 100; // Initial poll interval
-    const maxBackoffMs = 2000; // Max 2 seconds between polls
-
-    // Poll for response with exponential backoff
-    while (Date.now() - startTime < timeout) {
-      const response = this.pendingResponses.get(requestId);
-      if (response) {
-        this.pendingResponses.delete(requestId);
-        return response;
-      }
-      await _webhookPluginDeps.sleep(backoffMs);
-      // Exponential backoff: double interval up to max
-      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+    // Check if a response already arrived before receive() was called
+    const early = this.pendingResponses.get(requestId);
+    if (early) {
+      this.pendingResponses.delete(requestId);
+      return early;
     }
 
-    // Timeout
-    return {
-      requestId,
-      action: "skip",
-      respondedBy: "timeout",
-      respondedAt: Date.now(),
-    };
+    // Event-driven: resolve immediately when handleRequest delivers the response
+    return new Promise<InteractionResponse>((resolve) => {
+      const timer = setTimeout(() => {
+        this.receiveCallbacks.delete(requestId);
+        resolve({
+          requestId,
+          action: "skip",
+          respondedBy: "timeout",
+          respondedAt: Date.now(),
+        });
+      }, timeout);
+
+      this.receiveCallbacks.set(requestId, (response) => {
+        clearTimeout(timer);
+        this.receiveCallbacks.delete(requestId);
+        resolve(response);
+      });
+    });
   }
 
   async cancel(requestId: string): Promise<void> {
     this.pendingResponses.delete(requestId);
+    this.receiveCallbacks.delete(requestId);
+  }
+
+  /**
+   * Deliver a response to a waiting receive() callback, or store for later pickup.
+   */
+  private deliverResponse(requestId: string, response: InteractionResponse): void {
+    const cb = this.receiveCallbacks.get(requestId);
+    if (cb) {
+      cb(response);
+    } else {
+      // receive() hasn't been called yet — store for early-pickup path
+      this.pendingResponses.set(requestId, response);
+    }
   }
 
   /**
@@ -220,7 +239,7 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
       try {
         const parsed = JSON.parse(body);
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         // Sanitize error - do not leak parse/validation details
         return new Response("Bad Request: Invalid response format", { status: 400 });
@@ -230,7 +249,7 @@ export class WebhookInteractionPlugin implements InteractionPlugin {
       try {
         const parsed = await req.json();
         const response = InteractionResponseSchema.parse(parsed);
-        this.pendingResponses.set(requestId, response);
+        this.deliverResponse(requestId, response);
       } catch {
         // Sanitize error - do not leak parse/validation details
         return new Response("Bad Request: Invalid response format", { status: 400 });

package/src/tdd/cleanup.ts

@@ -7,6 +7,13 @@
 
 import { getLogger } from "../logger";
 
+/** Injectable deps for testability — mock _cleanupDeps instead of global Bun.spawn/process.kill */
+export const _cleanupDeps = {
+  spawn: Bun.spawn as typeof Bun.spawn,
+  sleep: Bun.sleep as typeof Bun.sleep,
+  kill: process.kill.bind(process) as typeof process.kill,
+};
+
 /**
  * Get process group ID (PGID) for a given process ID.
  *
@@ -24,17 +31,19 @@ import { getLogger } from "../logger";
 export async function getPgid(pid: number): Promise<number | null> {
   try {
     // Use ps to get PGID for the process
-    const proc = Bun.spawn(["ps", "-o", "pgid=", "-p", String(pid)], {
+    const proc = _cleanupDeps.spawn(["ps", "-o", "pgid=", "-p", String(pid)], {
       stdout: "pipe",
       stderr: "pipe",
     });
 
+    // Read stdout BEFORE awaiting exit — stream may be closed after exit in Bun 1.3.9.
+    // Bun.readableStreamToText is more reliable than new Response(stream).text()
+    // with both real pipes and mocked streams.
+    const output = await Bun.readableStreamToText(proc.stdout);
     const exitCode = await proc.exited;
     if (exitCode !== 0) {
       return null;
     }
-
-    const output = await new Response(proc.stdout).text();
     const pgid = Number.parseInt(output.trim(), 10);
 
     return Number.isNaN(pgid) ? null : pgid;
@@ -72,7 +81,7 @@ export async function cleanupProcessTree(pid: number, gracePeriodMs = 3000): Pro
 
     // Send SIGTERM to all processes in the group (negative PGID)
     try {
-      process.kill(-pgid, "SIGTERM");
+      _cleanupDeps.kill(-pgid, "SIGTERM");
     } catch (error) {
       // ESRCH means no such process — already dead
       const err = error as NodeJS.ErrnoException;
@@ -83,7 +92,7 @@ export async function cleanupProcessTree(pid: number, gracePeriodMs = 3000): Pro
     }
 
     // Wait for graceful shutdown
-    await Bun.sleep(gracePeriodMs);
+    await _cleanupDeps.sleep(gracePeriodMs);
 
     // Re-check PGID before SIGKILL to prevent race condition
     // If the original process exited and a new process inherited its PID,
@@ -95,7 +104,7 @@ export async function cleanupProcessTree(pid: number, gracePeriodMs = 3000): Pro
     // 2. PGID hasn't changed (still the same process group)
     if (pgidAfterWait && pgidAfterWait === pgid) {
       try {
-        process.kill(-pgid, "SIGKILL");
+        _cleanupDeps.kill(-pgid, "SIGKILL");
       } catch {
         // Ignore errors — processes may have exited during the wait
       }

package/src/tdd/isolation.ts

@@ -8,6 +8,9 @@
 
 import type { IsolationCheck } from "./types";
 
+/** Injectable deps for testability — mock _isolationDeps.spawn instead of global Bun.spawn */
+export const _isolationDeps = { spawn: Bun.spawn as typeof Bun.spawn };
+
 /** Common test directory patterns */
 const TEST_PATTERNS = [/^test\//, /^tests\//, /^__tests__\//, /\.spec\.\w+$/, /\.test\.\w+$/, /\.e2e-spec\.\w+$/];
 
@@ -26,14 +29,18 @@ export function isSourceFile(filePath: string): boolean {
 
 /** Get changed files from git diff */
 export async function getChangedFiles(workdir: string, fromRef = "HEAD"): Promise<string[]> {
-  const proc = Bun.spawn(["git", "diff", "--name-only", fromRef], {
+  const proc = _isolationDeps.spawn(["git", "diff", "--name-only", fromRef], {
     cwd: workdir,
     stdout: "pipe",
     stderr: "pipe",
   });
 
+  // Use Bun.readableStreamToText — more reliable than new Response(stream).text()
+  // with both real pipes and mocked ReadableStreams across Bun versions.
+  // Must read BEFORE awaiting proc.exited to avoid stream-closed-on-exit issues.
+  const output = await Bun.readableStreamToText(proc.stdout);
   await proc.exited;
-  const output = await new Response(proc.stdout).text();
+
   return output.trim().split("\n").filter(Boolean);
 }