@nathapp/nax 0.22.3 → 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

@@ -127,6 +127,8 @@
 
 ### Stories
 - [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
@@ -140,6 +142,7 @@
 **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
@@ -284,6 +287,9 @@
 
 - [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~~

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/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

@@ -4,25 +4,34 @@
     "id": "run-2026-03-07T06-14-21-018Z",
     "feature": "status-file-consolidation",
     "startedAt": "2026-03-07T06:14:21.018Z",
-    "status": "completed",
+    "status": "crashed",
     "dryRun": false,
-    "pid": 217461
+    "pid": 217461,
+    "crashedAt": "2026-03-07T06:22:36.300Z",
+    "crashSignal": "SIGTERM"
   },
   "progress": {
     "total": 4,
-    "passed": 4,
+    "passed": 0,
     "failed": 0,
     "paused": 0,
     "blocked": 0,
-    "pending": 0
+    "pending": 4
   },
   "cost": {
     "spent": 0,
     "limit": 3
   },
-  "current": null,
+  "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:19:54.528Z",
-  "durationMs": 1000,
-  "lastHeartbeat": "2026-03-07T06:19:34.987Z"
+  "updatedAt": "2026-03-07T06:22:36.300Z",
+  "durationMs": 495282
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

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/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/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/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");
+  });
 });
 
 // ---------------------------------------------------------------------------