refactor(tui): TUI module split, CPU spinlock fix, and TUI enhancements

.gitignore

@@ -11,4 +11,8 @@ third_party/
 __pycache__
 
 ## Models
-ModernBERT-bash-classifier/
+ModernBERT-bash-classifier/
+vendor/fff/libfff_c.so
+vendor/local-models/
+.code-tandem/
+.opencode/

AGENTS.md

@@ -4,17 +4,52 @@ This project uses Zig version 0.16
 
 Always consult the tigerstyle skill when writing code.
 
-## Building the TUI
+## Setup
+
+- After cloning, vendor `fff` (build into `vendor/fff/libfff_c.so`) and the ModernBERT ONNX model (`vendor/local-models/ModernBERT-bash-classifier`). Both are gitignored.
+- Use `OMP_WAIT_POLICY=passive` at runtime to avoid MKL/CPU spin in the embedding worker.
+- `zig build install -Doptimize=ReleaseFast --prefix $HOME/.local` produces an installable binary under `~/.local/bin/`.
 
-We use libvaxis vxfw for building the TUI. The source code for this library is inside zig-pkg.
+## Building the TUI
 
-Prefer to use the primitives provided by the framework as much as possible.
+TUI built with libvaxis vxfw (source in zig-pkg). Prefer framework primitives.
+
+**vxfw gotcha:** widget methods like `TextField.widget()` are *mutating* — they take `*Self`, not `*const Self`. Accessors returning `*TextField` must be declared on `*App`, not `*const App`, or the call site fails to type-check.
+
+**Zig 0.16 field rule:** `pub` cannot precede a field declaration — only functions/variables. Cross-module field access goes through `pub fn` accessors (`getX()` form, never `X()`, because of the field-vs-method name collision).
+
+**TUI module split.** `src/tui.zig` holds the `App` lifecycle and the top-level
+`RootWidget`; the rest of `src/tui/` is split by concern. See `README.md`
+Architecture for the current module list (kept in sync as `tui.zig` shrinks).
+
+**Domain extraction pattern.** Isolated domain clusters (lane lifecycle, diff
+lifecycle, session switching, at-search, transcript navigation, permission,
+event callbacks, queue) live under `src/tui/` as free-function modules.
+Each module imports `const tui = @import("../tui.zig")` and defines `pub fn`
+taking `*App` as the first parameter. The original App method stays as a
+1-line delegate (Strangler Fig) so inline tests in `tui.zig` resolve via the
+struct. When a private App method is needed from the new module, promote it to
+`pub` — not `pub const` (that is for module-level re-exports of nested types).
+
+**Widget extraction pattern.** Isolated widgets live under `src/tui/widgets/`.
+A new widget file declares the outer border widget as
+`pub const NameWidget = struct { app: *App, pub fn widget(...) vxfw.Widget { ... } }`
+and a private `Inner` struct built inside `draw()` from a `vxfw.DrawContext`.
+The file imports `const tui = @import("../../tui.zig");`,
+`const tui_style = @import("../style.zig");`, `const panel = @import("panel.zig");`
+and re-aliases `const App = tui.App;`. Nested types from other modules
+(e.g. `BackgroundManager.JobView`, `ApprovalSnapshot`) are re-exported through
+`pub const` in `tui.zig` so widget files can reach them as `tui.<module>.<Type>`.
+
+**Per-mode command routing.** `src/tui/command_router.zig` holds one struct per
+`App.Mode` variant. Each struct owns a `handle` method that used to be a private
+method on `App`; the dispatcher is a free function delegating to the right
+struct. This is the place to add new per-mode logic — don't reintroduce
+private methods on `App` for key handling.
 
 ## Zig Development
 
-Use `zigdoc` to discover current APIs for the Zig standard library and any third-party dependencies before coding.
-
-Examples:
+Use `zigdoc` to discover APIs before coding.
 
 ```bash
 zigdoc std.fs
@@ -98,13 +133,16 @@ const output = try writer.toOwnedSlice();
 ## Safety
 
 - Add assertions at API boundaries and state transitions; avoid trivial assertions.
-- Keep functions small and push pure computation into helpers.
+- Keep functions small; push pure computation into helpers.
 - Comments should explain why, not what.
 
 ## Verifying
 
-Run the following:
+Run:
 
 - `zig fmt`
-
 - `zig build test`
+
+## Known Issues
+
+- **High CPU usage from spinlocks.** `std.atomic.Mutex` busy-waits and pegs the CPU on multi-core. Use `std.Io.Mutex` and `std.Io.Condition` instead (paired via `static_thread_pool` or similar). Symptom: 80% CPU at idle, drops to ~2% after the fix. Files affected: `lib/logger.zig`, `src/agent.zig`, `src/background.zig`, `src/session.zig`.

README.md

@@ -29,3 +29,51 @@ zig build run
 ```
 
 Add the binary (`zig-out/bin/nova`) to your PATH so you can invoke it from anywhere.
+
+# Architecture
+
+The TUI is a vxfw application. `src/tui.zig` holds the `App` lifecycle
+and the top-level `RootWidget`; the rest of `src/tui/` is split by
+concern:
+
+- `event_router.zig` — top-level event entry (`captureEvent`).
+- `command_router.zig` — per-mode key dispatch (one struct per `App.Mode`).
+- `app_state.zig` — `App` state grouped into sub-structs.
+- `background_delivery.zig` — background-job poll/format/deliver, modal toggling, job cancel.
+- `turn_lifecycle.zig` — turn start, interrupt, event application, cancel/reset.
+- `checkpoint.zig` — git-shadow checkpoint snapshotting, readiness checks, and `/save`.
+- `mode_lifecycle.zig` — command matching, slash menu checks, mode switching.
+- `input_lifecycle.zig` — input buffer peeking, clearing, vertical cursor navigation.
+- `transcript_lifecycle.zig` — runtime installation and transcript rebuilding.
+- `lane_lifecycle.zig` — lane naming, cycling, closing, merging, `/lanes` overlay.
+- `diff_lifecycle.zig` — async diff refresh pipeline (DiffCounts, schedule/cancel/drain).
+- `session_switcher.zig` — resume picker, session creation, timeline navigation.
+- `at_search.zig` — `@` file / `$` skill mention popup.
+- `transcript_nav.zig` — transcript scrolling, auto-scroll, long-message paging.
+- `permission.zig` — tool-call approval/rejection overlay.
+- `event_callbacks.zig` — vxfw input-change callbacks (`inputChanged`, `paletteInputChanged`).
+- `queue.zig` — enqueue, flush, and navigate queued user messages.
+- `layout.zig` — `rootLayout` math for `drawRoot` (transcript / loading / input row split).
+- `lane_column.zig` — per-lane bordered transcript column (split view).
+- `diff_viewer_overlay.zig` — full-screen `/diff` overlay.
+- `root_layout.zig` — top-level `drawRoot` layout (tile grid, loading, input, overlay stack).
+- `lifecycle.zig` — `deinit`, `handleTick`, `createParallelLane`, diff key handlers, `syncFocus`, `submit`, `ensureTick`.
+- `diff_utils.zig` — pure diff-count stat/numstat parsers, git label loader.
+- `lanes.zig` — `MergeSource` type + lane merge helpers (`workingLaneOf`, `laneErrorText`).
+- `provider_model.zig` — provider connection, model catalogue loading, model selection (~50 functions).
+- `thread.zig` — `Thread` (lane) state, multi-lane state machine.
+- `turn.zig` / `turn_view.zig` — turn lifecycle + render.
+- `diff_viewer.zig` — `/diff` inline-diff helpers (used by `widgets/diff.zig`).
+- `model_catalogue.zig` / `model_loader.zig` / `model_cache.zig` — model
+  catalogue, async loader, cached model handles.
+- `provider_controller.zig` — provider API controller.
+- `agent_worker.zig` — agent worker plumbing.
+- `blackhole.zig` — startup animation.
+- `metrics.zig` — runtime metrics.
+- `naming.zig` / `style.zig` / `status.zig` / `tool_policy.zig` —
+  shared helpers and policies.
+
+`src/tui/widgets/` holds the per-widget draw code (message, command
+panel, at_search, background_jobs, permission, diff, loading, transcript,
+input, overlay, lanes picker, model picker, provider picker, resume
+picker, help picker, tree selector, panel layout, tree art).

_pm/Archives/tui-domain-extract/backlog.md

@@ -0,0 +1,53 @@
+# tui-domain-extract — Backlog
+
+## Refactor targets
+
+Extract remaining domain clusters from `tui.zig` (5100 lines → target ~3000).
+Discovered by BFG analysis: `tui.zig` god object at 5.100 lines with 227
+functions is the #1 coupling hotspot (BFG coupling score 85, code quality 70).
+
+### Phase 1: Lane lifecycle → `tui/lane_lifecycle.zig` (~400 lines)
+
+28 functions: lane naming, cycling, closing, merging, fullscreen toggle,
+lanes picker, parked-lane management.
+
+Functions to move:
+- captureLaneContext, scheduleLaneNaming, drainLaneNaming, renameLaneBranch
+- cancelLaneNaming, namingActive, reportLaneError, activeIndex
+- anyTurnActive, cycleLane, switchToNextLane, toggleLaneFullscreen
+- closeActiveLane, abandonLane, laneMergeDir, mergeLane
+- createMergePicker, confirmMergeDest, openLanesPicker
+- collectParkedLanes, laneOpenAtPath, reloadParkedLanes
+- mergeSelectedParked, deleteSelectedParked, laneEntryCount
+- clearLanesState, buildLaneEntries, handleLanesKey
+
+### Phase 2: Diff lifecycle → `tui/diff_lifecycle.zig` (~110 lines)
+
+Types + helpers for the async diff refresh pipeline.
+
+Items to move:
+- DiffCounts, DiffRefreshJob, DiffRefreshOutcome structs
+- runDiffRefresh, diffCountCommand
+- refreshDiffCounts, installDiffCounts, scheduleDiffRefresh
+- cancelDiffRefresh, drainDiffRefresh, populateDiffFromCache
+- diffCountsVisible
+
+### Phase 3: Session switching → `tui/session_switcher.zig` (~140 lines)
+
+Resume picker state management + session creation/switching.
+
+Functions to move:
+- openResumePicker, reloadResumeSessions, selectedResumeSummary
+- visibleResumeCount, toggleSelectedResumeProject, resumeFoldIndex
+- resumeClearFolds, resumeClear, syncResumeListCursor
+- reloadTreeNodes, navigateToEntry, restoreCheckpointForBranch
+- switchToSession, switchToNewSession, createRuntime
+- reportSessionSwitchError
+
+### Spotted but deferred
+
+- submitMode / cancelMode (~125 lines) — stays per tui-split R6.0 audit
+- At-search (~110 lines) — tightly coupled to input, low ROI
+- Transcript navigation (~100 lines) — spread across metrics + lifecycle
+- Queue management (~80 lines) — tightly coupled to beginSubmit
+- test blocks (~200 lines) — belong with tested code

_pm/Archives/tui-domain-extract/done.md

@@ -0,0 +1,38 @@
+# tui-domain-extract — Done
+
+Completed items, kept for history.
+
+- **Phase 1** `tui/lane_lifecycle.zig` — extract lane lifecycle *(2026-07-22, commit `6c38502`)*
+  - 19 pub functions + 4 internal helpers moved. Strangler Fig pattern.
+  - `tui.zig` 5100 → **4728** (-372, -7.3%). `lane_lifecycle.zig` +491 lines.
+  - `zig build` and `zig build test` pass.
+
+- **Phase 2** `tui/diff_lifecycle.zig` — extract diff lifecycle *(2026-07-22, commit `8867b57`)*
+  - 3 structs (DiffCounts, DiffRefreshJob, DiffRefreshOutcome), 1 command const,
+    8 App methods, 1 private free function moved. Re-exported as `tui.DiffCounts`
+    / `tui.DiffRefreshOutcome` for backward compat.
+  - `tui.zig` 4728 → **4571** (-157, -3.3%). `diff_lifecycle.zig` +193 lines.
+  - `zig build` and `zig build test` pass.
+
+- **Phase 3** `tui/session_switcher.zig` — extract session switching *(2026-07-22, commit `c9b7a5c`)*
+  - 14 App methods + 2 private helpers + 2 free functions moved. Covers resume
+    picker (openResumePicker, reloadResumeSessions, etc.), session creation
+    (switchToSession, switchToNewSession, createRuntime), timeline navigation
+    (navigateToEntry, restoreCheckpointForBranch, reloadTreeNodes).
+  - Promotions: `templateRuntime`, `installRuntime`, `clearConversation`,
+    `rebuildTranscriptFromAgent` made `pub` (were `fn` private, now called from
+    `session_switcher.zig`). `resumeSummaryLessThan` made `pub`.
+  - `tui.zig` 4571 → **4409** (-162, -3.5%). `session_switcher.zig` +226 lines.
+  - `zig build` and `zig build test` pass.
+
+## Total impact (all 3 phases)
+
+| Metric | Before | After | Delta |
+|--------|--------|-------|-------|
+| `tui.zig` lines | 5100 | **4409** | **-691 (-13.5%)** |
+| New modules | — | 3 (491 + 193 + 226 = **910 lines**) | |
+| Functions moved | — | 28 lane + 11 diff + 18 session = **57** | |
+| Promotions to `pub` | — | activeIndex, templateRuntime, installRuntime, clearConversation, rebuildTranscriptFromAgent, resumeSummaryLessThan | |
+| `zig build` | ✓ | ✓ | |
+| `zig build test` | ✓ | ✓ | |
+| Commits | — | 3 (`6c38502`, `8867b57`, `c9b7a5c`) | |

_pm/Archives/tui-domain-extract/todo.md

@@ -0,0 +1,11 @@
+# tui-domain-extract — Todo
+
+Items committed to, not yet started.
+
+## Status
+
+All phases completed:
+
+- [x] Phase 1: Lane lifecycle → `tui/lane_lifecycle.zig` *(`6c38502`)*
+- [x] Phase 2: Diff lifecycle → `tui/diff_lifecycle.zig` *(`8867b57`)*
+- [x] Phase 3: Session switching → `tui/session_switcher.zig` *(`c9b7a5c`)*

_pm/Archives/tui-domain-extract/wip.md

@@ -0,0 +1,15 @@
+# tui-domain-extract — In progress
+
+One item at a time (Rule 9).
+
+## Status
+
+All three phases committed and pushed. `tui.zig` 5100 → **4409** (-691, -13.5%).
+3 new modules totalling 910 lines. `zig build && zig build test` pass.
+
+## Constraints
+
+- Strangler Fig pattern: original methods stay as 1-line delegates.
+- `pub fn` accessors where cross-module reads need Zig 0.16 field bypass.
+- `zig build && zig build test` must pass after each commit.
+- atomic commits, pushed to `origin/main`.

_pm/Archives/tui-split/README.md

@@ -0,0 +1,86 @@
+# tui-split
+
+Refactor `src/tui.zig` into focused modules. Started 2026-07-21 from 8586 lines; down to ~5943 (-2643, -30.8%) after R1–R7 (35 atomic commits). Target ≤ 2500 lines.
+
+## Why
+
+BFG analysis (2026-07-21) flagged `src/tui.zig` as the worst coupling hotspot in the codebase:
+
+- 8586 lines (Rule 10 limit: 200 ideal, 300 split threshold; this was 28× over)
+- `captureEvent` 87 lines, 0.828 transform ratio (cognitive load)
+- `handleCommandKey` exhaustive call graph: 882 nodes, 12491 edges, cycles=true
+- 4 hubs >400 edges each (`captureEvent` 457, `handleCommandKey` 457, `cancelLaneNaming` 442, `freeDelivery` 441)
+- Single change to TUI flow touches many of them — high blast radius
+
+The file already imports 40+ submodules. It's not a monolith that knows nothing — it's a monolith that knows too much about each one.
+
+## Approach
+
+Strangler Fig (Rule 15):
+1. Create new module file
+2. Move related code
+3. Update `tui.zig` to import + delegate
+4. Build passes
+5. Old code removed in same commit
+
+No "compatibility shim" left behind (Rule 9 outcome-oriented).
+
+## Modules shipped (R1–R7.5)
+
+| File | Phase | Pulled from `tui.zig` |
+| --- | --- | --- |
+| `tui/event_router.zig` | R1 | `captureEvent` — key/mouse event dispatch |
+| `tui/command_router.zig` | R2 | `handleCommandKey` mode switch (struct-per-mode) |
+| `tui/app_state.zig` | R3 | `App` state grouped into 6 sub-structs |
+| `tui/background_delivery.zig` | R4 | background-job poll/format/deliver |
+| `tui/lane_column.zig` | R5.2a | `drawLaneColumn` |
+| `tui/diff_viewer_overlay.zig` | R5.2b | `drawDiffViewer` |
+| `tui/layout.zig` | R5.2c | `rootLayout` math |
+| `tui/root_layout.zig` | R6.2 | `drawRoot` layout |
+| `tui/lifecycle.zig` | R6.3–R7.3 | deinit, handleTick, createParallelLane, diff handlers, syncFocus, submit, ensureTick |
+| `tui/diff_utils.zig` | R7.4 | pure diff-count parsers |
+| `tui/lanes.zig` | R7.4 | MergeSource + lane helpers |
+| `tui/provider_model.zig` | R7.5 | provider + model catalogue setup (~50 fns) |
+| `tui/widgets/background_jobs.zig` | R5.1a | `BackgroundJobsWidget` |
+| `tui/widgets/permission.zig` | R5.1a | `PermissionWidget` |
+| `tui/widgets/diff.zig` | R5.1b | `DiffBodyWidget` + `DiffCommentEditor` + `DiffSearchWidget` |
+| `tui/widgets/loading.zig` | R5.1c | `LoadingWidget` |
+| `tui/widgets/transcript.zig` | R5.1d | `TranscriptWidget` + `MessageListBuilder` |
+| `tui/widgets/input.zig` | R6.1 | `InputWidget` + 13 wrapping helpers |
+| `tui/widgets/overlay.zig` | R7.1 | `OverlayWidget` + `OverlayInner` |
+
+## Remaining
+
+`tui.zig` ~5100 lines. No further extraction planned — each remaining
+block requires 5–15 pub promotions for diminishing ROI. Key stays:
+- `submitMode` (95 lines, ~25 private helpers — stays per R6.0 audit)
+- App business logic (provider, session, lane, diff lifecycle)
+- Event callbacks (`inputChanged`, `paletteInputChanged`)
+- Inline test blocks (~200 lines)
+
+Target: ≤ 2500 lines. 50.8% there.
+
+## What stays in `tui.zig`
+
+- `App` struct (with state fields moved to sub-structs)
+- `RootWidget` (top-level vxfw widget)
+- `init` / `run` lifecycle (deinit may move to R6 lifecycle module)
+- Cross-module glue (calls into the routers)
+
+Target: ≤ 2500 lines.
+
+## Non-goals
+
+- No behaviour change
+- No new features
+- No test additions (out of scope for this refactor; tracked separately if needed)
+- No rename of public App methods (just relocate)
+
+## Risks
+
+- `captureEvent` is the hot path on every keypress. Inlining decisions matter. (Mitigated by R1.)
+- `App` fields are read by ~30 files. Splitting state into sub-structs touches every call site. (Mitigated by R3.)
+- `handleCommandKey` switch arms have shared local state — pulling them apart requires care. (Mitigated by R2.)
+- R6 lifecycle extraction is blocked on private App method promotion; doing it without rethinking the boundary just churns `pub` keywords. (Documented; pick up in a dedicated session.)
+
+Mitigation: do it in small commits, run `zig build` after each, do a manual smoke test (launch, type, submit, switch modes).