Skip to main content

Module runtime_log

Module runtime_log 

Source
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:

  1. A tracing-subscriber writes formatted logs to ~/.codewhale/logs/tui-YYYY-MM-DD-PID.log so tracing::warn! / tracing::error! calls go somewhere observable instead of disappearing into the void (the TUI previously had no global subscriber, so contributors reached for eprintln!).
  2. 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.
  3. Crate-level #![deny(clippy::print_stderr, clippy::print_stdout)] on the TUI runtime modules forbids new eprintln! / println! calls at compile time. CLI-output paths (main.rs eval, 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§

TuiLogGuard
Owns the active tracing subscriber and (on Unix/Windows) a saved copy of the original stderr handle/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