Severity: LOW (architecture)
Status: ✅ FIXED
Files: AGENTS.md:59, docs/architecture.md:153, src/char_width.zig:30, src/thai.zig:460, src/log.zig:36
Two documents state the principle as absolute:
<!-- AGENTS.md:59 -->
4. **No global state.** Pass context explicitly. Use build-time dependency
injection for testing.
<!-- docs/architecture.md:153 -->
- No global state — context passed explicitly through `Server`/`Screen`/`Pane`.
rg -n '^var ' src/ returns eleven mutable module-level globals:
| Global | File | Assessment |
|---|---|---|
override_count, overrides |
char_width.zig:30-31 |
genuine design debt — causes bug #506 |
variation_selector_always_wide |
char_width.zig:47 |
genuine design debt — causes bug #506 |
libthai_instance, libthai_state |
thai.zig:460-461 |
acceptable; justified in the getLibThai docstring (bug #504) and confined to lazy dylib init |
log_fd |
log.zig:36 |
genuine design debt |
log_fd_failed, log_enabled |
log.zig:37-38 |
genuine design debt |
runtime_log_level |
log.zig:112 |
genuine design debt |
sigchldFlag |
server/server.zig:12 |
required — async-signal-safe handler target |
sigwinchFlag, sighupFlag |
main.zig:36,39 |
required — async-signal-safe handler targets |
The signal-handler globals cannot be threaded through context: a POSIX signal
handler may only touch volatile sig_atomic_t objects, so these are a correct
and unavoidable exception that simply is not documented as one.
The remaining eight are ordinary configuration and cache state that could be
reached through an explicit context parameter. The char_width group is not
cosmetic — it is the mechanism behind bug #506, where a session-scoped option
mutates a process-global table.
An unqualified “no global state” claim in the project’s own agent instructions is worse than no claim at all, because an agent or reviewer reading AGENTS.md will assume the invariant holds and will not look for exceptions.
Two options, in order of effort:
sigchldFlag, sigwinchFlag, sighupFlag),
the lazily-initialised libthai handle (bug #504), and the logger’s fd and
level state. Terminal-width and codepoint-width tables are the remaining
candidates for removal — see bug #506.”log_fd / log_enabled /
runtime_log_level into a Logger struct passed by pointer, and resolve
char_width’s tables per bug #506. This makes the original claim true.Option 1 should land regardless, since option 2 depends on the scope decision in bug #506.
Fixed by qualifying the claim in both places rather than removing the globals, which depends on the scope decision in bug #506.
AGENTS.md principle 4 is now “Minimize global state” and names all three
exception groups: the async-signal handler flags (with the POSIX reason they
cannot be threaded through context), the lazily-loaded libthai handle
(bug #504), and the logger state (bug #510, whose fd is now atomic). It also
points at rg -n '^var ' src/ as the way to check the invariant, and notes
that char_width’s tables are honestly server-scoped per bug #506.docs/architecture.md carries the same qualified list.The claim is now true as written: it is a default to defend, with the exceptions enumerated, rather than an absolute that a reviewer would not think to check.