@nathapp/nax 0.22.2 → 0.22.4

package/README.md

@@ -223,14 +223,33 @@ Config is layered — project overrides global:
   },
   "quality": {
     "commands": {
-      "test": "bun test",
+      "test": "bun test test/ --timeout=60000",
+      "testScoped": "bun test --timeout=60000 {{files}}",
       "lint": "bun run lint",
-      "typecheck": "bun x tsc --noEmit"
+      "typecheck": "bun x tsc --noEmit",
+      "lintFix": "bun x biome check --fix src/",
+      "formatFix": "bun x biome format --write src/"
     }
   }
 }
 ```
 
+### Scoped Test Command
+
+By default, nax runs scoped tests (per-story verification) by appending discovered test files to the `test` command. This can produce incorrect commands when the base command includes a directory path (e.g. `bun test test/`), since the path is not replaced — it is appended alongside it.
+
+Use `testScoped` to define the exact scoped test command with a `{{files}}` placeholder:
+
+| Runner | `test` | `testScoped` |
+|:-------|:-------|:-------------|
+| Bun | `bun test test/ --timeout=60000` | `bun test --timeout=60000 {{files}}` |
+| Jest | `npx jest` | `npx jest -- {{files}}` |
+| pytest | `pytest tests/` | `pytest {{files}}` |
+| cargo | `cargo test` | `cargo test {{files}}` |
+| go | `go test ./...` | `go test {{files}}` |
+
+If `testScoped` is not configured, nax falls back to a heuristic that replaces the last path-like token in the `test` command. **Recommended:** always configure `testScoped` explicitly to avoid surprises.
+
 **TDD strategy options:**
 
 | Value | Behaviour |

package/docs/ROADMAP.md

@@ -118,28 +118,31 @@
 
 ---
 
-## v0.22.2 — Status File Consolidation
+## v0.23.0 — Status File Consolidation
 
 **Theme:** Auto-write status.json to well-known paths, align readers, remove dead options
-**Status:** 🔲 Planned
+**Status:** 🔄 In Progress (self-dev running, SFC-001 ✅)
 **Spec:** [docs/specs/status-file-consolidation.md](specs/status-file-consolidation.md)
-**Pre-requisite for:** v0.23.0 (Central Run Registry)
+**Pre-requisite for:** v0.24.0 (Central Run Registry)
 
 ### Stories
-- [ ] **SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`
+- [x] ~~**SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`~~
+- [ ] **BUG-043:** Fix scoped test command construction + add `testScoped` config with `{{files}}` template
+- [ ] **BUG-044:** Log scoped and full-suite test commands at info level in verify stage
 - [ ] **SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`
 - [ ] **SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths
 - [ ] **SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references
 
 ---
 
-## v0.23.0 — Central Run Registry
+## v0.24.0 — Central Run Registry
 
 **Theme:** Global run index across all projects — single source of truth for all nax run history
 **Status:** 🔲 Planned
 **Spec:** [docs/specs/central-run-registry.md](specs/central-run-registry.md)
 
 ### Stories
+- [ ] **CRR-000:** `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`, writes lifecycle events to `~/.nax/events/<project>/events.jsonl` (machine-readable completion signal for watchdog/CI)
 - [ ] **CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)
 - [ ] **CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`
 - [ ] **CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory
@@ -221,6 +224,7 @@
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
 | v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
+| v0.22.2 | Routing Stability + SFC-001 | 2026-03-07 | BUG-040 floating outputPromise crash on LLM timeout retry; SFC-001 auto-write status.json |
 | v0.22.1 | Pipeline Re-Architecture | 2026-03-07 | VerificationOrchestrator, EventBus, new stages (rectify/autofix/regression/deferred-regression), post-run SSOT. 2264 pass |
 | v0.20.0 | Verification Architecture v2 | 2026-03-06 | Deferred regression gate, remove duplicate tests, BUG-037 |
 | v0.19.0 | Hardening & Compliance | 2026-03-04 | SEC-1 to SEC-5, BUG-1, Node.js API removal, _deps rollout |
@@ -283,12 +287,15 @@
 
 - [x] ~~**BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. Fixed: `.slice(-20)` tail — shipped in v0.22.1 (re-arch phase 2).~~
 - [x] ~~**BUG-038:** `smart-runner` over-matching when global defaults change. Fixed by FEAT-010 (v0.21.0) — per-attempt `storyGitRef` baseRef tracking; `git diff <baseRef>..HEAD` prevents cross-story file pollution.~~
+- [ ] **BUG-043:** Scoped test command appends files instead of replacing path — `runners.ts:scoped()` concatenates `scopedTestPaths` to full-suite command, resulting in `bun test test/ --timeout=60000 /path/to/file.ts` (runs everything). Fix: use `testScoped` config with `{{files}}` template, fall back to `buildSmartTestCommand()` heuristic. **Location:** `src/verification/runners.ts:scoped()`
+- [ ] **BUG-044:** Scoped/full-suite test commands not logged — no visibility into what command was actually executed during verify stage. Fix: log at info level before execution.
+
 ### Features
 - [x] ~~`nax unlock` command~~
 - [x] ~~Constitution file support~~
 - [x] ~~Per-story testStrategy override — v0.18.1~~
 - [x] ~~Smart Test Runner — v0.18.2~~
-- [ ] **Central Run Registry** — moved to v0.23.0
+- [ ] **Central Run Registry** — moved to v0.24.0
 - [x] ~~**BUN-001:** Bun PTY Migration — replace `node-pty` with `Bun.spawn` (piped stdio). Shipped in v0.18.5.~~
 - [ ] **CI-001:** CI Memory Optimization — parallel test sharding for 1GB runners
 - [ ] **CI-001:** CI Memory Optimization — parallel test sharding to pass on 1GB runners (currently requires 8GB). Evaluate `bun test --shard` when stable.

package/docs/specs/central-run-registry.md

@@ -1,6 +1,6 @@
 # Central Run Registry — Spec
 
-**Version:** v0.23.0
+**Version:** v0.24.0
 **Status:** Planned
 
 ---
@@ -60,6 +60,18 @@ A global `~/.nax/runs/` registry that indexes every nax run via path references
 
 ## Implementation
 
+### CRR-000: Events File Writer (new subscriber)
+
+- New module: `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`
+- Writes to `~/.nax/events/<project>/events.jsonl` — one JSON line per lifecycle event
+- Listens to event bus: `run:started`, `story:started`, `story:completed`, `story:failed`, `run:completed`
+- Each line: `{"ts", "event", "runId", "feature", "project", "storyId?"}`
+- `run:completed` emits an `on-complete` event — used by external tooling (watchdog) to distinguish clean exit from crash
+- Best-effort: never throw/block the main run on write failure
+- Directory created on first write
+
+**Motivation:** External tools (nax-watchdog, CI integrations) need a reliable signal that nax exited gracefully. Currently nax writes no machine-readable completion event, causing false crash reports. This also provides the foundation for CRR — `meta.json` can reference the events file path.
+
 ### CRR-001: Registry Writer (new subscriber)
 
 - New module: `src/execution/run-registry.ts` — `registerRun(meta)`, `getRunsDir()`

package/nax/config.json

@@ -52,7 +52,7 @@
       "fallbackToKeywords": true,
       "cacheDecisions": true,
       "mode": "hybrid",
-      "timeoutMs": 15000
+      "timeoutMs": 60000
     }
   },
   "execution": {
@@ -84,7 +84,8 @@
     "commands": {
       "test": "bun run test",
       "typecheck": "bun run typecheck",
-      "lint": "bun run lint"
+      "lint": "bun run lint",
+      "testScoped": "bun test --timeout=60000 {{files}}"
     },
     "forceExit": false,
     "detectOpenHandles": true,
@@ -150,4 +151,4 @@
       "scopeToStory": true
     }
   }
-}
+}

package/nax/features/post-rearch-bugfix/prd.json

@@ -0,0 +1,137 @@
+{
+  "project": "nax",
+  "branchName": "feat/post-rearch-bugfix",
+  "feature": "post-rearch-bugfix",
+  "version": "0.22.3",
+  "description": "Fix all critical and key high-priority bugs found in post-re-architecture code review. Stream deadlocks, unhandled rejections, signal handler safety, lock file reliability, interaction system, parallel executor race, and error swallowing.",
+  "userStories": [
+    {
+      "id": "FIX-C1",
+      "title": "Fix stream deadlock in acceptance and autofix stages",
+      "description": "In src/pipeline/stages/acceptance.ts (line ~136) and src/pipeline/stages/autofix.ts (line ~116), the code awaits proc.exited BEFORE reading stdout/stderr. When output exceeds the 64KB OS pipe buffer, the child blocks on write and proc.exited never resolves, causing a silent deadlock. Fix: use Promise.all([proc.exited, new Response(proc.stdout).text(), new Response(proc.stderr).text()]) to read streams concurrently with exit.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "acceptance.ts reads stdout/stderr concurrently with proc.exited using Promise.all",
+        "autofix.ts reads stdout/stderr concurrently with proc.exited using Promise.all",
+        "No sequential await proc.exited before stream reads in either file",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C2",
+      "title": "Fix emitAsync never called for human-in-the-loop interaction",
+      "description": "In src/execution/pipeline-result-handler.ts (line ~151), human-review:requested is emitted via fire-and-forget emit() instead of emitAsync(). The emitAsync() method in src/pipeline/subscribers/interaction.ts was specifically designed to wait for human response but is never called anywhere. The pipeline races past without waiting for human input. Fix: use await pipelineEventBus.emitAsync() for human-review events.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "human-review:requested event uses emitAsync instead of emit",
+        "Pipeline waits for human response before continuing",
+        "emitAsync is properly awaited at the call site",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C5",
+      "title": "Fix timeoutPromise unhandled rejection in LLM routing",
+      "description": "In src/routing/strategies/llm.ts, the timeoutPromise created in callLlmOnce() uses reject() but if the timer fires between race resolution and clearTimeout, the rejection is unhandled. Add timeoutPromise.catch(() => {}) right after creation, or restructure to use a clearable pattern that does not reject.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "timeoutPromise rejection is always handled (no unhandled rejection possible)",
+        "Existing BUG-040 tests still pass",
+        "Add test verifying no unhandled rejection when timeout fires after successful completion"
+      ]
+    },
+    {
+      "id": "FIX-C3",
+      "title": "Fix TDZ crash in signal handler — prd accessed before initialization",
+      "description": "In src/execution/runner.ts around line 123, the crash handler closure references prd which is declared later (~line 134). If SIGTERM arrives during setupRun(), accessing prd throws ReferenceError. Fix: declare let prd: PRD | undefined before the crash handler setup, and add a null guard in the getter: () => prd ? countStories(prd).total : 0.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "prd variable declared before crash handler registration",
+        "Crash handler getter has null guard for prd",
+        "SIGTERM during setupRun does not throw ReferenceError",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C6",
+      "title": "Fix parallel executor shared mutable state race condition",
+      "description": "In src/execution/parallel.ts around line 191 and 213, results.totalCost += ... and executing.splice(index, 1) are mutated concurrently from parallel promises. The splice inside .finally() can corrupt array indices when two promises resolve in the same microtask batch. Fix: replace executing array with a Set pattern; use executing.delete(p) instead of splice.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "executing collection uses Set instead of Array with splice",
+        "totalCost accumulation is safe against concurrent updates",
+        "No array index corruption possible when promises resolve simultaneously",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C7",
+      "title": "Fix corrupt lock file permanently blocking all runs",
+      "description": "In src/execution/lock.ts around line 48-79, if JSON.parse(lockContent) throws on a corrupted lock file, the error propagates to the outer catch which returns false, the caller interprets this as another process is running. Fix: wrap JSON.parse in its own try-catch; treat unparseable lock files as stale and delete them.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Corrupt/unparseable lock file is treated as stale and deleted",
+        "A warning is logged when a corrupt lock file is found",
+        "nax can start normally after encountering a corrupt lock file",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C8",
+      "title": "Fix empty catch in drainWithDeadline swallowing all errors",
+      "description": "In src/verification/executor.ts around line 36-39, the catch block in drainWithDeadline swallows ALL exceptions including TypeError, OutOfMemoryError etc. Output silently becomes empty string with no diagnostic. Fix: narrow the catch to expected stream-destroyed errors only; log unexpected errors at debug level.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Expected stream errors (after kill) are still silently handled",
+        "Unexpected errors are logged at debug level",
+        "Output defaults to empty string on expected stream errors",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-H16",
+      "title": "Fix lock file not released when setupRun fails",
+      "description": "In src/execution/lifecycle/run-setup.ts around line 153-193, the lock is acquired during setupRun but if setupRun fails, it is outside the runner main try block so the lock is never released. Fix: ensure lock release in a finally block within setupRun, or move lock acquisition inside the runner try/finally.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Lock file is released when setupRun throws an error",
+        "Lock file is released on all error paths during setup",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C4",
+      "title": "Replace uncancellable Bun.sleep timer in executor",
+      "description": "In src/verification/executor.ts around line 97-100, Bun.sleep() is used for the timeout promise but cannot be cancelled. When the process exits quickly, the sleep continues for the full timeoutMs. Fix: replace with a clearable setTimeout-based promise pattern, clearing the timer in the success path.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Timeout in executeWithTimeout uses clearable setTimeout not Bun.sleep",
+        "Timer is cleared when process exits before timeout",
+        "No timer leak after successful execution",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-H5",
+      "title": "Add hard deadline to async signal handlers",
+      "description": "In src/execution/crash-recovery.ts around line 149-170, signal handlers contain multiple await operations. If any hangs, process.exit() is never reached. Fix: add a setTimeout hard deadline (e.g. 10s) at the top of each signal handler that calls process.exit() as a fallback.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "SIGTERM handler has a hard deadline timeout (10s) that calls process.exit",
+        "SIGINT handler has the same hard deadline",
+        "Hard deadline fires even if async operations hang",
+        "Existing tests pass"
+      ]
+    }
+  ]
+}

package/nax/features/status-file-consolidation/prd.json

@@ -10,13 +10,36 @@
       "title": "Auto-write project-level status",
       "description": "Remove --status-file CLI option. StatusWriter always writes to <workdir>/nax/status.json automatically. In bin/nax.ts, remove --status-file option and compute statusFile = join(workdir, 'nax', 'status.json'). In runner.ts, statusFile is no longer optional. In status-writer.ts, remove the if (!this.statusFile) guard in update().",
       "complexity": "medium",
-      "status": "passed",
+      "status": "pending",
       "acceptanceCriteria": [
         "Running nax without --status-file flag writes nax/status.json automatically",
         "nax/status.json contains valid NaxStatusFile schema with run.id, run.status, progress counts",
         "--status-file CLI option no longer exists",
         "StatusWriter.update() always writes (no no-op guard on missing statusFile)"
-      ]
+      ],
+      "attempts": 0,
+      "priorErrors": [
+        "Attempt 1 failed with model tier: fast: Review failed: test failed (exit code -1)"
+      ],
+      "priorFailures": [
+        {
+          "attempt": 1,
+          "modelTier": "fast",
+          "stage": "escalation",
+          "summary": "Failed with tier fast, escalating to next tier",
+          "timestamp": "2026-03-07T06:22:18.122Z"
+        }
+      ],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 1,
+      "routing": {
+        "complexity": "medium",
+        "modelTier": "balanced",
+        "testStrategy": "test-after",
+        "reasoning": "Straightforward refactor: remove CLI option, hardcode path computation, remove null guard across 3 files"
+      }
     },
     {
       "id": "SFC-002",
@@ -29,12 +52,19 @@
         "After a failed run, nax/features/<feature>/status.json exists with status 'failed'",
         "After a crash, nax/features/<feature>/status.json exists with status 'crashed'",
         "Feature status.json uses the same NaxStatusFile schema as project-level"
-      ]
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 1
     },
     {
       "id": "SFC-003",
       "title": "Align status readers",
-      "description": "Make nax status read project-level status from nax/status.json for currently running info. Make nax diagnose read from nax/status.json instead of .nax-status.json. status-features.ts loadStatusFile() already reads <featureDir>/status.json which SFC-002 now writes \u2014 no change needed for feature-level reads.",
+      "description": "Make nax status read project-level status from nax/status.json for currently running info. Make nax diagnose read from nax/status.json instead of .nax-status.json. status-features.ts loadStatusFile() already reads <featureDir>/status.json which SFC-002 now writes — no change needed for feature-level reads.",
       "complexity": "simple",
       "status": "pending",
       "acceptanceCriteria": [
@@ -42,7 +72,14 @@
         "nax status shows per-feature historical status from nax/features/<feature>/status.json",
         "nax diagnose reads from nax/status.json (not .nax-status.json)",
         "No references to .nax-status.json remain in codebase"
-      ]
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 1
     },
     {
       "id": "SFC-004",
@@ -55,7 +92,15 @@
         "No references to .nax-status.json in codebase",
         "RunOptions.statusFile is required (not optional)",
         "All existing tests pass"
-      ]
+      ],
+      "attempts": 0,
+      "priorErrors": [],
+      "priorFailures": [],
+      "escalations": [],
+      "dependencies": [],
+      "tags": [],
+      "storyPoints": 1
     }
-  ]
+  ],
+  "updatedAt": "2026-03-07T06:22:18.122Z"
 }

package/nax/status.json

@@ -1,27 +1,37 @@
 {
   "version": 1,
   "run": {
-    "id": "run-2026-03-05T02-37-04-540Z",
-    "feature": "nax-compliance",
-    "startedAt": "2026-03-05T02:37:04.540Z",
-    "status": "stalled",
+    "id": "run-2026-03-07T06-14-21-018Z",
+    "feature": "status-file-consolidation",
+    "startedAt": "2026-03-07T06:14:21.018Z",
+    "status": "crashed",
     "dryRun": false,
-    "pid": 814245
+    "pid": 217461,
+    "crashedAt": "2026-03-07T06:22:36.300Z",
+    "crashSignal": "SIGTERM"
   },
   "progress": {
-    "total": 1,
+    "total": 4,
     "passed": 0,
-    "failed": 1,
+    "failed": 0,
     "paused": 0,
     "blocked": 0,
-    "pending": 0
+    "pending": 4
   },
   "cost": {
     "spent": 0,
-    "limit": 8
+    "limit": 3
   },
-  "current": null,
-  "iterations": 3,
-  "updatedAt": "2026-03-05T02:38:46.469Z",
-  "durationMs": 101929
+  "current": {
+    "storyId": "SFC-002",
+    "title": "Write feature-level status on run end",
+    "complexity": "medium",
+    "tddStrategy": "test-after",
+    "model": "balanced",
+    "attempt": 1,
+    "phase": "routing"
+  },
+  "iterations": 0,
+  "updatedAt": "2026-03-07T06:22:36.300Z",
+  "durationMs": 495282
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.22.2",
+  "version": "0.22.4",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
@@ -44,4 +44,4 @@
     "tdd",
     "coding"
   ]
-}
+}

package/src/config/types.ts

@@ -140,6 +140,8 @@ export interface QualityConfig {
     typecheck?: string;
     lint?: string;
     test?: string;
+    /** Scoped test command template with {{files}} placeholder (e.g., "bun test --timeout=60000 {{files}}") */
+    testScoped?: string;
     /** Auto-fix lint errors (e.g., "biome check --fix") */
     lintFix?: string;
     /** Auto-fix formatting (e.g., "biome format --write") */

package/src/execution/crash-recovery.ts

@@ -147,6 +147,12 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
 
   // Signal handler
   const handleSignal = async (signal: NodeJS.Signals) => {
+    // Hard deadline: force exit if any async operation hangs (FIX-H5)
+    const hardDeadline = setTimeout(() => {
+      process.exit(128 + getSignalNumber(signal));
+    }, 10_000);
+    if (hardDeadline.unref) hardDeadline.unref();
+
     logger?.error("crash-recovery", `Received ${signal}, shutting down...`, { signal });
 
     // Kill all spawned agent processes
@@ -166,6 +172,7 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Stop heartbeat
     stopHeartbeat();
 
+    clearTimeout(hardDeadline);
     // Exit cleanly
     process.exit(128 + getSignalNumber(signal));
   };

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

@@ -26,7 +26,7 @@ import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
 import { loadPRD } from "../../prd";
 import { installCrashHandlers } from "../crash-recovery";
-import { acquireLock, hookCtx } from "../helpers";
+import { acquireLock, hookCtx, releaseLock } from "../helpers";
 import { PidRegistry } from "../pid-registry";
 import { StatusWriter } from "../status-writer";
 
@@ -157,48 +157,56 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     throw new LockAcquisitionError(workdir);
   }
 
-  // Load plugins (before try block so it's accessible in finally)
-  const globalPluginsDir = path.join(os.homedir(), ".nax", "plugins");
-  const projectPluginsDir = path.join(workdir, "nax", "plugins");
-  const configPlugins = config.plugins || [];
-  const pluginRegistry = await loadPlugins(globalPluginsDir, projectPluginsDir, configPlugins, workdir);
-
-  // Log plugins loaded
-  logger?.info("plugins", `Loaded ${pluginRegistry.plugins.length} plugins`, {
-    plugins: pluginRegistry.plugins.map((p) => ({ name: p.name, version: p.version, provides: p.provides })),
-  });
+  // Everything after lock acquisition is wrapped in try-catch to ensure
+  // the lock is released if any setup step fails (FIX-H16)
+  try {
+    // Load plugins (before try block so it's accessible in finally)
+    const globalPluginsDir = path.join(os.homedir(), ".nax", "plugins");
+    const projectPluginsDir = path.join(workdir, "nax", "plugins");
+    const configPlugins = config.plugins || [];
+    const pluginRegistry = await loadPlugins(globalPluginsDir, projectPluginsDir, configPlugins, workdir);
+
+    // Log plugins loaded
+    logger?.info("plugins", `Loaded ${pluginRegistry.plugins.length} plugins`, {
+      plugins: pluginRegistry.plugins.map((p) => ({ name: p.name, version: p.version, provides: p.provides })),
+    });
 
-  // Log run start
-  const routingMode = config.routing.llm?.mode ?? "hybrid";
-  logger?.info("run.start", `Starting feature: ${feature}`, {
-    runId,
-    feature,
-    workdir,
-    dryRun,
-    routingMode,
-  });
+    // Log run start
+    const routingMode = config.routing.llm?.mode ?? "hybrid";
+    logger?.info("run.start", `Starting feature: ${feature}`, {
+      runId,
+      feature,
+      workdir,
+      dryRun,
+      routingMode,
+    });
 
-  // Fire on-start hook
-  await fireHook(hooks, "on-start", hookCtx(feature), workdir);
+    // Fire on-start hook
+    await fireHook(hooks, "on-start", hookCtx(feature), workdir);
 
-  // Initialize run: check agent, reconcile state, validate limits
-  const { initializeRun } = await import("./run-initialization");
-  const initResult = await initializeRun({
-    config,
-    prdPath,
-    workdir,
-    dryRun,
-  });
-  prd = initResult.prd;
-  const counts = initResult.storyCounts;
+    // Initialize run: check agent, reconcile state, validate limits
+    const { initializeRun } = await import("./run-initialization");
+    const initResult = await initializeRun({
+      config,
+      prdPath,
+      workdir,
+      dryRun,
+    });
+    prd = initResult.prd;
+    const counts = initResult.storyCounts;
 
-  return {
-    statusWriter,
-    pidRegistry,
-    cleanupCrashHandlers,
-    pluginRegistry,
-    prd,
-    storyCounts: counts,
-    interactionChain,
-  };
+    return {
+      statusWriter,
+      pidRegistry,
+      cleanupCrashHandlers,
+      pluginRegistry,
+      prd,
+      storyCounts: counts,
+      interactionChain,
+    };
+  } catch (error) {
+    // Release lock before re-throwing so the directory isn't permanently locked
+    await releaseLock(workdir);
+    throw error;
+  }
 }

package/src/execution/lock.ts

@@ -49,22 +49,38 @@ export async function acquireLock(workdir: string): Promise<boolean> {
     if (exists) {
       // Read lock data
       const lockContent = await lockFile.text();
-      const lockData = JSON.parse(lockContent);
-      const lockPid = lockData.pid;
-
-      // Check if the process is still alive
-      if (isProcessAlive(lockPid)) {
-        // Process is alive, lock is valid
-        return false;
+      let lockData: { pid: number };
+      try {
+        lockData = JSON.parse(lockContent);
+      } catch {
+        // Corrupt/unparseable lock file — treat as stale and delete
+        const logger = getSafeLogger();
+        logger?.warn("execution", "Corrupt lock file detected, removing", {
+          lockPath,
+        });
+        const fs = await import("node:fs/promises");
+        await fs.unlink(lockPath).catch(() => {});
+        // Fall through to create a new lock
+        lockData = undefined as unknown as { pid: number };
       }
 
-      // Process is dead, remove stale lock
-      const logger = getSafeLogger();
-      logger?.warn("execution", "Removing stale lock", {
-        pid: lockPid,
-      });
-      const fs = await import("node:fs/promises");
-      await fs.unlink(lockPath).catch(() => {});
+      if (lockData) {
+        const lockPid = lockData.pid;
+
+        // Check if the process is still alive
+        if (isProcessAlive(lockPid)) {
+          // Process is alive, lock is valid
+          return false;
+        }
+
+        // Process is dead, remove stale lock
+        const logger = getSafeLogger();
+        logger?.warn("execution", "Removing stale lock", {
+          pid: lockPid,
+        });
+        const fs = await import("node:fs/promises");
+        await fs.unlink(lockPath).catch(() => {});
+      }
     }
 
     // Create lock file atomically using exclusive create (O_CREAT | O_EXCL)

package/src/execution/parallel.ts

@@ -180,8 +180,7 @@ async function executeParallelBatch(
   }
 
   // Execute stories in parallel with concurrency limit
-  const executing: Promise<void>[] = [];
-  let activeCount = 0;
+  const executing = new Set<Promise<void>>();
 
   for (const { story, worktreePath } of worktreeSetup) {
     const routing = routeTask(story.title, story.description, story.acceptanceCriteria, story.tags, config);
@@ -205,19 +204,13 @@ async function executeParallelBatch(
         }
       })
       .finally(() => {
-        activeCount--;
-        // BUG-4 fix: Remove completed promise from executing array
-        const index = executing.indexOf(executePromise);
-        if (index > -1) {
-          executing.splice(index, 1);
-        }
+        executing.delete(executePromise);
       });
 
-    executing.push(executePromise);
-    activeCount++;
+    executing.add(executePromise);
 
     // Wait if we've hit the concurrency limit
-    if (activeCount >= maxConcurrency) {
+    if (executing.size >= maxConcurrency) {
       await Promise.race(executing);
     }
   }

package/src/execution/pipeline-result-handler.ts

@@ -148,7 +148,7 @@ export async function handlePipelineFailure(
       });
 
       if (ctx.story.attempts !== undefined && ctx.story.attempts >= ctx.config.execution.rectification.maxRetries) {
-        pipelineEventBus.emit({
+        await pipelineEventBus.emitAsync({
           type: "human-review:requested",
           storyId: ctx.story.id,
           reason: pipelineResult.reason || "Max retries exceeded",

package/src/execution/runner.ts

@@ -99,6 +99,9 @@ export async function run(options: RunOptions): Promise<RunResult> {
 
   const logger = getSafeLogger();
 
+  // Declare prd before crash handler setup to avoid TDZ if SIGTERM arrives during setupRun
+  let prd: Awaited<ReturnType<typeof import("./lifecycle/run-setup").setupRun>>["prd"] | undefined;
+
   // ── Execute initial setup phase ──────────────────────────────────────────────
   const { setupRun } = await import("./lifecycle/run-setup");
   const setupResult = await setupRun({
@@ -120,7 +123,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     getIterations: () => iterations,
     // BUG-017: Pass getters for run.complete event on SIGTERM
     getStoriesCompleted: () => storiesCompleted,
-    getTotalStories: () => countStories(prd).total,
+    getTotalStories: () => (prd ? countStories(prd).total : 0),
   });
 
   const {
@@ -131,7 +134,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     storyCounts: counts,
     interactionChain,
   } = setupResult;
-  let prd = setupResult.prd;
+  prd = setupResult.prd;
 
   try {
     // ── Output run header in headless mode ─────────────────────────────────

package/src/pipeline/stages/acceptance.ts

@@ -133,9 +133,11 @@ export const acceptanceStage: PipelineStage = {
       stderr: "pipe",
     });
 
-    const exitCode = await proc.exited;
-    const stdout = await new Response(proc.stdout).text();
-    const stderr = await new Response(proc.stderr).text();
+    const [exitCode, stdout, stderr] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
 
     // Combine stdout and stderr for parsing
     const output = `${stdout}\n${stderr}`;

package/src/pipeline/stages/autofix.ts

@@ -113,9 +113,11 @@ interface CommandResult {
 async function runCommand(cmd: string, cwd: string): Promise<CommandResult> {
   const parts = cmd.split(/\s+/);
   const proc = Bun.spawn(parts, { cwd, stdout: "pipe", stderr: "pipe" });
-  const exitCode = await proc.exited;
-  const stdout = await new Response(proc.stdout).text();
-  const stderr = await new Response(proc.stderr).text();
+  const [exitCode, stdout, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
   return { exitCode, output: `${stdout}\n${stderr}` };
 }
 

package/src/pipeline/stages/verify.ts

@@ -31,6 +31,18 @@ function coerceSmartTestRunner(val: boolean | SmartTestRunnerConfig | undefined)
   return val;
 }
 
+/**
+ * Build the scoped test command from discovered test files.
+ * Uses the testScoped template (with {{files}} placeholder) if configured,
+ * otherwise falls back to buildSmartTestCommand heuristic.
+ */
+function buildScopedCommand(testFiles: string[], baseCommand: string, testScopedTemplate?: string): string {
+  if (testScopedTemplate) {
+    return testScopedTemplate.replace("{{files}}", testFiles.join(" "));
+  }
+  return _smartRunnerDeps.buildSmartTestCommand(testFiles, baseCommand);
+}
+
 export const verifyStage: PipelineStage = {
   name: "verify",
   enabled: () => true,
@@ -46,6 +58,7 @@ export const verifyStage: PipelineStage = {
 
     // Skip verification if no test command is configured
     const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test;
+    const testScopedTemplate = ctx.config.quality.commands.testScoped;
     if (!testCommand) {
       logger.debug("verify", "Skipping verification (no test command configured)", { storyId: ctx.story.id });
       return { action: "continue" };
@@ -68,7 +81,7 @@ export const verifyStage: PipelineStage = {
         logger.info("verify", `[smart-runner] Pass 1: path convention matched ${pass1Files.length} test files`, {
           storyId: ctx.story.id,
         });
-        effectiveCommand = _smartRunnerDeps.buildSmartTestCommand(pass1Files, testCommand);
+        effectiveCommand = buildScopedCommand(pass1Files, testCommand, testScopedTemplate);
         isFullSuite = false;
       } else if (smartRunnerConfig.fallback === "import-grep") {
         // Pass 2: import-grep fallback
@@ -81,7 +94,7 @@ export const verifyStage: PipelineStage = {
           logger.info("verify", `[smart-runner] Pass 2: import-grep matched ${pass2Files.length} test files`, {
             storyId: ctx.story.id,
           });
-          effectiveCommand = _smartRunnerDeps.buildSmartTestCommand(pass2Files, testCommand);
+          effectiveCommand = buildScopedCommand(pass2Files, testCommand, testScopedTemplate);
           isFullSuite = false;
         }
       }
@@ -102,6 +115,12 @@ export const verifyStage: PipelineStage = {
       });
     }
 
+    // BUG-044: Log the effective command for observability
+    logger.info("verify", isFullSuite ? "Running full suite" : "Running scoped tests", {
+      storyId: ctx.story.id,
+      command: effectiveCommand,
+    });
+
     // Use unified regression gate (includes 2s wait for agent process cleanup)
     const result = await _verifyDeps.regression({
       workdir: ctx.workdir,

package/src/routing/strategies/llm.ts

@@ -98,6 +98,8 @@ async function callLlmOnce(modelTier: string, prompt: string, config: NaxConfig,
       reject(new Error(`LLM call timeout after ${timeoutMs}ms`));
     }, timeoutMs);
   });
+  // Prevent unhandled rejection if timer fires between race resolution and clearTimeout
+  timeoutPromise.catch(() => {});
 
   const outputPromise = (async () => {
     const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
@@ -116,20 +118,16 @@ async function callLlmOnce(modelTier: string, prompt: string, config: NaxConfig,
     return result;
   } catch (err) {
     clearTimeout(timeoutId);
-    // Silence the floating outputPromise — after kill() the proc exits non-zero,
-    // causing outputPromise to throw. Without this, it becomes an unhandled rejection.
+    // Silence the floating outputPromise BEFORE killing the process.
+    // proc.kill() causes piped streams to error → Response.text() rejects →
+    // outputPromise rejects. The .catch() must be attached first to prevent
+    // an unhandled rejection that crashes nax via crash-recovery.
     outputPromise.catch(() => {});
-    try {
-      proc.stdout.cancel();
-    } catch {
-      // ignore cancel errors — stream may already be locked by Response
-    }
-    try {
-      proc.stderr.cancel();
-    } catch {
-      // ignore cancel errors — stream may already be locked by Response
-    }
     proc.kill();
+    // DO NOT call proc.stdout.cancel() / proc.stderr.cancel() here.
+    // The streams are locked by Response.text() readers. Per Web Streams spec,
+    // cancel() on a locked stream returns a rejected Promise (not a sync throw),
+    // which becomes an unhandled rejection. Let proc.kill() handle cleanup.
     throw err;
   }
 }

package/src/verification/executor.ts

@@ -34,8 +34,16 @@ async function drainWithDeadline(proc: Subprocess, deadlineMs: number): Promise<
     if (o !== EMPTY) out += o;
     if (e !== EMPTY) out += (out ? "\n" : "") + e;
   } catch (error) {
-    // Streams may already be destroyed - this is expected after kill
-    // No logger available in this utility function context
+    // Expected: streams destroyed after kill (e.g. TypeError from closed ReadableStream)
+    const isExpectedStreamError =
+      error instanceof TypeError ||
+      (error instanceof Error && /abort|cancel|close|destroy|locked/i.test(error.message));
+    if (!isExpectedStreamError) {
+      const { getSafeLogger } = await import("../logger");
+      getSafeLogger()?.debug("executor", "Unexpected error draining process output", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
   }
   return out;
 }
@@ -93,15 +101,19 @@ export async function executeWithTimeout(
   const timeoutMs = timeoutSeconds * 1000;
 
   let timedOut = false;
+  const timer = { id: undefined as ReturnType<typeof setTimeout> | undefined };
 
-  const timeoutPromise = (async () => {
-    await Bun.sleep(timeoutMs);
-    timedOut = true;
-  })();
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timer.id = setTimeout(() => {
+      timedOut = true;
+      resolve();
+    }, timeoutMs);
+  });
 
   const processPromise = proc.exited;
 
   const raceResult = await Promise.race([processPromise, timeoutPromise]);
+  clearTimeout(timer.id);
 
   if (timedOut) {
     const pid = proc.pid;

package/src/verification/orchestrator-types.ts

@@ -23,6 +23,8 @@ export type VerifyStrategy = "scoped" | "regression" | "deferred-regression" | "
 export interface VerifyContext {
   workdir: string;
   testCommand: string;
+  /** Scoped test command template with {{files}} placeholder — overrides buildSmartTestCommand heuristic */
+  testScopedTemplate?: string;
   timeoutSeconds: number;
   storyId: string;
   storyGitRef?: string;

package/src/verification/smart-runner.ts

@@ -174,8 +174,11 @@ export function buildSmartTestCommand(testFiles: string[], baseCommand: string):
     return `${baseCommand} ${testFiles.join(" ")}`;
   }
 
-  // Replace the last path argument with the specific test files
-  const newParts = [...parts.slice(0, lastPathIndex), ...testFiles];
+  // Replace the last path argument with the specific test files,
+  // preserving any flags that appear after the path (e.g. --timeout=60000).
+  const beforePath = parts.slice(0, lastPathIndex);
+  const afterPath = parts.slice(lastPathIndex + 1);
+  const newParts = [...beforePath, ...testFiles, ...afterPath];
   return newParts.join(" ");
 }
 

package/src/verification/strategies/scoped.ts

@@ -29,6 +29,13 @@ function coerceSmartRunner(val: unknown) {
   return val as typeof DEFAULT_SMART_RUNNER_CONFIG;
 }
 
+function buildScopedCommand(testFiles: string[], baseCommand: string, testScopedTemplate?: string): string {
+  if (testScopedTemplate) {
+    return testScopedTemplate.replace("{{files}}", testFiles.join(" "));
+  }
+  return _scopedDeps.buildSmartTestCommand(testFiles, baseCommand);
+}
+
 export class ScopedStrategy implements IVerificationStrategy {
   readonly name = "scoped" as const;
 
@@ -48,7 +55,7 @@ export class ScopedStrategy implements IVerificationStrategy {
         logger.info("verify[scoped]", `Pass 1: path convention matched ${pass1Files.length} test files`, {
           storyId: ctx.storyId,
         });
-        effectiveCommand = _scopedDeps.buildSmartTestCommand(pass1Files, ctx.testCommand);
+        effectiveCommand = buildScopedCommand(pass1Files, ctx.testCommand, ctx.testScopedTemplate);
         isFullSuite = false;
       } else if (smartCfg.fallback === "import-grep") {
         const pass2Files = await _scopedDeps.importGrepFallback(sourceFiles, ctx.workdir, smartCfg.testFilePatterns);
@@ -56,7 +63,7 @@ export class ScopedStrategy implements IVerificationStrategy {
           logger.info("verify[scoped]", `Pass 2: import-grep matched ${pass2Files.length} test files`, {
             storyId: ctx.storyId,
           });
-          effectiveCommand = _scopedDeps.buildSmartTestCommand(pass2Files, ctx.testCommand);
+          effectiveCommand = buildScopedCommand(pass2Files, ctx.testCommand, ctx.testScopedTemplate);
           isFullSuite = false;
         }
       }

package/src/verification/types.ts

@@ -112,4 +112,6 @@ export interface VerificationGateOptions {
   acceptOnTimeout?: boolean;
   /** Scoped test paths (for scoped verification) */
   scopedTestPaths?: string[];
+  /** Scoped test command template with {{files}} placeholder — overrides buildSmartTestCommand heuristic */
+  testScopedTemplate?: string;
 }

package/test/helpers/helpers.test.ts

@@ -283,9 +283,9 @@ describe("acquireLock and releaseLock", () => {
     // Create invalid JSON lock file
     await Bun.write(lockPath, "not valid json");
 
-    // Should fail to acquire but not crash
+    // Should treat corrupt lock as stale and acquire successfully
     const acquired = await acquireLock(testDir);
-    expect(acquired).toBe(false);
+    expect(acquired).toBe(true);
   });
 
   test("handles release when lock file doesn't exist", async () => {

package/test/unit/routing/strategies/llm.test.ts

@@ -112,17 +112,15 @@ afterEach(() => {
   resetLogger();
 });
 
-describe("BUG-039: callLlmOnce stream drain on timeout", () => {
-  test("cancels stdout and stderr before proc.kill() on timeout", async () => {
-    const { proc, stdoutCancelled, stderrCancelled, killCalled, killCalledAfterCancel } = makeHangingProc();
+describe("BUG-039/BUG-040: stream cleanup on timeout", () => {
+  test("kills process on timeout without calling cancel() on locked streams", async () => {
+    const { proc, stdoutCancelled, stderrCancelled, killCalled } = makeHangingProc();
 
     const originalSpawn = _deps.spawn;
     _deps.spawn = mock(() => proc as PipedProc);
 
     const config = makeConfig({ timeoutMs: 30 });
 
-    // Import callLlmOnce indirectly through llmStrategy to trigger the private function.
-    // We test via the exported llmStrategy.route() which calls callLlm → callLlmOnce.
     const { llmStrategy } = await import("../../../../src/routing/strategies/llm");
 
     const story = {
@@ -147,15 +145,72 @@ describe("BUG-039: callLlmOnce stream drain on timeout", () => {
     // Should resolve promptly — within 500ms of the 30ms timeout
     expect(elapsed).toBeLessThan(500);
 
-    expect(stdoutCancelled.value).toBe(true);
-    expect(stderrCancelled.value).toBe(true);
+    // BUG-040: cancel() must NOT be called on locked streams — it returns a rejected
+    // Promise (per Web Streams spec) which becomes an unhandled rejection crash.
+    expect(stdoutCancelled.value).toBe(false);
+    expect(stderrCancelled.value).toBe(false);
     expect(killCalled.value).toBe(true);
-    // kill() was called after both streams were cancelled
-    expect(killCalledAfterCancel.value).toBe(true);
 
     _deps.spawn = originalSpawn;
   });
 
+  test("no unhandled rejection when Response.text() locks streams and proc is killed", async () => {
+    // Simulate the exact BUG-040 scenario:
+    // 1. Spawn proc with piped streams
+    // 2. Response(proc.stdout).text() locks the streams
+    // 3. Timeout fires, proc.kill() called
+    // 4. No unhandled rejection should occur
+
+    const unhandledRejections: Error[] = [];
+    const handler = (event: PromiseRejectionEvent) => {
+      unhandledRejections.push(event.reason as Error);
+      event.preventDefault();
+    };
+
+    // biome-ignore lint/suspicious/noGlobalAssign: test-only override
+    globalThis.addEventListener("unhandledrejection", handler);
+
+    // Create a proc where streams are locked by Response readers
+    const stdout = new ReadableStream({ start() {} });
+    const stderr = new ReadableStream({ start() {} });
+    const proc = {
+      stdout,
+      stderr,
+      exited: new Promise<number>(() => {}),
+      kill: mock(() => {}),
+    };
+
+    const originalSpawn = _deps.spawn;
+    _deps.spawn = mock(() => proc as PipedProc);
+
+    const config = makeConfig({ timeoutMs: 20, retries: 0 });
+
+    const { llmStrategy } = await import("../../../../src/routing/strategies/llm");
+    const story = {
+      id: "BUG040",
+      title: "Bug test",
+      description: "Test",
+      acceptanceCriteria: ["AC1"],
+      tags: [],
+      dependencies: [],
+      status: "pending" as const,
+      passes: false,
+      escalations: [],
+      attempts: 0,
+    };
+
+    await expect(llmStrategy.route(story, { config })).rejects.toThrow(/timeout/i);
+
+    // Give microtasks time to settle
+    await Bun.sleep(50);
+
+    globalThis.removeEventListener("unhandledrejection", handler);
+    _deps.spawn = originalSpawn;
+
+    // No unhandled rejections should have occurred
+    expect(unhandledRejections).toHaveLength(0);
+  });
+
   test("clearTimeout is called on success path (no resource leak)", async () => {
     const originalSpawn = _deps.spawn;
 

package/test/unit/verification/smart-runner.test.ts

@@ -50,6 +50,22 @@ describe("buildSmartTestCommand", () => {
     );
     expect(result).toBe("bun test --coverage test/unit/foo.test.ts");
   });
+
+  test("preserves trailing flags after path argument (BUG-043)", () => {
+    const result = buildSmartTestCommand(
+      ["test/unit/foo.test.ts"],
+      "bun test test/ --timeout=60000",
+    );
+    expect(result).toBe("bun test test/unit/foo.test.ts --timeout=60000");
+  });
+
+  test("preserves trailing flags with multiple test files", () => {
+    const result = buildSmartTestCommand(
+      ["test/unit/foo.test.ts", "test/unit/bar.test.ts"],
+      "bun test test/ --timeout=60000 --bail",
+    );
+    expect(result).toBe("bun test test/unit/foo.test.ts test/unit/bar.test.ts --timeout=60000 --bail");
+  });
 });
 
 // ---------------------------------------------------------------------------