@nathapp/nax 0.22.3 → 0.23.0

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/docs/tdd/strategies.md

@@ -0,0 +1,97 @@
+# TDD Strategies
+
+nax supports three test strategies, selectable via `config.tdd.strategy` or per-story override.
+
+## Strategy Comparison
+
+| Aspect | `three-session-tdd` | `three-session-tdd-lite` | `test-after` |
+|---|---|---|---|
+| **Sessions** | 3 separate sessions | 3 separate sessions | 1 session |
+| **Session 1 (Test Writer)** | Strict isolation — tests only, NO src/ reads, NO stubs | Relaxed — can read src/, create stubs in src/ | ❌ No dedicated test writer |
+| **Session 2 (Implementer)** | Implements against pre-written tests | Same | Implements + writes tests |
+| **Session 3 (Verifier)** | Verifies isolation wasn't violated | Same | ❌ No verifier |
+| **Isolation check** | ✅ Full isolation enforcement | ✅ Full isolation enforcement | ❌ None |
+| **Isolation-violation fallback** | Triggers lite-mode retry | N/A (already lite) | N/A |
+| **Rectification gate** | Checks implementer isolation | ⚡ Skips `verifyImplementerIsolation` | Standard |
+
+---
+
+## When Each Strategy Is Used
+
+Controlled by `config.tdd.strategy`:
+
+| Config value | Behaviour |
+|---|---|
+| `"strict"` | Always `three-session-tdd` |
+| `"lite"` | Always `three-session-tdd-lite` |
+| `"off"` | Always `test-after` |
+| `"auto"` | LLM/keyword router decides (see routing rules below) |
+
+### Auto-Routing Rules (FEAT-013)
+
+`test-after` is **deprecated** from auto mode. Default fallback is now `three-session-tdd-lite`.
+
+| Condition | Strategy |
+|---|---|
+| Security / auth logic | `three-session-tdd` |
+| Public API / complex / expert | `three-session-tdd` |
+| UI / layout / CLI / integration / polyglot tags | `three-session-tdd-lite` |
+| Simple / medium (default) | `three-session-tdd-lite` |
+
+---
+
+## Session Detail
+
+### `three-session-tdd` — Full Mode
+
+1. **Test Writer** — writes failing tests only. Cannot read src/ files or create any source stubs. Strict isolation enforced by post-session diff check.
+2. **Implementer** — makes all failing tests pass. Works against the test-writer's output.
+3. **Verifier** — confirms isolation: tests were written before implementation, no cheating.
+
+If the test writer violates isolation (touches src/), the orchestrator flags it as `isolation-violation` and schedules a lite-mode retry on the next attempt.
+
+### `three-session-tdd-lite` — Lite Mode
+
+Same 3-session flow, but the test writer prompt is relaxed:
+- **Can read** existing src/ files (needed when importing existing types/interfaces).
+- **Can create minimal stubs** in src/ (empty exports, no logic) to make imports resolve.
+- Implementer isolation check (`verifyImplementerIsolation`) is **skipped** in the rectification gate.
+
+Best for: existing codebases where greenfield isolation is impractical, or stories that modify existing modules.
+
+### `test-after` — Single Session
+
+One Claude Code session writes tests and implements the feature together. No structured TDD flow.
+
+- Higher failure rate observed in practice — Claude tends to write tests that are trivially passing or implementation-first.
+- Use only when `tdd.strategy: "off"` or explicitly set per-story.
+
+---
+
+## Per-Story Override
+
+Add `testStrategy` to a story in `prd.json` to override routing:
+
+```json
+{
+  "userStories": [
+    {
+      "id": "US-001",
+      "testStrategy": "three-session-tdd-lite",
+      ...
+    }
+  ]
+}
+```
+
+Supported values: `"test-after"`, `"three-session-tdd"`, `"three-session-tdd-lite"`.
+
+---
+
+## Known Issues
+
+- **BUG-045:** LLM batch routing bypasses `config.tdd.strategy`. `buildBatchPrompt()` only offers `test-after` and `three-session-tdd` to the LLM — no `three-session-tdd-lite`. The cache hit path returns the LLM decision directly without calling `determineTestStrategy()`, so `tdd.strategy: "lite"` is silently ignored for batch-routed stories. Fix: post-process batch decisions through `determineTestStrategy()`. See `src/routing/strategies/llm.ts:routeBatch()`.
+
+---
+
+*Last updated: 2026-03-07*

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/diagnose/acceptance.test.ts

@@ -97,7 +97,9 @@ async function createStatusFile(
 		...overrides,
 	};
 
-	await Bun.write(join(dir, ".nax-status.json"), JSON.stringify(status, null, 2));
+	// Ensure nax directory exists
+	mkdirSync(join(dir, "nax"), { recursive: true });
+	await Bun.write(join(dir, "nax", "status.json"), JSON.stringify(status, null, 2));
 }
 
 /**

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,7 +1,7 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.22.3",
-  "description": "AI Coding Agent Orchestrator \u2014 loops until done",
+  "version": "0.23.0",
+  "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
     "nax": "./bin/nax.ts"
@@ -9,7 +9,7 @@
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
     "dev": "bun run bin/nax.ts",
-    "build": "bun build bin/nax.ts --outdir dist --target bun",
+    "build": "bun build bin/nax.ts --outdir dist --target bun --define \"GIT_COMMIT=\\\"$(git rev-parse --short HEAD)\\\"\"",
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x biome check src/ bin/",
     "test": "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
@@ -44,4 +44,4 @@
     "tdd",
     "coding"
   ]
-}
+}

package/src/cli/diagnose.ts

@@ -86,7 +86,7 @@ function isProcessAlive(pid: number): boolean {
 }
 
 async function loadStatusFile(workdir: string): Promise<NaxStatusFile | null> {
-  const statusPath = join(workdir, ".nax-status.json");
+  const statusPath = join(workdir, "nax", "status.json");
   if (!existsSync(statusPath)) return null;
   try {
     return (await Bun.file(statusPath).json()) as NaxStatusFile;

package/src/cli/status-features.ts

@@ -41,14 +41,11 @@ interface FeatureSummary {
   };
 }
 
-/** Check if a process is alive via PID check */
+/** Check if a process is alive via POSIX signal 0 (portable, no subprocess) */
 function isPidAlive(pid: number): boolean {
   try {
-    const result = Bun.spawnSync(["ps", "-p", String(pid)], {
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    return result.exitCode === 0;
+    process.kill(pid, 0);
+    return true;
   } catch {
     return false;
   }
@@ -69,6 +66,21 @@ async function loadStatusFile(featureDir: string): Promise<NaxStatusFile | null>
   }
 }
 
+/** Load project-level status.json (if it exists) */
+async function loadProjectStatusFile(projectDir: string): Promise<NaxStatusFile | null> {
+  const statusPath = join(projectDir, "nax", "status.json");
+  if (!existsSync(statusPath)) {
+    return null;
+  }
+
+  try {
+    const content = Bun.file(statusPath);
+    return (await content.json()) as NaxStatusFile;
+  } catch {
+    return null;
+  }
+}
+
 /** Get feature summary from prd.json and optional status.json */
 async function getFeatureSummary(featureName: string, featureDir: string): Promise<FeatureSummary> {
   const prdPath = join(featureDir, "prd.json");
@@ -154,10 +166,46 @@ async function displayAllFeatures(projectDir: string): Promise<void> {
     return;
   }
 
+  // Load project-level status if available (current run info)
+  const projectStatus = await loadProjectStatusFile(projectDir);
+
+  // Display current run info if available
+  if (projectStatus) {
+    const pidAlive = isPidAlive(projectStatus.run.pid);
+
+    if (projectStatus.run.status === "running" && pidAlive) {
+      console.log(chalk.yellow("⚡ Currently Running:\n"));
+      console.log(chalk.dim(`   Feature:    ${projectStatus.run.feature}`));
+      console.log(chalk.dim(`   Run ID:     ${projectStatus.run.id}`));
+      console.log(chalk.dim(`   Started:    ${projectStatus.run.startedAt}`));
+      console.log(chalk.dim(`   Progress:   ${projectStatus.progress.passed}/${projectStatus.progress.total} stories`));
+      console.log(chalk.dim(`   Cost:       $${projectStatus.cost.spent.toFixed(4)}`));
+
+      if (projectStatus.current) {
+        console.log(chalk.dim(`   Current:    ${projectStatus.current.storyId} - ${projectStatus.current.title}`));
+      }
+
+      console.log();
+    } else if ((projectStatus.run.status === "running" && !pidAlive) || projectStatus.run.status === "crashed") {
+      console.log(chalk.red("💥 Crashed Run Detected:\n"));
+      console.log(chalk.dim(`   Feature:    ${projectStatus.run.feature}`));
+      console.log(chalk.dim(`   Run ID:     ${projectStatus.run.id}`));
+      console.log(chalk.dim(`   PID:        ${projectStatus.run.pid} (dead)`));
+      console.log(chalk.dim(`   Started:    ${projectStatus.run.startedAt}`));
+      if (projectStatus.run.crashedAt) {
+        console.log(chalk.dim(`   Crashed:    ${projectStatus.run.crashedAt}`));
+      }
+      if (projectStatus.run.crashSignal) {
+        console.log(chalk.dim(`   Signal:     ${projectStatus.run.crashSignal}`));
+      }
+      console.log();
+    }
+  }
+
   // Load summaries for all features
   const summaries = await Promise.all(features.map((name) => getFeatureSummary(name, join(featuresDir, name))));
 
-  console.log(chalk.bold("\n📊 Features\n"));
+  console.log(chalk.bold("📊 Features\n"));
 
   // Print table header
   const header = `  ${"Feature".padEnd(25)} ${"Done".padEnd(6)} ${"Failed".padEnd(8)} ${"Pending".padEnd(9)} ${"Last Run".padEnd(22)} ${"Cost".padEnd(10)} Status`;

package/src/config/schemas.ts

@@ -117,6 +117,9 @@ const QualityConfigSchema = z.object({
     typecheck: z.string().optional(),
     lint: z.string().optional(),
     test: z.string().optional(),
+    testScoped: z.string().optional(),
+    lintFix: z.string().optional(),
+    formatFix: z.string().optional(),
   }),
   forceExit: z.boolean().default(false),
   detectOpenHandles: z.boolean().default(true),

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

@@ -27,6 +27,8 @@ export interface CrashRecoveryContext {
   // BUG-017: Additional context for run.complete event on SIGTERM
   runId?: string;
   feature?: string;
+  // SFC-002: Feature directory for writing feature-level status on crash
+  featureDir?: string;
   getStartTime?: () => number;
   getTotalStories?: () => number;
   getStoriesCompleted?: () => number;
@@ -115,13 +117,14 @@ async function writeRunComplete(ctx: CrashRecoveryContext, exitReason: string):
 }
 
 /**
- * Update status.json to "crashed" state
+ * Update status.json to "crashed" state (both project-level and feature-level)
  */
 async function updateStatusToCrashed(
   statusWriter: StatusWriter,
   totalCost: number,
   iterations: number,
   signal: string,
+  featureDir?: string,
 ): Promise<void> {
   try {
     statusWriter.setRunStatus("crashed");
@@ -129,6 +132,14 @@ async function updateStatusToCrashed(
       crashedAt: new Date().toISOString(),
       crashSignal: signal,
     });
+
+    // Write feature-level status (SFC-002)
+    if (featureDir) {
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations, {
+        crashedAt: new Date().toISOString(),
+        crashSignal: signal,
+      });
+    }
   } catch (err) {
     console.error("[crash-recovery] Failed to update status.json:", err);
   }
@@ -166,8 +177,8 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write run.complete event (BUG-017)
     await writeRunComplete(ctx, signal.toLowerCase());
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal);
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), signal, ctx.featureDir);
 
     // Stop heartbeat
     stopHeartbeat();
@@ -201,8 +212,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log with stack trace
     await writeFatalLog(ctx.jsonlFilePath, "uncaughtException", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "uncaughtException");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "uncaughtException",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();
@@ -228,8 +245,14 @@ export function installCrashHandlers(ctx: CrashRecoveryContext): () => void {
     // Write fatal log
     await writeFatalLog(ctx.jsonlFilePath, "unhandledRejection", error);
 
-    // Update status.json to crashed
-    await updateStatusToCrashed(ctx.statusWriter, ctx.getTotalCost(), ctx.getIterations(), "unhandledRejection");
+    // Update status.json to crashed (SFC-002: include feature-level status)
+    await updateStatusToCrashed(
+      ctx.statusWriter,
+      ctx.getTotalCost(),
+      ctx.getIterations(),
+      "unhandledRejection",
+      ctx.featureDir,
+    );
 
     // Stop heartbeat
     stopHeartbeat();

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

@@ -25,6 +25,7 @@ import { loadPlugins } from "../../plugins/loader";
 import type { PluginRegistry } from "../../plugins/registry";
 import type { PRD } from "../../prd";
 import { loadPRD } from "../../prd";
+import { NAX_BUILD_INFO, NAX_COMMIT, NAX_VERSION } from "../../version";
 import { installCrashHandlers } from "../crash-recovery";
 import { acquireLock, hookCtx, releaseLock } from "../helpers";
 import { PidRegistry } from "../pid-registry";
@@ -36,6 +37,7 @@ export interface RunSetupOptions {
   config: NaxConfig;
   hooks: LoadedHooksConfig;
   feature: string;
+  featureDir?: string;
   dryRun: boolean;
   statusFile: string;
   logFilePath?: string;
@@ -117,6 +119,7 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
     // BUG-017: Pass context for run.complete event on SIGTERM
     runId: options.runId,
     feature: options.feature,
+    featureDir: options.featureDir,
     getStartTime: () => options.startTime,
     getTotalStories: options.getTotalStories,
     getStoriesCompleted: options.getStoriesCompleted,
@@ -173,12 +176,14 @@ export async function setupRun(options: RunSetupOptions): Promise<RunSetupResult
 
     // Log run start
     const routingMode = config.routing.llm?.mode ?? "hybrid";
-    logger?.info("run.start", `Starting feature: ${feature}`, {
+    logger?.info("run.start", `Starting feature: ${feature} [nax ${NAX_BUILD_INFO}]`, {
       runId,
       feature,
       workdir,
       dryRun,
       routingMode,
+      naxVersion: NAX_VERSION,
+      naxCommit: NAX_COMMIT,
     });
 
     // Fire on-start hook

package/src/execution/runner.ts

@@ -110,6 +110,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
     config,
     hooks,
     feature,
+    featureDir,
     dryRun,
     statusFile,
     logFilePath,
@@ -307,6 +308,13 @@ export async function run(options: RunOptions): Promise<RunResult> {
 
     const { durationMs, runCompletedAt, finalCounts } = completionResult;
 
+    // ── Write feature-level status (SFC-002) ────────────────────────────────
+    if (featureDir) {
+      const finalStatus = isComplete(prd) ? "completed" : "failed";
+      statusWriter.setRunStatus(finalStatus);
+      await statusWriter.writeFeatureStatus(featureDir, totalCost, iterations);
+    }
+
     // ── Output run footer in headless mode ─────────────────────────────────
     if (headless && formatterMode !== "json") {
       const { outputRunFooter } = await import("./lifecycle/headless-formatter");