Nuclear review 2026-07-09: tracking issue

[arzafran]

Umbrella for the 2026-07-09 nuclear review (whole-codebase maintainability audit: 10 module reviewers + Codex cross-model pass + dependency audit). Verdict: NEEDS RESTRUCTURING — behavior and dependencies are healthy, but 17 files sit over 1,000 lines (five god-objects) and the dominant systemic defect is copy-paste duplication that has already drifted into real bugs.

Recommended attack order:

1. Correctness first (small, ship independently)

• Socket telemetry blocks on DispatchQueue.main.sync in surface.report_tty and surface.ports_kick #82 telemetry main.sync on the prompt hot path
• Reconfiguring a connected remote workspace leaves stale per-panel remote bookkeeping #83 remote reconfigure leaves stale state
• tmuxNewWindow parses -t but never uses it (target session silently ignored) #84 tmuxNewWindow drops -t
• synchronizeHostedView has three diverged copies of its hide/retry block #85 synchronizeHostedView diverged retry copies
• Focus intent tracked in two independently-set booleans that can diverge #86 focus tracked in two divergent booleans

2. Pure deletions (same spirit as PR #81)

• Delete SurfacePool: 264 lines of permanently disabled machinery #89 delete SurfacePool
• Delete orphaned npm manifest, stale CLAUDE.md web/ reference, and verify build-sign-upload.sh #103 orphaned npm manifest, stale CLAUDE.md ref, build-sign-upload.sh

3. Biggest lines-moved-per-risk

• Evict the two squatters in TabManager: 1,340 lines of DEBUG harness and a 640-line stateless git/gh library #90 TabManager evictions + canonical lookup
• Finish the command-palette extraction: 3,900 lines and 30 @State properties never left ContentView #88 command-palette controller extraction

4. Highest long-term leverage

• One command catalog: socket dispatch, capabilities list, CLI table, and CLI help are four hand-maintained copies of the protocol #87 one command catalog (kills two shadow copies of the protocol)

5. Dedups

• Browser: one inspector-dock implementation instead of four; stop duplicating WK delegates in popups #91 browser inspector-dock + popup delegates
• Remote: one POSIX shell-quoting function and one SSH connection policy instead of 4+ copies #92 shell-quoting + SSH policy
• CLI: collapse 4 copy-pasted handle normalizers and the duplicated option-scan loop #93 CLI handle normalizers

6. Mechanical file splits (any order, independent)

• Split ContentView.swift (13,605 lines, ~90 types, 14 sub-domains) #94 ContentView
• Split AppDelegate.swift (11,871 lines); untangle handleCustomShortcut #95 AppDelegate
• Split TerminalController.swift (9,615) + BrowserAutomation (3,682) along command domains #96 TerminalController
• Split GhosttyTerminalView.swift (9,490) and TerminalWindowPortal.swift (2,045) #97 GhosttyTerminalView + TerminalWindowPortal
• Split Workspace.swift (7,437) and the remote-session files #98 Workspace + remote
• Browser subsystem: make Panel/View/Portal a real separation (24k lines, 4 files over 1k) #99 Browser Panel/View/Portal
• Split ProgramaApp.swift (5,854); dedupe file-watchers; clarify the three config systems #100 ProgramaApp + config systems
• Finish the CLI split: programa.swift is still 6,259 lines after #78 #101 CLI
• Split tmux_compat.go (1,801) and main.go (1,105) along their self-announced seams #102 Go daemon

Ground rules carried from the review: typing-latency paths (TabItemView shape, hitTest gating, forceRefresh, keyDown) are file-move-only, never reshape; socket commands with no in-app callers are live (CLI/daemon); whoever lands fixes owes CHANGELOG entries per nuclear-review Phase 4. Full evidence with line ranges lives in the review workflow output; each issue is self-contained enough to hand to an agent.

[arzafran]

All clusters executed in parallel worktrees, every branch green on both build and build-for-testing before push. PR map:

PR	Closes	Notes
#105	#82 #96	review flag: #82 changes the report_tty/ports_kick response contract (async echo instead of main-resolved surface)
#106	#88, refs #94	#94 remainder: WindowChrome/SidebarResizer/WorkspaceHandoff still in ContentView
#107	#95
#108	#85 #86 #89, refs #97	found and fixed the real focus dedup bug, not just the symptom
#109	#83 #92, refs #98	the missing per-panel reset fields were the reconfigure bug
#110	#91, refs #99 #103	one real inspector divergence preserved explicitly, documented per call site
#111	#100
#112	#90, refs #103
#113	#93 #101	also renames CMUXCLI to ProgramaCLI
#114	#84 #102	includes regression tests for the -t fix; go.mod module renamed
#115	#103	side-find: tests/test_ci_universal_release_settings.sh is unwired in CI and was already failing pre-change

#87 (command catalog) is deferred until #105 and #113 land, since it redesigns surfaces both PRs touch.

Merging guidance: the split PRs (#105 #106 #107 #108 #109 #110 #111 #112) all add entries to project.pbxproj, so merge them one at a time; each add/add conflict resolves by keeping both sides. #113 #114 #115 touch disjoint files and can merge any time. Every commit is individually revertible; behavior changes are called out in each PR's review-flag section.

[arzafran]

All merged. Final state:

• Merged individually: fix + split: TerminalController off-main telemetry and domain split #105 (tc), refactor: finish the CLI split, dedupe normalizers, rename CMUXCLI #113 (cli), fix + split: tmux new-window target honored, daemon files split #114 (go), chore: drop orphaned npm manifest, stale docs claim, dead release script #115 (hy)
• Merged consolidated: Nuclear review: consolidated fixes and splits (supersedes #106-#112) #116 (cv+ad+gv+ws+br+pa+tm, superseding refactor: extract command palette controller and split ContentView #106-refactor: evict UI-test harness and git prober from TabManager #112)
• Issues closed by the merges: Socket telemetry blocks on DispatchQueue.main.sync in surface.report_tty and surface.ports_kick #82 Reconfiguring a connected remote workspace leaves stale per-panel remote bookkeeping #83 tmuxNewWindow parses -t but never uses it (target session silently ignored) #84 synchronizeHostedView has three diverged copies of its hide/retry block #85 Focus intent tracked in two independently-set booleans that can diverge #86 Finish the command-palette extraction: 3,900 lines and 30 @State properties never left ContentView #88 Delete SurfacePool: 264 lines of permanently disabled machinery #89 Evict the two squatters in TabManager: 1,340 lines of DEBUG harness and a 640-line stateless git/gh library #90 Browser: one inspector-dock implementation instead of four; stop duplicating WK delegates in popups #91 Remote: one POSIX shell-quoting function and one SSH connection policy instead of 4+ copies #92 CLI: collapse 4 copy-pasted handle normalizers and the duplicated option-scan loop #93 Split AppDelegate.swift (11,871 lines); untangle handleCustomShortcut #95 Split ProgramaApp.swift (5,854); dedupe file-watchers; clarify the three config systems #100 Finish the CLI split: programa.swift is still 6,259 lines after #78 #101 Split tmux_compat.go (1,801) and main.go (1,105) along their self-announced seams #102 Delete orphaned npm manifest, stale CLAUDE.md web/ reference, and verify build-sign-upload.sh #103

Still open, by design:

• Split ContentView.swift (13,605 lines, ~90 types, 14 sub-domains) #94 Split GhosttyTerminalView.swift (9,490) and TerminalWindowPortal.swift (2,045) #97 Split Workspace.swift (7,437) and the remote-session files #98 Browser subsystem: make Panel/View/Portal a real separation (24k lines, 4 files over 1k) #99: split remainders (each issue body notes what's left)
• One command catalog: socket dispatch, capabilities list, CLI table, and CLI help are four hand-maintained copies of the protocol #87: the shared command catalog, now unblocked since both fix + split: TerminalController off-main telemetry and domain split #105 and refactor: finish the CLI split, dedupe normalizers, rename CMUXCLI #113 are on main. Note there is a pre-existing local branch refactor/ct1-command-descriptor-table that looks related; check it before starting fresh.

All nr/* branches deleted. Rolling release auto-ships from the #116 merge once main CI is green.