Expand description
TUI runtime logging. Initializes a tracing-subscriber that writes to a
per-process file under ~/.codewhale/logs/tui-YYYY-MM-DD-PID.log, and (on
Unix and Windows) redirects the process’s stderr handle/fd to that same
file for the lifetime of the alt-screen TUI.
Why this exists:
The TUI runs inside an alt-screen buffer drawn by ratatui using an
incremental diff renderer. The renderer assumes nothing else is writing
to the terminal — its internal “current cells” model is the only source
of truth for what’s on screen. If anything emits raw bytes to stdout or
stderr while the alt-screen is active (an eprintln! from a sub-agent,
a tracing warning that defaulted to stderr, a panic message, a
third-party crate’s verbose output, …) those bytes land in the alt-screen
buffer at the current cursor position, scroll the buffer up, and leave
the renderer’s model out of sync with reality. The visible symptom is
“scroll demon”: the TUI content drifts down, leaving a band of blank
rows above the header. This was the regression in issue #1085 (fixed in
v0.8.18 by adding a viewport-reset path) and re-surfaced in v0.8.27
when the flicker fix dropped the \x1b[2J\x1b[3J deep-clear that had
been masking the underlying leak.
Defence-in-depth:
- A
tracing-subscriberwrites formatted logs to~/.codewhale/logs/tui-YYYY-MM-DD-PID.logsotracing::warn!/tracing::error!calls go somewhere observable instead of disappearing into the void (the TUI previously had no global subscriber, so contributors reached foreprintln!). - On Unix and Windows the process’s stderr handle/fd is redirected to
the same log file for the lifetime of
TuiLogGuard. Any raw stderr write — ours, a dependency’s, a panic message — lands in the log file instead of the alt-screen. The guard restores the original stderr handle/fd on drop so post-TUI shutdown messages still reach the user’s terminal. - Crate-level
#![deny(clippy::print_stderr, clippy::print_stdout)]on the TUI runtime modules forbids neweprintln!/println!calls at compile time. CLI-output paths (main.rseval, init,runtime_api::print_*,logging::info/warn) keep their existing prints via#[allow(clippy::print_stderr)]because they run before the alt-screen is entered.
Structs§
- TuiLog
Guard - Owns the active tracing subscriber and (on Unix/Windows) a saved copy of
the original
stderrhandle/fd so it can be restored on drop. Dropped when the TUI exits the alt-screen.
Functions§
- init
- Initialize the TUI logging subsystem. Idempotent across re-entry by way
of
set_default— if a global subscriber is already set we still install the stderr redirect. - log_
directory