@nathapp/nax 0.20.0 → 0.22.0

package/src/pipeline/subscribers/interaction.ts

@@ -0,0 +1,68 @@
+// RE-ARCH: keep
+/**
+ * Interaction Subscriber (ADR-005, Phase 3 US-P3-003)
+ *
+ * Maps pipeline events to interaction trigger calls.
+ * Currently handles:
+ *   - human-review:requested → executeTrigger("human-review")
+ *
+ * Future triggers (story-ambiguity, merge-conflict, etc.) can be added
+ * by subscribing to the appropriate events.
+ *
+ * Design:
+ * - Interaction triggers MAY block (await user response) — uses emitAsync where needed
+ * - Errors are caught and logged; never rethrown to avoid blocking the pipeline
+ * - Returns unsubscribe function for cleanup
+ */
+
+import type { NaxConfig } from "../../config";
+import type { InteractionChain } from "../../interaction/chain";
+import { executeTrigger, isTriggerEnabled } from "../../interaction/triggers";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+/**
+ * Wire interaction triggers to the event bus.
+ *
+ * @param bus              - The pipeline event bus
+ * @param interactionChain - The active interaction chain (may be null)
+ * @param config           - Nax config (for isTriggerEnabled checks)
+ * @returns Unsubscribe function
+ */
+export function wireInteraction(
+  bus: PipelineEventBus,
+  interactionChain: InteractionChain | null | undefined,
+  config: NaxConfig,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+  const unsubs: UnsubscribeFn[] = [];
+
+  // human-review:requested → executeTrigger("human-review")
+  if (interactionChain && isTriggerEnabled("human-review", config)) {
+    unsubs.push(
+      bus.on("human-review:requested", (ev) => {
+        executeTrigger(
+          "human-review",
+          {
+            featureName: ev.feature ?? "",
+            storyId: ev.storyId,
+            iteration: ev.attempts ?? 0,
+            reason: ev.reason,
+          },
+          config,
+          interactionChain,
+        ).catch((err) => {
+          logger?.warn("interaction-subscriber", "human-review trigger failed", {
+            storyId: ev.storyId,
+            error: String(err),
+          });
+        });
+      }),
+    );
+  }
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}

package/src/pipeline/subscribers/reporters.ts

@@ -0,0 +1,174 @@
+// RE-ARCH: keep
+/**
+ * Reporters Subscriber (ADR-005, Phase 3 US-P3-002)
+ *
+ * Maps pipeline events to IReporter plugin methods
+ * (onRunStart, onStoryComplete, onRunEnd).
+ *
+ * Design:
+ * - Each reporter call is fire-and-forget
+ * - Errors in individual reporters are caught and logged
+ * - Returns unsubscribe function for cleanup
+ */
+
+import { getSafeLogger } from "../../logger";
+import type { PluginRegistry } from "../../plugins";
+import type { PipelineEventBus } from "../event-bus";
+import type { UnsubscribeFn } from "./hooks";
+
+/**
+ * Wire reporter plugin lifecycle events to the event bus.
+ *
+ * @param bus            - The pipeline event bus
+ * @param pluginRegistry - Plugin registry exposing getReporters()
+ * @param runId          - Current run ID (for reporter events)
+ * @param startTime      - Run start timestamp in ms (for duration calculation)
+ * @returns Unsubscribe function
+ */
+export function wireReporters(
+  bus: PipelineEventBus,
+  pluginRegistry: PluginRegistry,
+  runId: string,
+  startTime: number,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+
+  const safe = (name: string, fn: () => Promise<void>) => {
+    fn().catch((err) => logger?.warn("reporters-subscriber", `Reporter "${name}" error`, { error: String(err) }));
+  };
+
+  const unsubs: UnsubscribeFn[] = [];
+
+  // run:started → reporter.onRunStart
+  unsubs.push(
+    bus.on("run:started", (ev) => {
+      safe("onRunStart", async () => {
+        const reporters = pluginRegistry.getReporters();
+        for (const r of reporters) {
+          if (r.onRunStart) {
+            try {
+              await r.onRunStart({
+                runId,
+                feature: ev.feature,
+                totalStories: ev.totalStories,
+                startTime: new Date(startTime).toISOString(),
+              });
+            } catch (err) {
+              logger?.warn("plugins", `Reporter '${r.name}' onRunStart failed`, { error: err });
+            }
+          }
+        }
+      });
+    }),
+  );
+
+  // story:completed → reporter.onStoryComplete(status: "completed")
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      safe("onStoryComplete(completed)", async () => {
+        const reporters = pluginRegistry.getReporters();
+        for (const r of reporters) {
+          if (r.onStoryComplete) {
+            try {
+              await r.onStoryComplete({
+                runId,
+                storyId: ev.storyId,
+                status: "completed",
+                durationMs: ev.durationMs,
+                cost: ev.cost ?? 0,
+                tier: ev.modelTier ?? "balanced",
+                testStrategy: ev.testStrategy ?? "test-after",
+              });
+            } catch (err) {
+              logger?.warn("plugins", `Reporter '${r.name}' onStoryComplete failed`, { error: err });
+            }
+          }
+        }
+      });
+    }),
+  );
+
+  // story:failed → reporter.onStoryComplete(status: "failed")
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      safe("onStoryComplete(failed)", async () => {
+        const reporters = pluginRegistry.getReporters();
+        for (const r of reporters) {
+          if (r.onStoryComplete) {
+            try {
+              await r.onStoryComplete({
+                runId,
+                storyId: ev.storyId,
+                status: "failed",
+                durationMs: Date.now() - startTime,
+                cost: 0,
+                tier: "balanced",
+                testStrategy: "test-after",
+              });
+            } catch (err) {
+              logger?.warn("plugins", `Reporter '${r.name}' onStoryComplete failed`, { error: err });
+            }
+          }
+        }
+      });
+    }),
+  );
+
+  // story:paused → reporter.onStoryComplete(status: "paused")
+  unsubs.push(
+    bus.on("story:paused", (ev) => {
+      safe("onStoryComplete(paused)", async () => {
+        const reporters = pluginRegistry.getReporters();
+        for (const r of reporters) {
+          if (r.onStoryComplete) {
+            try {
+              await r.onStoryComplete({
+                runId,
+                storyId: ev.storyId,
+                status: "paused",
+                durationMs: Date.now() - startTime,
+                cost: 0,
+                tier: "balanced",
+                testStrategy: "test-after",
+              });
+            } catch (err) {
+              logger?.warn("plugins", `Reporter '${r.name}' onStoryComplete failed`, { error: err });
+            }
+          }
+        }
+      });
+    }),
+  );
+
+  // run:completed → reporter.onRunEnd
+  unsubs.push(
+    bus.on("run:completed", (ev) => {
+      safe("onRunEnd", async () => {
+        const reporters = pluginRegistry.getReporters();
+        for (const r of reporters) {
+          if (r.onRunEnd) {
+            try {
+              await r.onRunEnd({
+                runId,
+                totalDurationMs: Date.now() - startTime,
+                totalCost: ev.totalCost ?? 0,
+                storySummary: {
+                  completed: ev.passedStories,
+                  failed: ev.failedStories,
+                  skipped: 0,
+                  paused: 0,
+                },
+              });
+            } catch (err) {
+              logger?.warn("plugins", `Reporter '${r.name}' onRunEnd failed`, { error: err });
+            }
+          }
+        }
+      });
+    }),
+  );
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}

package/src/pipeline/types.ts

@@ -15,6 +15,7 @@ import type { PluginRegistry } from "../plugins/registry";
 import type { PRD, UserStory } from "../prd/types";
 import type { ReviewResult } from "../review/types";
 import type { FailureCategory } from "../tdd/types";
+import type { VerifyResult } from "../verification/orchestrator-types";
 
 /**
  * Routing result from complexity classification
@@ -82,6 +83,8 @@ export interface PipelineContext {
   prompt?: string;
   /** Agent execution result (set by executionStage) */
   agentResult?: AgentResult;
+  /** Verify result (set by verifyStage) */
+  verifyResult?: VerifyResult;
   /** Review result (set by reviewStage) */
   reviewResult?: ReviewResult;
   /** Acceptance test failures (set by acceptanceStage) */
@@ -91,6 +94,12 @@ export interface PipelineContext {
   };
   /** Story start timestamp (ISO string, set by runner before pipeline) */
   storyStartTime?: string;
+  /** Tracks how many times the rectify stage has run this pipeline (for event attempt numbers). */
+  rectifyAttempt?: number;
+  /** Tracks how many times the autofix stage has run this pipeline (for event attempt numbers). */
+  autofixAttempt?: number;
+  /** Git HEAD ref captured before agent ran this attempt (FEAT-010: precise smart-runner diff) */
+  storyGitRef?: string;
   /** Collected story metrics (set by completionStage) */
   storyMetrics?: StoryMetrics[];
   /** Whether to retry the story in lite mode after a failure */
@@ -112,7 +121,9 @@ export type StageAction =
   /** Escalate to a higher tier and retry the pipeline */
   | { action: "escalate"; reason?: string; cost?: number }
   /** Pause execution (user intervention required via queue command) */
-  | { action: "pause"; reason: string; cost?: number };
+  | { action: "pause"; reason: string; cost?: number }
+  /** Retry from a specific stage (used by rectify/autofix stages) */
+  | { action: "retry"; fromStage: string; cost?: number };
 
 /**
  * Result returned by a pipeline stage after execution.

package/src/review/orchestrator.ts

@@ -0,0 +1,105 @@
+/**
+ * Review Orchestrator (ADR-005, Phase 2)
+ *
+ * Single entry point for all post-implementation review. Delegates to the
+ * review runner and plugin reviewers. Provides a unified result.
+ *
+ * Usage:
+ *   const result = await reviewOrchestrator.review(config, workdir, executionConfig, plugins);
+ */
+
+import { spawn } from "bun";
+import type { NaxConfig } from "../config";
+import { getSafeLogger } from "../logger";
+import type { PluginRegistry } from "../plugins";
+import { runReview } from "./runner";
+import type { ReviewConfig, ReviewResult } from "./types";
+
+async function getChangedFiles(workdir: string): Promise<string[]> {
+  try {
+    const [stagedProc, unstagedProc] = [
+      spawn({ cmd: ["git", "diff", "--name-only", "--cached"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+      spawn({ cmd: ["git", "diff", "--name-only"], cwd: workdir, stdout: "pipe", stderr: "pipe" }),
+    ];
+    await Promise.all([stagedProc.exited, unstagedProc.exited]);
+    const staged = (await new Response(stagedProc.stdout).text()).trim().split("\n").filter(Boolean);
+    const unstaged = (await new Response(unstagedProc.stdout).text()).trim().split("\n").filter(Boolean);
+    return Array.from(new Set([...staged, ...unstaged]));
+  } catch {
+    return [];
+  }
+}
+
+export interface OrchestratorReviewResult {
+  /** Built-in review result (typecheck, lint, format) */
+  builtIn: ReviewResult;
+  /** Whether ALL checks passed (built-in + plugin reviewers) */
+  success: boolean;
+  /** Failure reason if success === false */
+  failureReason?: string;
+  /** Plugin reviewer hard-failure flag (determines escalate vs fail) */
+  pluginFailed: boolean;
+}
+
+export class ReviewOrchestrator {
+  /** Run built-in checks + plugin reviewers. Returns unified result. */
+  async review(
+    reviewConfig: ReviewConfig,
+    workdir: string,
+    executionConfig: NaxConfig["execution"],
+    plugins?: PluginRegistry,
+  ): Promise<OrchestratorReviewResult> {
+    const logger = getSafeLogger();
+
+    const builtIn = await runReview(reviewConfig, workdir, executionConfig);
+
+    if (!builtIn.success) {
+      return { builtIn, success: false, failureReason: builtIn.failureReason, pluginFailed: false };
+    }
+
+    if (plugins) {
+      const reviewers = plugins.getReviewers();
+      if (reviewers.length > 0) {
+        const changedFiles = await getChangedFiles(workdir);
+        const pluginResults: ReviewResult["pluginReviewers"] = [];
+
+        for (const reviewer of reviewers) {
+          logger?.info("review", `Running plugin reviewer: ${reviewer.name}`);
+          try {
+            const result = await reviewer.check(workdir, changedFiles);
+            pluginResults.push({
+              name: reviewer.name,
+              passed: result.passed,
+              output: result.output,
+              exitCode: result.exitCode,
+            });
+            if (!result.passed) {
+              builtIn.pluginReviewers = pluginResults;
+              return {
+                builtIn,
+                success: false,
+                failureReason: `plugin reviewer '${reviewer.name}' failed`,
+                pluginFailed: true,
+              };
+            }
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            pluginResults.push({ name: reviewer.name, passed: false, output: "", error: errorMsg });
+            builtIn.pluginReviewers = pluginResults;
+            return {
+              builtIn,
+              success: false,
+              failureReason: `plugin reviewer '${reviewer.name}' threw error`,
+              pluginFailed: true,
+            };
+          }
+        }
+        builtIn.pluginReviewers = pluginResults;
+      }
+    }
+
+    return { builtIn, success: true, pluginFailed: false };
+  }
+}
+
+export const reviewOrchestrator = new ReviewOrchestrator();

package/src/review/runner.ts

@@ -76,8 +76,13 @@ async function resolveCommand(
   return null;
 }
 
+/** Default timeout for review checks (lint, typecheck). BUG-039. */
+const REVIEW_CHECK_TIMEOUT_MS = 120_000;
+
 /**
- * Run a single review check
+ * Run a single review check with a hard timeout.
+ *
+ * BUG-039: Added SIGTERM + SIGKILL cleanup to prevent orphan lint/typecheck processes.
  */
 async function runCheck(check: ReviewCheckName, command: string, workdir: string): Promise<ReviewCheckResult> {
   const startTime = Date.now();
@@ -96,8 +101,38 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
       stderr: "pipe",
     });
 
+    // BUG-039: Hard timeout — kill the process if it hangs
+    let timedOut = false;
+    const timerId = setTimeout(() => {
+      timedOut = true;
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        /* already exited */
+      }
+      setTimeout(() => {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+          /* already exited */
+        }
+      }, 5000);
+    }, REVIEW_CHECK_TIMEOUT_MS);
+
     // Wait for completion
-    const result = await proc.exited;
+    const exitCode = await proc.exited;
+    clearTimeout(timerId);
+
+    if (timedOut) {
+      return {
+        check,
+        command,
+        success: false,
+        exitCode: -1,
+        output: `[nax] ${check} timed out after ${REVIEW_CHECK_TIMEOUT_MS / 1000}s`,
+        durationMs: Date.now() - startTime,
+      };
+    }
 
     // Collect output
     const stdout = await new Response(proc.stdout).text();
@@ -107,8 +142,8 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
     return {
       check,
       command,
-      success: result === 0,
-      exitCode: result,
+      success: exitCode === 0,
+      exitCode,
       output,
       durationMs: Date.now() - startTime,
     };

package/src/routing/router.ts

@@ -152,7 +152,7 @@ const LITE_TAGS = ["ui", "layout", "cli", "integration", "polyglot"];
  * - 'auto'   → existing heuristic logic, plus:
  *              if tags include ui/layout/cli/integration/polyglot → three-session-tdd-lite
  *              if security/public-api/complex/expert → three-session-tdd
- *              otherwise → test-after
+ *              otherwise → three-session-tdd-lite (test-after deprecated from auto mode)
  *
  * @param complexity - Pre-classified complexity level
  * @param title - Story title
@@ -201,8 +201,8 @@ export function determineTestStrategy(
     return hasLiteTag ? "three-session-tdd-lite" : "three-session-tdd";
   }
 
-  // Simple/medium → test-after (default)
-  return "test-after";
+  // Simple/medium → three-session-tdd-lite (FEAT-013: test-after deprecated from auto mode)
+  return "three-session-tdd-lite";
 }
 
 /** Map complexity to model tier */

package/src/routing/strategies/keyword.ts

@@ -117,7 +117,8 @@ function determineTestStrategy(
     return "three-session-tdd";
   }
 
-  return "test-after";
+  // FEAT-013: test-after deprecated from auto mode — use three-session-tdd-lite as default
+  return "three-session-tdd-lite";
 }
 
 /** Map complexity to model tier */
@@ -160,7 +161,9 @@ export const keywordStrategy: RoutingStrategy = {
       modelTier,
       testStrategy,
       reasoning:
-        reasons.length > 0 ? `three-session-tdd: ${reasons.join(", ")}` : `test-after: simple task (${complexity})`,
+        reasons.length > 0
+          ? `three-session-tdd: ${reasons.join(", ")}`
+          : `three-session-tdd-lite: simple task (${complexity})`,
     };
   },
 };

package/src/routing/strategies/llm.ts

@@ -49,6 +49,22 @@ function evictOldest(): void {
   }
 }
 
+/** Minimal proc shape returned by spawn for piped stdio. */
+export interface PipedProc {
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill(signal?: number | NodeJS.Signals): void;
+}
+
+/**
+ * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ */
+export const _deps = {
+  spawn: (cmd: string[], opts: { stdout: "pipe"; stderr: "pipe" }): PipedProc =>
+    Bun.spawn(cmd, opts) as unknown as PipedProc,
+};
+
 /**
  * Call LLM via claude CLI with timeout.
  *
@@ -69,7 +85,7 @@ async function callLlmOnce(modelTier: string, prompt: string, config: NaxConfig,
   const modelArg = modelDef.model;
 
   // Spawn claude CLI with timeout
-  const proc = Bun.spawn(["claude", "-p", prompt, "--model", modelArg], {
+  const proc = _deps.spawn(["claude", "-p", prompt, "--model", modelArg], {
     stdout: "pipe",
     stderr: "pipe",
   });
@@ -100,6 +116,16 @@ async function callLlmOnce(modelTier: string, prompt: string, config: NaxConfig,
     return result;
   } catch (err) {
     clearTimeout(timeoutId);
+    try {
+      proc.stdout.cancel();
+    } catch {
+      // ignore cancel errors
+    }
+    try {
+      proc.stderr.cancel();
+    } catch {
+      // ignore cancel errors
+    }
     proc.kill();
     throw err;
   }

package/src/tdd/prompts.ts

@@ -1,7 +1,7 @@
 import type { RectificationConfig } from "../config";
-import { createRectificationPrompt } from "../execution/rectification";
 import type { TestFailure } from "../execution/test-output-parser";
 import type { UserStory } from "../prd";
+import { createRectificationPrompt } from "../verification/rectification";
 import type { TddSessionRole } from "./types";
 
 /**

package/src/utils/git.ts

@@ -4,6 +4,48 @@
 
 import { spawn } from "bun";
 
+/**
+ * Default timeout for git subprocess calls.
+ * Prevents git from hanging indefinitely on locked repos or network mounts.
+ */
+const GIT_TIMEOUT_MS = 10_000;
+
+/**
+ * Spawn a git command with a hard timeout.
+ *
+ * Kills the process with SIGKILL after GIT_TIMEOUT_MS if it hasn't exited.
+ * Returns empty stdout and exit code 1 on timeout.
+ *
+ * @internal
+ */
+export async function gitWithTimeout(args: string[], workdir: string): Promise<{ stdout: string; exitCode: number }> {
+  const proc = Bun.spawn(["git", ...args], {
+    cwd: workdir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let timedOut = false;
+  const timerId = setTimeout(() => {
+    timedOut = true;
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Process may have already exited
+    }
+  }, GIT_TIMEOUT_MS);
+
+  const exitCode = await proc.exited;
+  clearTimeout(timerId);
+
+  if (timedOut) {
+    return { stdout: "", exitCode: 1 };
+  }
+
+  const stdout = await new Response(proc.stdout).text();
+  return { stdout, exitCode };
+}
+
 /**
  * Capture current git HEAD ref.
  *
@@ -23,17 +65,8 @@ import { spawn } from "bun";
  */
 export async function captureGitRef(workdir: string): Promise<string | undefined> {
   try {
-    const proc = spawn({
-      cmd: ["git", "rev-parse", "HEAD"],
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
+    const { stdout, exitCode } = await gitWithTimeout(["rev-parse", "HEAD"], workdir);
     if (exitCode !== 0) return undefined;
-
-    const stdout = await new Response(proc.stdout).text();
     return stdout.trim() || undefined;
   } catch {
     return undefined;
@@ -43,7 +76,7 @@ export async function captureGitRef(workdir: string): Promise<string | undefined
 /**
  * Check if a story ID appears in recent git commit messages.
  *
- * Searches the last 20 commits for commit messages containing the story ID.
+ * Searches the last N commits for commit messages containing the story ID.
  * Used for state reconciliation: if a failed story has commits in git history,
  * it means the story was partially completed and should be marked as passed.
  *
@@ -62,21 +95,12 @@ export async function captureGitRef(workdir: string): Promise<string | undefined
  */
 export async function hasCommitsForStory(workdir: string, storyId: string, maxCommits = 20): Promise<boolean> {
   try {
-    const proc = spawn({
-      cmd: ["git", "log", `-${maxCommits}`, "--oneline", "--grep", storyId],
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const exitCode = await proc.exited;
+    const { stdout, exitCode } = await gitWithTimeout(
+      ["log", `-${maxCommits}`, "--oneline", "--grep", storyId],
+      workdir,
+    );
     if (exitCode !== 0) return false;
-
-    const stdout = await new Response(proc.stdout).text();
-    const commits = stdout.trim();
-
-    // If any commits found, return true
-    return commits.length > 0;
+    return stdout.trim().length > 0;
   } catch {
     return false;
   }

package/src/verification/executor.ts

@@ -17,8 +17,14 @@ import type { TestExecutionResult } from "./types";
  */
 async function drainWithDeadline(proc: Subprocess, deadlineMs: number): Promise<string> {
   const EMPTY = Symbol("timeout");
-  const race = <T>(p: Promise<T>) =>
-    Promise.race([p, new Promise<typeof EMPTY>((r) => setTimeout(() => r(EMPTY), deadlineMs))]);
+  const race = <T>(p: Promise<T>) => {
+    // BUG-039: Store timer handle so it can be cleared after race resolves (prevent leak)
+    let timerId: ReturnType<typeof setTimeout>;
+    const timeoutPromise = new Promise<typeof EMPTY>((r) => {
+      timerId = setTimeout(() => r(EMPTY), deadlineMs);
+    });
+    return Promise.race([p, timeoutPromise]).finally(() => clearTimeout(timerId));
+  };
 
   let out = "";
   try {

package/src/verification/index.ts

@@ -8,5 +8,5 @@
 export * from "./types";
 export * from "./executor";
 export * from "./parser";
-export * from "./gate";
+export * from "./runners";
 export * from "./rectification";