fix(tui): stop background cache-warning writes from corrupting TUI screen

Merged
JU
4mo ago
+89-20

Fixes #893

Root causes

Two independent, stackable issues cause the TUI's screen to get corrupted when a background cache shard save fails:

  1. Why the write fails on Windows (Access is denied (os error 5)): fs_atomic::windows_replace_file calls MoveFileExW(..., MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) exactly once, with no retry. This is a well-known source of transient ERROR_ACCESS_DENIED (5) / ERROR_SHARING_VIOLATION (32) on Windows — antivirus, indexing, and cloud-sync agents routinely hold a brief scan handle open on a just-written file. fs_atomic::replace_file is the single shared atomic-rename primitive used by 10 call sites across both crates, so this failure mode isn't unique to the cache.

  2. Why the failure corrupts the TUI display: message_cache::warn_cache_failure_once always calls tracing::warn!, then falls back to a raw eprintln! the first time each failure context is seen — because most non-TUI commands never install a tracing subscriber, so tracing::warn! alone would be silent. But the TUI only installs a subscriber under --debug. In normal (non-debug) use, that eprintln! writes directly to stdio while the TUI owns raw mode and the crossterm alternate screen, corrupting the rendered display exactly as reported.

Fix

  • fs_atomic.rs: wrap the Windows MoveFileExW call in a bounded retry loop (5 attempts, ~10ms × attempt backoff, ≤100ms worst case), retrying only on the two known-transient error codes. Benefits all 10 existing replace_file call sites with no call-site changes. Non-Windows path (std::fs::rename) is untouched.
  • New tui_signal.rs: a small process-wide AtomicBool flag (set_tui_active/is_tui_active), mirroring the existing style of paths::is_config_dir_overridden().
  • message_cache.rs: gate the eprintln! fallback in warn_cache_failure_once on !tui_signal::is_tui_active(). tracing::warn! still fires unconditionally and is unchanged. Non-TUI command behavior is byte-for-byte unchanged.
  • tui/mod.rs: toggle the flag to true right after the TUI successfully enters the alternate screen, and back to false in both terminal-restore paths (normal exit and the panic hook's best-effort restore), so it can never get stuck.

Verification

  • cargo build -p tokscale-core -p tokscale-cli — clean
  • cargo clippy -p tokscale-core -p tokscale-cli --all-targets -- -D warnings — zero warnings
  • cargo test -p tokscale-core — 1216 passed, 0 failed, including a new tui_signal::tests::round_trips test
  • cargo fmt --check — clean
  • Manual review of the unsafe extern "system" MoveFileExW retry loop — no Windows machine available locally to compile/run the #[cfg(windows)] path; relying on the existing build-native.yml Windows CI job plus this manual review

Not tested: actual Windows MoveFileEx retry behavior under real transient file-lock contention (AV/indexer/cloud-sync), since no Windows machine is available in this environment.


Summary by cubic

Prevents TUI screen corruption when background cache save warnings fire by suppressing raw stderr during TUI and making Windows file replacement more resilient. Fixes #893.

  • Bug Fixes

    • Windows: retry MoveFileExW in fs_atomic::replace_file (up to 5 attempts with short backoff) on transient ERROR_ACCESS_DENIED/ERROR_SHARING_VIOLATION. Non-Windows unchanged.
    • TUI: add tokscale-core::tui_signal and toggle it from tokscale-cli when entering/leaving the TUI; suppress message_cache::warn_cache_failure_once eprintln! while active. tracing::warn! unchanged; non-TUI behavior remains the same.
  • Refactors

    • Run workspace-wide cargo fmt to satisfy CI; unrelated files only, no behavior changes.