@nathapp/nax 0.22.1 → 0.22.2

package/CLAUDE.md

@@ -75,6 +75,23 @@ Runner.run()  [src/execution/runner.ts — thin orchestrator only]
 
 Detailed coding standards, test architecture, and forbidden patterns are in `.claude/rules/`. Claude Code loads these automatically.
 
+
+## Code Intelligence (Solograph MCP)
+
+Use **solograph** MCP tools on-demand for code understanding. Do not use web_search, kb_search, or source_* tools.
+
+| Tool | When to use |
+|:-----|:------------|
+| `project_code_search` | Find existing patterns, symbols, or implementations before writing new code |
+| `codegraph_explain` | Get architecture overview of nax before tackling unfamiliar areas |
+| `codegraph_query` | Cypher queries — dependency analysis, impact analysis, hub files |
+| `codegraph_stats` | Quick graph stats (file/symbol counts) |
+| `codegraph_shared` | Find packages shared across projects |
+| `session_search` | Search prior Claude Code session history for relevant context |
+| `project_info` | Project registry info |
+| `project_code_reindex` | Reindex after creating or deleting source files, or major refactors |
+
+Single source of truth: VPS solograph instance (Mac01 tunnels to VPS — same data either way).
 ## IMPORTANT
 
 - Do NOT push to remote — let the human review and push.

package/bin/nax.ts

@@ -39,7 +39,7 @@
 
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 
@@ -217,7 +217,6 @@ program
   .option("--silent", "Silent mode (errors only)", false)
   .option("--json", "JSON mode (raw JSONL output to stdout)", false)
   .option("-d, --dir <path>", "Working directory", process.cwd())
-  .option("--status-file <path>", "Write machine-readable JSON status file (updated during run)")
   .option("--skip-precheck", "Skip precheck validations (advanced users only)", false)
   .action(async (options) => {
     // Validate directory path
@@ -331,8 +330,8 @@ program
       console.log(chalk.dim("   [Headless mode — pipe output]"));
     }
 
-    // Resolve --status-file relative to cwd (absolute paths unchanged)
-    const statusFilePath = options.statusFile ? resolve(process.cwd(), options.statusFile) : undefined;
+    // Compute status file path: <workdir>/nax/status.json
+    const statusFilePath = join(workdir, "nax", "status.json");
 
     // Parse --parallel option
     let parallel: number | undefined;

package/docs/ROADMAP.md

@@ -6,10 +6,10 @@
 
 ---
 
-## Next: v0.18.0 — Orchestration Quality
+## v0.18.0 — Orchestration Quality ✅
 
 **Theme:** Fix execution bugs and improve orchestration reliability
-**Status:** 🔲 Planned
+**Status:** ✅ Shipped (2026-03-03)
 
 ### Bugfixes (Priority)
 - [x] ~~**BUG-016:** Hardcoded 120s timeout in verify stage → read from config~~
@@ -64,19 +64,8 @@
 - [x] ~~Result: verify drops from ~125s to ~10-20s for typical single-file fixes~~
 
 ### Bun PTY Migration (BUN-001)
-- [ ] Replace `node-pty` (native addon, requires python/make/g++ to build) with `Bun.Terminal` API (v1.3.5+)
-- [ ] Update `src/agents/claude.ts` `runInteractive()` — replace `nodePty.spawn()` with `Bun.Terminal`
-- [ ] Update `src/tui/hooks/usePty.ts` — replace `IPty` interface with Bun equivalent
-- [ ] Remove `node-pty` from `dependencies` in `package.json`
-- [ ] Remove `--ignore-scripts` workaround from `.gitlab-ci.yml`
-- [ ] Benefit: no native build, no gyp/python/gcc in CI, cleaner alpine support
-
-### CI Memory Optimization (CI-001)
-- [ ] Investigate splitting test suite into parallel jobs (unit / integration / ui) to reduce per-job peak memory
-- [ ] Evaluate `bun test --shard` when stable (currently experimental)
-- [ ] Target: make test suite pass on 1GB runners (currently requires 8GB shared runner)
-- [ ] Known constraints: 2008 tests across 125 files, ~75s on local VPS (3.8GB), OOMs even with `--smol --concurrency 1`
-- [ ] Current workaround: use `saas-linux-small-amd64` (8GB) shared runner
+- [x] ~~Replace `node-pty` with `Bun.spawn` (piped stdio) — shipped in v0.18.5~~
+
 
 ---
 
@@ -125,12 +114,35 @@
 **Spec:** [docs/specs/bun-pty-migration.md](specs/bun-pty-migration.md)
 
 ### BUN-001: Replace node-pty with Bun.spawn
-- [x] Research gate: verify `Bun.Terminal` availability on Bun 1.3.9; confirm Claude Code works with piped stdio
-- [ ] `src/agents/claude.ts` `runInteractive()` — replace `nodePty.spawn()` with `Bun.spawn` (piped stdio)
-- [ ] `src/tui/hooks/usePty.ts` — replace `pty.IPty` state with `Bun.Subprocess`
-- [ ] `src/agents/types.ts` — remove `IPty` dependency from `PtyHandle` interface
-- [ ] `package.json` — remove `node-pty` from dependencies
-- [ ] `.gitlab-ci.yml` — remove `python3 make g++` from `apk add`; remove `--ignore-scripts` from `bun install`
+- [x] ~~All sub-items complete — `claude.ts` + `usePty.ts` migrated to `Bun.spawn`, `node-pty` removed from `package.json`, CI cleaned up~~
+
+---
+
+## v0.22.2 — Status File Consolidation
+
+**Theme:** Auto-write status.json to well-known paths, align readers, remove dead options
+**Status:** 🔲 Planned
+**Spec:** [docs/specs/status-file-consolidation.md](specs/status-file-consolidation.md)
+**Pre-requisite for:** v0.23.0 (Central Run Registry)
+
+### Stories
+- [ ] **SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`
+- [ ] **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
+
+**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-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
 
 ---
 
@@ -148,25 +160,25 @@
 - [x] ~~**BUG-041:**~~ Won't fix — superseded by FEAT-010
 - [x] ~~**FEAT-012:**~~ Won't fix — balanced tier sufficient for test-writer
 
-### → v0.22.0 Pipeline Re-Architecture (in progress)
+### → v0.22.1 Pipeline Re-Architecture ✅ Shipped (2026-03-07)
 **ADR:** [docs/adr/ADR-005-pipeline-re-architecture.md](adr/ADR-005-pipeline-re-architecture.md)
 **Plan:** [docs/adr/ADR-005-implementation-plan.md](adr/ADR-005-implementation-plan.md)
-**Branch:** `feat/re-architecture`
 
-**Theme:** Eliminate ad-hoc orchestration, consolidate 4 scattered verification paths into single orchestrator, add event-bus-driven hooks/plugins/interaction, new stages (rectify, autofix, regression).
+**Theme:** Eliminate ad-hoc orchestration, consolidate 4 scattered verification paths into single orchestrator, add event-bus-driven hooks/plugins/interaction, new stages (rectify, autofix, regression), post-run pipeline SSOT.
 
-- [ ] **Phase 0:** Test suite preparation — reorganize, split monsters, RE-ARCH tags, coverage gaps
-- [ ] **Phase 1:** VerificationOrchestrator + Pipeline Event Bus (additive, no behavior change)
-- [ ] **Phase 2:** New stages — `rectify`, `autofix`, `regression` + `retry` stage action
-- [ ] **Phase 3:** Event-bus subscribers for hooks, reporters, interaction (replace 20+ scattered call sites)
-- [ ] **Phase 4:** Delete deprecated files, simplify sequential executor to ~80 lines
+- [x] **Phase 1:** VerificationOrchestrator + Pipeline Event Bus (additive, no behavior change)
+- [x] **Phase 2:** New stages — `rectify`, `autofix`, `regression` + `retry` stage action
+- [x] **Phase 3:** Event-bus subscribers for hooks, reporters, interaction (replace 20+ scattered call sites)
+- [x] **Phase 5:** Post-run pipeline SSOT — `deferred-regression` stage, tier escalation into `iteration-runner`, `runAcceptanceLoop` → `runPipeline(postRunPipeline)`
 
-**Resolves in this version:**
-- [ ] **BUG-040:** Lint/typecheck auto-repair → `autofix` stage + `quality.commands.lintFix/formatFix`
-- [ ] **BUG-042:** Verifier failure capture → unified `VerifyResult` with `failures[]` always populated
-- [ ] **FEAT-014:** Heartbeat observability → Pipeline Event Bus with typed events
-- [ ] **BUG-026:** Regression gate triggers full retry → targeted `rectify` stage with `retry` action
-- [ ] **BUG-028:** Routing cache ignores escalation tier → cache key includes tier
+**Resolved:**
+- [x] **BUG-040:** Lint/typecheck auto-repair → `autofix` stage + `quality.commands.lintFix/formatFix`
+- [x] **BUG-042:** Verifier failure capture → unified `VerifyResult` with `failures[]` always populated
+- [x] **FEAT-014:** Heartbeat observability → Pipeline Event Bus with typed events
+- [x] **BUG-026:** Regression gate triggers full retry → targeted `rectify` stage with `retry` action
+- [x] **BUG-028:** Routing cache ignores escalation tier → cache key includes tier
+
+**Test results:** 2264 pass, 12 skip, 1 fail (pre-existing disk space flaky)
 
 ---
 
@@ -202,9 +214,6 @@
 - [x] `priorFailures` injected into escalated agent prompts via `context/builder.ts`
 - [x] Reverse file mapping for regression attribution
 
-### Central Run Registry (carried forward)
-- [ ] `~/.nax/runs/<project>-<feature>-<runId>/` with status.json + events.jsonl symlink
-
 ---
 
 ## Shipped
@@ -212,6 +221,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.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 |
 | v0.18.5 | Bun PTY Migration | 2026-03-04 | BUN-001: node-pty → Bun.spawn, CI cleanup, flaky test fix |
@@ -271,16 +281,17 @@
 - [x] **BUG-032:** Routing stage overrides escalated `modelTier` with complexity-derived tier. `src/pipeline/stages/routing.ts:43` always runs `complexityToModelTier(routing.complexity, config)` even when `story.routing.modelTier` was explicitly set by `handleTierEscalation()`. BUG-026 was escalated to `balanced` (logged in iteration header), but `Task classified` shows `modelTier=fast` because `complexityToModelTier("simple", config)` → `"fast"`. Related to BUG-013 (escalation routing not applied) which was marked fixed, but the fix in `applyCachedRouting()` in `pipeline-result-handler.ts:295-310` runs **after** the routing stage — too late. **Location:** `src/pipeline/stages/routing.ts:43`. **Fix:** When `story.routing.modelTier` is explicitly set (by escalation), skip `complexityToModelTier()` and use the cached tier directly. Only derive from complexity when `story.routing.modelTier` is absent.
 - [x] **BUG-033:** LLM routing has no retry on timeout — single attempt with hardcoded 15s default. All 5 LLM routing attempts in the v0.18.3 run timed out at 15s, forcing keyword fallback every time. `src/routing/strategies/llm.ts:63` reads `llmConfig?.timeoutMs ?? 15000` but there's no retry logic — one timeout = immediate fallback. **Location:** `src/routing/strategies/llm.ts:callLlm()`. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Also surface `routing.llm.timeoutMs` in `nax config --explain` and consider raising default to 30s for batch routing which processes multiple stories.
 
-- [ ] **BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. **Symptom:** Logs show successful prechecks (Head) instead of failed tests (Tail). **Fix:** Change `Test output preview` log to tail the last 20 lines of output instead of heading the first 10.
-- [ ] **BUG-038:** `smart-runner` over-matching when global defaults change. **Symptom:** Changing `DEFAULT_CONFIG` matches broad integration tests that fail due to environment/precheck side effects, obscuring targeted results. **Fix:** Refine path mapping to prioritize direct unit tests and exclude known heavy integration tests from default smart-runner matches unless explicitly relevant.
+- [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.~~
 ### Features
 - [x] ~~`nax unlock` command~~
 - [x] ~~Constitution file support~~
 - [x] ~~Per-story testStrategy override — v0.18.1~~
 - [x] ~~Smart Test Runner — v0.18.2~~
-- [x] ~~Central Run Registry — v0.19.0~~
-- [ ] **BUN-001:** Bun PTY Migration — replace `node-pty` with `Bun.Terminal` API
+- [ ] **Central Run Registry** — moved to v0.23.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.
 - [ ] Cost tracking dashboard
 - [ ] npm publish setup
 - [ ] `nax diagnose --ai` flag (LLM-assisted, future TBD)
@@ -296,4 +307,4 @@ Sequential canary → stable: `v0.12.0-canary.0` → `canary.N` → `v0.12.0`
 Canary: `npm publish --tag canary`
 Stable: `npm publish` (latest)
 
-*Last updated: 2026-03-06 (v0.21.0 shipped; v0.22.0: Pipeline Re-Architecture in progress — ADR-005, 5 phases, resolves BUG-026/028/040/042 + FEAT-014)*
+*Last updated: 2026-03-07 (v0.22.1 shipped — Pipeline Re-Architecture: VerificationOrchestrator, EventBus, new stages, post-run SSOT)*

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

@@ -0,0 +1,104 @@
+# Central Run Registry — Spec
+
+**Version:** v0.23.0
+**Status:** Planned
+
+---
+
+## Problem
+
+nax stores run state per-project at `<workdir>/nax/features/<feature>/status.json`. There is no global index — you must `cd` into each project to see its run history. There is no way to answer "what has nax run across all my projects recently?"
+
+## Existing Layout (per-project)
+
+```
+<workdir>/nax/
+  config.json
+  features/
+    <feature>/
+      prd.json
+      status.json       ← live run state (NaxStatusFile, written continuously)
+      runs/
+        <timestamp>.jsonl ← event log
+```
+
+`status.json` already contains: runId, feature, status (running/completed/failed/crashed), progress counts, cost, current story, startedAt, etc. — everything needed for a global view.
+
+## Goal
+
+A global `~/.nax/runs/` registry that indexes every nax run via path references — no data duplication, no symlinks.
+
+---
+
+## Directory Structure
+
+```
+~/.nax/runs/
+  <project>-<feature>-<runId>/
+    meta.json    ← pointer record only (paths + minimal identifiers)
+```
+
+### meta.json Schema
+
+```json
+{
+  "runId": "run-2026-03-07T05-30-00-000Z",
+  "project": "my-app",
+  "feature": "auth-system",
+  "workdir": "/Users/william/projects/my-app",
+  "statusPath": "/Users/william/projects/my-app/nax/features/auth-system/status.json",
+  "eventsDir": "/Users/william/projects/my-app/nax/features/auth-system/runs",
+  "registeredAt": "2026-03-07T05:30:00.000Z"
+}
+```
+
+- Written **once** on run start — never updated (source of truth stays in `statusPath`)
+- `nax runs` reads `meta.json` to locate `statusPath`, then reads live `status.json` for current state
+- If `statusPath` doesn't exist (project deleted/moved) → show `[unavailable]` gracefully
+
+---
+
+## Implementation
+
+### CRR-001: Registry Writer (new subscriber)
+
+- New module: `src/execution/run-registry.ts` — `registerRun(meta)`, `getRunsDir()`
+- On run start: create `~/.nax/runs/<project>-<feature>-<runId>/meta.json`
+- Wire as **event bus subscriber** (`wireRegistry()` in `src/pipeline/subscribers/registry.ts`) — listens to `run:started`
+- Best-effort: never throw/block the main run on registry failure (try/catch + warn log)
+- `~/.nax/runs/` created on first call — no separate init step
+
+### CRR-002: `nax runs` CLI Command
+
+```
+nax runs                         # All runs, newest first (default: last 20)
+nax runs --project my-app        # Filter by project name
+nax runs --last 50               # Show last N runs
+nax runs --status failed         # Filter by status (running/completed/failed/crashed)
+```
+
+**Output table:**
+```
+RUN ID                        PROJECT    FEATURE        STATUS      STORIES   DURATION   DATE
+run-2026-03-07T05-30-00-000Z  my-app     auth-system    completed   5/5       45m        2026-03-07 13:30
+run-2026-03-07T04-00-00-000Z  nax        re-arch        failed      3/5       1h 2m      2026-03-07 12:00
+```
+
+- Reads all `~/.nax/runs/*/meta.json`, resolves live `status.json` from `statusPath`
+- Sorts by `registeredAt` desc
+- If `statusPath` missing → status shows `[unavailable]`
+- New command: `src/commands/runs.ts`
+
+### CRR-003: `nax logs` Enhancement
+
+- `nax logs --run <runId>` — resolve run from global registry, locate `eventsDir`, stream logs
+- No need to be in the project directory
+- Falls back to current behaviour (local feature context) when `--run` not specified
+
+---
+
+## Out of Scope
+
+- Registry cleanup/prune command (future)
+- Remote sync (future)
+- Search by story ID (future)

package/docs/specs/status-file-consolidation.md

@@ -0,0 +1,93 @@
+# Status File Consolidation — Spec
+
+**Version:** v0.22.2
+**Status:** Planned
+**Pre-requisite for:** v0.23.0 (Central Run Registry)
+
+---
+
+## Problem
+
+StatusWriter only writes `status.json` when the `--status-file` CLI flag is explicitly passed. Without it, no status file is written. Additionally, `nax status` and `nax diagnose` read from different (non-existent) paths, creating a three-way disconnect.
+
+### Current State
+
+| Component | Path | Exists? |
+|-----------|------|---------|
+| StatusWriter (writer) | `--status-file <path>` (opt-in) | Only if flag passed |
+| `nax status` (reader) | `nax/features/<feature>/status.json` | ❌ Never written |
+| `nax diagnose` (reader) | `<workdir>/.nax-status.json` | ❌ Legacy path |
+| Actual file on disk | `nax/status.json` | Only from manual flag usage |
+
+## Goal
+
+Auto-write status files to well-known paths. Zero config, zero flags. Both project-level and feature-level status always available.
+
+### Target State
+
+| File | Written | Purpose |
+|------|---------|---------|
+| `<workdir>/nax/status.json` | Continuously during run | Live monitoring: "is nax running? which feature? cost?" |
+| `<workdir>/nax/features/<feature>/status.json` | Once at run end | Historical: "what was the last run result for this feature?" |
+
+---
+
+## Stories
+
+### SFC-001: Auto-write project-level status
+
+**What:** Remove `--status-file` CLI option. StatusWriter always writes to `<workdir>/nax/status.json` automatically.
+
+**Changes:**
+- `bin/nax.ts` — remove `--status-file` option, compute `statusFile = join(workdir, "nax", "status.json")` automatically
+- `src/execution/runner.ts` — `statusFile` no longer optional in `RunOptions`, always provided
+- `src/execution/status-writer.ts` — remove the `if (!this.statusFile)` guard in `update()` (statusFile is always set)
+- `src/execution/lifecycle/run-setup.ts` — statusFile always provided
+
+**Test:** Run nax without `--status-file` flag → verify `nax/status.json` is written with correct schema.
+
+### SFC-002: Write feature-level status on run end
+
+**What:** On run complete/fail/crash, copy the final status snapshot to `<workdir>/nax/features/<feature>/status.json`.
+
+**Changes:**
+- `src/execution/status-writer.ts` — add `writeFeatureStatus(featureDir: string)` method that writes current snapshot to `<featureDir>/status.json`
+- `src/execution/runner.ts` — call `statusWriter.writeFeatureStatus(featureDir)` in the finally block (after run completes, fails, or crashes)
+- `src/execution/crash-recovery.ts` — also write feature status on crash
+
+**Test:** After a completed run, verify `nax/features/<feature>/status.json` exists with `status: "completed"` or `"failed"`.
+
+### SFC-003: Align status readers
+
+**What:** Make `nax status` and `nax diagnose` read from the correct paths.
+
+**Changes:**
+- `src/cli/status-features.ts` — `loadStatusFile()` already reads from `<featureDir>/status.json` (correct after SFC-002 writes there). No change needed for feature-level.
+- `src/cli/status-features.ts` — add project-level status display: read `nax/status.json` to show "currently running" info at the top of `nax status` output
+- `src/cli/diagnose.ts` — change `.nax-status.json` → `nax/status.json`
+
+**Test:** `nax status` shows current run info from project-level status + per-feature historical info. `nax diagnose` correctly detects running/stalled/crashed state.
+
+### SFC-004: Clean up dead code
+
+**What:** Remove deprecated paths and dead options.
+
+**Changes:**
+- `bin/nax.ts` — remove `--status-file` option definition and `statusFilePath` resolve logic
+- `src/cli/diagnose.ts` — remove `.nax-status.json` path reference
+- `src/execution/runner.ts` — remove `statusFile?` optional from `RunOptions` type (now required, auto-computed)
+
+**Test:** Verify no references to `.nax-status.json` or `--status-file` remain in codebase.
+
+---
+
+## Schema (unchanged)
+
+The `NaxStatusFile` interface in `src/execution/status-file.ts` is already correct. No schema changes needed — both project-level and feature-level files use the same `NaxStatusFile` type.
+
+---
+
+## Out of Scope
+
+- Central Run Registry (`~/.nax/runs/`) — v0.23.0
+- Status file cleanup/rotation — future

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

@@ -0,0 +1,61 @@
+{
+  "project": "nax",
+  "branchName": "feat/status-file-consolidation",
+  "feature": "status-file-consolidation",
+  "version": "0.22.2",
+  "description": "Auto-write status.json to well-known paths (project-level + feature-level). Remove --status-file CLI flag. Align nax status and nax diagnose readers.",
+  "userStories": [
+    {
+      "id": "SFC-001",
+      "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",
+      "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)"
+      ]
+    },
+    {
+      "id": "SFC-002",
+      "title": "Write feature-level status on run end",
+      "description": "On run complete/fail/crash, write the final status snapshot to <workdir>/nax/features/<feature>/status.json. Add writeFeatureStatus(featureDir) method to StatusWriter. Call it in runner.ts finally block and in crash-recovery.ts.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After a completed run, nax/features/<feature>/status.json exists with status 'completed'",
+        "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"
+      ]
+    },
+    {
+      "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.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax status shows current run info from nax/status.json at the top",
+        "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"
+      ]
+    },
+    {
+      "id": "SFC-004",
+      "title": "Clean up dead code",
+      "description": "Remove --status-file option definition from bin/nax.ts. Remove .nax-status.json path from diagnose.ts. Remove statusFile optional from RunOptions type (now required, auto-computed). Verify no stale references remain.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "No references to --status-file CLI option in codebase",
+        "No references to .nax-status.json in codebase",
+        "RunOptions.statusFile is required (not optional)",
+        "All existing tests pass"
+      ]
+    }
+  ]
+}

package/package.json

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

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

@@ -37,7 +37,7 @@ export interface RunSetupOptions {
   hooks: LoadedHooksConfig;
   feature: string;
   dryRun: boolean;
-  statusFile?: string;
+  statusFile: string;
   logFilePath?: string;
   runId: string;
   startedAt: string;

package/src/execution/runner.ts

@@ -47,8 +47,8 @@ export interface RunOptions {
   parallel?: number;
   /** Optional event emitter for TUI integration */
   eventEmitter?: PipelineEventEmitter;
-  /** Path to write a machine-readable JSON status file. Omit to skip writing. */
-  statusFile?: string;
+  /** Path to write a machine-readable JSON status file */
+  statusFile: string;
   /** Path to JSONL log file (for crash recovery) */
   logFilePath?: string;
   /** Formatter verbosity mode for headless stdout (default: "normal") */

package/src/execution/status-writer.ts

@@ -50,7 +50,7 @@ export interface StatusWriterContext {
  *   await sw.update(totalCost, iterations);
  */
 export class StatusWriter {
-  private readonly statusFile: string | undefined;
+  private readonly statusFile: string;
   private readonly costLimit: number | null;
   private readonly ctx: StatusWriterContext;
 
@@ -60,7 +60,7 @@ export class StatusWriter {
   private _currentStory: RunStateSnapshot["currentStory"] = null;
   private _consecutiveWriteFailures = 0; // BUG-2: Track consecutive write failures
 
-  constructor(statusFile: string | undefined, config: NaxConfig, ctx: StatusWriterContext) {
+  constructor(statusFile: string, config: NaxConfig, ctx: StatusWriterContext) {
     this.statusFile = statusFile;
     this.costLimit = config.execution.costLimit === Number.POSITIVE_INFINITY ? null : config.execution.costLimit;
     this.ctx = ctx;
@@ -107,7 +107,7 @@ export class StatusWriter {
   /**
    * Write the current status to disk (atomic via .tmp + rename).
    *
-   * No-ops if statusFile was not provided or _prd has not been set.
+   * No-ops if _prd has not been set.
    * On failure, logs a warning/error and increments the BUG-2 failure counter.
    * Counter resets to 0 on next successful write.
    *
@@ -116,7 +116,7 @@ export class StatusWriter {
    * @param overrides  - Optional partial snapshot overrides (spread last)
    */
   async update(totalCost: number, iterations: number, overrides: Partial<RunStateSnapshot> = {}): Promise<void> {
-    if (!this.statusFile || !this._prd) return;
+    if (!this._prd) return;
     const safeLogger = getSafeLogger();
     try {
       const base = this.getSnapshot(totalCost, iterations);

package/src/routing/strategies/llm.ts

@@ -116,15 +116,18 @@ 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.
+    outputPromise.catch(() => {});
     try {
       proc.stdout.cancel();
     } catch {
-      // ignore cancel errors
+      // ignore cancel errors — stream may already be locked by Response
     }
     try {
       proc.stderr.cancel();
     } catch {
-      // ignore cancel errors
+      // ignore cancel errors — stream may already be locked by Response
     }
     proc.kill();
     throw err;

package/test/integration/execution/status-file-integration.test.ts

@@ -3,12 +3,11 @@
  * Integration Tests: Status File — runner + CLI (T2)
  *
  * Verifies:
- * - RunOptions.statusFile?: string exists
- * - Status file written at all 4 write points (dry-run path)
- * - Status file NOT written when statusFile omitted
+ * - RunOptions.statusFile: string is required
+ * - Status file always written at all 4 write points (dry-run path)
  * - Valid JSON at each stage, NaxStatusFile schema correct
  * - completed status, progress counts, null current at end
- * - --status-file CLI option wiring (type-level)
+ * - CLI automatically computes statusFile to <workdir>/nax/status.json
  */
 
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
@@ -53,13 +52,13 @@ class MockAgentAdapter implements AgentAdapter {
     return [this.binary];
   }
   async run(_o: AgentRunOptions): Promise<AgentResult> {
-    return { success: true, exitCode: 0, output: "", durationMs: 10, estimatedCost: 0 };
+    return { success: true, exitCode: 0, output: "", durationMs: 10, estimatedCost: 0, rateLimited: false };
   }
   async plan(_o: PlanOptions): Promise<PlanResult> {
-    return { specContent: "# Feature\n", success: true };
+    return { specContent: "# Feature\n" };
   }
   async decompose(_o: DecomposeOptions): Promise<DecomposeResult> {
-    return { stories: [], success: true };
+    return { stories: [] };
   }
 }
 
@@ -143,7 +142,7 @@ async function runWithStatus(feature: string, storyCount = 1, extraOpts: Partial
 // RunOptions type-level checks
 // ============================================================================
 describe("RunOptions.statusFile", () => {
-  it("is optional (can be omitted)", () => {
+  it("is required", () => {
     const opts: RunOptions = {
       prdPath: "/tmp/prd.json",
       workdir: "/tmp",
@@ -151,52 +150,25 @@ describe("RunOptions.statusFile", () => {
       hooks: { hooks: {} },
       feature: "test",
       dryRun: true,
+      statusFile: "/tmp/nax/status.json",
     };
-    expect(opts.statusFile).toBeUndefined();
-  });
-
-  it("accepts a string value", () => {
-    const opts: RunOptions = {
-      prdPath: "/tmp/prd.json",
-      workdir: "/tmp",
-      config: createTestConfig(),
-      hooks: { hooks: {} },
-      feature: "test",
-      dryRun: true,
-      statusFile: "/tmp/nax-status.json",
-    };
-    expect(opts.statusFile).toBe("/tmp/nax-status.json");
+    expect(opts.statusFile).toBe("/tmp/nax/status.json");
   });
 });
 
 // ============================================================================
-// No status file when option omitted (regression test)
+// Status file is always written when provided
 // ============================================================================
-describe("status file not written when omitted", () => {
+describe("status file always written when provided", () => {
   let tmpDir: string;
   afterEach(async () => {
     if (tmpDir) await fs.rm(tmpDir, { recursive: true, force: true });
   });
 
-  it("does not create any .json file in tmpDir", async () => {
-    const setup = await setupDir("no-sf", 1);
+  it("writes status file to provided path during dry-run", async () => {
+    const { setup, statusFilePath } = await runWithStatus("sf-always-written", 1);
     tmpDir = setup.tmpDir;
-    const before = await fs.readdir(setup.tmpDir);
-
-    await run({
-      prdPath: setup.prdPath,
-      workdir: setup.tmpDir,
-      config: createTestConfig(),
-      hooks: { hooks: {} },
-      feature: "no-sf",
-      featureDir: setup.featureDir,
-      dryRun: true, // no statusFile
-      skipPrecheck: true,
-    });
-
-    const after = await fs.readdir(setup.tmpDir);
-    const newJson = after.filter((f) => f.endsWith(".json") && !before.includes(f));
-    expect(newJson).toHaveLength(0);
+    expect(nodeFs.existsSync(statusFilePath)).toBe(true);
   });
 });
 
@@ -299,28 +271,19 @@ describe("status file written during dry-run", () => {
 });
 
 // ============================================================================
-// CLI --status-file wiring (type check only)
+// CLI status file wiring (type check only)
 // ============================================================================
-describe("CLI --status-file wiring", () => {
-  it("RunOptions.statusFile is passed through correctly", () => {
-    const withFile: RunOptions = {
-      prdPath: "/tmp/prd.json",
-      workdir: "/tmp",
-      config: createTestConfig(),
-      hooks: { hooks: {} },
-      feature: "test",
-      dryRun: false,
-      statusFile: "/tmp/status.json",
-    };
-    const withoutFile: RunOptions = {
+describe("CLI auto-computed status file", () => {
+  it("RunOptions.statusFile is required and always provided", () => {
+    const opts: RunOptions = {
       prdPath: "/tmp/prd.json",
       workdir: "/tmp",
       config: createTestConfig(),
       hooks: { hooks: {} },
       feature: "test",
       dryRun: false,
+      statusFile: "/tmp/nax/status.json",
     };
-    expect(withFile.statusFile).toBe("/tmp/status.json");
-    expect(withoutFile.statusFile).toBeUndefined();
+    expect(opts.statusFile).toBe("/tmp/nax/status.json");
   });
 });

package/test/integration/execution/status-writer.test.ts

@@ -77,14 +77,10 @@ function makeCtx(overrides: Partial<StatusWriterContext> = {}): StatusWriterCont
 // ============================================================================
 
 describe("StatusWriter construction", () => {
-  test("constructs without error when statusFile is defined", () => {
+  test("constructs without error with statusFile path", () => {
     expect(() => new StatusWriter("/tmp/status.json", makeConfig(), makeCtx())).not.toThrow();
   });
 
-  test("constructs without error when statusFile is undefined (no-op mode)", () => {
-    expect(() => new StatusWriter(undefined, makeConfig(), makeCtx())).not.toThrow();
-  });
-
   test("costLimit Infinity → stored as null in snapshot", async () => {
     const dir = await mkdtemp(join(tmpdir(), "sw-test-"));
     const path = join(dir, "status.json");
@@ -214,13 +210,6 @@ describe("StatusWriter.getSnapshot", () => {
 // ============================================================================
 
 describe("StatusWriter.update no-op guards", () => {
-  test("no-op when statusFile is undefined (even with prd set)", async () => {
-    const sw = new StatusWriter(undefined, makeConfig(), makeCtx());
-    sw.setPrd(makePrd());
-    // Should not throw
-    await expect(sw.update(0, 0)).resolves.toBeUndefined();
-  });
-
   test("no-op when prd not yet set", async () => {
     const dir = await mkdtemp(join(tmpdir(), "sw-test-"));
     const path = join(dir, "status.json");