[RFC / Discussion] Reflections on TUI async lifecycle, blast radius, and modular boundaries in Zero

[hazyhaar]

Hi everyone, cc @jatmn,

First of all, thank you for the thorough and rigorous reviews on recent PRs (such as #953). The high bar on concurrency invariants and platform safety is truly appreciated.

Going through these successive review rounds got me reflecting on our debugging ergonomics: I rarely experienced this much ping-pong while tracking down lifecycle and UI regressions, and it made me wonder whether our current repository structure and state coupling might be contributing to these cascading side effects.

When working inside internal/tui/model.go (and across internal/ in general), I noticed how easily a change targeting a specific view or an async loading path can inadvertently cross paths with other components (modal routing, git sweeps, or terminal resizing) due to shared state fields and distributed lifecycle checks.

To explore this, I put together an experimental spike on a separate branch in my fork (proposal/decoupled-architecture) with a structure that feels more modular and familiar to me, trying to see if we could naturally minimize blast radius and isolate unit tests.

I documented some thoughts in docs/repostructure.md, but I would love to get your perspective and humble advice on a few design questions:

---

1. Pure, Zero-Dependency Utility Packages (pkg/)

Would there be value in extracting completely self-contained, pure algorithms out of internal/tui/ into standalone pkg/ packages?

• For instance, in the spike:
  • pkg/difftool: purely handles canonical line key normalizations (CanonicalLineKey, MatchChangedLines) so that terminal presentation transforms (tabs, control bytes) can never interfere with diff gutter alignment (▎).
  • pkg/ansi: dedicated to terminal string sanitization (SanitizeFileLine).
  • pkg/safefs: houses non-wrapping integer bounds arithmetic (InBoundsNonWrapping for $2^{64}-1$ anti-wrap) and atomic file updates.
• Question: Does having standalone pkg/ packages (which execute unit tests in ~2ms with zero UI setup) align with the long-term vision of Zero, or is keeping all helpers under internal/ an intentional boundary design?

---

2. Unified Monotonic Authority Store vs. Distributed State Fields

In #953, moving to a monotonically increasing source revision (pathRevisions map[string]uint64) proved to be the key to eliminating race conditions where intermediate resize/theme events could drop required source refreshes.

• In the experimental branch, we isolated this into internal/ui/state.MonotonicAuthority (liveSeq, lifetimeToken, pathRevisions, generation).
• Question: How do maintainers view centralizing async lifecycle authorities into a dedicated state store versus continuing to maintain sequence tokens on the main model struct?

---

3. Structuring internal/tui/ by Sub-domains

With internal/tui/ currently holding ~250 files and over 90k lines in a flat directory, navigating and assessing caller impact can be challenging.

• Question: Would the core team be open in the future to grouping TUI components into sub-packages (such as ui/views, ui/components, ui/layout, ui/state), or does the current flat internal/tui layout provide specific advantages for Bubbletea model composition that I might be overlooking?

---

Everything on the experimental branch is fully green under go test -race -count=1 ./... across all 83 packages, but this is purely shared as food for thought and an open conversation starter.

I would love to hear your thoughts on whether any of these patterns could be helpful as Zero continues to scale!

Thanks again for your time and feedback.

[jatmn]

I don’t lead this project, so I may not be the right person to direct this proposal to. That said, I do think the information is useful and worth considering.

From my perspective, the extended review process is primarily driven by three factors:

1. Review feedback can unintentionally expand the scope of a PR.

   CodeRabbit AI provides useful feedback, but its suggestions can sometimes lead to scope drift—either directly or through follow-up changes. This appears to have become more noticeable over the past month, with reviews increasingly prompting changes beyond the PR’s original purpose.

2. Many built-in PR-review workflows are intentionally lightweight.

   The general PR-review capabilities included with most coding harnesses, including Zero, are often designed to provide a “good enough” review for common cases.

   The review workflow I use is custom-built and performs several independent, critical passes. In practice, it is closer to running a standard review five to ten times, with each pass approaching the code from a fresh, blind context.

   This is important because current models—including the Fabel family—can be biased toward their own generated code and preferred coding styles. They also do not always follow every review requirement consistently. Even when a review appears thorough, the model may concentrate heavily on one issue while only sampling other parts of the change.

3. How authors use their own coding harnesses to address findings can create additional churn.

   I’m not pointing fingers here; I have encountered the same challenge in my own reviews and have sometimes gone through many rounds of review against my own PR-review workflow.

   The central issue is how the model is instructed to address reported findings. If the instructions are too broad—or sometimes even too narrow—one of two outcomes commonly occurs:

   • The fix introduces additional scope drift. The model may make broader changes than necessary while attempting to address the feedback. If those changes generate new review findings, the process can become a cycle of correcting changes introduced by earlier corrections. A relatively small feature or bug fix can gradually become a rewrite of every function it touches.
   • The fix is applied too literally. When instructions are overly specific, the model may correct only the exact instance that was reported without checking for the same issue elsewhere. This can lead to repeated review rounds as each related occurrence is discovered separately.

Ultimately, I believe the extended review cycle comes down to three closely related factors:

• CodeRabbit AI can unintentionally encourage scope drift, depending on how its findings are interpreted.
• Many standard PR-review workflows do not perform a genuinely comprehensive review without several independent passes.
• The way we prompt our own models to implement fixes—and the care with which we inspect those changes—has a significant effect on review churn.

One practical way to reduce this is to challenge each proposed fix before accepting it. Ask whether the change stays within the PR’s intended scope, whether it introduces unnecessary refactoring, and whether the same issue exists elsewhere in the relevant code.

A rapidly growing PR is often a useful warning sign that scope drift may be occurring. Stepping back and reviewing how the PR expanded can help identify where the model chose an overly broad or expedient solution. It can also reveal cases where the reported issue already exists on the main branch and would be better handled in a separate PR.

[PierrunoYT]

A separate whole-repository audit at 1b5db17 reached a compatible but narrower conclusion, so I am adding evidence here rather than opening a competing architecture thread.

Observed concentration:

• internal/tui/model.go: 6,064 production lines;
• internal/agent/loop.go: 3,487 lines;
• internal/cli/app.go: 1,589 lines;
• CLI imports 59 internal packages; TUI imports 39.

The audit does not treat line count as a defect and does not recommend a pkg/ extraction target, microservices, a new framework, or a big-bang package move. Existing provider, execution, registry, sandbox, storage, and extension boundaries are meaningful and test-rich.

The proposed incremental direction for findings ARCH-01 through ARCH-04 is:

1. Keep one modular monolith and retain agent.Run and the Bubble Tea root as stable facades.
2. Extract one state owner at a time: provider session, turn/compaction driver, permission state, tool batching, and finalization in the agent; feature-owned models behind the TUI root/router.
3. At the CLI edge, introduce command-specific application services instead of expanding the all-command appDeps shape.
4. Separate config parse/layer/trust normalization from narrow domain validators while preserving exact precedence and fail-closed project restrictions.
5. Consolidate permission identifiers and tool outcomes only after persisted/session/plugin compatibility is inventoried; aliases remain at ingress and unknown permission values fail closed.

Each step should preserve event traces, render/session fixtures, native-platform tests, race coverage, and current public CLI/config behavior. The useful fitness signal is reduced ownership/fan-out ambiguity, not hitting a line-count goal.

Full current/target maps and rationale:

• https://github.com/PierrunoYT/zero/blob/audit/codebase-audit-2026-09-08/docs/audit/CURRENT_ARCHITECTURE.md
• https://github.com/PierrunoYT/zero/blob/audit/codebase-audit-2026-09-08/docs/audit/TARGET_ARCHITECTURE.md
• https://github.com/PierrunoYT/zero/blob/audit/codebase-audit-2026-09-08/docs/audit/DECISIONS.md

[hazyhaar]

Thanks @PierrunoYT for this remarkable audit, and thanks to both you and @jatmn for taking the time to explain the collective mechanics of Go and upstream repository governance.

Coming mostly from local, dedicated environments where I focus heavily on low-level performance and isolated system tuning, I have to humbly admit I am still a rookie when it comes to the collaborative conventions and boundary discipline of a large-scale Go project. Your explanation completely clarified the philosophy behind Go’s internal/ boundary for an autonomous CLI tool.

I now fully understand why my initial mention of pkg/ (as well as referencing my standalone c2* packages) triggered skepticism: Zero is an hermetic, self-contained binary that should not be burdened with maintaining accidental public APIs or foreign external dependencies. That is 100% fine with me and I fully endorse this stance.

My core motivation has never been about exposing libraries or forcing a rewrite—it came purely from the review fatigue and regression churn we experienced on PR #953.
When state and dependencies are concentrated into massive structures—like the current appDeps bag in the CLI or the giant model struct in the TUI—running a unit test for a pure text or diff manipulation requires compiling and initializing half the application runtime. That coupling is what created the endless back-and-forth ping-pong on edge cases.

Keeping these utilities strictly within the monolith under internal/ (e.g. internal/difftool, internal/textutil), as isolated leaf packages without external exports:

1. Completely preserves Zero’s hermetic nature (0 public surface).
2. Shrinks the test compilation graph down to ~2ms with zero mocks and zero UI side-effects.
3. Radically reduces the review blast radius before reaching production.

Your phased migration roadmap (especially Phase 5 on isolating state owners behind stable facades like agent.Run and the Bubble Tea root router) is exceptionally well-structured.

Whenever you and the core team decide to greenlight portions of this roadmap, I'd be happy to pitch in. Often toward the end of the week I have leftover AI model quota and tokens to burn on open-source, so if there are well-scoped tasks where an extra pair of hands (and model cycles) would be useful, feel free to point me in that direction.

Thanks again for the masterclass in Go architecture!