v0.9.3 Refactor: converge runtime ownership, delete duplication, and ship one executable

[Hmbown]

Why this is the v0.9.3 umbrella

Current main has 18 Rust packages and roughly 771k Rust lines, but about 87% remains inside codewhale-tui. The problem is not the crate count by itself: the TUI still owns parallel runtime, tool, config, session, hook, and control paths beside much smaller shared crates. v0.9.3 should make existing boundaries real, delete duplication, and measure the result.

Product goals

• one durable runtime and event/control vocabulary;
• one resolver for model, route, configuration, home, and secret-backend decisions;
• one canonical tool contract and dispatch registry;
• TUI, CLI, API, Fleet, and CWC as thin projections over owned runtime interfaces;
• one required installed executable, after the entrypoints and runtime seam are ready;
• fewer publish units only where the ownership/dependency evidence supports folding a crate.

Sequence

0. Ownership and measurement

• Refactor roadmap: ownership map and extraction plan #1897 — current source-of-truth and desired-owner map.
• Add cross-model context ablation and token-attribution release gates #4707 — prompt/schema size and offline quality attribution.
• Perf: explain and bound RSS after cancelling a 32-worker storm #4326 — repeated fanout/cancel latency and RSS plateau.
• Record dependency fanout, clean/incremental build time, artifact size, publish role, and live consumers for every crate before merge/fold decisions.

1. Correctness foundation

• runtime: serialize durable event writes across simultaneous TUI and web processes #4522 — serialize durable writes across processes.
• v0.9.3 Engine: build a mode invariant test matrix #3945 — one authority/mode invariant matrix.
• v0.9.3: define CLI/TUI parity for subagent and runtime control surfaces #4022 — explicit cross-surface capability and control parity.

2. Deletion-friendly performance

• perf(skills): full multi-root recursive skill rescan on every prompt build, load_skill call, and /skills command #3921 — cache skill discovery and prove zero unchanged recursive walks.
• v0.9.3: Remove the unmaintained ttf-parser PDF dependency chain #4382 — remove the unused font-parser dependency chain.
• Dead-code sweep: 464 #[allow(dead_code)] attributes are hiding drift #4785 and v0.9.3: Legacy follow-up and dead-code inventory: delete, wire, or track #3490 — delete or justify dormant code and allowances.

3. Runtime convergence

Land in dependency order:

1. Architecture D-2: unify ModelRegistry with RouteResolver #4166 — one route/model resolver.
2. v0.9.3 architecture: reconcile codewhale-tools and TUI ToolRegistry systems #4174 — one tool contract and registry.
3. Architecture D-3: merge JobManager and TaskManager #4167 — one durable background-work contract.
4. v0.9.3 architecture D-1: consolidate TUI engine onto core Runtime #4165 — move TUI execution onto the canonical runtime.
5. finish v0.9.3: define CLI/TUI parity for subagent and runtime control surfaces #4022 identity/control parity.

4. Structural decomposition

After ownership is settled:

• v0.9.3 Refactor: make codewhale-tui main.rs a thin CLI dispatcher #3948 — thin CLI entrypoint.
• v0.9.3 Refactor: split the agent tool runtime from schema, routing, and worktree plumbing #3950 — split subagent schema, manager, worker, routing, naming, and worktree ownership.
• Refactor: split shared modal infrastructure and owned views #3957 — shared modal infrastructure and owned views.
• refactor(tui): extract the EngineEvent drain from the 1,774-line run_event_loop; split sidebar.rs and widgets/mod.rs along their existing seams #3925 — engine/event-drain and widget ownership.

Code-motion changes must not carry behavior changes. Prefer moving contiguous code with its tests, then deleting the old block.

5. Distribution convergence

• v0.9.3 Single-binary distribution: library-backed TUI with in-process dispatch #4747 — library-backed TUI and one required installed executable.
• Update npm, archives, Homebrew, containers, dogfood, PTY tests, and CWC launch contracts together.
• Do not copy the TUI runtime into the CLI to claim a single binary.

6. Completion gate

• Refactor completion gate: architecture boundaries, ADRs, and module ownership #1899 — ADRs, ownership checks, compatibility tests, and anti-drift receipts.

Crate decision rule

Do not create or delete a crate to improve a count. For each small crate, choose one outcome with evidence:

• canonical owner: all duplicate callers migrate behind it;
• optional/heavy boundary: retain and keep out of default paths where possible;
• release/build-only boundary: retain if it removes duplicated release logic;
• fold: only after its consumers, compile impact, publication need, and compatibility surface are measured.

Acceptance

• Every selected issue states what remains on current main and which duplicate tracker it supersedes.
• Provider-free baselines capture clean/incremental build time, prompt/schema size, fanout latency, cancellation, RSS, and artifact size with exact SHA and repeated runs.
• TUI executes through the canonical runtime rather than a parallel engine.
• One registry owns tool identity, schema, capability metadata, and dispatch.
• Cross-surface session identity and unsupported states are explicit.
• Large-file extraction preserves byte-identical CLI/help and wire behavior.
• A normal install needs one executable and the release matrix proves it on every platform.
• The release removes more obsolete paths and blanket allowances than it adds.

[Hmbown]

Tracking tickets now filed for v0.8.63:

• v0.9.3: Extract inline tests from the largest Rust files before deeper refactors #3307 extracts inline tests from the largest Rust files before deeper refactors.
• v0.9.2: Split TUI history renderers into focused modules #3308 splits TUI history renderers into focused modules.
• v0.9.2: Split mcp.rs transports into focused modules #3310 splits mcp.rs transports into focused modules.
• v0.8.63: Split runtime_api.rs by API domain and stabilize handler ownership #3309 splits runtime_api.rs by API domain.
• v0.9.2: Split RuntimeThreadManager into store, executor, events, and types #3313 splits RuntimeThreadManager into store/executor/events/types.
• v0.8.65: Split config modules around provider/model/catalog boundaries #3311 splits config modules and centralizes provider lookup tables.
• v0.9.2: Extract App god object state into owned submodules #3314 extracts App god-object state into owned submodules.
• v0.9.3: Extract ui.rs run_event_loop into context-owned handlers #3312 extracts ui.rs::run_event_loop into context-owned handlers.

Related existing issue: #2608 tracks the provider-registry subset and has also been moved to v0.8.63.

Release-risk note: everything is now targeted at v0.8.63 per planning, but the intended implementation order should still be tests first, then low-risk file splits, then runtime/config work, with App and ui.rs last.